@query-farm/vgi-rpc 0.3.4 → 0.6.0

package/dist/otel.d.ts

@@ -0,0 +1,47 @@
+/**
+ * OpenTelemetry instrumentation for vgi-rpc TypeScript servers.
+ *
+ * Implements {@link DispatchHook} to add distributed tracing (spans) and
+ * metrics (request counter, duration histogram) to RPC dispatch.
+ *
+ * Requires `@opentelemetry/api` as a peer dependency.
+ *
+ * @example
+ * ```typescript
+ * import { createOtelHook } from "vgi-rpc/otel";
+ * import { createHttpHandler } from "vgi-rpc";
+ *
+ * const handler = createHttpHandler(protocol, {
+ *   dispatchHook: createOtelHook(),
+ * });
+ * ```
+ */
+import { type Meter, type Tracer } from "@opentelemetry/api";
+import type { DispatchHook } from "./types.js";
+/** Configuration for OpenTelemetry instrumentation. */
+export interface OtelConfig {
+    /** Custom TracerProvider; uses the global provider when omitted. */
+    tracerProvider?: {
+        getTracer(name: string): Tracer;
+    };
+    /** Custom MeterProvider; uses the global provider when omitted. */
+    meterProvider?: {
+        getMeter(name: string): Meter;
+    };
+    /** Enable span creation. Default: true. */
+    enableTracing?: boolean;
+    /** Enable counter/histogram recording. Default: true. */
+    enableMetrics?: boolean;
+    /** Record exceptions on error spans. Default: true. */
+    recordExceptions?: boolean;
+    /** Service name for the rpc.service attribute. Default: "TypeScriptRpcServer". */
+    serviceName?: string;
+}
+/**
+ * Create a {@link DispatchHook} that instruments RPC calls with OpenTelemetry.
+ *
+ * Creates a span for each RPC call with method attributes, and records
+ * request count and duration metrics.
+ */
+export declare function createOtelHook(config?: OtelConfig): DispatchHook;
+//# sourceMappingURL=otel.d.ts.map

package/dist/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAIL,KAAK,KAAK,EAKV,KAAK,MAAM,EAEZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAkB,YAAY,EAA2B,MAAM,YAAY,CAAC;AAIxF,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,cAAc,CAAC,EAAE;QAAE,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACrD,mEAAmE;IACnE,aAAa,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAC;IAClD,2CAA2C;IAC3C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,yDAAyD;IACzD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CA+FhE"}

package/dist/s3.d.ts

@@ -0,0 +1,43 @@
+/**
+ * S3 storage backend for external storage of large Arrow IPC batches.
+ *
+ * Requires `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`
+ * as peer dependencies.
+ *
+ * @example
+ * ```typescript
+ * import { createS3Storage } from "@query-farm/vgi-rpc/s3";
+ *
+ * const storage = createS3Storage({
+ *   bucket: "my-bucket",
+ *   prefix: "vgi-rpc/",
+ * });
+ * const handler = createHttpHandler(protocol, {
+ *   externalLocation: { storage, externalizeThresholdBytes: 1_048_576 },
+ * });
+ * ```
+ */
+import type { ExternalStorage } from "./external.js";
+/** Configuration for the S3 storage backend. */
+export interface S3StorageConfig {
+    /** S3 bucket name. */
+    bucket: string;
+    /** Key prefix for uploaded objects. Default: "vgi-rpc/". */
+    prefix?: string;
+    /** Lifetime of pre-signed GET URLs in seconds. Default: 3600 (1 hour). */
+    presignExpirySeconds?: number;
+    /** AWS region. If omitted, uses default SDK config. */
+    region?: string;
+    /** Custom S3 endpoint URL (for MinIO, LocalStack, etc.). */
+    endpointUrl?: string;
+    /** Force path-style addressing (required for some S3-compatible services). */
+    forcePathStyle?: boolean;
+}
+/**
+ * Create an S3-backed ExternalStorage.
+ *
+ * Lazily imports `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`
+ * on first upload to avoid loading the AWS SDK unless needed.
+ */
+export declare function createS3Storage(config: S3StorageConfig): ExternalStorage;
+//# sourceMappingURL=s3.d.ts.map

package/dist/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../src/s3.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CA8CxE"}

package/dist/server.d.ts

@@ -1,4 +1,6 @@
+import type { ExternalLocationConfig } from "./external.js";
 import type { Protocol } from "./protocol.js";
+import { type DispatchHook } from "./types.js";
 /**
  * RPC server that reads Arrow IPC requests from stdin and writes responses to stdout.
  * Supports unary and streaming (producer/exchange) methods.
@@ -8,9 +10,13 @@ export declare class VgiRpcServer {
     private enableDescribe;
     private serverId;
     private describeBatch;
+    private dispatchHook;
+    private externalConfig;
     constructor(protocol: Protocol, options?: {
         enableDescribe?: boolean;
         serverId?: string;
+        dispatchHook?: DispatchHook;
+        externalLocation?: ExternalLocationConfig;
     });
     /** Start the server loop. Reads requests until stdin closes. */
     run(): Promise<void>;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAS9C;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAA+D;gBAExE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;IAWzF,gEAAgE;IAC1D,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YAwCZ,QAAQ;CA0DvB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAuB,KAAK,YAAY,EAAiC,MAAM,YAAY,CAAC;AAQnG;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAA+D;IACpF,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,cAAc,CAAqC;gBAGzD,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,YAAY,CAAC;QAC5B,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;KAC3C;IAcH,gEAAgE;IAC1D,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YAwCZ,QAAQ;CA+EvB"}

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import { RecordBatch, type Schema } from "@query-farm/apache-arrow";
+import { AuthContext } from "./auth.js";
 export declare enum MethodType {
     UNARY = "unary",
     STREAM = "stream"
@@ -7,6 +8,10 @@ export declare enum MethodType {
 export interface LogContext {
     clientLog(level: string, message: string, extra?: Record<string, string>): void;
 }
+/** Extended context with authentication info, available to handlers. */
+export interface CallContext extends LogContext {
+    readonly auth: AuthContext;
+}
 /** Handler for unary (request-response) RPC methods. */
 export type UnaryHandler = (params: Record<string, any>, ctx: LogContext) => Promise<Record<string, any>> | Record<string, any>;
 /** Initialization function for producer streams. Returns the initial state object. */
@@ -37,6 +42,36 @@ export interface MethodDefinition {
     defaults?: Record<string, any>;
     paramTypes?: Record<string, string>;
 }
+/** Metadata passed to dispatch hooks before and after RPC method execution. */
+export interface DispatchInfo {
+    /** RPC method name. */
+    method: string;
+    /** "unary" or "stream". */
+    methodType: string;
+    /** Server identifier. */
+    serverId: string;
+    /** Client-supplied request identifier, or null. */
+    requestId: string | null;
+}
+/** Per-call I/O counters, matching Python's CallStatistics. */
+export interface CallStatistics {
+    inputBatches: number;
+    outputBatches: number;
+    inputRows: number;
+    outputRows: number;
+    inputBytes: number;
+    outputBytes: number;
+}
+/** Opaque token returned by onDispatchStart, passed back to onDispatchEnd. */
+export type HookToken = unknown;
+/**
+ * Observability hook called around RPC dispatch.
+ * Implementations must be safe for concurrent use (HTTP transport is concurrent).
+ */
+export interface DispatchHook {
+    onDispatchStart(info: DispatchInfo): HookToken;
+    onDispatchEnd(token: HookToken, info: DispatchInfo, stats: CallStatistics, error?: Error): void;
+}
 export interface EmittedBatch {
     batch: RecordBatch;
     metadata?: Map<string, string>;
@@ -45,7 +80,7 @@ export interface EmittedBatch {
  * Accumulates output batches during a produce/exchange call.
  * Enforces that exactly one data batch is emitted per call (plus any number of log batches).
  */
-export declare class OutputCollector implements LogContext {
+export declare class OutputCollector implements CallContext {
     private _batches;
     private _dataBatchIdx;
     private _finished;
@@ -53,7 +88,8 @@ export declare class OutputCollector implements LogContext {
     private _outputSchema;
     private _serverId;
     private _requestId;
-    constructor(outputSchema: Schema, producerMode?: boolean, serverId?: string, requestId?: string | null);
+    readonly auth: AuthContext;
+    constructor(outputSchema: Schema, producerMode?: boolean, serverId?: string, requestId?: string | null, authContext?: AuthContext);
     get outputSchema(): Schema;
     get finished(): boolean;
     get batches(): EmittedBatch[];

package/dist/types.d.ts.map

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi-rpc",
-  "version": "0.3.4",
+  "version": "0.6.0",
   "license": "Apache-2.0",
   "homepage": "https://vgi-rpc-typescript.query.farm",
   "repository": {
@@ -15,6 +15,21 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "bun": "./src/index.ts"
+    },
+    "./otel": {
+      "import": "./dist/otel.js",
+      "types": "./dist/otel.d.ts",
+      "bun": "./src/otel.ts"
+    },
+    "./s3": {
+      "import": "./dist/s3.js",
+      "types": "./dist/s3.d.ts",
+      "bun": "./src/s3.ts"
+    },
+    "./gcs": {
+      "import": "./dist/gcs.js",
+      "types": "./dist/gcs.d.ts",
+      "bun": "./src/gcs.ts"
     }
   },
   "files": [
@@ -22,10 +37,39 @@
     "src"
   ],
   "dependencies": {
-    "@query-farm/apache-arrow": "*"
+    "@query-farm/apache-arrow": "*",
+    "oauth4webapi": "^3.8.5"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.4.0",
+    "@aws-sdk/client-s3": ">=3.0.0",
+    "@aws-sdk/s3-request-presigner": ">=3.0.0",
+    "@google-cloud/storage": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    },
+    "@google-cloud/storage": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.5",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^2.6.0",
+    "@opentelemetry/sdk-metrics": "^2.6.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.0",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
+    "@aws-sdk/client-s3": "^3.750.0",
+    "@aws-sdk/s3-request-presigner": "^3.750.0",
+    "@google-cloud/storage": "^7.15.0",
     "@types/bun": "latest"
   },
   "scripts": {

package/src/auth.ts

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

package/src/client/connect.ts

@@ -3,6 +3,8 @@
 
 import type { RecordBatch, Schema } from "@query-farm/apache-arrow";
 import { LOG_LEVEL_KEY, STATE_KEY } from "../constants.js";
+import { RpcError } from "../errors.js";
+import { isExternalLocationBatch, resolveExternalLocation } from "../external.js";
 import { ARROW_CONTENT_TYPE } from "../http/common.js";
 import { httpIntrospect, type MethodInfo, type ServiceDescription } from "./introspect.js";
 import {
@@ -26,9 +28,11 @@ export interface RpcClient {
 }
 
 export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcClient {
-  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: Map<string, MethodInfo> | null = null;
   let compressFn: CompressFn | undefined;
@@ -55,6 +59,9 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
       headers["Content-Encoding"] = "zstd";
       headers["Accept-Encoding"] = "zstd";
     }
+    if (authorization) {
+      headers.Authorization = authorization;
+    }
     return headers;
   }
 
@@ -65,6 +72,12 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
     return content;
   }
 
+  function checkAuth(resp: Response): void {
+    if (resp.status === 401) {
+      throw new RpcError("AuthenticationError", "Authentication required", "");
+    }
+  }
+
   async function readResponse(resp: Response): Promise<Uint8Array<ArrayBuffer>> {
     let body = new Uint8Array(await resp.arrayBuffer());
     if (resp.headers.get("Content-Encoding") === "zstd" && decompressFn) {
@@ -75,7 +88,7 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
 
   async function ensureMethodCache(): Promise<Map<string, MethodInfo>> {
     if (methodCache) return methodCache;
-    const desc = await httpIntrospect(baseUrl, { prefix });
+    const desc = await httpIntrospect(baseUrl, { prefix, authorization });
     methodCache = new Map(desc.methods.map((m) => [m.name, m]));
     return methodCache;
   }
@@ -98,16 +111,22 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
         headers: buildHeaders(),
         body: prepareBody(body) as unknown as BodyInit,
       });
+      checkAuth(resp);
 
       const responseBody = await readResponse(resp);
       const { batches } = await readResponseBatches(responseBody);
 
-      // Process batches: dispatch logs, find result
+      // Process batches: dispatch logs, resolve external pointers, find result
       let resultBatch: RecordBatch | null = null;
-      for (const batch of batches) {
+      for (let batch of batches) {
         if (batch.numRows === 0) {
-          dispatchLogOrError(batch, onLog);
-          continue;
+          // Check for external location pointer batch
+          if (isExternalLocationBatch(batch)) {
+            batch = await resolveExternalLocation(batch, externalConfig);
+          } else {
+            dispatchLogOrError(batch, onLog);
+            continue;
+          }
         }
         resultBatch = batch;
       }
@@ -146,6 +165,7 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
         headers: buildHeaders(),
         body: prepareBody(body) as unknown as BodyInit,
       });
+      checkAuth(resp);
 
       const responseBody = await readResponse(resp);
 
@@ -288,6 +308,8 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
         compressionLevel,
         compressFn,
         decompressFn,
+        authorization,
+        externalConfig,
       });
     },
 

package/src/client/index.ts

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

package/src/client/introspect.ts

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

package/src/client/oauth.ts

@@ -0,0 +1,167 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+/** RFC 9728 OAuth Protected Resource Metadata (client-side response). */
+export interface OAuthResourceMetadataResponse {
+  resource: string;
+  authorizationServers: string[];
+  scopesSupported?: string[];
+  bearerMethodsSupported?: string[];
+  resourceSigningAlgValuesSupported?: string[];
+  resourceName?: string;
+  resourceDocumentation?: string;
+  resourcePolicyUri?: string;
+  resourceTosUri?: string;
+  /** OAuth client_id advertised by the server. */
+  clientId?: string;
+  /** OAuth client_secret advertised by the server. */
+  clientSecret?: string;
+  /** When true, use the OIDC id_token as the Bearer token instead of access_token. */
+  useIdTokenAsBearer?: boolean;
+  /** OAuth client_id for device code flow. */
+  deviceCodeClientId?: string;
+  /** OAuth client_secret for device code flow. */
+  deviceCodeClientSecret?: string;
+}
+
+function parseMetadataJson(json: Record<string, any>): OAuthResourceMetadataResponse {
+  const result: OAuthResourceMetadataResponse = {
+    resource: json.resource,
+    authorizationServers: json.authorization_servers,
+  };
+  if (json.scopes_supported) result.scopesSupported = json.scopes_supported;
+  if (json.bearer_methods_supported) result.bearerMethodsSupported = json.bearer_methods_supported;
+  if (json.resource_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;
+}
+
+/**
+ * Discover OAuth Protected Resource Metadata (RFC 9728) from a vgi-rpc server.
+ * Returns `null` if the server does not serve the well-known endpoint.
+ */
+export async function httpOAuthMetadata(
+  baseUrl: string,
+  prefix?: string,
+): Promise<OAuthResourceMetadataResponse | null> {
+  const effectivePrefix = (prefix ?? "").replace(/\/+$/, "");
+  const metadataUrl = `${baseUrl.replace(/\/+$/, "")}/.well-known/oauth-protected-resource${effectivePrefix}`;
+
+  try {
+    return await fetchOAuthMetadata(metadataUrl);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch OAuth Protected Resource Metadata from an explicit metadata URL.
+ */
+export async function fetchOAuthMetadata(metadataUrl: string): Promise<OAuthResourceMetadataResponse> {
+  const response = await fetch(metadataUrl);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch OAuth metadata from ${metadataUrl}: ${response.status}`);
+  }
+  const json = await response.json();
+  return parseMetadataJson(json);
+}
+
+/**
+ * Extract the `resource_metadata` URL from a WWW-Authenticate Bearer challenge.
+ * Returns `null` if no resource_metadata parameter is found.
+ */
+export function parseResourceMetadataUrl(wwwAuthenticate: string): string | null {
+  // Parse Bearer challenge parameters per RFC 6750
+  const bearerMatch = wwwAuthenticate.match(/^Bearer\s+(.*)/i);
+  if (!bearerMatch) return null;
+
+  const params = bearerMatch[1];
+  const metadataMatch = params.match(/resource_metadata="([^"]+)"/);
+  if (!metadataMatch) return null;
+
+  return metadataMatch[1];
+}
+
+/**
+ * Extract the `client_id` from a WWW-Authenticate Bearer challenge.
+ * Returns `null` if no client_id parameter is found.
+ */
+export function parseClientId(wwwAuthenticate: string): string | null {
+  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];
+}
+
+/**
+ * Extract the `client_secret` from a WWW-Authenticate Bearer challenge.
+ * Returns `null` if no client_secret parameter is found.
+ */
+export function parseClientSecret(wwwAuthenticate: string): string | null {
+  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];
+}
+
+/**
+ * Extract the `use_id_token_as_bearer` flag from a WWW-Authenticate Bearer challenge.
+ * Returns `true` if the parameter is present and set to "true", `false` otherwise.
+ */
+export function parseUseIdTokenAsBearer(wwwAuthenticate: string): boolean {
+  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";
+}
+
+/**
+ * Extract the `device_code_client_id` from a WWW-Authenticate Bearer challenge.
+ * Returns `null` if no device_code_client_id parameter is found.
+ */
+export function parseDeviceCodeClientId(wwwAuthenticate: string): string | null {
+  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];
+}
+
+/**
+ * Extract the `device_code_client_secret` from a WWW-Authenticate Bearer challenge.
+ * Returns `null` if no device_code_client_secret parameter is found.
+ */
+export function parseDeviceCodeClientSecret(wwwAuthenticate: string): string | null {
+  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];
+}