@query-farm/vgi-rpc 0.3.3 → 0.4.0

package/src/http/jwt.ts

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

package/src/http/types.ts

@@ -1,6 +1,8 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
+import type { AuthenticateFn, OAuthResourceMetadata } from "./auth.js";
+
 /** Configuration options for createHttpHandler(). */
 export interface HttpHandlerOptions {
   /** URL path prefix for all endpoints. Default: "/vgi" */
@@ -22,6 +24,10 @@ export interface HttpHandlerOptions {
   /** zstd compression level for responses (1-22). If set, responses are
    *  compressed when the client sends Accept-Encoding: zstd. */
   compressionLevel?: number;
+  /** Optional authentication callback. Called for each request before dispatch. */
+  authenticate?: AuthenticateFn;
+  /** Optional RFC 9728 OAuth Protected Resource Metadata. Served at well-known endpoint. */
+  oauthResourceMetadata?: OAuthResourceMetadata;
 }
 
 /** Serializer for stream state objects stored in state tokens. */

package/src/index.ts

@@ -1,6 +1,7 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
+export { AuthContext } from "./auth.js";
 export * from "./client/index.js";
 export {
   DESCRIBE_METHOD_NAME,
@@ -20,9 +21,14 @@ export {
 export { RpcError, VersionError } from "./errors.js";
 export {
   ARROW_CONTENT_TYPE,
+  type AuthenticateFn,
   createHttpHandler,
   type HttpHandlerOptions,
+  type JwtAuthenticateOptions,
   jsonStateSerializer,
+  jwtAuthenticate,
+  type OAuthResourceMetadata,
+  oauthResourceMetadataToJson,
   type StateSerializer,
   type UnpackedToken,
   unpackStateToken,
@@ -42,6 +48,7 @@ export {
 } from "./schema.js";
 export { VgiRpcServer } from "./server.js";
 export {
+  type CallContext,
   type ExchangeFn,
   type ExchangeInit,
   type HeaderInit,

package/src/types.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { RecordBatch, recordBatchFromArrays, type Schema } from "@query-farm/apache-arrow";
+import { AuthContext } from "./auth.js";
 import { buildLogBatch, coerceInt64 } from "./wire/response.js";
 
 export enum MethodType {
@@ -14,6 +15,11 @@ 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>,
@@ -61,7 +67,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 class OutputCollector implements LogContext {
+export class OutputCollector implements CallContext {
   private _batches: EmittedBatch[] = [];
   private _dataBatchIdx: number | null = null;
   private _finished = false;
@@ -69,12 +75,20 @@ export class OutputCollector implements LogContext {
   private _outputSchema: Schema;
   private _serverId: string;
   private _requestId: string | null;
-
-  constructor(outputSchema: Schema, producerMode = true, serverId = "", requestId: string | null = null) {
+  readonly auth: AuthContext;
+
+  constructor(
+    outputSchema: Schema,
+    producerMode = true,
+    serverId = "",
+    requestId: string | null = null,
+    authContext?: AuthContext,
+  ) {
     this._outputSchema = outputSchema;
     this._producerMode = producerMode;
     this._serverId = serverId;
     this._requestId = requestId;
+    this.auth = authContext ?? AuthContext.anonymous();
   }
 
   get outputSchema(): Schema {

package/src/util/conform.ts

@@ -1,7 +1,31 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
-import { RecordBatch, Struct, makeData, type Schema } from "@query-farm/apache-arrow";
+import {
+  type DataType,
+  makeData,
+  RecordBatch,
+  type Schema,
+  Struct,
+  Type,
+  vectorFromArray,
+} from "@query-farm/apache-arrow";
+
+/** Return true when the source type's values can be losslessly read and
+ *  re-encoded into the target type (e.g., int32 → float64). */
+function needsValueCast(src: DataType, dst: DataType): boolean {
+  if (src.typeId === dst.typeId) return false;
+  // Same broad family (e.g. Float → Float64) — clone is sufficient.
+  if (src.constructor === dst.constructor) return false;
+  return true;
+}
+
+/** Check if a type is a numeric type we can cast between.
+ *  Uses typeId instead of instanceof because IPC-deserialized types
+ *  may be generic (e.g., Int_ instead of Int64). */
+function isNumeric(t: DataType): boolean {
+  return t.typeId === Type.Int || t.typeId === Type.Float;
+}
 
 /**
  * Rebuild a batch's data to match the given schema's field types.
@@ -12,13 +36,52 @@ import { RecordBatch, Struct, makeData, type Schema } from "@query-farm/apache-a
  * match the writer's schema.  Cloning each child Data with the schema's field
  * type fixes the type metadata while preserving the underlying buffers.
  *
- * This is also used to cast compatible input types (e.g., decimal→double,
- * int32→int64) when the input batch schema doesn't exactly match the method's
- * declared input schema.
+ * This is also used to cast compatible input types (e.g., int32→float64,
+ * float32→float64) when the input batch schema doesn't exactly match the
+ * method's declared input schema.  When the underlying buffer layout differs
+ * (e.g., 4-byte int32 vs 8-byte float64), we read the values and build a
+ * new vector with the target type.
  */
 export function conformBatchToSchema(batch: RecordBatch, schema: Schema): RecordBatch {
   if (batch.numRows === 0) return batch;
-  const children = schema.fields.map((f, i) => batch.data.children[i].clone(f.type));
+
+  // Validate field count and names match before attempting any cast.
+  if (batch.schema.fields.length !== schema.fields.length) {
+    throw new TypeError(`Field count mismatch: expected ${schema.fields.length}, got ${batch.schema.fields.length}`);
+  }
+  for (let i = 0; i < schema.fields.length; i++) {
+    if (batch.schema.fields[i].name !== schema.fields[i].name) {
+      throw new TypeError(
+        `Field name mismatch at index ${i}: expected '${schema.fields[i].name}', got '${batch.schema.fields[i].name}'`,
+      );
+    }
+  }
+
+  const children = schema.fields.map((f, i) => {
+    const srcChild = batch.data.children[i];
+    const srcType = srcChild.type;
+    const dstType = f.type;
+
+    if (!needsValueCast(srcType, dstType)) {
+      return srcChild.clone(dstType);
+    }
+
+    // Numeric → numeric: read values and rebuild with target type.
+    if (isNumeric(srcType) && isNumeric(dstType)) {
+      // Read source values via the batch's column vector.
+      const col = batch.getChildAt(i)!;
+      const values: number[] = [];
+      for (let r = 0; r < batch.numRows; r++) {
+        const v = col.get(r);
+        values.push(typeof v === "bigint" ? Number(v) : (v as number));
+      }
+      return vectorFromArray(values, dstType).data[0];
+    }
+
+    // Fallback: clone type metadata (works for same-layout types).
+    return srcChild.clone(dstType);
+  });
+
   const structType = new Struct(schema.fields);
   const data = makeData({
     type: structType,

package/src/wire/response.ts

@@ -133,25 +133,39 @@ export function buildLogBatch(
   return buildEmptyBatch(schema, metadata);
 }
 
+/**
+ * Recursively create empty (0-row) Data for any Arrow type,
+ * including complex types (Struct, List, FixedSizeList, Map).
+ */
+function makeEmptyData(type: DataType): Data {
+  if (DataType.isStruct(type)) {
+    const children = type.children.map((f: Field) => 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]) } as any);
+  }
+  if (DataType.isFixedSizeList(type)) {
+    const childData = makeEmptyData(type.children[0].type);
+    return makeData({ type, length: 0, child: childData, nullCount: 0 } as any);
+  }
+  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]) } as any);
+  }
+  return makeData({ type, length: 0, nullCount: 0 });
+}
+
 /**
  * Build a 0-row batch from a schema with metadata.
  * Used for error/log batches.
  */
 export function buildEmptyBatch(schema: Schema, metadata?: Map<string, string>): RecordBatch {
-  const children = schema.fields.map((f: Field) => {
-    return makeData({ type: f.type, length: 0, nullCount: 0 });
-  });
-
-  if (schema.fields.length === 0) {
-    const structType = new Struct(schema.fields);
-    const data = makeData({
-      type: structType,
-      length: 0,
-      children: [],
-      nullCount: 0,
-    });
-    return new RecordBatch(schema, data, metadata);
-  }
+  const children = schema.fields.map((f: Field) => makeEmptyData(f.type));
 
   const structType = new Struct(schema.fields);
   const data = makeData({