@query-farm/vgi-rpc 0.3.4 → 0.6.0

package/dist/index.js

@@ -50,6 +50,48 @@ var init_zstd = __esm(() => {
   isBun = typeof globalThis.Bun !== "undefined";
 });
 
+// src/errors.ts
+class RpcError extends Error {
+  errorType;
+  errorMessage;
+  remoteTraceback;
+  constructor(errorType, errorMessage, remoteTraceback) {
+    super(`${errorType}: ${errorMessage}`);
+    this.errorType = errorType;
+    this.errorMessage = errorMessage;
+    this.remoteTraceback = remoteTraceback;
+    this.name = "RpcError";
+  }
+}
+
+class VersionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VersionError";
+  }
+}
+
+// src/auth.ts
+class AuthContext {
+  domain;
+  authenticated;
+  principal;
+  claims;
+  constructor(domain, authenticated, principal, claims = {}) {
+    this.domain = domain;
+    this.authenticated = authenticated;
+    this.principal = principal;
+    this.claims = claims;
+  }
+  static anonymous() {
+    return new AuthContext("", false, null);
+  }
+  requireAuthenticated() {
+    if (!this.authenticated) {
+      throw new RpcError("AuthenticationError", "Authentication required", "");
+    }
+  }
+}
 // src/constants.ts
 var RPC_METHOD_KEY = "vgi_rpc.method";
 var LOG_LEVEL_KEY = "vgi_rpc.log_level";
@@ -61,21 +103,247 @@ var SERVER_ID_KEY = "vgi_rpc.server_id";
 var REQUEST_ID_KEY = "vgi_rpc.request_id";
 var PROTOCOL_NAME_KEY = "vgi_rpc.protocol_name";
 var DESCRIBE_VERSION_KEY = "vgi_rpc.describe_version";
-var DESCRIBE_VERSION = "2";
+var DESCRIBE_VERSION = "3";
 var DESCRIBE_METHOD_NAME = "__describe__";
 var STATE_KEY = "vgi_rpc.stream_state#b64";
+var LOCATION_KEY = "vgi_rpc.location";
+var LOCATION_SHA256_KEY = "vgi_rpc.location.sha256";
 
-// src/http/common.ts
+// src/external.ts
 import { RecordBatchReader, RecordBatchStreamWriter } from "@query-farm/apache-arrow";
+init_zstd();
 
-// src/util/conform.ts
+// src/wire/response.ts
 import {
+  Data,
+  DataType,
   makeData,
   RecordBatch,
   Struct,
-  Type,
   vectorFromArray
 } from "@query-farm/apache-arrow";
+function coerceInt64(schema, values) {
+  const result = { ...values };
+  for (const field of schema.fields) {
+    const val = result[field.name];
+    if (val === undefined)
+      continue;
+    if (!DataType.isInt(field.type) || field.type.bitWidth !== 64)
+      continue;
+    if (Array.isArray(val)) {
+      result[field.name] = val.map((v) => typeof v === "number" ? BigInt(v) : v);
+    } else if (typeof val === "number") {
+      result[field.name] = BigInt(val);
+    }
+  }
+  return result;
+}
+function buildResultBatch(schema, values, serverId, requestId) {
+  const metadata = new Map;
+  metadata.set(SERVER_ID_KEY, serverId);
+  if (requestId !== null) {
+    metadata.set(REQUEST_ID_KEY, requestId);
+  }
+  if (schema.fields.length === 0) {
+    return buildEmptyBatch(schema, metadata);
+  }
+  for (const field of schema.fields) {
+    if (values[field.name] === undefined && !field.nullable) {
+      const got = Object.keys(values);
+      throw new TypeError(`Handler result missing required field '${field.name}'. Got keys: [${got.join(", ")}]`);
+    }
+  }
+  const coerced = coerceInt64(schema, values);
+  const children = schema.fields.map((f) => {
+    const val = coerced[f.name];
+    if (val instanceof Data) {
+      return val;
+    }
+    const arr = vectorFromArray([val], f.type);
+    return arr.data[0];
+  });
+  const structType = new Struct(schema.fields);
+  const data = makeData({
+    type: structType,
+    length: 1,
+    children,
+    nullCount: 0
+  });
+  return new RecordBatch(schema, data, metadata);
+}
+function buildErrorBatch(schema, error, serverId, requestId) {
+  const metadata = new Map;
+  metadata.set(LOG_LEVEL_KEY, "EXCEPTION");
+  metadata.set(LOG_MESSAGE_KEY, `${error.constructor.name}: ${error.message}`);
+  const extra = {
+    exception_type: error.constructor.name,
+    exception_message: error.message,
+    traceback: error.stack ?? ""
+  };
+  metadata.set(LOG_EXTRA_KEY, JSON.stringify(extra));
+  metadata.set(SERVER_ID_KEY, serverId);
+  if (requestId !== null) {
+    metadata.set(REQUEST_ID_KEY, requestId);
+  }
+  return buildEmptyBatch(schema, metadata);
+}
+function buildLogBatch(schema, level, message, extra, serverId, requestId) {
+  const metadata = new Map;
+  metadata.set(LOG_LEVEL_KEY, level);
+  metadata.set(LOG_MESSAGE_KEY, message);
+  if (extra) {
+    metadata.set(LOG_EXTRA_KEY, JSON.stringify(extra));
+  }
+  if (serverId != null) {
+    metadata.set(SERVER_ID_KEY, serverId);
+  }
+  if (requestId != null) {
+    metadata.set(REQUEST_ID_KEY, requestId);
+  }
+  return buildEmptyBatch(schema, metadata);
+}
+function makeEmptyData(type) {
+  if (DataType.isStruct(type)) {
+    const children = type.children.map((f) => makeEmptyData(f.type));
+    return makeData({ type, length: 0, children, nullCount: 0 });
+  }
+  if (DataType.isList(type)) {
+    const childData = makeEmptyData(type.children[0].type);
+    return makeData({ type, length: 0, children: [childData], nullCount: 0, valueOffsets: new Int32Array([0]) });
+  }
+  if (DataType.isFixedSizeList(type)) {
+    const childData = makeEmptyData(type.children[0].type);
+    return makeData({ type, length: 0, child: childData, nullCount: 0 });
+  }
+  if (DataType.isMap(type)) {
+    const entryType = type.children[0]?.type;
+    const entryData = entryType ? makeEmptyData(entryType) : makeData({ type: new Struct([]), length: 0, children: [], nullCount: 0 });
+    return makeData({ type, length: 0, children: [entryData], nullCount: 0, valueOffsets: new Int32Array([0]) });
+  }
+  return makeData({ type, length: 0, nullCount: 0 });
+}
+function buildEmptyBatch(schema, metadata) {
+  const children = schema.fields.map((f) => makeEmptyData(f.type));
+  const structType = new Struct(schema.fields);
+  const data = makeData({
+    type: structType,
+    length: 0,
+    children,
+    nullCount: 0
+  });
+  return new RecordBatch(schema, data, metadata);
+}
+
+// src/external.ts
+var DEFAULT_THRESHOLD = 1048576;
+function httpsOnlyValidator(url) {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:") {
+    throw new Error(`External location URL must use HTTPS, got "${parsed.protocol}"`);
+  }
+}
+async function sha256Hex(data) {
+  const buf = new ArrayBuffer(data.byteLength);
+  new Uint8Array(buf).set(data);
+  const hash = await crypto.subtle.digest("SHA-256", buf);
+  return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function isExternalLocationBatch(batch) {
+  if (batch.numRows !== 0)
+    return false;
+  const meta = batch.metadata;
+  if (!meta)
+    return false;
+  return meta.has(LOCATION_KEY) && !meta.has(LOG_LEVEL_KEY);
+}
+function makeExternalLocationBatch(schema, url, sha256) {
+  const metadata = new Map;
+  metadata.set(LOCATION_KEY, url);
+  if (sha256) {
+    metadata.set(LOCATION_SHA256_KEY, sha256);
+  }
+  return buildEmptyBatch(schema, metadata);
+}
+function serializeBatchToIpc(batch) {
+  const writer = new RecordBatchStreamWriter;
+  writer.reset(undefined, batch.schema);
+  writer.write(batch);
+  writer.close();
+  return writer.toUint8Array(true);
+}
+function batchByteSize(batch) {
+  const writer = new RecordBatchStreamWriter;
+  writer.reset(undefined, batch.schema);
+  writer.write(batch);
+  writer.close();
+  return writer.toUint8Array(true).byteLength;
+}
+async function maybeExternalizeBatch(batch, config) {
+  if (!config?.storage)
+    return batch;
+  if (batch.numRows === 0)
+    return batch;
+  const threshold = config.externalizeThresholdBytes ?? DEFAULT_THRESHOLD;
+  if (batchByteSize(batch) < threshold)
+    return batch;
+  let ipcData = serializeBatchToIpc(batch);
+  const checksum = await sha256Hex(ipcData);
+  let contentEncoding = "";
+  if (config.compression?.algorithm === "zstd") {
+    ipcData = zstdCompress(ipcData, config.compression.level ?? 3);
+    contentEncoding = "zstd";
+  }
+  const url = await config.storage.upload(ipcData, contentEncoding);
+  return makeExternalLocationBatch(batch.schema, url, checksum);
+}
+async function resolveExternalLocation(batch, config) {
+  if (!config)
+    return batch;
+  if (!isExternalLocationBatch(batch))
+    return batch;
+  const url = batch.metadata?.get(LOCATION_KEY);
+  if (!url)
+    return batch;
+  const validator = config.urlValidator === null ? undefined : config.urlValidator ?? httpsOnlyValidator;
+  if (validator) {
+    validator(url);
+  }
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`External location fetch failed: ${response.status} ${response.statusText} [url: ${url}]`);
+  }
+  let data = new Uint8Array(await response.arrayBuffer());
+  const contentEncoding = response.headers.get("Content-Encoding");
+  if (contentEncoding === "zstd") {
+    data = new Uint8Array(zstdDecompress(data));
+  }
+  const expectedSha256 = batch.metadata?.get(LOCATION_SHA256_KEY);
+  if (expectedSha256) {
+    const actualSha256 = await sha256Hex(data);
+    if (actualSha256 !== expectedSha256) {
+      throw new Error(`SHA-256 checksum mismatch for ${url}: expected ${expectedSha256}, got ${actualSha256}`);
+    }
+  }
+  const reader = await RecordBatchReader.from(data);
+  await reader.open();
+  const resolved = reader.next();
+  if (!resolved || resolved.done || !resolved.value) {
+    throw new Error(`No data batch found in external IPC stream from ${url}`);
+  }
+  return resolved.value;
+}
+
+// src/http/common.ts
+import { RecordBatchReader as RecordBatchReader2, RecordBatchStreamWriter as RecordBatchStreamWriter2 } from "@query-farm/apache-arrow";
+
+// src/util/conform.ts
+import {
+  makeData as makeData2,
+  RecordBatch as RecordBatch2,
+  Struct as Struct2,
+  Type,
+  vectorFromArray as vectorFromArray2
+} from "@query-farm/apache-arrow";
 function needsValueCast(src, dst) {
   if (src.typeId === dst.typeId)
     return false;
@@ -111,19 +379,19 @@ function conformBatchToSchema(batch, schema) {
         const v = col.get(r);
         values.push(typeof v === "bigint" ? Number(v) : v);
       }
-      return vectorFromArray(values, dstType).data[0];
+      return vectorFromArray2(values, dstType).data[0];
     }
     return srcChild.clone(dstType);
   });
-  const structType = new Struct(schema.fields);
-  const data = makeData({
+  const structType = new Struct2(schema.fields);
+  const data = makeData2({
     type: structType,
     length: batch.numRows,
     children,
     nullCount: batch.data.nullCount,
     nullBitmap: batch.data.nullBitmap
   });
-  return new RecordBatch(schema, data, batch.metadata);
+  return new RecordBatch2(schema, data, batch.metadata);
 }
 
 // src/http/common.ts
@@ -138,7 +406,7 @@ class HttpRpcError extends Error {
   }
 }
 function serializeIpcStream(schema, batches) {
-  const writer = new RecordBatchStreamWriter;
+  const writer = new RecordBatchStreamWriter2;
   writer.reset(undefined, schema);
   for (const batch of batches) {
     writer.write(conformBatchToSchema(batch, schema));
@@ -152,7 +420,7 @@ function arrowResponse(body, status = 200, extraHeaders) {
   return new Response(body, { status, headers });
 }
 async function readRequestFromBody(body) {
-  const reader = await RecordBatchReader.from(body);
+  const reader = await RecordBatchReader2.from(body);
   await reader.open();
   const schema = reader.schema;
   if (!schema) {
@@ -166,46 +434,25 @@ async function readRequestFromBody(body) {
 }
 
 // src/client/introspect.ts
-import { Schema as ArrowSchema, RecordBatchReader as RecordBatchReader4 } from "@query-farm/apache-arrow";
+import { Schema as ArrowSchema, RecordBatchReader as RecordBatchReader5 } from "@query-farm/apache-arrow";
 
 // src/client/ipc.ts
 import {
   Binary,
   Bool,
-  DataType,
+  DataType as DataType2,
   Float64,
   Int64,
-  makeData as makeData2,
-  RecordBatch as RecordBatch2,
-  RecordBatchReader as RecordBatchReader3,
-  Struct as Struct2,
+  makeData as makeData3,
+  RecordBatch as RecordBatch3,
+  RecordBatchReader as RecordBatchReader4,
+  Struct as Struct3,
   Utf8,
-  vectorFromArray as vectorFromArray2
+  vectorFromArray as vectorFromArray3
 } from "@query-farm/apache-arrow";
 
-// src/errors.ts
-class RpcError extends Error {
-  errorType;
-  errorMessage;
-  remoteTraceback;
-  constructor(errorType, errorMessage, remoteTraceback) {
-    super(`${errorType}: ${errorMessage}`);
-    this.errorType = errorType;
-    this.errorMessage = errorMessage;
-    this.remoteTraceback = remoteTraceback;
-    this.name = "RpcError";
-  }
-}
-
-class VersionError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "VersionError";
-  }
-}
-
 // src/wire/reader.ts
-import { RecordBatchReader as RecordBatchReader2 } from "@query-farm/apache-arrow";
+import { RecordBatchReader as RecordBatchReader3 } from "@query-farm/apache-arrow";
 
 class IpcStreamReader {
   reader;
@@ -215,7 +462,7 @@ class IpcStreamReader {
     this.reader = reader;
   }
   static async create(input) {
-    const reader = await RecordBatchReader2.from(input);
+    const reader = await RecordBatchReader3.from(input);
     await reader.open({ autoDestroy: false });
     if (reader.closed) {
       throw new Error("Input stream closed before first IPC message");
@@ -292,12 +539,12 @@ function inferArrowType(value) {
 function coerceForArrow(type, value) {
   if (value == null)
     return value;
-  if (DataType.isInt(type) && type.bitWidth === 64) {
+  if (DataType2.isInt(type) && type.bitWidth === 64) {
     if (typeof value === "number")
       return BigInt(value);
     return value;
   }
-  if (DataType.isMap(type)) {
+  if (DataType2.isMap(type)) {
     if (value instanceof Map) {
       const entriesField = type.children[0];
       const valueType = entriesField.type.children[1].type;
@@ -309,7 +556,7 @@ function coerceForArrow(type, value) {
     }
     return value;
   }
-  if (DataType.isList(type)) {
+  if (DataType2.isList(type)) {
     if (Array.isArray(value)) {
       const elemType = type.children[0].type;
       return value.map((v) => coerceForArrow(elemType, v));
@@ -323,32 +570,32 @@ function buildRequestIpc(schema, params, method) {
   metadata.set(RPC_METHOD_KEY, method);
   metadata.set(REQUEST_VERSION_KEY, REQUEST_VERSION);
   if (schema.fields.length === 0) {
-    const structType2 = new Struct2(schema.fields);
-    const data2 = makeData2({
+    const structType2 = new Struct3(schema.fields);
+    const data2 = makeData3({
       type: structType2,
       length: 1,
       children: [],
       nullCount: 0
     });
-    const batch2 = new RecordBatch2(schema, data2, metadata);
+    const batch2 = new RecordBatch3(schema, data2, metadata);
     return serializeIpcStream(schema, [batch2]);
   }
   const children = schema.fields.map((f) => {
     const val = coerceForArrow(f.type, params[f.name]);
-    return vectorFromArray2([val], f.type).data[0];
+    return vectorFromArray3([val], f.type).data[0];
   });
-  const structType = new Struct2(schema.fields);
-  const data = makeData2({
+  const structType = new Struct3(schema.fields);
+  const data = makeData3({
     type: structType,
     length: 1,
     children,
     nullCount: 0
   });
-  const batch = new RecordBatch2(schema, data, metadata);
+  const batch = new RecordBatch3(schema, data, metadata);
   return serializeIpcStream(schema, [batch]);
 }
 async function readResponseBatches(body) {
-  const reader = await RecordBatchReader3.from(body);
+  const reader = await RecordBatchReader4.from(body);
   await reader.open();
   const schema = reader.schema;
   if (!schema) {
@@ -422,7 +669,7 @@ async function readSequentialStreams(body) {
 
 // src/client/introspect.ts
 async function deserializeSchema(bytes) {
-  const reader = await RecordBatchReader4.from(bytes);
+  const reader = await RecordBatchReader5.from(bytes);
   await reader.open();
   return reader.schema;
 }
@@ -486,21 +733,28 @@ async function parseDescribeResponse(batches, onLog) {
   return { protocolName, methods };
 }
 async function httpIntrospect(baseUrl, options) {
-  const prefix = options?.prefix ?? "/vgi";
+  const prefix = options?.prefix ?? "";
   const emptySchema = new ArrowSchema([]);
   const body = buildRequestIpc(emptySchema, {}, DESCRIBE_METHOD_NAME);
+  const headers = { "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
   });
+  if (response.status === 401) {
+    throw new RpcError("AuthenticationError", "Authentication required", "");
+  }
   const responseBody = new Uint8Array(await response.arrayBuffer());
   const { batches } = await readResponseBatches(responseBody);
   return parseDescribeResponse(batches);
 }
 
 // src/client/stream.ts
-import { Field, makeData as makeData3, RecordBatch as RecordBatch3, Schema, Struct as Struct3, vectorFromArray as vectorFromArray3 } from "@query-farm/apache-arrow";
+import { Field, makeData as makeData4, RecordBatch as RecordBatch4, Schema, Struct as Struct4, vectorFromArray as vectorFromArray4 } from "@query-farm/apache-arrow";
 class HttpStreamSession {
   _baseUrl;
   _prefix;
@@ -515,6 +769,8 @@ class HttpStreamSession {
   _compressionLevel;
   _compressFn;
   _decompressFn;
+  _authorization;
+  _externalConfig;
   constructor(opts) {
     this._baseUrl = opts.baseUrl;
     this._prefix = opts.prefix;
@@ -529,6 +785,8 @@ class HttpStreamSession {
     this._compressionLevel = opts.compressionLevel;
     this._compressFn = opts.compressFn;
     this._decompressFn = opts.decompressFn;
+    this._authorization = opts.authorization;
+    this._externalConfig = opts.externalConfig;
   }
   get header() {
     return this._header;
@@ -541,6 +799,9 @@ class HttpStreamSession {
       headers["Content-Encoding"] = "zstd";
       headers["Accept-Encoding"] = "zstd";
     }
+    if (this._authorization) {
+      headers.Authorization = this._authorization;
+    }
     return headers;
   }
   _prepareBody(content) {
@@ -565,7 +826,7 @@ class HttpStreamSession {
       const emptyBatch = this._buildEmptyBatch(zeroSchema);
       const metadata2 = new Map;
       metadata2.set(STATE_KEY, this._stateToken);
-      const batchWithMeta = new RecordBatch3(zeroSchema, emptyBatch.data, metadata2);
+      const batchWithMeta = new RecordBatch4(zeroSchema, emptyBatch.data, metadata2);
       return this._doExchange(zeroSchema, [batchWithMeta]);
     }
     const keys = Object.keys(input[0]);
@@ -584,10 +845,10 @@ class HttpStreamSession {
     const inputSchema = new Schema(fields);
     const children = inputSchema.fields.map((f) => {
       const values = input.map((row) => row[f.name]);
-      return vectorFromArray3(values, f.type).data[0];
+      return vectorFromArray4(values, f.type).data[0];
     });
-    const structType = new Struct3(inputSchema.fields);
-    const data = makeData3({
+    const structType = new Struct4(inputSchema.fields);
+    const data = makeData4({
       type: structType,
       length: input.length,
       children,
@@ -595,7 +856,7 @@ class HttpStreamSession {
     });
     const metadata = new Map;
     metadata.set(STATE_KEY, this._stateToken);
-    const batch = new RecordBatch3(inputSchema, data, metadata);
+    const batch = new RecordBatch4(inputSchema, data, metadata);
     return this._doExchange(inputSchema, [batch]);
   }
   async _doExchange(schema, batches) {
@@ -605,6 +866,9 @@ class HttpStreamSession {
       headers: this._buildHeaders(),
       body: this._prepareBody(body)
     });
+    if (resp.status === 401) {
+      throw new RpcError("AuthenticationError", "Authentication required", "");
+    }
     const responseBody = await this._readResponse(resp);
     const { batches: responseBatches } = await readResponseBatches(responseBody);
     let resultRows = [];
@@ -627,22 +891,26 @@ class HttpStreamSession {
   }
   _buildEmptyBatch(schema) {
     const children = schema.fields.map((f) => {
-      return makeData3({ type: f.type, length: 0, nullCount: 0 });
+      return makeData4({ type: f.type, length: 0, nullCount: 0 });
     });
-    const structType = new Struct3(schema.fields);
-    const data = makeData3({
+    const structType = new Struct4(schema.fields);
+    const data = makeData4({
       type: structType,
       length: 0,
       children,
       nullCount: 0
     });
-    return new RecordBatch3(schema, data);
+    return new RecordBatch4(schema, data);
   }
   async* [Symbol.asyncIterator]() {
-    for (const batch of this._pendingBatches) {
+    for (let batch of this._pendingBatches) {
       if (batch.numRows === 0) {
-        dispatchLogOrError(batch, this._onLog);
-        continue;
+        if (isExternalLocationBatch(batch)) {
+          batch = await resolveExternalLocation(batch, this._externalConfig);
+        } else {
+          dispatchLogOrError(batch, this._onLog);
+          continue;
+        }
       }
       yield extractBatchRows(batch);
     }
@@ -655,7 +923,7 @@ class HttpStreamSession {
       const responseBody = await this._sendContinuation(this._stateToken);
       const { batches } = await readResponseBatches(responseBody);
       let gotContinuation = false;
-      for (const batch of batches) {
+      for (let batch of batches) {
         if (batch.numRows === 0) {
           const token = batch.metadata?.get(STATE_KEY);
           if (token) {
@@ -663,8 +931,12 @@ class HttpStreamSession {
             gotContinuation = true;
             continue;
           }
-          dispatchLogOrError(batch, this._onLog);
-          continue;
+          if (isExternalLocationBatch(batch)) {
+            batch = await resolveExternalLocation(batch, this._externalConfig);
+          } else {
+            dispatchLogOrError(batch, this._onLog);
+            continue;
+          }
         }
         yield extractBatchRows(batch);
       }
@@ -676,20 +948,23 @@ class HttpStreamSession {
     const emptySchema = new Schema([]);
     const metadata = new Map;
     metadata.set(STATE_KEY, token);
-    const structType = new Struct3(emptySchema.fields);
-    const data = makeData3({
+    const structType = new Struct4(emptySchema.fields);
+    const data = makeData4({
       type: structType,
       length: 1,
       children: [],
       nullCount: 0
     });
-    const batch = new RecordBatch3(emptySchema, data, metadata);
+    const batch = new RecordBatch4(emptySchema, data, metadata);
     const body = serializeIpcStream(emptySchema, [batch]);
     const resp = await fetch(`${this._baseUrl}${this._prefix}/${this._method}/exchange`, {
       method: "POST",
       headers: this._buildHeaders(),
       body: this._prepareBody(body)
     });
+    if (resp.status === 401) {
+      throw new RpcError("AuthenticationError", "Authentication required", "");
+    }
     return this._readResponse(resp);
   }
   close() {}
@@ -697,9 +972,11 @@ class HttpStreamSession {
 
 // src/client/connect.ts
 function httpConnect(baseUrl, options) {
-  const prefix = (options?.prefix ?? "/vgi").replace(/\/+$/, "");
+  const prefix = (options?.prefix ?? "").replace(/\/+$/, "");
   const onLog = options?.onLog;
   const compressionLevel = options?.compressionLevel;
+  const authorization = options?.authorization;
+  const externalConfig = options?.externalLocation;
   let methodCache = null;
   let compressFn;
   let decompressFn;
@@ -722,6 +999,9 @@ function httpConnect(baseUrl, options) {
       headers["Content-Encoding"] = "zstd";
       headers["Accept-Encoding"] = "zstd";
     }
+    if (authorization) {
+      headers.Authorization = authorization;
+    }
     return headers;
   }
   function prepareBody(content) {
@@ -730,6 +1010,11 @@ function httpConnect(baseUrl, options) {
     }
     return content;
   }
+  function checkAuth(resp) {
+    if (resp.status === 401) {
+      throw new RpcError("AuthenticationError", "Authentication required", "");
+    }
+  }
   async function readResponse(resp) {
     let body = new Uint8Array(await resp.arrayBuffer());
     if (resp.headers.get("Content-Encoding") === "zstd" && decompressFn) {
@@ -740,7 +1025,7 @@ function httpConnect(baseUrl, options) {
   async function ensureMethodCache() {
     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;
   }
@@ -759,13 +1044,18 @@ function httpConnect(baseUrl, options) {
         headers: buildHeaders(),
         body: prepareBody(body)
       });
+      checkAuth(resp);
       const responseBody = await readResponse(resp);
       const { batches } = await readResponseBatches(responseBody);
       let resultBatch = null;
-      for (const batch of batches) {
+      for (let batch of batches) {
         if (batch.numRows === 0) {
-          dispatchLogOrError(batch, onLog);
-          continue;
+          if (isExternalLocationBatch(batch)) {
+            batch = await resolveExternalLocation(batch, externalConfig);
+          } else {
+            dispatchLogOrError(batch, onLog);
+            continue;
+          }
         }
         resultBatch = batch;
       }
@@ -794,6 +1084,7 @@ function httpConnect(baseUrl, options) {
         headers: buildHeaders(),
         body: prepareBody(body)
       });
+      checkAuth(resp);
       const responseBody = await readResponse(resp);
       let header = null;
       let stateToken = null;
@@ -899,7 +1190,9 @@ function httpConnect(baseUrl, options) {
         header,
         compressionLevel,
         compressFn,
-        decompressFn
+        decompressFn,
+        authorization,
+        externalConfig
       });
     },
     async describe() {
@@ -908,15 +1201,124 @@ function httpConnect(baseUrl, options) {
     close() {}
   };
 }
+// src/client/oauth.ts
+function parseMetadataJson(json) {
+  const result = {
+    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_signing_alg_values_supported)
+    result.resourceSigningAlgValuesSupported = json.resource_signing_alg_values_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;
+  if (json.client_id)
+    result.clientId = json.client_id;
+  if (json.client_secret)
+    result.clientSecret = json.client_secret;
+  if (json.use_id_token_as_bearer)
+    result.useIdTokenAsBearer = json.use_id_token_as_bearer;
+  if (json.device_code_client_id)
+    result.deviceCodeClientId = json.device_code_client_id;
+  if (json.device_code_client_secret)
+    result.deviceCodeClientSecret = json.device_code_client_secret;
+  return result;
+}
+async function httpOAuthMetadata(baseUrl, prefix) {
+  const effectivePrefix = (prefix ?? "").replace(/\/+$/, "");
+  const metadataUrl = `${baseUrl.replace(/\/+$/, "")}/.well-known/oauth-protected-resource${effectivePrefix}`;
+  try {
+    return await fetchOAuthMetadata(metadataUrl);
+  } catch {
+    return null;
+  }
+}
+async function fetchOAuthMetadata(metadataUrl) {
+  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);
+}
+function parseResourceMetadataUrl(wwwAuthenticate) {
+  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];
+}
+function parseClientId(wwwAuthenticate) {
+  const bearerMatch = wwwAuthenticate.match(/^Bearer\s+(.*)/i);
+  if (!bearerMatch)
+    return null;
+  const params = bearerMatch[1];
+  const clientIdMatch = params.match(/client_id="([^"]+)"/);
+  if (!clientIdMatch)
+    return null;
+  return clientIdMatch[1];
+}
+function parseClientSecret(wwwAuthenticate) {
+  const bearerMatch = wwwAuthenticate.match(/^Bearer\s+(.*)/i);
+  if (!bearerMatch)
+    return null;
+  const params = bearerMatch[1];
+  const match = params.match(/client_secret="([^"]+)"/);
+  if (!match)
+    return null;
+  return match[1];
+}
+function parseUseIdTokenAsBearer(wwwAuthenticate) {
+  const bearerMatch = wwwAuthenticate.match(/^Bearer\s+(.*)/i);
+  if (!bearerMatch)
+    return false;
+  const params = bearerMatch[1];
+  const match = params.match(/use_id_token_as_bearer="([^"]+)"/);
+  if (!match)
+    return false;
+  return match[1] === "true";
+}
+function parseDeviceCodeClientId(wwwAuthenticate) {
+  const bearerMatch = wwwAuthenticate.match(/^Bearer\s+(.*)/i);
+  if (!bearerMatch)
+    return null;
+  const params = bearerMatch[1];
+  const match = params.match(/device_code_client_id="([^"]+)"/);
+  if (!match)
+    return null;
+  return match[1];
+}
+function parseDeviceCodeClientSecret(wwwAuthenticate) {
+  const bearerMatch = wwwAuthenticate.match(/^Bearer\s+(.*)/i);
+  if (!bearerMatch)
+    return null;
+  const params = bearerMatch[1];
+  const match = params.match(/device_code_client_secret="([^"]+)"/);
+  if (!match)
+    return null;
+  return match[1];
+}
 // src/client/pipe.ts
 import {
   Field as Field2,
-  makeData as makeData4,
-  RecordBatch as RecordBatch4,
-  RecordBatchStreamWriter as RecordBatchStreamWriter2,
+  makeData as makeData5,
+  RecordBatch as RecordBatch5,
+  RecordBatchStreamWriter as RecordBatchStreamWriter3,
   Schema as Schema2,
-  Struct as Struct4,
-  vectorFromArray as vectorFromArray4
+  Struct as Struct5,
+  vectorFromArray as vectorFromArray5
 } from "@query-farm/apache-arrow";
 class PipeIncrementalWriter {
   writer;
@@ -924,7 +1326,7 @@ class PipeIncrementalWriter {
   closed = false;
   constructor(writeFn, schema) {
     this.writeFn = writeFn;
-    this.writer = new RecordBatchStreamWriter2;
+    this.writer = new RecordBatchStreamWriter3;
     this.writer.reset(undefined, schema);
     this.drain();
   }
@@ -962,6 +1364,7 @@ class PipeStreamSession {
   _outputSchema;
   _releaseBusy;
   _setDrainPromise;
+  _externalConfig;
   constructor(opts) {
     this._reader = opts.reader;
     this._writeFn = opts.writeFn;
@@ -970,6 +1373,7 @@ class PipeStreamSession {
     this._outputSchema = opts.outputSchema;
     this._releaseBusy = opts.releaseBusy;
     this._setDrainPromise = opts.setDrainPromise;
+    this._externalConfig = opts.externalConfig;
   }
   get header() {
     return this._header;
@@ -980,6 +1384,9 @@ class PipeStreamSession {
       if (batch === null)
         return null;
       if (batch.numRows === 0) {
+        if (isExternalLocationBatch(batch)) {
+          return await resolveExternalLocation(batch, this._externalConfig);
+        }
         if (dispatchLogOrError(batch, this._onLog)) {
           continue;
         }
@@ -1005,16 +1412,16 @@ class PipeStreamSession {
     if (input.length === 0) {
       inputSchema = this._inputSchema ?? this._outputSchema;
       const children = inputSchema.fields.map((f) => {
-        return makeData4({ type: f.type, length: 0, nullCount: 0 });
+        return makeData5({ type: f.type, length: 0, nullCount: 0 });
       });
-      const structType = new Struct4(inputSchema.fields);
-      const data = makeData4({
+      const structType = new Struct5(inputSchema.fields);
+      const data = makeData5({
         type: structType,
         length: 0,
         children,
         nullCount: 0
       });
-      batch = new RecordBatch4(inputSchema, data);
+      batch = new RecordBatch5(inputSchema, data);
     } else {
       const keys = Object.keys(input[0]);
       const fields = keys.map((key) => {
@@ -1039,16 +1446,16 @@ class PipeStreamSession {
       }
       const children = inputSchema.fields.map((f) => {
         const values = input.map((row) => row[f.name]);
-        return vectorFromArray4(values, f.type).data[0];
+        return vectorFromArray5(values, f.type).data[0];
       });
-      const structType = new Struct4(inputSchema.fields);
-      const data = makeData4({
+      const structType = new Struct5(inputSchema.fields);
+      const data = makeData5({
         type: structType,
         length: input.length,
         children,
         nullCount: 0
       });
-      batch = new RecordBatch4(inputSchema, data);
+      batch = new RecordBatch5(inputSchema, data);
     }
     if (!this._inputWriter) {
       this._inputWriter = new PipeIncrementalWriter(this._writeFn, inputSchema);
@@ -1087,14 +1494,14 @@ class PipeStreamSession {
     try {
       const tickSchema = new Schema2([]);
       this._inputWriter = new PipeIncrementalWriter(this._writeFn, tickSchema);
-      const structType = new Struct4(tickSchema.fields);
-      const tickData = makeData4({
+      const structType = new Struct5(tickSchema.fields);
+      const tickData = makeData5({
         type: structType,
         length: 0,
         children: [],
         nullCount: 0
       });
-      const tickBatch = new RecordBatch4(tickSchema, tickData);
+      const tickBatch = new RecordBatch5(tickSchema, tickData);
       while (true) {
         this._inputWriter.write(tickBatch);
         await this._ensureOutputStream();
@@ -1149,6 +1556,7 @@ class PipeStreamSession {
 }
 function pipeConnect(readable, writable, options) {
   const onLog = options?.onLog;
+  const externalConfig = options?.externalLocation;
   let reader = null;
   let readerPromise = null;
   let methodCache = null;
@@ -1224,10 +1632,14 @@ function pipeConnect(readable, writable, options) {
           throw new Error("EOF reading response");
         }
         let resultBatch = null;
-        for (const batch of response.batches) {
+        for (let batch of response.batches) {
           if (batch.numRows === 0) {
-            dispatchLogOrError(batch, onLog);
-            continue;
+            if (isExternalLocationBatch(batch)) {
+              batch = await resolveExternalLocation(batch, externalConfig);
+            } else {
+              dispatchLogOrError(batch, onLog);
+              continue;
+            }
           }
           resultBatch = batch;
         }
@@ -1280,7 +1692,8 @@ function pipeConnect(readable, writable, options) {
           header,
           outputSchema,
           releaseBusy,
-          setDrainPromise
+          setDrainPromise,
+          externalConfig
         });
       } catch (e) {
         try {
@@ -1330,7 +1743,8 @@ function subprocessConnect(cmd, options) {
     }
   };
   const client = pipeConnect(stdout, writable, {
-    onLog: options?.onLog
+    onLog: options?.onLog,
+    externalLocation: options?.externalLocation
   });
   const originalClose = client.close;
   client.close = () => {
@@ -1341,127 +1755,144 @@ function subprocessConnect(cmd, options) {
   };
   return client;
 }
-// src/http/handler.ts
-import { randomBytes } from "node:crypto";
-import { Schema as Schema5 } from "@query-farm/apache-arrow";
-
-// src/types.ts
-import { RecordBatch as RecordBatch6, recordBatchFromArrays } from "@query-farm/apache-arrow";
-
-// src/wire/response.ts
-import {
-  Data,
-  DataType as DataType2,
-  makeData as makeData5,
-  RecordBatch as RecordBatch5,
-  Struct as Struct5,
-  vectorFromArray as vectorFromArray5
-} from "@query-farm/apache-arrow";
-function coerceInt64(schema, values) {
-  const result = { ...values };
-  for (const field of schema.fields) {
-    const val = result[field.name];
-    if (val === undefined)
-      continue;
-    if (!DataType2.isInt(field.type) || field.type.bitWidth !== 64)
-      continue;
-    if (Array.isArray(val)) {
-      result[field.name] = val.map((v) => typeof v === "number" ? BigInt(v) : v);
-    } else if (typeof val === "number") {
-      result[field.name] = BigInt(val);
+// src/http/auth.ts
+function oauthResourceMetadataToJson(metadata) {
+  const json = {
+    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;
   }
-  return result;
-}
-function buildResultBatch(schema, values, serverId, requestId) {
-  const metadata = new Map;
-  metadata.set(SERVER_ID_KEY, serverId);
-  if (requestId !== null) {
-    metadata.set(REQUEST_ID_KEY, requestId);
-  }
-  if (schema.fields.length === 0) {
-    return buildEmptyBatch(schema, metadata);
+  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;
   }
-  for (const field of schema.fields) {
-    if (values[field.name] === undefined && !field.nullable) {
-      const got = Object.keys(values);
-      throw new TypeError(`Handler result missing required field '${field.name}'. Got keys: [${got.join(", ")}]`);
+  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;
   }
-  const coerced = coerceInt64(schema, values);
-  const children = schema.fields.map((f) => {
-    const val = coerced[f.name];
-    if (val instanceof Data) {
-      return val;
+  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\\-._~]`);
     }
-    const arr = vectorFromArray5([val], f.type);
-    return arr.data[0];
-  });
-  const structType = new Struct5(schema.fields);
-  const data = makeData5({
-    type: structType,
-    length: 1,
-    children,
-    nullCount: 0
-  });
-  return new RecordBatch5(schema, data, metadata);
-}
-function buildErrorBatch(schema, error, serverId, requestId) {
-  const metadata = new Map;
-  metadata.set(LOG_LEVEL_KEY, "EXCEPTION");
-  metadata.set(LOG_MESSAGE_KEY, `${error.constructor.name}: ${error.message}`);
-  const extra = {
-    exception_type: error.constructor.name,
-    exception_message: error.message,
-    traceback: error.stack ?? ""
-  };
-  metadata.set(LOG_EXTRA_KEY, JSON.stringify(extra));
-  metadata.set(SERVER_ID_KEY, serverId);
-  if (requestId !== null) {
-    metadata.set(REQUEST_ID_KEY, requestId);
+    json.device_code_client_secret = metadata.deviceCodeClientSecret;
   }
-  return buildEmptyBatch(schema, metadata);
+  if (metadata.useIdTokenAsBearer) {
+    json.use_id_token_as_bearer = true;
+  }
+  return json;
 }
-function buildLogBatch(schema, level, message, extra, serverId, requestId) {
-  const metadata = new Map;
-  metadata.set(LOG_LEVEL_KEY, level);
-  metadata.set(LOG_MESSAGE_KEY, message);
-  if (extra) {
-    metadata.set(LOG_EXTRA_KEY, JSON.stringify(extra));
+function wellKnownPath(prefix) {
+  return `/.well-known/oauth-protected-resource${prefix}`;
+}
+function buildWwwAuthenticateHeader(metadataUrl, clientId, clientSecret, useIdTokenAsBearer, deviceCodeClientId, deviceCodeClientSecret) {
+  let header = "Bearer";
+  if (metadataUrl) {
+    header += ` resource_metadata="${metadataUrl}"`;
   }
-  if (serverId != null) {
-    metadata.set(SERVER_ID_KEY, serverId);
+  if (clientId) {
+    header += `, client_id="${clientId}"`;
   }
-  if (requestId != null) {
-    metadata.set(REQUEST_ID_KEY, requestId);
+  if (clientSecret) {
+    header += `, client_secret="${clientSecret}"`;
   }
-  return buildEmptyBatch(schema, metadata);
+  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;
 }
-function buildEmptyBatch(schema, metadata) {
-  const children = schema.fields.map((f) => {
-    return makeData5({ type: f.type, length: 0, nullCount: 0 });
-  });
-  if (schema.fields.length === 0) {
-    const structType2 = new Struct5(schema.fields);
-    const data2 = makeData5({
-      type: structType2,
-      length: 0,
-      children: [],
-      nullCount: 0
-    });
-    return new RecordBatch5(schema, data2, metadata);
+// src/http/bearer.ts
+import { timingSafeEqual } from "node:crypto";
+function bearerAuthenticate(options) {
+  const { validate } = options;
+  return async function authenticate(request) {
+    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);
+  };
+}
+function safeEqual(a, b) {
+  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);
+}
+function bearerAuthenticateStatic(options) {
+  const entries = options.tokens instanceof Map ? [...options.tokens.entries()] : Object.entries(options.tokens);
+  function validate(token) {
+    for (const [key, ctx] of entries) {
+      if (safeEqual(token, key))
+        return ctx;
+    }
+    throw new Error("Unknown bearer token");
   }
-  const structType = new Struct5(schema.fields);
-  const data = makeData5({
-    type: structType,
-    length: 0,
-    children,
-    nullCount: 0
-  });
-  return new RecordBatch5(schema, data, metadata);
+  return bearerAuthenticate({ validate });
+}
+function isCredentialError(err) {
+  return err instanceof Error && err.constructor === Error && err.name !== "PermissionError";
+}
+function chainAuthenticate(...authenticators) {
+  if (authenticators.length === 0) {
+    throw new Error("chainAuthenticate requires at least one authenticator");
+  }
+  return async function authenticate(request) {
+    let lastError = 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;
+  };
 }
+// src/http/handler.ts
+import { randomBytes } from "node:crypto";
+import { Schema as Schema5 } from "@query-farm/apache-arrow";
 
 // src/types.ts
+import { RecordBatch as RecordBatch6, recordBatchFromArrays } from "@query-farm/apache-arrow";
 var MethodType;
 ((MethodType2) => {
   MethodType2["UNARY"] = "unary";
@@ -1476,11 +1907,13 @@ class OutputCollector {
   _outputSchema;
   _serverId;
   _requestId;
-  constructor(outputSchema, producerMode = true, serverId = "", requestId = null) {
+  auth;
+  constructor(outputSchema, producerMode = true, serverId = "", requestId = null, authContext) {
     this._outputSchema = outputSchema;
     this._producerMode = producerMode;
     this._serverId = serverId;
     this._requestId = requestId;
+    this.auth = authContext ?? AuthContext.anonymous();
   }
   get outputSchema() {
     return this._outputSchema;
@@ -1528,7 +1961,7 @@ class OutputCollector {
 init_zstd();
 
 // src/http/dispatch.ts
-import { RecordBatch as RecordBatch8, RecordBatchReader as RecordBatchReader5, Schema as Schema4 } from "@query-farm/apache-arrow";
+import { RecordBatch as RecordBatch8, RecordBatchReader as RecordBatchReader6, Schema as Schema4 } from "@query-farm/apache-arrow";
 
 // src/dispatch/describe.ts
 import {
@@ -1544,9 +1977,9 @@ import {
 } from "@query-farm/apache-arrow";
 
 // src/util/schema.ts
-import { RecordBatchStreamWriter as RecordBatchStreamWriter3 } from "@query-farm/apache-arrow";
+import { RecordBatchStreamWriter as RecordBatchStreamWriter4 } from "@query-farm/apache-arrow";
 function serializeSchema(schema) {
-  const writer = new RecordBatchStreamWriter3;
+  const writer = new RecordBatchStreamWriter4;
   writer.reset(undefined, schema);
   writer.close();
   return writer.toUint8Array(true);
@@ -1563,7 +1996,9 @@ var DESCRIBE_SCHEMA = new Schema3([
   new Field3("param_types_json", new Utf82, true),
   new Field3("param_defaults_json", new Utf82, true),
   new Field3("has_header", new Bool2, false),
-  new Field3("header_schema_ipc", new Binary2, true)
+  new Field3("header_schema_ipc", new Binary2, true),
+  new Field3("is_exchange", new Bool2, true),
+  new Field3("param_docs_json", new Utf82, true)
 ]);
 function buildDescribeBatch(protocolName, methods, serverId) {
   const sortedEntries = [...methods.entries()].sort(([a], [b]) => a.localeCompare(b));
@@ -1577,6 +2012,8 @@ function buildDescribeBatch(protocolName, methods, serverId) {
   const paramDefaultsJsons = [];
   const hasHeaders = [];
   const headerSchemas = [];
+  const isExchanges = [];
+  const paramDocsJsons = [];
   for (const [name, method] of sortedEntries) {
     names.push(name);
     methodTypes.push(method.type);
@@ -1603,6 +2040,14 @@ function buildDescribeBatch(protocolName, methods, serverId) {
     }
     hasHeaders.push(!!method.headerSchema);
     headerSchemas.push(method.headerSchema ? serializeSchema(method.headerSchema) : null);
+    if (method.exchangeFn) {
+      isExchanges.push(true);
+    } else if (method.producerFn) {
+      isExchanges.push(false);
+    } else {
+      isExchanges.push(null);
+    }
+    paramDocsJsons.push(null);
   }
   const nameArr = vectorFromArray6(names, new Utf82);
   const methodTypeArr = vectorFromArray6(methodTypes, new Utf82);
@@ -1614,6 +2059,8 @@ function buildDescribeBatch(protocolName, methods, serverId) {
   const paramDefaultsArr = vectorFromArray6(paramDefaultsJsons, new Utf82);
   const hasHeaderArr = vectorFromArray6(hasHeaders, new Bool2);
   const headerSchemaArr = vectorFromArray6(headerSchemas, new Binary2);
+  const isExchangeArr = vectorFromArray6(isExchanges, new Bool2);
+  const paramDocsArr = vectorFromArray6(paramDocsJsons, new Utf82);
   const children = [
     nameArr.data[0],
     methodTypeArr.data[0],
@@ -1624,7 +2071,9 @@ function buildDescribeBatch(protocolName, methods, serverId) {
     paramTypesArr.data[0],
     paramDefaultsArr.data[0],
     hasHeaderArr.data[0],
-    headerSchemaArr.data[0]
+    headerSchemaArr.data[0],
+    isExchangeArr.data[0],
+    paramDocsArr.data[0]
   ];
   const structType = new Struct6(DESCRIBE_SCHEMA.fields);
   const data = makeData6({
@@ -1687,7 +2136,7 @@ function parseRequest(schema, batch) {
 }
 
 // src/http/token.ts
-import { createHmac, timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual as timingSafeEqual2 } from "node:crypto";
 var TOKEN_VERSION = 2;
 var HMAC_LEN = 32;
 var MIN_TOKEN_LEN = 1 + 8 + 12 + HMAC_LEN;
@@ -1724,7 +2173,7 @@ function unpackStateToken(tokenBase64, signingKey, tokenTtl) {
   const payload = token.subarray(0, token.length - HMAC_LEN);
   const receivedMac = token.subarray(token.length - HMAC_LEN);
   const expectedMac = createHmac("sha256", signingKey).update(payload).digest();
-  if (!timingSafeEqual(receivedMac, expectedMac)) {
+  if (!timingSafeEqual2(receivedMac, expectedMac)) {
     throw new Error("State token HMAC verification failed");
   }
   let offset = 0;
@@ -1766,7 +2215,7 @@ function unpackStateToken(tokenBase64, signingKey, tokenTtl) {
 
 // src/http/dispatch.ts
 async function deserializeSchema2(bytes) {
-  const reader = await RecordBatchReader5.from(bytes);
+  const reader = await RecordBatchReader6.from(bytes);
   await reader.open();
   return reader.schema;
 }
@@ -1783,15 +2232,20 @@ async function httpDispatchUnary(method, body, ctx) {
   if (parsed.methodName !== method.name) {
     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) {
     const errBatch = buildErrorBatch(schema, error, ctx.serverId, parsed.requestId);
-    return arrowResponse(serializeIpcStream(schema, [errBatch]), 500);
+    const response = arrowResponse(serializeIpcStream(schema, [errBatch]), 500);
+    response.__dispatchError = error;
+    return response;
   }
 }
 async function httpDispatchStreamInit(method, body, ctx) {
@@ -1813,21 +2267,25 @@ async function httpDispatchStreamInit(method, body, ctx) {
   } catch (error) {
     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.__dispatchError = error;
+    return response;
   }
   const resolvedOutputSchema = state?.__outputSchema ?? outputSchema;
   const effectiveProducer = state?.__isProducer ?? isProducer;
   let headerBytes = 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) {
       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.__dispatchError = error;
+      return response;
     }
   }
   if (effectiveProducer) {
@@ -1888,7 +2346,7 @@ async function httpDispatchStreamExchange(method, body, ctx) {
   if (effectiveProducer) {
     return produceStreamResponse(method, state, outputSchema, inputSchema, ctx, null, null);
   } else {
-    const out = new OutputCollector(outputSchema, effectiveProducer, ctx.serverId, null);
+    const out = new OutputCollector(outputSchema, effectiveProducer, ctx.serverId, null, ctx.authContext);
     const conformedBatch = conformBatchToSchema(reqBatch, inputSchema);
     try {
       if (method.exchangeFn) {
@@ -1902,7 +2360,9 @@ async function httpDispatchStreamExchange(method, body, ctx) {
 `).slice(0, 5).join(`
 `));
       const errBatch = buildErrorBatch(outputSchema, error, ctx.serverId, null);
-      return arrowResponse(serializeIpcStream(outputSchema, [errBatch]), 500);
+      const response = arrowResponse(serializeIpcStream(outputSchema, [errBatch]), 500);
+      response.__dispatchError = error;
+      return response;
     }
     const batches = [];
     if (out.finished) {
@@ -1937,8 +2397,9 @@ async function produceStreamResponse(method, state, outputSchema, inputSchema, c
   const allBatches = [];
   const maxBytes = ctx.maxStreamResponseBytes;
   let estimatedBytes = 0;
+  let producerError;
   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) {
         await method.producerFn(state, out);
@@ -1952,6 +2413,7 @@ async function produceStreamResponse(method, state, outputSchema, inputSchema, c
 `).slice(0, 3).join(`
 `));
       allBatches.push(buildErrorBatch(outputSchema, error, ctx.serverId, requestId));
+      producerError = error instanceof Error ? error : new Error(String(error));
       break;
     }
     for (const emitted of out.batches) {
@@ -1981,7 +2443,11 @@ async function produceStreamResponse(method, state, outputSchema, inputSchema, c
   } else {
     responseBody = dataBytes;
   }
-  return arrowResponse(responseBody);
+  const response = arrowResponse(responseBody);
+  if (producerError) {
+    response.__dispatchError = producerError;
+  }
+  return response;
 }
 function concatBytes(...arrays) {
   const totalLen = arrays.reduce((sum, a) => sum + a.length, 0);
@@ -1994,6 +2460,261 @@ function concatBytes(...arrays) {
   return result;
 }
 
+// src/http/pages.ts
+var LOGO_URL = "https://vgi-rpc-python.query.farm/assets/logo-hero.png";
+var FONTS = `<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet">`;
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function arrowTypeToString(type) {
+  const id = type.typeId;
+  if (id === 5)
+    return "str";
+  if (id === 4)
+    return "bytes";
+  if (id === 2)
+    return "int";
+  if (id === 3)
+    return "float";
+  if (id === 6)
+    return "bool";
+  if (id === 12)
+    return "list";
+  if (id === 17)
+    return "map";
+  if (id === 24)
+    return "enum";
+  return type.toString();
+}
+function buildLandingPage(protocolName, serverId, describePath, repoUrl) {
+  const links = [];
+  if (describePath) {
+    links.push(`<a class="primary" href="${escapeHtml(describePath)}">View service API</a>`);
+  }
+  if (repoUrl) {
+    links.push(`<a href="${escapeHtml(repoUrl)}">Source repository</a>`);
+  }
+  links.push(`<a href="https://vgi-rpc.query.farm">Learn more about <code>vgi-rpc</code></a>`);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(protocolName)} — vgi-rpc</title>
+${FONTS}
+<style>
+body { font-family: 'Inter', system-ui, -apple-system, sans-serif; max-width: 600px;
+       margin: 0 auto; padding: 60px 20px 0; color: #2c2c1e; text-align: center;
+       background: #faf8f0; }
+.logo { margin-bottom: 24px; }
+.logo img { width: 140px; height: 140px; border-radius: 50%;
+             box-shadow: 0 4px 24px rgba(0,0,0,0.12); }
+h1 { color: #2d5016; margin-bottom: 8px; font-weight: 700; }
+code { font-family: 'JetBrains Mono', monospace; background: #f0ece0;
+        padding: 2px 6px; border-radius: 3px; font-size: 0.9em; color: #2c2c1e; }
+a { color: #2d5016; text-decoration: none; }
+a:hover { color: #4a7c23; }
+p { line-height: 1.7; color: #6b6b5a; }
+.meta { font-size: 0.9em; color: #6b6b5a; }
+.links { margin-top: 28px; display: flex; flex-wrap: wrap; justify-content: center; gap: 8px; }
+.links a { display: inline-block; padding: 8px 18px; border-radius: 6px;
+            border: 1px solid #4a7c23; color: #2d5016; font-weight: 600;
+            font-size: 0.9em; transition: all 0.2s ease; }
+.links a:hover { background: #4a7c23; color: #fff; }
+.links a.primary { background: #2d5016; color: #fff; border-color: #2d5016; }
+.links a.primary:hover { background: #4a7c23; border-color: #4a7c23; }
+footer { margin-top: 48px; padding: 20px 0; border-top: 1px solid #f0ece0;
+          color: #6b6b5a; font-size: 0.85em; }
+footer a { color: #2d5016; font-weight: 600; }
+footer a:hover { color: #4a7c23; }
+</style>
+</head>
+<body>
+<div class="logo">
+  <img src="${LOGO_URL}" alt="vgi-rpc logo">
+</div>
+<h1>${escapeHtml(protocolName)}</h1>
+<p class="meta">Powered by <code>vgi-rpc</code> (TypeScript) &middot; server <code>${escapeHtml(serverId)}</code></p>
+<p>This is a <code>vgi-rpc</code> service endpoint.</p>
+<div class="links">
+${links.join(`
+`)}
+</div>
+<footer>
+  &copy; 2026 &#x1F69C; <a href="https://query.farm">Query.Farm LLC</a>
+</footer>
+</body>
+</html>`;
+}
+function buildNotFoundPage(prefix, protocolName) {
+  const nameFragment = protocolName ? ` (<strong>${escapeHtml(protocolName)}</strong>)` : "";
+  const prefixDisplay = prefix || "/";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>404 — vgi-rpc endpoint</title>
+<style>
+body { font-family: system-ui, -apple-system, sans-serif; max-width: 600px;
+       margin: 60px auto; padding: 0 20px; color: #333; text-align: center; }
+.logo { margin-bottom: 24px; }
+.logo img { width: 120px; height: 120px; }
+h1 { color: #555; }
+code { background: #f4f4f4; padding: 2px 6px; border-radius: 3px; font-size: 0.95em; }
+a { color: #0066cc; }
+p { line-height: 1.6; }
+</style>
+</head>
+<body>
+<div class="logo">
+  <img src="${LOGO_URL}" alt="vgi-rpc logo">
+</div>
+<h1>404 — Not Found</h1>
+<p>This is a <code>vgi-rpc</code> service endpoint${nameFragment}.</p>
+<p>RPC methods are available under <code>${escapeHtml(prefixDisplay)}/&lt;method&gt;</code>.</p>
+<p>Learn more at <a href="https://vgi-rpc.query.farm">vgi-rpc.query.farm</a>.</p>
+</body>
+</html>`;
+}
+function buildMethodCard(method) {
+  const name = escapeHtml(method.name);
+  const isUnary = method.type === "unary";
+  const hasHeader = !!method.headerSchema;
+  const badges = [];
+  badges.push(isUnary ? `<span class="badge badge-unary">unary</span>` : `<span class="badge badge-stream">stream</span>`);
+  if (hasHeader)
+    badges.push(`<span class="badge badge-header">header</span>`);
+  let paramsHtml = "";
+  const paramsSchema = method.paramsSchema;
+  if (paramsSchema.fields.length > 0) {
+    const rows = paramsSchema.fields.map((f) => {
+      const paramName = escapeHtml(f.name);
+      const paramType = escapeHtml(arrowTypeToString(f.type));
+      const defaultVal = method.defaults && f.name in method.defaults ? escapeHtml(JSON.stringify(method.defaults[f.name])) : "&mdash;";
+      return `<tr><td><code>${paramName}</code></td><td><code>${paramType}</code></td><td>${defaultVal}</td><td>&mdash;</td></tr>`;
+    });
+    paramsHtml = `<div class="section-label">Parameters</div>
+<table><tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
+${rows.join(`
+`)}
+</table>`;
+  } else {
+    paramsHtml = `<p class="no-params">No parameters</p>`;
+  }
+  let returnsHtml = "";
+  if (isUnary && method.resultSchema.fields.length > 0) {
+    const rows = method.resultSchema.fields.map((f) => {
+      return `<tr><td><code>${escapeHtml(f.name)}</code></td><td><code>${escapeHtml(arrowTypeToString(f.type))}</code></td></tr>`;
+    });
+    returnsHtml = `<div class="section-label">Returns</div>
+<table><tr><th>Name</th><th>Type</th></tr>
+${rows.join(`
+`)}
+</table>`;
+  }
+  let headerHtml = "";
+  if (hasHeader && method.headerSchema && method.headerSchema.fields.length > 0) {
+    const rows = method.headerSchema.fields.map((f) => {
+      return `<tr><td><code>${escapeHtml(f.name)}</code></td><td><code>${escapeHtml(arrowTypeToString(f.type))}</code></td></tr>`;
+    });
+    headerHtml = `<div class="section-label">Stream Header</div>
+<table><tr><th>Name</th><th>Type</th></tr>
+${rows.join(`
+`)}
+</table>`;
+  }
+  const docHtml = method.doc ? `<p class="docstring">${escapeHtml(method.doc)}</p>` : "";
+  return `<div class="card">
+<div class="card-header">
+<span class="method-name">${name}</span>
+${badges.join(`
+`)}
+</div>
+${docHtml}
+${paramsHtml}
+${returnsHtml}
+${headerHtml}
+</div>`;
+}
+function buildDescribePage(protocolName, serverId, methods, repoUrl) {
+  const sortedMethods = [...methods.entries()].filter(([name]) => name !== "__describe__").sort(([a], [b]) => a.localeCompare(b));
+  const cards = sortedMethods.map(([, method]) => buildMethodCard(method)).join(`
+`);
+  const repoLink = repoUrl ? ` &middot; <a href="${escapeHtml(repoUrl)}">Source</a>` : "";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(protocolName)} API Reference — vgi-rpc</title>
+${FONTS}
+<style>
+body { font-family: 'Inter', system-ui, -apple-system, sans-serif; max-width: 900px;
+       margin: 0 auto; padding: 40px 20px 0; color: #2c2c1e; background: #faf8f0; }
+.header { text-align: center; margin-bottom: 40px; }
+.header .logo img { width: 80px; height: 80px; border-radius: 50%;
+                     box-shadow: 0 3px 16px rgba(0,0,0,0.10); }
+.header h1 { margin-bottom: 4px; color: #2d5016; font-weight: 700; }
+.header .subtitle { color: #6b6b5a; font-size: 1.1em; margin-top: 0; }
+.header .meta { color: #6b6b5a; font-size: 0.9em; }
+.header .meta a { color: #2d5016; font-weight: 600; }
+.header .meta a:hover { color: #4a7c23; }
+code { font-family: 'JetBrains Mono', monospace; background: #f0ece0;
+        padding: 2px 6px; border-radius: 3px; font-size: 0.85em; color: #2c2c1e; }
+a { color: #2d5016; text-decoration: none; }
+a:hover { color: #4a7c23; }
+.card { border: 1px solid #f0ece0; border-radius: 8px; padding: 20px;
+         margin-bottom: 16px; background: #fff; }
+.card:hover { border-color: #c8a43a; }
+.card-header { display: flex; align-items: center; gap: 10px; margin-bottom: 12px; }
+.method-name { font-family: 'JetBrains Mono', monospace; font-size: 1.1em; font-weight: 600;
+                color: #2d5016; }
+.badge { display: inline-block; padding: 2px 8px; border-radius: 4px;
+          font-size: 0.75em; font-weight: 600; text-transform: uppercase;
+          letter-spacing: 0.03em; }
+.badge-unary { background: #e8f5e0; color: #2d5016; }
+.badge-stream { background: #e0ecf5; color: #1a4a6b; }
+.badge-exchange { background: #f5e6f0; color: #6b234a; }
+.badge-producer { background: #e0f0f5; color: #1a5a6b; }
+.badge-header { background: #f5eee0; color: #6b4423; }
+.docstring { color: #6b6b5a; font-size: 0.9em; margin-top: 0; }
+table { width: 100%; border-collapse: collapse; font-size: 0.9em; }
+th { text-align: left; padding: 8px 10px; background: #f0ece0; color: #2c2c1e;
+      font-weight: 600; border-bottom: 2px solid #e0dcd0; }
+td { padding: 8px 10px; border-bottom: 1px solid #f0ece0; }
+td code { font-size: 0.85em; }
+.no-params { color: #6b6b5a; font-style: italic; font-size: 0.9em; }
+.section-label { font-size: 0.8em; font-weight: 600; text-transform: uppercase;
+                  letter-spacing: 0.05em; color: #6b6b5a; margin-top: 14px;
+                  margin-bottom: 6px; }
+footer { text-align: center; margin-top: 48px; padding: 20px 0;
+          border-top: 1px solid #f0ece0; color: #6b6b5a; font-size: 0.85em; }
+footer a { color: #2d5016; font-weight: 600; }
+footer a:hover { color: #4a7c23; }
+</style>
+</head>
+<body>
+<div class="header">
+  <div class="logo">
+    <img src="${LOGO_URL}" alt="vgi-rpc logo">
+  </div>
+  <h1>${escapeHtml(protocolName)}</h1>
+  <p class="subtitle">API Reference</p>
+  <p class="meta">Powered by <code>vgi-rpc</code> (TypeScript) &middot; server <code>${escapeHtml(serverId)}</code>${repoLink}</p>
+</div>
+${cards}
+<footer>
+  <a href="https://vgi-rpc.query.farm">Learn more about <code>vgi-rpc</code></a>
+  &middot;
+  &copy; 2026 &#x1F69C; <a href="https://query.farm">Query.Farm LLC</a>
+</footer>
+</body>
+</html>`;
+}
+
 // src/http/types.ts
 var jsonStateSerializer = {
   serialize(state) {
@@ -2007,22 +2728,35 @@ var jsonStateSerializer = {
 // src/http/handler.ts
 var EMPTY_SCHEMA2 = new Schema5([]);
 function createHttpHandler(protocol, options) {
-  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;
   const maxRequestBytes = options?.maxRequestBytes;
   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 = {
+  const dispatchHook = options?.dispatchHook;
+  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;
+  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 baseCtx = {
     signingKey,
     tokenTtl,
     serverId,
     maxStreamResponseBytes,
-    stateSerializer
+    stateSerializer,
+    externalLocation
   };
   function addCorsHeaders(headers) {
     if (corsOrigins) {
@@ -2053,6 +2787,18 @@ function createHttpHandler(protocol, options) {
   return async function handler(request) {
     const url = new URL(request.url);
     const path = url.pathname;
+    if (oauthMetadata && path === wellKnownPath(prefix)) {
+      if (request.method !== "GET") {
+        return new Response("Method Not Allowed", { status: 405 });
+      }
+      const body2 = JSON.stringify(oauthResourceMetadataToJson(oauthMetadata));
+      const headers = new Headers({
+        "Content-Type": "application/json",
+        "Cache-Control": "public, max-age=60"
+      });
+      addCorsHeaders(headers);
+      return new Response(body2, { status: 200, headers });
+    }
     if (request.method === "OPTIONS") {
       if (path === `${prefix}/__capabilities__`) {
         const headers = new Headers;
@@ -2069,6 +2815,24 @@ function createHttpHandler(protocol, options) {
       }
       return new Response(null, { status: 405 });
     }
+    if (request.method === "GET") {
+      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 });
+      }
+      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 });
+      }
+      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 });
     }
@@ -2088,6 +2852,22 @@ function createHttpHandler(protocol, options) {
     if (contentEncoding === "zstd") {
       body = zstdDecompress(body);
     }
+    const ctx = { ...baseCtx };
+    if (authenticate) {
+      try {
+        ctx.authContext = await authenticate(request);
+      } catch (error) {
+        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 });
+      }
+    }
     if (path === `${prefix}/${DESCRIBE_METHOD_NAME}`) {
       try {
         const response = httpDispatchDescribe(protocol.name, methods, serverId);
@@ -2119,6 +2899,18 @@ function createHttpHandler(protocol, options) {
       const err = new Error(`Unknown method: '${methodName}'. Available methods: [${available.join(", ")}]`);
       return compressIfAccepted(makeErrorResponse(err, 404), clientAcceptsZstd);
     }
+    const methodType = method.type === "unary" /* UNARY */ ? "unary" : "stream";
+    const info = { method: methodName, methodType, serverId, requestId: null };
+    const stats = {
+      inputBatches: 0,
+      outputBatches: 0,
+      inputRows: 0,
+      outputRows: 0,
+      inputBytes: 0,
+      outputBytes: 0
+    };
+    const hookToken = dispatchHook?.onDispatchStart(info);
+    let dispatchError;
     try {
       let response;
       if (action === "call") {
@@ -2137,100 +2929,1510 @@ function createHttpHandler(protocol, options) {
         }
         response = await httpDispatchStreamExchange(method, body, ctx);
       }
+      const internalError = response.__dispatchError;
+      if (internalError) {
+        dispatchError = internalError instanceof Error ? internalError : new Error(String(internalError));
+      }
       addCorsHeaders(response.headers);
       return compressIfAccepted(response, clientAcceptsZstd);
     } catch (error) {
+      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);
     }
   };
 }
-// src/protocol.ts
-import { Schema as Schema7 } from "@query-farm/apache-arrow";
-
-// src/schema.ts
-import {
-  Binary as Binary3,
-  Bool as Bool3,
-  DataType as DataType4,
-  Field as Field4,
-  Float32,
-  Float64 as Float642,
-  Int16,
-  Int32,
-  Int64 as Int642,
-  Schema as Schema6,
-  Utf8 as Utf83
-} from "@query-farm/apache-arrow";
-var str = new Utf83;
-var bytes = new Binary3;
-var int = new Int642;
-var int32 = new Int32;
-var float = new Float642;
-var float32 = new Float32;
-var bool = new Bool3;
-function toSchema(spec) {
-  if (spec instanceof Schema6)
-    return spec;
-  const fields = [];
-  for (const [name, value] of Object.entries(spec)) {
-    if (value instanceof Field4) {
-      fields.push(value);
-    } else if (value instanceof DataType4) {
-      fields.push(new Field4(name, value, false));
-    } else {
-      throw new TypeError(`Invalid schema value for "${name}": expected DataType or Field, got ${typeof value}`);
-    }
+// node_modules/oauth4webapi/build/index.js
+var USER_AGENT;
+if (typeof navigator === "undefined" || !navigator.userAgent?.startsWith?.("Mozilla/5.0 ")) {
+  const NAME = "oauth4webapi";
+  const VERSION = "v3.8.5";
+  USER_AGENT = `${NAME}/${VERSION}`;
+}
+function looseInstanceOf(input, expected) {
+  if (input == null) {
+    return false;
+  }
+  try {
+    return input instanceof expected || Object.getPrototypeOf(input)[Symbol.toStringTag] === expected.prototype[Symbol.toStringTag];
+  } catch {
+    return false;
   }
-  return new Schema6(fields);
 }
-var TYPE_MAP = [
-  [Utf83, "str"],
-  [Binary3, "bytes"],
-  [Bool3, "bool"],
-  [Float642, "float"],
-  [Float32, "float"],
-  [Int642, "int"],
-  [Int32, "int"],
-  [Int16, "int"]
-];
-function inferParamTypes(spec) {
-  const schema = toSchema(spec);
-  if (schema.fields.length === 0)
-    return;
-  const result = {};
-  for (const field of schema.fields) {
-    let mapped;
-    for (const [ctor, name] of TYPE_MAP) {
-      if (field.type instanceof ctor) {
-        mapped = name;
-        break;
+var ERR_INVALID_ARG_VALUE = "ERR_INVALID_ARG_VALUE";
+var ERR_INVALID_ARG_TYPE = "ERR_INVALID_ARG_TYPE";
+function CodedTypeError(message, code, cause) {
+  const err = new TypeError(message, { cause });
+  Object.assign(err, { code });
+  return err;
+}
+var allowInsecureRequests = Symbol();
+var clockSkew = Symbol();
+var clockTolerance = Symbol();
+var customFetch = Symbol();
+var modifyAssertion = Symbol();
+var jweDecrypt = Symbol();
+var jwksCache = Symbol();
+var encoder = new TextEncoder;
+var decoder = new TextDecoder;
+function buf(input) {
+  if (typeof input === "string") {
+    return encoder.encode(input);
+  }
+  return decoder.decode(input);
+}
+var encodeBase64Url;
+if (Uint8Array.prototype.toBase64) {
+  encodeBase64Url = (input) => {
+    if (input instanceof ArrayBuffer) {
+      input = new Uint8Array(input);
+    }
+    return input.toBase64({ alphabet: "base64url", omitPadding: true });
+  };
+} else {
+  const CHUNK_SIZE = 32768;
+  encodeBase64Url = (input) => {
+    if (input instanceof ArrayBuffer) {
+      input = new Uint8Array(input);
+    }
+    const arr = [];
+    for (let i = 0;i < input.byteLength; i += CHUNK_SIZE) {
+      arr.push(String.fromCharCode.apply(null, input.subarray(i, i + CHUNK_SIZE)));
+    }
+    return btoa(arr.join("")).replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+  };
+}
+var decodeBase64Url;
+if (Uint8Array.fromBase64) {
+  decodeBase64Url = (input) => {
+    try {
+      return Uint8Array.fromBase64(input, { alphabet: "base64url" });
+    } catch (cause) {
+      throw CodedTypeError("The input to be decoded is not correctly encoded.", ERR_INVALID_ARG_VALUE, cause);
+    }
+  };
+} else {
+  decodeBase64Url = (input) => {
+    try {
+      const binary = atob(input.replace(/-/g, "+").replace(/_/g, "/").replace(/\s/g, ""));
+      const bytes = new Uint8Array(binary.length);
+      for (let i = 0;i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
       }
+      return bytes;
+    } catch (cause) {
+      throw CodedTypeError("The input to be decoded is not correctly encoded.", ERR_INVALID_ARG_VALUE, cause);
     }
-    if (!mapped)
-      return;
-    result[field.name] = mapped;
+  };
+}
+function b64u(input) {
+  if (typeof input === "string") {
+    return decodeBase64Url(input);
   }
-  return result;
+  return encodeBase64Url(input);
 }
 
-// src/protocol.ts
-var EMPTY_SCHEMA3 = new Schema7([]);
+class UnsupportedOperationError extends Error {
+  code;
+  constructor(message, options) {
+    super(message, options);
+    this.name = this.constructor.name;
+    this.code = UNSUPPORTED_OPERATION;
+    Error.captureStackTrace?.(this, this.constructor);
+  }
+}
 
-class Protocol {
-  name;
-  _methods = new Map;
-  constructor(name) {
-    this.name = name;
+class OperationProcessingError extends Error {
+  code;
+  constructor(message, options) {
+    super(message, options);
+    this.name = this.constructor.name;
+    if (options?.code) {
+      this.code = options?.code;
+    }
+    Error.captureStackTrace?.(this, this.constructor);
   }
-  unary(name, config) {
-    const params = toSchema(config.params);
-    this._methods.set(name, {
-      name,
-      type: "unary" /* UNARY */,
-      paramsSchema: params,
+}
+function OPE(message, code, cause) {
+  return new OperationProcessingError(message, { code, cause });
+}
+async function calculateJwkThumbprint(jwk) {
+  let components;
+  switch (jwk.kty) {
+    case "EC":
+      components = {
+        crv: jwk.crv,
+        kty: jwk.kty,
+        x: jwk.x,
+        y: jwk.y
+      };
+      break;
+    case "OKP":
+      components = {
+        crv: jwk.crv,
+        kty: jwk.kty,
+        x: jwk.x
+      };
+      break;
+    case "AKP":
+      components = {
+        alg: jwk.alg,
+        kty: jwk.kty,
+        pub: jwk.pub
+      };
+      break;
+    case "RSA":
+      components = {
+        e: jwk.e,
+        kty: jwk.kty,
+        n: jwk.n
+      };
+      break;
+    default:
+      throw new UnsupportedOperationError("unsupported JWK key type", { cause: jwk });
+  }
+  return b64u(await crypto.subtle.digest("SHA-256", buf(JSON.stringify(components))));
+}
+function assertCryptoKey(key, it) {
+  if (!(key instanceof CryptoKey)) {
+    throw CodedTypeError(`${it} must be a CryptoKey`, ERR_INVALID_ARG_TYPE);
+  }
+}
+function assertPrivateKey(key, it) {
+  assertCryptoKey(key, it);
+  if (key.type !== "private") {
+    throw CodedTypeError(`${it} must be a private CryptoKey`, ERR_INVALID_ARG_VALUE);
+  }
+}
+function assertPublicKey(key, it) {
+  assertCryptoKey(key, it);
+  if (key.type !== "public") {
+    throw CodedTypeError(`${it} must be a public CryptoKey`, ERR_INVALID_ARG_VALUE);
+  }
+}
+function normalizeTyp(value) {
+  return value.toLowerCase().replace(/^application\//, "");
+}
+function isJsonObject(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    return false;
+  }
+  return true;
+}
+function prepareHeaders(input) {
+  if (looseInstanceOf(input, Headers)) {
+    input = Object.fromEntries(input.entries());
+  }
+  const headers = new Headers(input ?? {});
+  if (USER_AGENT && !headers.has("user-agent")) {
+    headers.set("user-agent", USER_AGENT);
+  }
+  if (headers.has("authorization")) {
+    throw CodedTypeError('"options.headers" must not include the "authorization" header name', ERR_INVALID_ARG_VALUE);
+  }
+  return headers;
+}
+function signal(url, value) {
+  if (value !== undefined) {
+    if (typeof value === "function") {
+      value = value(url.href);
+    }
+    if (!(value instanceof AbortSignal)) {
+      throw CodedTypeError('"options.signal" must return or be an instance of AbortSignal', ERR_INVALID_ARG_TYPE);
+    }
+    return value;
+  }
+  return;
+}
+function replaceDoubleSlash(pathname) {
+  if (pathname.includes("//")) {
+    return pathname.replace("//", "/");
+  }
+  return pathname;
+}
+function prependWellKnown(url, wellKnown, allowTerminatingSlash = false) {
+  if (url.pathname === "/") {
+    url.pathname = wellKnown;
+  } else {
+    url.pathname = replaceDoubleSlash(`${wellKnown}/${allowTerminatingSlash ? url.pathname : url.pathname.replace(/(\/)$/, "")}`);
+  }
+  return url;
+}
+function appendWellKnown(url, wellKnown) {
+  url.pathname = replaceDoubleSlash(`${url.pathname}/${wellKnown}`);
+  return url;
+}
+async function performDiscovery(input, urlName, transform, options) {
+  if (!(input instanceof URL)) {
+    throw CodedTypeError(`"${urlName}" must be an instance of URL`, ERR_INVALID_ARG_TYPE);
+  }
+  checkProtocol(input, options?.[allowInsecureRequests] !== true);
+  const url = transform(new URL(input.href));
+  const headers = prepareHeaders(options?.headers);
+  headers.set("accept", "application/json");
+  return (options?.[customFetch] || fetch)(url.href, {
+    body: undefined,
+    headers: Object.fromEntries(headers.entries()),
+    method: "GET",
+    redirect: "manual",
+    signal: signal(url, options?.signal)
+  });
+}
+async function discoveryRequest(issuerIdentifier, options) {
+  return performDiscovery(issuerIdentifier, "issuerIdentifier", (url) => {
+    switch (options?.algorithm) {
+      case undefined:
+      case "oidc":
+        appendWellKnown(url, ".well-known/openid-configuration");
+        break;
+      case "oauth2":
+        prependWellKnown(url, ".well-known/oauth-authorization-server");
+        break;
+      default:
+        throw CodedTypeError('"options.algorithm" must be "oidc" (default), or "oauth2"', ERR_INVALID_ARG_VALUE);
+    }
+    return url;
+  }, options);
+}
+function assertString(input, it, code, cause) {
+  try {
+    if (typeof input !== "string") {
+      throw CodedTypeError(`${it} must be a string`, ERR_INVALID_ARG_TYPE, cause);
+    }
+    if (input.length === 0) {
+      throw CodedTypeError(`${it} must not be empty`, ERR_INVALID_ARG_VALUE, cause);
+    }
+  } catch (err) {
+    if (code) {
+      throw OPE(err.message, code, cause);
+    }
+    throw err;
+  }
+}
+async function processDiscoveryResponse(expectedIssuerIdentifier, response) {
+  const expected = expectedIssuerIdentifier;
+  if (!(expected instanceof URL) && expected !== _nodiscoverycheck) {
+    throw CodedTypeError('"expectedIssuerIdentifier" must be an instance of URL', ERR_INVALID_ARG_TYPE);
+  }
+  if (!looseInstanceOf(response, Response)) {
+    throw CodedTypeError('"response" must be an instance of Response', ERR_INVALID_ARG_TYPE);
+  }
+  if (response.status !== 200) {
+    throw OPE('"response" is not a conform Authorization Server Metadata response (unexpected HTTP status code)', RESPONSE_IS_NOT_CONFORM, response);
+  }
+  assertReadableResponse(response);
+  const json = await getResponseJsonBody(response);
+  assertString(json.issuer, '"response" body "issuer" property', INVALID_RESPONSE, { body: json });
+  if (expected !== _nodiscoverycheck && new URL(json.issuer).href !== expected.href) {
+    throw OPE('"response" body "issuer" property does not match the expected value', JSON_ATTRIBUTE_COMPARISON, { expected: expected.href, body: json, attribute: "issuer" });
+  }
+  return json;
+}
+function assertApplicationJson(response) {
+  assertContentType(response, "application/json");
+}
+function notJson(response, ...types) {
+  let msg = '"response" content-type must be ';
+  if (types.length > 2) {
+    const last = types.pop();
+    msg += `${types.join(", ")}, or ${last}`;
+  } else if (types.length === 2) {
+    msg += `${types[0]} or ${types[1]}`;
+  } else {
+    msg += types[0];
+  }
+  return OPE(msg, RESPONSE_IS_NOT_JSON, response);
+}
+function assertContentTypes(response, ...types) {
+  if (!types.includes(getContentType(response))) {
+    throw notJson(response, ...types);
+  }
+}
+function assertContentType(response, contentType) {
+  if (getContentType(response) !== contentType) {
+    throw notJson(response, contentType);
+  }
+}
+function randomBytes2() {
+  return b64u(crypto.getRandomValues(new Uint8Array(32)));
+}
+function psAlg(key) {
+  switch (key.algorithm.hash.name) {
+    case "SHA-256":
+      return "PS256";
+    case "SHA-384":
+      return "PS384";
+    case "SHA-512":
+      return "PS512";
+    default:
+      throw new UnsupportedOperationError("unsupported RsaHashedKeyAlgorithm hash name", {
+        cause: key
+      });
+  }
+}
+function rsAlg(key) {
+  switch (key.algorithm.hash.name) {
+    case "SHA-256":
+      return "RS256";
+    case "SHA-384":
+      return "RS384";
+    case "SHA-512":
+      return "RS512";
+    default:
+      throw new UnsupportedOperationError("unsupported RsaHashedKeyAlgorithm hash name", {
+        cause: key
+      });
+  }
+}
+function esAlg(key) {
+  switch (key.algorithm.namedCurve) {
+    case "P-256":
+      return "ES256";
+    case "P-384":
+      return "ES384";
+    case "P-521":
+      return "ES512";
+    default:
+      throw new UnsupportedOperationError("unsupported EcKeyAlgorithm namedCurve", { cause: key });
+  }
+}
+function keyToJws(key) {
+  switch (key.algorithm.name) {
+    case "RSA-PSS":
+      return psAlg(key);
+    case "RSASSA-PKCS1-v1_5":
+      return rsAlg(key);
+    case "ECDSA":
+      return esAlg(key);
+    case "Ed25519":
+    case "ML-DSA-44":
+    case "ML-DSA-65":
+    case "ML-DSA-87":
+      return key.algorithm.name;
+    case "EdDSA":
+      return "Ed25519";
+    default:
+      throw new UnsupportedOperationError("unsupported CryptoKey algorithm name", { cause: key });
+  }
+}
+function getClockSkew(client) {
+  const skew = client?.[clockSkew];
+  return typeof skew === "number" && Number.isFinite(skew) ? skew : 0;
+}
+function getClockTolerance(client) {
+  const tolerance = client?.[clockTolerance];
+  return typeof tolerance === "number" && Number.isFinite(tolerance) && Math.sign(tolerance) !== -1 ? tolerance : 30;
+}
+function epochTime() {
+  return Math.floor(Date.now() / 1000);
+}
+function assertAs(as) {
+  if (typeof as !== "object" || as === null) {
+    throw CodedTypeError('"as" must be an object', ERR_INVALID_ARG_TYPE);
+  }
+  assertString(as.issuer, '"as.issuer"');
+}
+async function signJwt(header, payload, key) {
+  if (!key.usages.includes("sign")) {
+    throw CodedTypeError('CryptoKey instances used for signing assertions must include "sign" in their "usages"', ERR_INVALID_ARG_VALUE);
+  }
+  const input = `${b64u(buf(JSON.stringify(header)))}.${b64u(buf(JSON.stringify(payload)))}`;
+  const signature = b64u(await crypto.subtle.sign(keyToSubtle(key), key, buf(input)));
+  return `${input}.${signature}`;
+}
+var jwkCache;
+async function getSetPublicJwkCache(key, alg) {
+  const { kty, e, n, x, y, crv, pub } = await crypto.subtle.exportKey("jwk", key);
+  const jwk = { kty, e, n, x, y, crv, pub };
+  if (kty === "AKP")
+    jwk.alg = alg;
+  jwkCache.set(key, jwk);
+  return jwk;
+}
+async function publicJwk(key, alg) {
+  jwkCache ||= new WeakMap;
+  return jwkCache.get(key) || getSetPublicJwkCache(key, alg);
+}
+var URLParse = URL.parse ? (url, base) => URL.parse(url, base) : (url, base) => {
+  try {
+    return new URL(url, base);
+  } catch {
+    return null;
+  }
+};
+function checkProtocol(url, enforceHttps) {
+  if (enforceHttps && url.protocol !== "https:") {
+    throw OPE("only requests to HTTPS are allowed", HTTP_REQUEST_FORBIDDEN, url);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw OPE("only HTTP and HTTPS requests are allowed", REQUEST_PROTOCOL_FORBIDDEN, url);
+  }
+}
+function validateEndpoint(value, endpoint, useMtlsAlias, enforceHttps) {
+  let url;
+  if (typeof value !== "string" || !(url = URLParse(value))) {
+    throw OPE(`authorization server metadata does not contain a valid ${useMtlsAlias ? `"as.mtls_endpoint_aliases.${endpoint}"` : `"as.${endpoint}"`}`, value === undefined ? MISSING_SERVER_METADATA : INVALID_SERVER_METADATA, { attribute: useMtlsAlias ? `mtls_endpoint_aliases.${endpoint}` : endpoint });
+  }
+  checkProtocol(url, enforceHttps);
+  return url;
+}
+function resolveEndpoint(as, endpoint, useMtlsAlias, enforceHttps) {
+  if (useMtlsAlias && as.mtls_endpoint_aliases && endpoint in as.mtls_endpoint_aliases) {
+    return validateEndpoint(as.mtls_endpoint_aliases[endpoint], endpoint, useMtlsAlias, enforceHttps);
+  }
+  return validateEndpoint(as[endpoint], endpoint, useMtlsAlias, enforceHttps);
+}
+class DPoPHandler {
+  #header;
+  #privateKey;
+  #publicKey;
+  #clockSkew;
+  #modifyAssertion;
+  #map;
+  #jkt;
+  constructor(client, keyPair, options) {
+    assertPrivateKey(keyPair?.privateKey, '"DPoP.privateKey"');
+    assertPublicKey(keyPair?.publicKey, '"DPoP.publicKey"');
+    if (!keyPair.publicKey.extractable) {
+      throw CodedTypeError('"DPoP.publicKey.extractable" must be true', ERR_INVALID_ARG_VALUE);
+    }
+    this.#modifyAssertion = options?.[modifyAssertion];
+    this.#clockSkew = getClockSkew(client);
+    this.#privateKey = keyPair.privateKey;
+    this.#publicKey = keyPair.publicKey;
+    branded.add(this);
+  }
+  #get(key) {
+    this.#map ||= new Map;
+    let item = this.#map.get(key);
+    if (item) {
+      this.#map.delete(key);
+      this.#map.set(key, item);
+    }
+    return item;
+  }
+  #set(key, val) {
+    this.#map ||= new Map;
+    this.#map.delete(key);
+    if (this.#map.size === 100) {
+      this.#map.delete(this.#map.keys().next().value);
+    }
+    this.#map.set(key, val);
+  }
+  async calculateThumbprint() {
+    if (!this.#jkt) {
+      const jwk = await crypto.subtle.exportKey("jwk", this.#publicKey);
+      this.#jkt ||= await calculateJwkThumbprint(jwk);
+    }
+    return this.#jkt;
+  }
+  async addProof(url, headers, htm, accessToken) {
+    const alg = keyToJws(this.#privateKey);
+    this.#header ||= {
+      alg,
+      typ: "dpop+jwt",
+      jwk: await publicJwk(this.#publicKey, alg)
+    };
+    const nonce = this.#get(url.origin);
+    const now = epochTime() + this.#clockSkew;
+    const payload = {
+      iat: now,
+      jti: randomBytes2(),
+      htm,
+      nonce,
+      htu: `${url.origin}${url.pathname}`,
+      ath: accessToken ? b64u(await crypto.subtle.digest("SHA-256", buf(accessToken))) : undefined
+    };
+    this.#modifyAssertion?.(this.#header, payload);
+    headers.set("dpop", await signJwt(this.#header, payload, this.#privateKey));
+  }
+  cacheNonce(response, url) {
+    try {
+      const nonce = response.headers.get("dpop-nonce");
+      if (nonce) {
+        this.#set(url.origin, nonce);
+      }
+    } catch {}
+  }
+}
+var tokenMatch = "[a-zA-Z0-9!#$%&\\'\\*\\+\\-\\.\\^_`\\|~]+";
+var token68Match = "[a-zA-Z0-9\\-\\._\\~\\+\\/]+={0,2}";
+var quotedMatch = '"((?:[^"\\\\]|\\\\[\\s\\S])*)"';
+var quotedParamMatcher = "(" + tokenMatch + ")\\s*=\\s*" + quotedMatch;
+var paramMatcher = "(" + tokenMatch + ")\\s*=\\s*(" + tokenMatch + ")";
+var schemeRE = new RegExp("^[,\\s]*(" + tokenMatch + ")");
+var quotedParamRE = new RegExp("^[,\\s]*" + quotedParamMatcher + "[,\\s]*(.*)");
+var unquotedParamRE = new RegExp("^[,\\s]*" + paramMatcher + "[,\\s]*(.*)");
+var token68ParamRE = new RegExp("^(" + token68Match + ")(?:$|[,\\s])(.*)");
+var jwksMap;
+function setJwksCache(as, jwks, uat, cache) {
+  jwksMap ||= new WeakMap;
+  jwksMap.set(as, {
+    jwks,
+    uat,
+    get age() {
+      return epochTime() - this.uat;
+    }
+  });
+  if (cache) {
+    Object.assign(cache, { jwks: structuredClone(jwks), uat });
+  }
+}
+function isFreshJwksCache(input) {
+  if (typeof input !== "object" || input === null) {
+    return false;
+  }
+  if (!("uat" in input) || typeof input.uat !== "number" || epochTime() - input.uat >= 300) {
+    return false;
+  }
+  if (!("jwks" in input) || !isJsonObject(input.jwks) || !Array.isArray(input.jwks.keys) || !Array.prototype.every.call(input.jwks.keys, isJsonObject)) {
+    return false;
+  }
+  return true;
+}
+function clearJwksCache(as, cache) {
+  jwksMap?.delete(as);
+  delete cache?.jwks;
+  delete cache?.uat;
+}
+async function getPublicSigKeyFromIssuerJwksUri(as, options, header) {
+  const { alg, kid } = header;
+  checkSupportedJwsAlg(header);
+  if (!jwksMap?.has(as) && isFreshJwksCache(options?.[jwksCache])) {
+    setJwksCache(as, options?.[jwksCache].jwks, options?.[jwksCache].uat);
+  }
+  let jwks;
+  let age;
+  if (jwksMap?.has(as)) {
+    ({ jwks, age } = jwksMap.get(as));
+    if (age >= 300) {
+      clearJwksCache(as, options?.[jwksCache]);
+      return getPublicSigKeyFromIssuerJwksUri(as, options, header);
+    }
+  } else {
+    jwks = await jwksRequest(as, options).then(processJwksResponse);
+    age = 0;
+    setJwksCache(as, jwks, epochTime(), options?.[jwksCache]);
+  }
+  let kty;
+  switch (alg.slice(0, 2)) {
+    case "RS":
+    case "PS":
+      kty = "RSA";
+      break;
+    case "ES":
+      kty = "EC";
+      break;
+    case "Ed":
+      kty = "OKP";
+      break;
+    case "ML":
+      kty = "AKP";
+      break;
+    default:
+      throw new UnsupportedOperationError("unsupported JWS algorithm", { cause: { alg } });
+  }
+  const candidates = jwks.keys.filter((jwk2) => {
+    if (jwk2.kty !== kty) {
+      return false;
+    }
+    if (kid !== undefined && kid !== jwk2.kid) {
+      return false;
+    }
+    if (jwk2.alg !== undefined && alg !== jwk2.alg) {
+      return false;
+    }
+    if (jwk2.use !== undefined && jwk2.use !== "sig") {
+      return false;
+    }
+    if (jwk2.key_ops?.includes("verify") === false) {
+      return false;
+    }
+    switch (true) {
+      case (alg === "ES256" && jwk2.crv !== "P-256"):
+      case (alg === "ES384" && jwk2.crv !== "P-384"):
+      case (alg === "ES512" && jwk2.crv !== "P-521"):
+      case (alg === "Ed25519" && jwk2.crv !== "Ed25519"):
+      case (alg === "EdDSA" && jwk2.crv !== "Ed25519"):
+        return false;
+    }
+    return true;
+  });
+  const { 0: jwk, length } = candidates;
+  if (!length) {
+    if (age >= 60) {
+      clearJwksCache(as, options?.[jwksCache]);
+      return getPublicSigKeyFromIssuerJwksUri(as, options, header);
+    }
+    throw OPE("error when selecting a JWT verification key, no applicable keys found", KEY_SELECTION, { header, candidates, jwks_uri: new URL(as.jwks_uri) });
+  }
+  if (length !== 1) {
+    throw OPE('error when selecting a JWT verification key, multiple applicable keys found, a "kid" JWT Header Parameter is required', KEY_SELECTION, { header, candidates, jwks_uri: new URL(as.jwks_uri) });
+  }
+  return importJwk(alg, jwk);
+}
+var skipSubjectCheck = Symbol();
+function getContentType(input) {
+  return input.headers.get("content-type")?.split(";")[0];
+}
+var idTokenClaims = new WeakMap;
+var jwtRefs = new WeakMap;
+function validateAudience(expected, result) {
+  if (Array.isArray(result.claims.aud)) {
+    if (!result.claims.aud.includes(expected)) {
+      throw OPE('unexpected JWT "aud" (audience) claim value', JWT_CLAIM_COMPARISON, {
+        expected,
+        claims: result.claims,
+        claim: "aud"
+      });
+    }
+  } else if (result.claims.aud !== expected) {
+    throw OPE('unexpected JWT "aud" (audience) claim value', JWT_CLAIM_COMPARISON, {
+      expected,
+      claims: result.claims,
+      claim: "aud"
+    });
+  }
+  return result;
+}
+function validateIssuer(as, result) {
+  const expected = as[_expectedIssuer]?.(result) ?? as.issuer;
+  if (result.claims.iss !== expected) {
+    throw OPE('unexpected JWT "iss" (issuer) claim value', JWT_CLAIM_COMPARISON, {
+      expected,
+      claims: result.claims,
+      claim: "iss"
+    });
+  }
+  return result;
+}
+var branded = new WeakSet;
+var nopkce = Symbol();
+var jwtClaimNames = {
+  aud: "audience",
+  c_hash: "code hash",
+  client_id: "client id",
+  exp: "expiration time",
+  iat: "issued at",
+  iss: "issuer",
+  jti: "jwt id",
+  nonce: "nonce",
+  s_hash: "state hash",
+  sub: "subject",
+  ath: "access token hash",
+  htm: "http method",
+  htu: "http uri",
+  cnf: "confirmation",
+  auth_time: "authentication time"
+};
+function validatePresence(required, result) {
+  for (const claim of required) {
+    if (result.claims[claim] === undefined) {
+      throw OPE(`JWT "${claim}" (${jwtClaimNames[claim]}) claim missing`, INVALID_RESPONSE, {
+        claims: result.claims
+      });
+    }
+  }
+  return result;
+}
+var expectNoNonce = Symbol();
+var skipAuthTimeCheck = Symbol();
+var UNSUPPORTED_OPERATION = "OAUTH_UNSUPPORTED_OPERATION";
+var PARSE_ERROR = "OAUTH_PARSE_ERROR";
+var INVALID_RESPONSE = "OAUTH_INVALID_RESPONSE";
+var INVALID_REQUEST = "OAUTH_INVALID_REQUEST";
+var RESPONSE_IS_NOT_JSON = "OAUTH_RESPONSE_IS_NOT_JSON";
+var RESPONSE_IS_NOT_CONFORM = "OAUTH_RESPONSE_IS_NOT_CONFORM";
+var HTTP_REQUEST_FORBIDDEN = "OAUTH_HTTP_REQUEST_FORBIDDEN";
+var REQUEST_PROTOCOL_FORBIDDEN = "OAUTH_REQUEST_PROTOCOL_FORBIDDEN";
+var JWT_TIMESTAMP_CHECK = "OAUTH_JWT_TIMESTAMP_CHECK_FAILED";
+var JWT_CLAIM_COMPARISON = "OAUTH_JWT_CLAIM_COMPARISON_FAILED";
+var JSON_ATTRIBUTE_COMPARISON = "OAUTH_JSON_ATTRIBUTE_COMPARISON_FAILED";
+var KEY_SELECTION = "OAUTH_KEY_SELECTION_FAILED";
+var MISSING_SERVER_METADATA = "OAUTH_MISSING_SERVER_METADATA";
+var INVALID_SERVER_METADATA = "OAUTH_INVALID_SERVER_METADATA";
+function checkJwtType(expected, result) {
+  if (typeof result.header.typ !== "string" || normalizeTyp(result.header.typ) !== expected) {
+    throw OPE('unexpected JWT "typ" header parameter value', INVALID_RESPONSE, {
+      header: result.header
+    });
+  }
+  return result;
+}
+function assertReadableResponse(response) {
+  if (response.bodyUsed) {
+    throw CodedTypeError('"response" body has been used already', ERR_INVALID_ARG_VALUE);
+  }
+}
+async function jwksRequest(as, options) {
+  assertAs(as);
+  const url = resolveEndpoint(as, "jwks_uri", false, options?.[allowInsecureRequests] !== true);
+  const headers = prepareHeaders(options?.headers);
+  headers.set("accept", "application/json");
+  headers.append("accept", "application/jwk-set+json");
+  return (options?.[customFetch] || fetch)(url.href, {
+    body: undefined,
+    headers: Object.fromEntries(headers.entries()),
+    method: "GET",
+    redirect: "manual",
+    signal: signal(url, options?.signal)
+  });
+}
+async function processJwksResponse(response) {
+  if (!looseInstanceOf(response, Response)) {
+    throw CodedTypeError('"response" must be an instance of Response', ERR_INVALID_ARG_TYPE);
+  }
+  if (response.status !== 200) {
+    throw OPE('"response" is not a conform JSON Web Key Set response (unexpected HTTP status code)', RESPONSE_IS_NOT_CONFORM, response);
+  }
+  assertReadableResponse(response);
+  const json = await getResponseJsonBody(response, (response2) => assertContentTypes(response2, "application/json", "application/jwk-set+json"));
+  if (!Array.isArray(json.keys)) {
+    throw OPE('"response" body "keys" property must be an array', INVALID_RESPONSE, { body: json });
+  }
+  if (!Array.prototype.every.call(json.keys, isJsonObject)) {
+    throw OPE('"response" body "keys" property members must be JWK formatted objects', INVALID_RESPONSE, { body: json });
+  }
+  return json;
+}
+function supported(alg) {
+  switch (alg) {
+    case "PS256":
+    case "ES256":
+    case "RS256":
+    case "PS384":
+    case "ES384":
+    case "RS384":
+    case "PS512":
+    case "ES512":
+    case "RS512":
+    case "Ed25519":
+    case "EdDSA":
+    case "ML-DSA-44":
+    case "ML-DSA-65":
+    case "ML-DSA-87":
+      return true;
+    default:
+      return false;
+  }
+}
+function checkSupportedJwsAlg(header) {
+  if (!supported(header.alg)) {
+    throw new UnsupportedOperationError('unsupported JWS "alg" identifier', {
+      cause: { alg: header.alg }
+    });
+  }
+}
+function checkRsaKeyAlgorithm(key) {
+  const { algorithm } = key;
+  if (typeof algorithm.modulusLength !== "number" || algorithm.modulusLength < 2048) {
+    throw new UnsupportedOperationError(`unsupported ${algorithm.name} modulusLength`, {
+      cause: key
+    });
+  }
+}
+function ecdsaHashName(key) {
+  const { algorithm } = key;
+  switch (algorithm.namedCurve) {
+    case "P-256":
+      return "SHA-256";
+    case "P-384":
+      return "SHA-384";
+    case "P-521":
+      return "SHA-512";
+    default:
+      throw new UnsupportedOperationError("unsupported ECDSA namedCurve", { cause: key });
+  }
+}
+function keyToSubtle(key) {
+  switch (key.algorithm.name) {
+    case "ECDSA":
+      return {
+        name: key.algorithm.name,
+        hash: ecdsaHashName(key)
+      };
+    case "RSA-PSS": {
+      checkRsaKeyAlgorithm(key);
+      switch (key.algorithm.hash.name) {
+        case "SHA-256":
+        case "SHA-384":
+        case "SHA-512":
+          return {
+            name: key.algorithm.name,
+            saltLength: parseInt(key.algorithm.hash.name.slice(-3), 10) >> 3
+          };
+        default:
+          throw new UnsupportedOperationError("unsupported RSA-PSS hash name", { cause: key });
+      }
+    }
+    case "RSASSA-PKCS1-v1_5":
+      checkRsaKeyAlgorithm(key);
+      return key.algorithm.name;
+    case "ML-DSA-44":
+    case "ML-DSA-65":
+    case "ML-DSA-87":
+    case "Ed25519":
+      return key.algorithm.name;
+  }
+  throw new UnsupportedOperationError("unsupported CryptoKey algorithm name", { cause: key });
+}
+async function validateJwsSignature(protectedHeader, payload, key, signature) {
+  const data = buf(`${protectedHeader}.${payload}`);
+  const algorithm = keyToSubtle(key);
+  const verified = await crypto.subtle.verify(algorithm, key, signature, data);
+  if (!verified) {
+    throw OPE("JWT signature verification failed", INVALID_RESPONSE, {
+      key,
+      data,
+      signature,
+      algorithm
+    });
+  }
+}
+async function validateJwt(jws, checkAlg, clockSkew2, clockTolerance2, decryptJwt) {
+  let { 0: protectedHeader, 1: payload, length } = jws.split(".");
+  if (length === 5) {
+    if (decryptJwt !== undefined) {
+      jws = await decryptJwt(jws);
+      ({ 0: protectedHeader, 1: payload, length } = jws.split("."));
+    } else {
+      throw new UnsupportedOperationError("JWE decryption is not configured", { cause: jws });
+    }
+  }
+  if (length !== 3) {
+    throw OPE("Invalid JWT", INVALID_RESPONSE, jws);
+  }
+  let header;
+  try {
+    header = JSON.parse(buf(b64u(protectedHeader)));
+  } catch (cause) {
+    throw OPE("failed to parse JWT Header body as base64url encoded JSON", PARSE_ERROR, cause);
+  }
+  if (!isJsonObject(header)) {
+    throw OPE("JWT Header must be a top level object", INVALID_RESPONSE, jws);
+  }
+  checkAlg(header);
+  if (header.crit !== undefined) {
+    throw new UnsupportedOperationError('no JWT "crit" header parameter extensions are supported', {
+      cause: { header }
+    });
+  }
+  let claims;
+  try {
+    claims = JSON.parse(buf(b64u(payload)));
+  } catch (cause) {
+    throw OPE("failed to parse JWT Payload body as base64url encoded JSON", PARSE_ERROR, cause);
+  }
+  if (!isJsonObject(claims)) {
+    throw OPE("JWT Payload must be a top level object", INVALID_RESPONSE, jws);
+  }
+  const now = epochTime() + clockSkew2;
+  if (claims.exp !== undefined) {
+    if (typeof claims.exp !== "number") {
+      throw OPE('unexpected JWT "exp" (expiration time) claim type', INVALID_RESPONSE, { claims });
+    }
+    if (claims.exp <= now - clockTolerance2) {
+      throw OPE('unexpected JWT "exp" (expiration time) claim value, expiration is past current timestamp', JWT_TIMESTAMP_CHECK, { claims, now, tolerance: clockTolerance2, claim: "exp" });
+    }
+  }
+  if (claims.iat !== undefined) {
+    if (typeof claims.iat !== "number") {
+      throw OPE('unexpected JWT "iat" (issued at) claim type', INVALID_RESPONSE, { claims });
+    }
+  }
+  if (claims.iss !== undefined) {
+    if (typeof claims.iss !== "string") {
+      throw OPE('unexpected JWT "iss" (issuer) claim type', INVALID_RESPONSE, { claims });
+    }
+  }
+  if (claims.nbf !== undefined) {
+    if (typeof claims.nbf !== "number") {
+      throw OPE('unexpected JWT "nbf" (not before) claim type', INVALID_RESPONSE, { claims });
+    }
+    if (claims.nbf > now + clockTolerance2) {
+      throw OPE('unexpected JWT "nbf" (not before) claim value', JWT_TIMESTAMP_CHECK, {
+        claims,
+        now,
+        tolerance: clockTolerance2,
+        claim: "nbf"
+      });
+    }
+  }
+  if (claims.aud !== undefined) {
+    if (typeof claims.aud !== "string" && !Array.isArray(claims.aud)) {
+      throw OPE('unexpected JWT "aud" (audience) claim type', INVALID_RESPONSE, { claims });
+    }
+  }
+  return { header, claims, jwt: jws };
+}
+function checkSigningAlgorithm(client, issuer, fallback, header) {
+  if (client !== undefined) {
+    if (typeof client === "string" ? header.alg !== client : !client.includes(header.alg)) {
+      throw OPE('unexpected JWT "alg" header parameter', INVALID_RESPONSE, {
+        header,
+        expected: client,
+        reason: "client configuration"
+      });
+    }
+    return;
+  }
+  if (Array.isArray(issuer)) {
+    if (!issuer.includes(header.alg)) {
+      throw OPE('unexpected JWT "alg" header parameter', INVALID_RESPONSE, {
+        header,
+        expected: issuer,
+        reason: "authorization server metadata"
+      });
+    }
+    return;
+  }
+  if (fallback !== undefined) {
+    if (typeof fallback === "string" ? header.alg !== fallback : typeof fallback === "function" ? !fallback(header.alg) : !fallback.includes(header.alg)) {
+      throw OPE('unexpected JWT "alg" header parameter', INVALID_RESPONSE, {
+        header,
+        expected: fallback,
+        reason: "default value"
+      });
+    }
+    return;
+  }
+  throw OPE('missing client or server configuration to verify used JWT "alg" header parameter', undefined, { client, issuer, fallback });
+}
+var skipStateCheck = Symbol();
+var expectNoState = Symbol();
+function algToSubtle(alg) {
+  switch (alg) {
+    case "PS256":
+    case "PS384":
+    case "PS512":
+      return { name: "RSA-PSS", hash: `SHA-${alg.slice(-3)}` };
+    case "RS256":
+    case "RS384":
+    case "RS512":
+      return { name: "RSASSA-PKCS1-v1_5", hash: `SHA-${alg.slice(-3)}` };
+    case "ES256":
+    case "ES384":
+      return { name: "ECDSA", namedCurve: `P-${alg.slice(-3)}` };
+    case "ES512":
+      return { name: "ECDSA", namedCurve: "P-521" };
+    case "EdDSA":
+      return "Ed25519";
+    case "Ed25519":
+    case "ML-DSA-44":
+    case "ML-DSA-65":
+    case "ML-DSA-87":
+      return alg;
+    default:
+      throw new UnsupportedOperationError("unsupported JWS algorithm", { cause: { alg } });
+  }
+}
+async function importJwk(alg, jwk) {
+  const { ext, key_ops, use, ...key } = jwk;
+  return crypto.subtle.importKey("jwk", key, algToSubtle(alg), true, ["verify"]);
+}
+function normalizeHtu(htu) {
+  const url = new URL(htu);
+  url.search = "";
+  url.hash = "";
+  return url.href;
+}
+async function validateDPoP(request, accessToken, accessTokenClaims, options) {
+  const headerValue = request.headers.get("dpop");
+  if (headerValue === null) {
+    throw OPE("operation indicated DPoP use but the request has no DPoP HTTP Header", INVALID_REQUEST, { headers: request.headers });
+  }
+  if (request.headers.get("authorization")?.toLowerCase().startsWith("dpop ") === false) {
+    throw OPE(`operation indicated DPoP use but the request's Authorization HTTP Header scheme is not DPoP`, INVALID_REQUEST, { headers: request.headers });
+  }
+  if (typeof accessTokenClaims.cnf?.jkt !== "string") {
+    throw OPE("operation indicated DPoP use but the JWT Access Token has no jkt confirmation claim", INVALID_REQUEST, { claims: accessTokenClaims });
+  }
+  const clockSkew2 = getClockSkew(options);
+  const proof = await validateJwt(headerValue, checkSigningAlgorithm.bind(undefined, options?.signingAlgorithms, undefined, supported), clockSkew2, getClockTolerance(options), undefined).then(checkJwtType.bind(undefined, "dpop+jwt")).then(validatePresence.bind(undefined, ["iat", "jti", "ath", "htm", "htu"]));
+  const now = epochTime() + clockSkew2;
+  const diff = Math.abs(now - proof.claims.iat);
+  if (diff > 300) {
+    throw OPE("DPoP Proof iat is not recent enough", JWT_TIMESTAMP_CHECK, {
+      now,
+      claims: proof.claims,
+      claim: "iat"
+    });
+  }
+  if (proof.claims.htm !== request.method) {
+    throw OPE("DPoP Proof htm mismatch", JWT_CLAIM_COMPARISON, {
+      expected: request.method,
+      claims: proof.claims,
+      claim: "htm"
+    });
+  }
+  if (typeof proof.claims.htu !== "string" || normalizeHtu(proof.claims.htu) !== normalizeHtu(request.url)) {
+    throw OPE("DPoP Proof htu mismatch", JWT_CLAIM_COMPARISON, {
+      expected: normalizeHtu(request.url),
+      claims: proof.claims,
+      claim: "htu"
+    });
+  }
+  {
+    const expected = b64u(await crypto.subtle.digest("SHA-256", buf(accessToken)));
+    if (proof.claims.ath !== expected) {
+      throw OPE("DPoP Proof ath mismatch", JWT_CLAIM_COMPARISON, {
+        expected,
+        claims: proof.claims,
+        claim: "ath"
+      });
+    }
+  }
+  {
+    const expected = await calculateJwkThumbprint(proof.header.jwk);
+    if (accessTokenClaims.cnf.jkt !== expected) {
+      throw OPE("JWT Access Token confirmation mismatch", JWT_CLAIM_COMPARISON, {
+        expected,
+        claims: accessTokenClaims,
+        claim: "cnf.jkt"
+      });
+    }
+  }
+  const { 0: protectedHeader, 1: payload, 2: encodedSignature } = headerValue.split(".");
+  const signature = b64u(encodedSignature);
+  const { jwk, alg } = proof.header;
+  if (!jwk) {
+    throw OPE("DPoP Proof is missing the jwk header parameter", INVALID_REQUEST, {
+      header: proof.header
+    });
+  }
+  const key = await importJwk(alg, jwk);
+  if (key.type !== "public") {
+    throw OPE("DPoP Proof jwk header parameter must contain a public key", INVALID_REQUEST, {
+      header: proof.header
+    });
+  }
+  await validateJwsSignature(protectedHeader, payload, key, signature);
+}
+async function validateJwtAccessToken(as, request, expectedAudience, options) {
+  assertAs(as);
+  if (!looseInstanceOf(request, Request)) {
+    throw CodedTypeError('"request" must be an instance of Request', ERR_INVALID_ARG_TYPE);
+  }
+  assertString(expectedAudience, '"expectedAudience"');
+  const authorization = request.headers.get("authorization");
+  if (authorization === null) {
+    throw OPE('"request" is missing an Authorization HTTP Header', INVALID_REQUEST, {
+      headers: request.headers
+    });
+  }
+  let { 0: scheme, 1: accessToken, length } = authorization.split(" ");
+  scheme = scheme.toLowerCase();
+  switch (scheme) {
+    case "dpop":
+    case "bearer":
+      break;
+    default:
+      throw new UnsupportedOperationError("unsupported Authorization HTTP Header scheme", {
+        cause: { headers: request.headers }
+      });
+  }
+  if (length !== 2) {
+    throw OPE("invalid Authorization HTTP Header format", INVALID_REQUEST, {
+      headers: request.headers
+    });
+  }
+  const requiredClaims = [
+    "iss",
+    "exp",
+    "aud",
+    "sub",
+    "iat",
+    "jti",
+    "client_id"
+  ];
+  if (options?.requireDPoP || scheme === "dpop" || request.headers.has("dpop")) {
+    requiredClaims.push("cnf");
+  }
+  const { claims, header } = await validateJwt(accessToken, checkSigningAlgorithm.bind(undefined, options?.signingAlgorithms, undefined, supported), getClockSkew(options), getClockTolerance(options), undefined).then(checkJwtType.bind(undefined, "at+jwt")).then(validatePresence.bind(undefined, requiredClaims)).then(validateIssuer.bind(undefined, as)).then(validateAudience.bind(undefined, expectedAudience)).catch(reassignRSCode);
+  for (const claim of ["client_id", "jti", "sub"]) {
+    if (typeof claims[claim] !== "string") {
+      throw OPE(`unexpected JWT "${claim}" claim type`, INVALID_REQUEST, { claims });
+    }
+  }
+  if ("cnf" in claims) {
+    if (!isJsonObject(claims.cnf)) {
+      throw OPE('unexpected JWT "cnf" (confirmation) claim value', INVALID_REQUEST, { claims });
+    }
+    const { 0: cnf, length: length2 } = Object.keys(claims.cnf);
+    if (length2) {
+      if (length2 !== 1) {
+        throw new UnsupportedOperationError("multiple confirmation claims are not supported", {
+          cause: { claims }
+        });
+      }
+      if (cnf !== "jkt") {
+        throw new UnsupportedOperationError("unsupported JWT Confirmation method", {
+          cause: { claims }
+        });
+      }
+    }
+  }
+  const { 0: protectedHeader, 1: payload, 2: encodedSignature } = accessToken.split(".");
+  const signature = b64u(encodedSignature);
+  const key = await getPublicSigKeyFromIssuerJwksUri(as, options, header);
+  await validateJwsSignature(protectedHeader, payload, key, signature);
+  if (options?.requireDPoP || scheme === "dpop" || claims.cnf?.jkt !== undefined || request.headers.has("dpop")) {
+    await validateDPoP(request, accessToken, claims, options).catch(reassignRSCode);
+  }
+  return claims;
+}
+function reassignRSCode(err) {
+  if (err instanceof OperationProcessingError && err?.code === INVALID_REQUEST) {
+    err.code = INVALID_RESPONSE;
+  }
+  throw err;
+}
+async function getResponseJsonBody(response, check = assertApplicationJson) {
+  let json;
+  try {
+    json = await response.json();
+  } catch (cause) {
+    check(response);
+    throw OPE('failed to parse "response" body as JSON', PARSE_ERROR, cause);
+  }
+  if (!isJsonObject(json)) {
+    throw OPE('"response" body must be a top level object', INVALID_RESPONSE, { body: json });
+  }
+  return json;
+}
+var _nodiscoverycheck = Symbol();
+var _expectedIssuer = Symbol();
+
+// src/http/jwt.ts
+function jwtAuthenticate(options) {
+  const principalClaim = options.principalClaim ?? "sub";
+  const domain = options.domain ?? "jwt";
+  const audience = options.audience;
+  let asPromise = null;
+  async function getAuthorizationServer() {
+    if (options.jwksUri) {
+      return {
+        issuer: options.issuer,
+        jwks_uri: options.jwksUri
+      };
+    }
+    const issuerUrl = new URL(options.issuer);
+    const response = await discoveryRequest(issuerUrl);
+    return processDiscoveryResponse(issuerUrl, response);
+  }
+  return async function authenticate(request) {
+    if (!asPromise) {
+      asPromise = getAuthorizationServer();
+    }
+    let as;
+    try {
+      as = await asPromise;
+    } catch (error) {
+      asPromise = null;
+      throw error;
+    }
+    const audiences = Array.isArray(audience) ? audience : [audience];
+    let claims;
+    let lastError;
+    for (const aud of audiences) {
+      try {
+        claims = await validateJwtAccessToken(as, request, aud);
+        break;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    if (!claims) {
+      throw lastError;
+    }
+    const principal = claims[principalClaim] ?? null;
+    return new AuthContext(domain, true, principal, claims);
+  };
+}
+// src/http/mtls.ts
+import { createHash, X509Certificate } from "node:crypto";
+function splitRespectingQuotes(text, delimiter) {
+  const parts = [];
+  let current = [];
+  let inQuotes = false;
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '"') {
+      inQuotes = !inQuotes;
+      current.push(ch);
+    } else if (ch === "\\" && inQuotes && i + 1 < text.length) {
+      current.push(ch);
+      current.push(text[i + 1]);
+      i++;
+    } else if (ch === delimiter && !inQuotes) {
+      parts.push(current.join(""));
+      current = [];
+    } else {
+      current.push(ch);
+    }
+    i++;
+  }
+  parts.push(current.join(""));
+  return parts;
+}
+function unescapeQuoted(text) {
+  return text.replace(/\\(.)/g, "$1");
+}
+function extractCn(subject) {
+  for (const part of subject.split(/(?<!\\),/)) {
+    const trimmed = part.trim();
+    if (trimmed.toUpperCase().startsWith("CN=")) {
+      return trimmed.slice(3);
+    }
+  }
+  return "";
+}
+function parseXfcc(headerValue) {
+  const elements = [];
+  for (const rawElement of splitRespectingQuotes(headerValue, ",")) {
+    const trimmed = rawElement.trim();
+    if (!trimmed)
+      continue;
+    const pairs = splitRespectingQuotes(trimmed, ";");
+    const fields = {};
+    for (const pair of pairs) {
+      const p = pair.trim();
+      if (!p)
+        continue;
+      const eqIdx = p.indexOf("=");
+      if (eqIdx < 0)
+        continue;
+      const key = p.slice(0, eqIdx).trim().toLowerCase();
+      let value = p.slice(eqIdx + 1).trim();
+      if (value.length >= 2 && value[0] === '"' && value[value.length - 1] === '"') {
+        value = unescapeQuoted(value.slice(1, -1));
+      }
+      if (key === "cert" || key === "uri" || key === "by") {
+        value = decodeURIComponent(value);
+      }
+      if (key === "dns") {
+        const existing = fields.dns;
+        if (Array.isArray(existing)) {
+          existing.push(value);
+        } else {
+          fields.dns = [value];
+        }
+      } else {
+        fields[key] = value;
+      }
+    }
+    const dns = Array.isArray(fields.dns) ? fields.dns : [];
+    elements.push({
+      hash: typeof fields.hash === "string" ? fields.hash : null,
+      cert: typeof fields.cert === "string" ? fields.cert : null,
+      subject: typeof fields.subject === "string" ? fields.subject : null,
+      uri: typeof fields.uri === "string" ? fields.uri : null,
+      dns,
+      by: typeof fields.by === "string" ? fields.by : null
+    });
+  }
+  return elements;
+}
+function mtlsAuthenticateXfcc(options) {
+  const validate = options?.validate;
+  const domain = options?.domain ?? "mtls";
+  const selectElement = options?.selectElement ?? "first";
+  return async function authenticate(request) {
+    const headerValue = request.headers.get("x-forwarded-client-cert");
+    if (!headerValue) {
+      throw new Error("Missing x-forwarded-client-cert header");
+    }
+    const elements = parseXfcc(headerValue);
+    if (elements.length === 0) {
+      throw new Error("Empty x-forwarded-client-cert header");
+    }
+    const element = selectElement === "first" ? elements[0] : elements[elements.length - 1];
+    if (validate) {
+      return validate(element);
+    }
+    const principal = element.subject ? extractCn(element.subject) : "";
+    const claims = {};
+    if (element.hash)
+      claims.hash = element.hash;
+    if (element.subject)
+      claims.subject = element.subject;
+    if (element.uri)
+      claims.uri = element.uri;
+    if (element.dns.length > 0)
+      claims.dns = [...element.dns];
+    if (element.by)
+      claims.by = element.by;
+    return new AuthContext(domain, true, principal, claims);
+  };
+}
+function parseCertFromHeader(request, header) {
+  const raw = request.headers.get(header);
+  if (!raw) {
+    throw new Error(`Missing ${header} header`);
+  }
+  const pemStr = decodeURIComponent(raw);
+  if (!pemStr.startsWith("-----BEGIN CERTIFICATE-----")) {
+    throw new Error("Header value is not a PEM certificate");
+  }
+  try {
+    return new X509Certificate(pemStr);
+  } catch (exc) {
+    throw new Error(`Failed to parse PEM certificate: ${exc}`);
+  }
+}
+function checkCertExpiry(cert) {
+  const now = new Date;
+  const notBefore = new Date(cert.validFrom);
+  const notAfter = new Date(cert.validTo);
+  if (now < notBefore) {
+    throw new Error("Certificate is not yet valid");
+  }
+  if (now > notAfter) {
+    throw new Error("Certificate has expired");
+  }
+}
+function mtlsAuthenticate(options) {
+  const { validate, header = "X-SSL-Client-Cert", checkExpiry = false } = options;
+  return async function authenticate(request) {
+    const cert = parseCertFromHeader(request, header);
+    if (checkExpiry) {
+      checkCertExpiry(cert);
+    }
+    return validate(cert);
+  };
+}
+var SUPPORTED_ALGORITHMS = new Set(["sha256", "sha1", "sha384", "sha512"]);
+function mtlsAuthenticateFingerprint(options) {
+  const { fingerprints, header, algorithm = "sha256", checkExpiry } = options;
+  if (!SUPPORTED_ALGORITHMS.has(algorithm)) {
+    throw new Error(`Unsupported hash algorithm: ${algorithm}`);
+  }
+  const entries = fingerprints instanceof Map ? fingerprints : new Map(Object.entries(fingerprints));
+  function validate(cert) {
+    const fp = createHash(algorithm).update(cert.raw).digest("hex");
+    const ctx = entries.get(fp);
+    if (!ctx) {
+      throw new Error(`Unknown certificate fingerprint: ${fp}`);
+    }
+    return ctx;
+  }
+  return mtlsAuthenticate({ validate, header, checkExpiry });
+}
+function mtlsAuthenticateSubject(options) {
+  const { header, domain = "mtls", allowedSubjects = null, checkExpiry } = options ?? {};
+  function validate(cert) {
+    const subjectParts = cert.subject.split(`
+`).map((s) => s.trim()).filter(Boolean);
+    const subjectDn = subjectParts.join(", ");
+    let cn = "";
+    for (const part of subjectParts) {
+      if (part.toUpperCase().startsWith("CN=")) {
+        cn = part.slice(3);
+        break;
+      }
+    }
+    if (allowedSubjects !== null && !allowedSubjects.has(cn)) {
+      throw new Error(`Subject CN '${cn}' not in allowed subjects`);
+    }
+    const serialHex = BigInt(`0x${cert.serialNumber}`).toString(16);
+    const notValidAfter = new Date(cert.validTo).toISOString();
+    return new AuthContext(domain, true, cn, {
+      subject_dn: subjectDn,
+      serial: serialHex,
+      not_valid_after: notValidAfter
+    });
+  }
+  return mtlsAuthenticate({ validate, header, checkExpiry });
+}
+// src/protocol.ts
+import { Schema as Schema7 } from "@query-farm/apache-arrow";
+
+// src/schema.ts
+import {
+  Binary as Binary3,
+  Bool as Bool3,
+  DataType as DataType4,
+  Field as Field4,
+  Float32,
+  Float64 as Float642,
+  Int16,
+  Int32,
+  Int64 as Int642,
+  Schema as Schema6,
+  Utf8 as Utf83
+} from "@query-farm/apache-arrow";
+var str = new Utf83;
+var bytes = new Binary3;
+var int = new Int642;
+var int32 = new Int32;
+var float = new Float642;
+var float32 = new Float32;
+var bool = new Bool3;
+function toSchema(spec) {
+  if (spec instanceof Schema6)
+    return spec;
+  const fields = [];
+  for (const [name, value] of Object.entries(spec)) {
+    if (value instanceof Field4) {
+      fields.push(value);
+    } else if (value instanceof DataType4) {
+      fields.push(new Field4(name, value, false));
+    } else {
+      throw new TypeError(`Invalid schema value for "${name}": expected DataType or Field, got ${typeof value}`);
+    }
+  }
+  return new Schema6(fields);
+}
+var TYPE_MAP = [
+  [Utf83, "str"],
+  [Binary3, "bytes"],
+  [Bool3, "bool"],
+  [Float642, "float"],
+  [Float32, "float"],
+  [Int642, "int"],
+  [Int32, "int"],
+  [Int16, "int"]
+];
+function inferParamTypes(spec) {
+  const schema = toSchema(spec);
+  if (schema.fields.length === 0)
+    return;
+  const result = {};
+  for (const field of schema.fields) {
+    let mapped;
+    for (const [ctor, name] of TYPE_MAP) {
+      if (field.type instanceof ctor) {
+        mapped = name;
+        break;
+      }
+    }
+    if (!mapped)
+      return;
+    result[field.name] = mapped;
+  }
+  return result;
+}
+
+// src/protocol.ts
+var EMPTY_SCHEMA3 = new Schema7([]);
+
+class Protocol {
+  name;
+  _methods = new Map;
+  constructor(name) {
+    this.name = name;
+  }
+  unary(name, config) {
+    const params = toSchema(config.params);
+    this._methods.set(name, {
+      name,
+      type: "unary" /* UNARY */,
+      paramsSchema: params,
       resultSchema: toSchema(config.result),
       handler: config.handler,
       doc: config.doc,
@@ -2287,7 +4489,7 @@ import { Schema as Schema9 } from "@query-farm/apache-arrow";
 // src/dispatch/stream.ts
 import { Schema as Schema8 } from "@query-farm/apache-arrow";
 var EMPTY_SCHEMA4 = new Schema8([]);
-async function dispatchStream(method, params, writer, reader, serverId, requestId) {
+async function dispatchStream(method, params, writer, reader, serverId, requestId, externalConfig) {
   const isProducer = !!method.producerFn;
   let state;
   try {
@@ -2341,8 +4543,11 @@ async function dispatchStream(method, params, writer, reader, serverId, requestI
       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) {
+            throw e;
+          }
+          console.debug?.(`Schema conformance skipped: ${e instanceof Error ? e.message : e}`);
         }
       }
       const out = new OutputCollector(outputSchema, effectiveProducer, serverId, requestId);
@@ -2352,7 +4557,11 @@ async function dispatchStream(method, params, writer, reader, serverId, requestI
         await method.exchangeFn(state, inputBatch, out);
       }
       for (const emitted of out.batches) {
-        stream.write(emitted.batch);
+        let batch = emitted.batch;
+        if (externalConfig) {
+          batch = await maybeExternalizeBatch(batch, externalConfig);
+        }
+        stream.write(batch);
       }
       if (out.finished) {
         break;
@@ -2368,12 +4577,15 @@ async function dispatchStream(method, params, writer, reader, serverId, requestI
 }
 
 // src/dispatch/unary.ts
-async function dispatchUnary(method, params, writer, serverId, requestId) {
+async function dispatchUnary(method, params, writer, serverId, requestId, externalConfig) {
   const schema = method.resultSchema;
   const out = new OutputCollector(schema, true, serverId, requestId);
   try {
     const result = await method.handler(params, out);
-    const resultBatch = buildResultBatch(schema, result, serverId, requestId);
+    let resultBatch = buildResultBatch(schema, result, serverId, requestId);
+    if (externalConfig) {
+      resultBatch = await maybeExternalizeBatch(resultBatch, externalConfig);
+    }
     const batches = [...out.batches.map((b) => b.batch), resultBatch];
     writer.writeStream(schema, batches);
   } catch (error) {
@@ -2384,7 +4596,7 @@ async function dispatchUnary(method, params, writer, serverId, requestId) {
 
 // src/wire/writer.ts
 import { writeSync } from "node:fs";
-import { RecordBatchStreamWriter as RecordBatchStreamWriter4 } from "@query-farm/apache-arrow";
+import { RecordBatchStreamWriter as RecordBatchStreamWriter5 } from "@query-farm/apache-arrow";
 var STDOUT_FD = 1;
 function writeAll(fd, data) {
   let offset = 0;
@@ -2410,7 +4622,7 @@ class IpcStreamWriter {
     this.fd = fd;
   }
   writeStream(schema, batches) {
-    const writer = new RecordBatchStreamWriter4;
+    const writer = new RecordBatchStreamWriter5;
     writer.reset(undefined, schema);
     for (const batch of batches) {
       writer._writeRecordBatch(batch);
@@ -2430,7 +4642,7 @@ class IncrementalStream {
   closed = false;
   constructor(fd, schema) {
     this.fd = fd;
-    this.writer = new RecordBatchStreamWriter4;
+    this.writer = new RecordBatchStreamWriter5;
     this.writer.reset(undefined, schema);
     this.drain();
   }
@@ -2464,10 +4676,14 @@ class VgiRpcServer {
   enableDescribe;
   serverId;
   describeBatch = null;
+  dispatchHook = null;
+  externalConfig;
   constructor(protocol, options) {
     this.protocol = protocol;
     this.enableDescribe = options?.enableDescribe ?? true;
     this.serverId = options?.serverId ?? crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+    this.dispatchHook = options?.dispatchHook ?? null;
+    this.externalConfig = options?.externalLocation;
     if (this.enableDescribe) {
       const { batch } = buildDescribeBatch(protocol.name, protocol.getMethods(), this.serverId);
       this.describeBatch = batch;
@@ -2537,10 +4753,29 @@ class VgiRpcServer {
       writer.writeStream(EMPTY_SCHEMA5, [errBatch]);
       return;
     }
-    if (method.type === "unary" /* UNARY */) {
-      await dispatchUnary(method, params, writer, this.serverId, requestId);
-    } else {
-      await dispatchStream(method, params, writer, reader, this.serverId, requestId);
+    const methodType = method.type === "unary" /* UNARY */ ? "unary" : "stream";
+    const info = { method: methodName, methodType, serverId: this.serverId, requestId };
+    const stats = {
+      inputBatches: 0,
+      outputBatches: 0,
+      inputRows: 0,
+      outputRows: 0,
+      inputBytes: 0,
+      outputBytes: 0
+    };
+    const token = this.dispatchHook?.onDispatchStart(info);
+    let dispatchError;
+    try {
+      if (method.type === "unary" /* UNARY */) {
+        await dispatchUnary(method, params, writer, this.serverId, requestId, this.externalConfig);
+      } else {
+        await dispatchStream(method, params, writer, reader, this.serverId, requestId, this.externalConfig);
+      }
+    } catch (e) {
+      dispatchError = e instanceof Error ? e : new Error(String(e));
+      throw e;
+    } finally {
+      this.dispatchHook?.onDispatchEnd(token, info, stats, dispatchError);
     }
   }
 }
@@ -2549,19 +4784,42 @@ export {
   toSchema,
   subprocessConnect,
   str,
+  resolveExternalLocation,
   pipeConnect,
+  parseXfcc,
+  parseUseIdTokenAsBearer,
+  parseResourceMetadataUrl,
+  parseDeviceCodeClientSecret,
+  parseDeviceCodeClientId,
   parseDescribeResponse,
+  parseClientSecret,
+  parseClientId,
+  oauthResourceMetadataToJson,
+  mtlsAuthenticateXfcc,
+  mtlsAuthenticateSubject,
+  mtlsAuthenticateFingerprint,
+  mtlsAuthenticate,
+  maybeExternalizeBatch,
+  makeExternalLocationBatch,
+  jwtAuthenticate,
   jsonStateSerializer,
+  isExternalLocationBatch,
   int32,
   int,
   inferParamTypes,
+  httpsOnlyValidator,
+  httpOAuthMetadata,
   httpIntrospect,
   httpConnect,
   float32,
   float,
+  fetchOAuthMetadata,
   createHttpHandler,
+  chainAuthenticate,
   bytes,
   bool,
+  bearerAuthenticateStatic,
+  bearerAuthenticate,
   VgiRpcServer,
   VersionError,
   STATE_KEY,
@@ -2583,7 +4841,8 @@ export {
   DESCRIBE_VERSION_KEY,
   DESCRIBE_VERSION,
   DESCRIBE_METHOD_NAME,
+  AuthContext,
   ARROW_CONTENT_TYPE
 };
 
-//# debugId=A10C22D56B2874CF64756E2164756E21
+//# debugId=37CD76108224132A64756E2164756E21