@query-farm/vgi-rpc 0.3.4 → 0.6.0

package/dist/http/mtls.d.ts

@@ -0,0 +1,78 @@
+import { X509Certificate } from "node:crypto";
+import { AuthContext } from "../auth.js";
+import type { AuthenticateFn } from "./auth.js";
+/** A single element from an `x-forwarded-client-cert` header. */
+export interface XfccElement {
+    hash: string | null;
+    cert: string | null;
+    subject: string | null;
+    uri: string | null;
+    dns: readonly string[];
+    by: string | null;
+}
+/** Receives a parsed XFCC element, returns an AuthContext on success. Must throw on failure. */
+export type XfccValidateFn = (element: XfccElement) => AuthContext | Promise<AuthContext>;
+/** Receives a parsed X509Certificate, returns an AuthContext on success. Must throw on failure. */
+export type CertValidateFn = (cert: X509Certificate) => AuthContext | Promise<AuthContext>;
+/**
+ * Parse an `x-forwarded-client-cert` header value.
+ *
+ * Handles comma-separated elements (respecting quoted values),
+ * semicolon-separated key=value pairs within each element, and
+ * URL-encoded Cert/URI/By fields.
+ */
+export declare function parseXfcc(headerValue: string): XfccElement[];
+/**
+ * Create an authenticate callback from Envoy `x-forwarded-client-cert`.
+ *
+ * Parses the `x-forwarded-client-cert` header and extracts client identity.
+ * Does not require any crypto dependencies.
+ *
+ * **Warning:** The reverse proxy MUST strip client-supplied
+ * `x-forwarded-client-cert` headers before forwarding.
+ */
+export declare function mtlsAuthenticateXfcc(options?: {
+    validate?: XfccValidateFn;
+    domain?: string;
+    selectElement?: "first" | "last";
+}): AuthenticateFn;
+/**
+ * Create an mTLS authenticate callback with custom certificate validation.
+ *
+ * Generic factory that parses the client certificate from a proxy header
+ * and delegates identity extraction to a user-supplied `validate` callback.
+ *
+ * **Warning:** The reverse proxy MUST strip client-supplied certificate
+ * headers before forwarding.
+ */
+export declare function mtlsAuthenticate(options: {
+    validate: CertValidateFn;
+    header?: string;
+    checkExpiry?: boolean;
+}): AuthenticateFn;
+/**
+ * Create an mTLS authenticate callback using certificate fingerprint lookup.
+ *
+ * Computes the certificate fingerprint and looks it up in the provided
+ * mapping. Fingerprints must be lowercase hex without colons.
+ */
+export declare function mtlsAuthenticateFingerprint(options: {
+    fingerprints: ReadonlyMap<string, AuthContext> | Record<string, AuthContext>;
+    header?: string;
+    algorithm?: string;
+    domain?: string;
+    checkExpiry?: boolean;
+}): AuthenticateFn;
+/**
+ * Create an mTLS authenticate callback using certificate subject CN.
+ *
+ * Extracts the Subject Common Name as `principal` and populates
+ * `claims` with the full DN, serial number (hex), and `not_valid_after`.
+ */
+export declare function mtlsAuthenticateSubject(options?: {
+    header?: string;
+    domain?: string;
+    allowedSubjects?: ReadonlySet<string> | null;
+    checkExpiry?: boolean;
+}): AuthenticateFn;
+//# sourceMappingURL=mtls.d.ts.map

package/dist/http/mtls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mtls.d.ts","sourceRoot":"","sources":["../../src/http/mtls.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,eAAe,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMhD,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IACvB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACnB;AAED,gGAAgG;AAChG,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;AAE1F,mGAAmG;AACnG,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,eAAe,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;AA2C3F;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,EAAE,CA0C5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IAC7C,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAClC,GAAG,cAAc,CA2BjB;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,cAAc,CAUjB;AAID;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,cAAc,CAkBjB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC7C,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,cAAc,CAkCjB"}

package/dist/http/pages.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Pre-rendered HTML pages for the vgi-rpc HTTP server.
+ * Matches the styling of the Python and Go implementations.
+ */
+import type { MethodDefinition } from "../types.js";
+export declare function buildLandingPage(protocolName: string, serverId: string, describePath: string | null, repoUrl: string | null): string;
+export declare function buildNotFoundPage(prefix: string, protocolName: string): string;
+export declare function buildDescribePage(protocolName: string, serverId: string, methods: Map<string, MethodDefinition>, repoUrl: string | null): string;
+//# sourceMappingURL=pages.d.ts.map

package/dist/http/pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../src/http/pages.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA8BpD,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,GACrB,MAAM,CA2DR;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CA8B9E;AA4ED,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACtC,OAAO,EAAE,MAAM,GAAG,IAAI,GACrB,MAAM,CA8ER"}

package/dist/http/types.d.ts

@@ -1,6 +1,9 @@
+import type { ExternalLocationConfig } from "../external.js";
+import type { DispatchHook } from "../types.js";
+import type { AuthenticateFn, OAuthResourceMetadata } from "./auth.js";
 /** Configuration options for createHttpHandler(). */
 export interface HttpHandlerOptions {
-    /** URL path prefix for all endpoints. Default: "/vgi" */
+    /** URL path prefix for all endpoints. Default: "" (root). */
     prefix?: string;
     /** HMAC-SHA256 signing key for state tokens. Random 32 bytes if omitted. */
     signingKey?: Uint8Array;
@@ -19,6 +22,24 @@ 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;
+    /** Optional dispatch hook for observability (tracing, metrics). */
+    dispatchHook?: DispatchHook;
+    /** Enable HTML landing page at GET {prefix}/. Default: true. */
+    enableLandingPage?: boolean;
+    /** Enable HTML describe/API reference page at GET {prefix}/describe. Default: true. */
+    enableDescribePage?: boolean;
+    /** Enable HTML 404 page for unmatched GET routes. Default: true. */
+    enableNotFoundPage?: boolean;
+    /** Protocol name shown in HTML pages. Defaults to the Protocol's name. */
+    protocolName?: string;
+    /** URL to service's source repository, shown in landing/describe pages. */
+    repositoryUrl?: string;
+    /** External storage config for externalizing large response batches. */
+    externalLocation?: ExternalLocationConfig;
 }
 /** Serializer for stream state objects stored in state tokens. */
 export interface StateSerializer {

package/dist/http/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/http/types.ts"],"names":[],"mappings":"AAGA,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;kEAC8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,UAAU,CAAC;IAClC,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,CAAC;CACrC;AAED,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,EAAE,eAWjC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/http/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAEvE,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;kEAC8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,0FAA0F;IAC1F,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,mEAAmE;IACnE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oEAAoE;IACpE,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C;AAED,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,UAAU,CAAC;IAClC,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,CAAC;CACrC;AAED,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,EAAE,eAWjC,CAAC"}

package/dist/index.d.ts

@@ -1,9 +1,11 @@
+export { AuthContext } from "./auth.js";
 export * from "./client/index.js";
 export { DESCRIBE_METHOD_NAME, DESCRIBE_VERSION, DESCRIBE_VERSION_KEY, LOG_EXTRA_KEY, LOG_LEVEL_KEY, LOG_MESSAGE_KEY, PROTOCOL_NAME_KEY, REQUEST_ID_KEY, REQUEST_VERSION, REQUEST_VERSION_KEY, RPC_METHOD_KEY, SERVER_ID_KEY, STATE_KEY, } from "./constants.js";
 export { RpcError, VersionError } from "./errors.js";
-export { ARROW_CONTENT_TYPE, createHttpHandler, type HttpHandlerOptions, jsonStateSerializer, type StateSerializer, type UnpackedToken, unpackStateToken, } from "./http/index.js";
+export { type ExternalLocationConfig, type ExternalStorage, httpsOnlyValidator, isExternalLocationBatch, makeExternalLocationBatch, maybeExternalizeBatch, resolveExternalLocation, } from "./external.js";
+export { ARROW_CONTENT_TYPE, type AuthenticateFn, type BearerValidateFn, bearerAuthenticate, bearerAuthenticateStatic, type CertValidateFn, chainAuthenticate, createHttpHandler, type HttpHandlerOptions, type JwtAuthenticateOptions, jsonStateSerializer, jwtAuthenticate, mtlsAuthenticate, mtlsAuthenticateFingerprint, mtlsAuthenticateSubject, mtlsAuthenticateXfcc, type OAuthResourceMetadata, oauthResourceMetadataToJson, parseXfcc, type StateSerializer, type UnpackedToken, unpackStateToken, type XfccElement, type XfccValidateFn, } from "./http/index.js";
 export { Protocol } from "./protocol.js";
 export { bool, bytes, float, float32, inferParamTypes, int, int32, type SchemaLike, str, toSchema, } from "./schema.js";
 export { VgiRpcServer } from "./server.js";
-export { type ExchangeFn, type ExchangeInit, type HeaderInit, type LogContext, type MethodDefinition, MethodType, OutputCollector, type ProducerFn, type ProducerInit, type UnaryHandler, } from "./types.js";
+export { type CallContext, type CallStatistics, type DispatchHook, type DispatchInfo, type ExchangeFn, type ExchangeInit, type HeaderInit, type HookToken, type LogContext, type MethodDefinition, MethodType, OutputCollector, type ProducerFn, type ProducerInit, type UnaryHandler, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,SAAS,GACV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,IAAI,EACJ,KAAK,EACL,KAAK,EACL,OAAO,EACP,eAAe,EACf,GAAG,EACH,KAAK,EACL,KAAK,UAAU,EACf,GAAG,EACH,QAAQ,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,UAAU,EACV,eAAe,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,SAAS,GACV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,EACzB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,kBAAkB,EAClB,wBAAwB,EACxB,KAAK,cAAc,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,2BAA2B,EAC3B,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,2BAA2B,EAC3B,SAAS,EACT,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,IAAI,EACJ,KAAK,EACL,KAAK,EACL,OAAO,EACP,eAAe,EACf,GAAG,EACH,KAAK,EACL,KAAK,UAAU,EACf,GAAG,EACH,QAAQ,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,UAAU,EACV,eAAe,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC"}