@query-farm/vgi-rpc 0.6.4 → 0.7.1

package/dist/http/common.d.ts

@@ -1,16 +1,52 @@
-import { type RecordBatch, type Schema } from "@query-farm/apache-arrow";
+import { type VgiBatch, type VgiSchema } from "../arrow/index.js";
+import type { CookieSpec } from "../types.js";
+/** MIME type for Arrow IPC stream request and response bodies. */
 export declare const ARROW_CONTENT_TYPE = "application/vnd.apache.arrow.stream";
+export declare const SESSION_HEADER = "VGI-Session";
+export declare const SESSION_ACCEPT_HEADER = "VGI-Session-Accept";
+export declare const SESSION_CLOSE_HEADER = "VGI-Session-Close";
+export declare const STICKY_ENABLED_HEADER = "VGI-Sticky-Enabled";
+export declare const STICKY_DEFAULT_TTL_HEADER = "VGI-Sticky-Default-TTL";
+export declare const STICKY_ECHO_HEADERS_HEADER = "VGI-Sticky-Echo-Headers";
+/** Prefix the server uses to tell the client "echo this header on subsequent
+ *  requests in this session". Clients capture and replay
+ *  `VGI-Echo-<name>: <value>` as plain `<name>: <value>` for the session
+ *  lifetime — used for client-driven routing (e.g. `fly-force-instance-id`). */
+export declare const ECHO_HEADER_PREFIX = "VGI-Echo-";
+/** Framework-managed sticky session teardown endpoint path component.
+ *  `DELETE {prefix}/__session__` idempotently closes the session referenced
+ *  by the request's `VGI-Session` header. */
+export declare const SESSION_ENDPOINT = "__session__";
+/** Serialize a CookieSpec into a Set-Cookie header value. */
+export declare function formatSetCookieHeader(c: CookieSpec): string;
+/** Append Set-Cookie headers for each queued CookieSpec onto an existing Headers object. */
+export declare function appendCookieHeaders(headers: Headers, cookies: readonly CookieSpec[]): void;
 export declare class HttpRpcError extends Error {
     readonly statusCode: number;
     constructor(message: string, statusCode: number);
 }
-/** Serialize a schema + batches into a complete IPC stream as Uint8Array. */
-export declare function serializeIpcStream(schema: Schema, batches: RecordBatch[]): Uint8Array;
-/** Create a Response with Arrow IPC content type. Casts Uint8Array for TS lib compat. */
+/**
+ * Serialize a schema + batches into a complete IPC stream as Uint8Array.
+ *
+ * A single IPC stream is `[schema_msg, batch_msg, batch_msg, ..., EOS]`.
+ * Each backend implements `serializeBatches` to write that atomically —
+ * arrow-js via `RecordBatchStreamWriter`, flechette via `tablesToIPC`
+ * (added in our flechette fork). Naive concatenation of per-batch streams
+ * produces multiple EOS markers and breaks readers.
+ */
+export declare function serializeIpcStream(schema: VgiSchema, batches: VgiBatch[]): Uint8Array;
+/**
+ * Create a Response with Arrow IPC content type.
+ *
+ * Server errors (status 500) are translated to HTTP 200 with an
+ * ``X-VGI-RPC-Error: true`` header so that clients which discard
+ * response bodies on 5xx still receive the Arrow IPC error metadata.
+ * Client errors (400, 401, 404, 415) are passed through unchanged.
+ */
 export declare function arrowResponse(body: Uint8Array, status?: number, extraHeaders?: Headers): Response;
-/** Read schema + first batch from an IPC stream body. */
+/** Read schema + first batch from an IPC stream body via the facade. */
 export declare function readRequestFromBody(body: Uint8Array): Promise<{
-    schema: Schema;
-    batch: RecordBatch;
+    schema: VgiSchema;
+    batch: VgiBatch;
 }>;
 //# sourceMappingURL=common.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/http/common.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,WAAW,EAA8C,KAAK,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAGrH,eAAO,MAAM,kBAAkB,wCAAwC,CAAC;AAExE,qBAAa,YAAa,SAAQ,KAAK;aAGnB,UAAU,EAAE,MAAM;gBADlC,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM;CAKrC;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,UAAU,CAQrF;AAED,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,SAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,QAAQ,CAI9F;AAED,yDAAyD;AACzD,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC,CAY3G"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/http/common.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,QAAQ,EACb,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,kEAAkE;AAClE,eAAO,MAAM,kBAAkB,wCAAwC,CAAC;AAKxE,eAAO,MAAM,cAAc,gBAAgB,CAAC;AAC5C,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAC1D,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AACxD,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAC1D,eAAO,MAAM,yBAAyB,2BAA2B,CAAC;AAClE,eAAO,MAAM,0BAA0B,4BAA4B,CAAC;AAEpE;;;gFAGgF;AAChF,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAE9C;;6CAE6C;AAC7C,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAE9C,6DAA6D;AAC7D,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAiB3D;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAI1F;AAED,qBAAa,YAAa,SAAQ,KAAK;aAGnB,UAAU,EAAE,MAAM;gBADlC,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM;CAKrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,UAAU,CAGrF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,SAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,QAAQ,CAQ9F;AAED,wEAAwE;AACxE,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC,CAU3G"}

package/dist/http/dispatch.d.ts

@@ -1,18 +1,36 @@
 import type { AuthContext } from "../auth.js";
 import { type ExternalLocationConfig } from "../external.js";
 import type { MethodDefinition } from "../types.js";
+import { TransportKind } from "../types.js";
 import type { StateSerializer } from "./types.js";
 export interface DispatchContext {
-    signingKey: Uint8Array;
+    tokenKey: Uint8Array;
     tokenTtl: number;
     serverId: string;
+    /** Producer-only soft wire-cap (deprecated alias for the producer-loop
+     *  byte budget). Unary/exchange ignore this. */
     maxStreamResponseBytes?: number;
+    /** Soft wire-cap for producer streams; hard wire-cap for unary/exchange.
+     *  Externalised payloads do not count toward this. */
+    maxResponseBytes?: number;
+    /** Hard cap on bytes uploaded to external storage during one HTTP response. */
+    maxExternalizedResponseBytes?: number;
     stateSerializer: StateSerializer;
     authContext?: AuthContext;
     externalLocation?: ExternalLocationConfig;
+    /** Incoming HTTP request cookies.  Empty/absent on non-HTTP paths. */
+    cookies?: ReadonlyMap<string, string>;
+    /** Transport identifier surfaced to handlers via CallContext.kind.
+     *  Defaults to HTTP when unset (the only caller that overrides it is
+     *  the AF_UNIX launcher path). */
+    kind?: TransportKind;
+    /** Per-request sticky-session sink. Installed by the handler when sticky
+     *  is enabled and the dispatcher attaches it to the OutputCollector so
+     *  `ctx.session` / `ctx.openSession` / `ctx.closeSession` work. */
+    stickyContext?: import("../types.js").StickyContext;
 }
 /** Dispatch a __describe__ request. */
-export declare function httpDispatchDescribe(protocolName: string, methods: Map<string, MethodDefinition>, serverId: string): Response;
+export declare function httpDispatchDescribe(protocolName: string, methods: Map<string, MethodDefinition>, serverId: string, protocolVersion?: string): Promise<Response>;
 /** Dispatch a unary HTTP request. */
 export declare function httpDispatchUnary(method: MethodDefinition, body: Uint8Array, ctx: DispatchContext): Promise<Response>;
 /** Dispatch a stream init HTTP request (producer or exchange). */

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

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/http/dispatch.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,OAAO,EAAE,KAAK,sBAAsB,EAAyB,MAAM,gBAAgB,CAAC;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAQpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAUlD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,eAAe,EAAE,eAAe,CAAC;IACjC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C;AAED,uCAAuC;AACvC,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACtC,QAAQ,EAAE,MAAM,GACf,QAAQ,CAIV;AAED,qCAAqC;AACrC,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,QAAQ,CAAC,CA0BnB;AAED,kEAAkE;AAClE,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,QAAQ,CAAC,CA2EnB;AAED,yFAAyF;AACzF,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,QAAQ,CAAC,CAqHnB"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/http/dispatch.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,OAAO,EACL,KAAK,sBAAsB,EAI5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAM7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAQlD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,UAAU,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB;oDACgD;IAChD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;0DACsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,eAAe,EAAE,eAAe,CAAC;IACjC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,sEAAsE;IACtE,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC;;sCAEkC;IAClC,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;uEAEmE;IACnE,aAAa,CAAC,EAAE,OAAO,aAAa,EAAE,aAAa,CAAC;CACrD;AA2BD,uCAAuC;AACvC,wBAAsB,oBAAoB,CACxC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACtC,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,QAAQ,CAAC,CAInB;AAED,qCAAqC;AACrC,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,QAAQ,CAAC,CA+FnB;AAED,kEAAkE;AAClE,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,QAAQ,CAAC,CAmGnB;AAED,yFAAyF;AACzF,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,QAAQ,CAAC,CAqMnB"}

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

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/http/handler.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAa/C,OAAO,EAAE,KAAK,kBAAkB,EAAuB,MAAM,YAAY,CAAC;AAI1E;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsSpD"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/http/handler.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAoD/C,OAAO,EAAE,KAAK,kBAAkB,EAAuB,MAAM,YAAY,CAAC;AAwB1E;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAo7BpD"}

package/dist/http/index.d.ts

@@ -8,6 +8,7 @@ export type { JwtAuthenticateOptions } from "./jwt.js";
 export { jwtAuthenticate } from "./jwt.js";
 export type { CertValidateFn, XfccElement, XfccValidateFn } from "./mtls.js";
 export { mtlsAuthenticate, mtlsAuthenticateFingerprint, mtlsAuthenticateSubject, mtlsAuthenticateXfcc, parseXfcc, } from "./mtls.js";
+export { cookieAuthenticate } from "./oauth-pkce.js";
 export { type UnpackedToken, unpackStateToken } from "./token.js";
 export type { HttpHandlerOptions, StateSerializer } from "./types.js";
 export { jsonStateSerializer } from "./types.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,2BAA2B,EAAE,MAAM,WAAW,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,uBAAuB,EACvB,oBAAoB,EACpB,SAAS,GACV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,2BAA2B,EAAE,MAAM,WAAW,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,uBAAuB,EACvB,oBAAoB,EACpB,SAAS,GACV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,KAAK,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/http/jwt.d.ts

@@ -1,4 +1,5 @@
 import type { AuthenticateFn } from "./auth.js";
+/** Options for {@link jwtAuthenticate}, configuring JWT Bearer-token validation. */
 export interface JwtAuthenticateOptions {
     /** The expected `iss` claim (also used to discover AS metadata). */
     issuer: string;

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

@@ -1 +1 @@
-{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/http/jwt.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,cAAc,CAqD/E"}
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/http/jwt.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,oFAAoF;AACpF,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,cAAc,CAqD/E"}

package/dist/http/mtls.d.ts

@@ -1,13 +1,20 @@
-import { X509Certificate } from "node:crypto";
 import { AuthContext } from "../auth.js";
 import type { AuthenticateFn } from "./auth.js";
+type X509Certificate = any;
 /** A single element from an `x-forwarded-client-cert` header. */
 export interface XfccElement {
+    /** Hex SHA-256 digest of the client certificate (`Hash` key). */
     hash: string | null;
+    /** URL-decoded PEM of the client certificate (`Cert` key), if the proxy
+     *  forwarded it. */
     cert: string | null;
+    /** Certificate Subject DN (`Subject` key). */
     subject: string | null;
+    /** URL-decoded URI-type Subject Alternative Name (`URI` key). */
     uri: string | null;
+    /** DNS-type Subject Alternative Names (`DNS` keys); may repeat in the header. */
     dns: readonly string[];
+    /** URL-decoded URI of the proxy that presented the cert (`By` key). */
     by: string | null;
 }
 /** Receives a parsed XFCC element, returns an AuthContext on success. Must throw on failure. */
@@ -75,4 +82,5 @@ export declare function mtlsAuthenticateSubject(options?: {
     allowedSubjects?: ReadonlySet<string> | null;
     checkExpiry?: boolean;
 }): AuthenticateFn;
+export {};
 //# sourceMappingURL=mtls.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"mtls.d.ts","sourceRoot":"","sources":["../../src/http/mtls.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMhD,KAAK,eAAe,GAAG,GAAG,CAAC;AAc3B,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;wBACoB;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iEAAiE;IACjE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,iFAAiF;IACjF,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IACvB,uEAAuE;IACvE,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;AAmCD;;;;;;;;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,CAmBjB;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/oauth-pkce.d.ts

@@ -0,0 +1,141 @@
+import type { AuthenticateFn } from "./auth.js";
+/** Generate a 43-character URL-safe random code verifier (RFC 7636 S4.1). */
+export declare function generateCodeVerifier(): string;
+/** Compute S256 code challenge from a code verifier (RFC 7636 S4.2). */
+export declare function generateCodeChallenge(verifier: string): string;
+/** Generate a random state nonce for CSRF protection. */
+export declare function generateStateNonce(): string;
+/** Derive a separate HMAC key for OAuth session cookies. */
+export declare function deriveSessionKey(signingKey: Uint8Array): Uint8Array;
+/**
+ * Pack PKCE session data into a signed, base64-encoded cookie value.
+ *
+ * Wire format v4:
+ *   [1B version=4] [8B created_at uint64 LE]
+ *   [2B cv_len uint16 LE] [cv_len bytes code_verifier]
+ *   [2B state_len uint16 LE] [state_len bytes state_nonce]
+ *   [2B url_len uint16 LE] [url_len bytes original_url]
+ *   [2B rt_len uint16 LE] [rt_len bytes return_to]
+ *   [32B HMAC-SHA256(session_key, all above)]
+ */
+export declare function packOAuthCookie(codeVerifier: string, stateNonce: string, originalUrl: string, sessionKey: Uint8Array, createdAt?: number, returnTo?: string): string;
+export interface UnpackedOAuthCookie {
+    codeVerifier: string;
+    stateNonce: string;
+    originalUrl: string;
+    returnTo: string;
+}
+/**
+ * Unpack and verify a signed OAuth session cookie.
+ *
+ * @throws Error on tampered, expired, or malformed cookies.
+ */
+export declare function unpackOAuthCookie(cookieValue: string, sessionKey: Uint8Array, maxAge?: number): UnpackedOAuthCookie;
+export interface OidcEndpoints {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+}
+/**
+ * Create a lazy-cached OIDC discovery function.
+ *
+ * Caches the Promise; resets on rejection so a transient failure is retried.
+ */
+export declare function createOidcDiscovery(issuer: string): () => Promise<OidcEndpoints | null>;
+export interface TokenExchangeResult {
+    token: string;
+    maxAge: number;
+    refreshToken: string | null;
+}
+/** Exchange an authorization code for a token via the token endpoint. */
+export declare function exchangeCodeForToken(tokenEndpoint: string, code: string, redirectUri: string, codeVerifier: string, clientId: string, clientSecret?: string, useIdToken?: boolean): Promise<TokenExchangeResult>;
+/** Validate the original URL is relative and within the expected prefix. */
+export declare function validateOriginalUrl(url: string, prefix: string): string;
+/** Validate an external return-to URL against an origin allowlist. */
+export declare function validateReturnTo(url: string, allowedOrigins?: ReadonlySet<string>): string;
+/** Parse the Cookie header from a Request into a Map. */
+export declare function parseCookies(request: Request): Map<string, string>;
+interface SetCookieOptions {
+    maxAge?: number;
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+}
+/** Build a Set-Cookie header string. */
+export declare function buildSetCookieHeader(name: string, value: string, options: SetCookieOptions): string;
+/** Render a user-friendly OAuth error page. */
+export declare function buildOAuthErrorPage(message: string, detail: string | null, retryUrl: string): string;
+/** Return HTML snippet (style + div + script) for user info display. */
+export declare function buildUserInfoHtml(prefix: string): string;
+/**
+ * Create an authenticate callback that reads a bearer token from a cookie.
+ *
+ * Extracts the token from the named cookie and delegates validation to the
+ * `innerAuth` authenticator by creating a new Request with an Authorization header.
+ */
+export declare function cookieAuthenticate(innerAuth: AuthenticateFn, cookieName?: string): AuthenticateFn;
+/** Configuration object produced by configureOAuthPkce. */
+export interface OAuthPkceConfig {
+    sessionKey: Uint8Array;
+    oidcDiscovery: () => Promise<OidcEndpoints | null>;
+    clientId: string;
+    clientSecret: string | undefined;
+    useIdToken: boolean;
+    prefix: string;
+    secureCookie: boolean;
+    redirectUri: string;
+    scope: string;
+    allowedReturnOrigins: ReadonlySet<string>;
+    cookieAuthenticate: AuthenticateFn;
+    userInfoHtml: string;
+}
+/** Options for configureOAuthPkce. */
+export interface OAuthPkceOptions {
+    signingKey: Uint8Array;
+    issuer: string;
+    clientId: string;
+    clientSecret?: string;
+    useIdToken?: boolean;
+    prefix: string;
+    secureCookie: boolean;
+    redirectUri: string;
+    scope?: string;
+    allowedReturnOrigins?: ReadonlySet<string>;
+}
+/**
+ * Resolve the OAuth PKCE `scope` string from available sources.
+ *
+ * Precedence:
+ *   1. `scopesSupported` from OAuth resource metadata (space-joined), when non-empty.
+ *   2. Explicit `optionsScope` override (e.g. `HttpHandlerOptions.oauthPkceScope`).
+ *   3. `undefined`, which lets `configureOAuthPkce` apply its built-in default of
+ *      `"openid email"`.
+ *
+ * Mirrors the Python reference behavior introduced in vgi-rpc v0.6.12: authorization
+ * requests should use the scopes the server publishes in its protected resource
+ * metadata, so clients ask for exactly what the resource advertises.
+ */
+export declare function resolvePkceScope(scopesSupported: readonly string[] | undefined, optionsScope: string | undefined): string | undefined;
+/** Factory function wiring all PKCE components. */
+export declare function configureOAuthPkce(opts: OAuthPkceOptions, innerAuth: AuthenticateFn): OAuthPkceConfig;
+/**
+ * Handle POST/OPTIONS {prefix}/_oauth/token — the PKCE token-exchange proxy.
+ *
+ * SPA PKCE clients cannot safely hold a client_secret, but some IdPs
+ * (notably Google) reject token-endpoint requests from "Web application"
+ * clients without one. This handler accepts authorization_code/refresh_token
+ * exchanges from a browser, injects the configured server-side
+ * client_secret, and forwards the request to the IdP's real token_endpoint.
+ * The IdP response is returned verbatim (status code + body).
+ */
+export declare function handleOAuthTokenProxy(request: Request, config: OAuthPkceConfig): Promise<Response>;
+/** Handle GET {prefix}/_oauth/callback — the redirect from the authorization server. */
+export declare function handleOAuthCallback(request: Request, config: OAuthPkceConfig): Promise<Response>;
+/** Handle GET {prefix}/_oauth/logout — clear auth cookie and redirect. */
+export declare function handleOAuthLogout(_request: Request, config: OAuthPkceConfig): Response;
+/** Redirect an unauthenticated browser GET to the OAuth authorization endpoint. Returns null if unable. */
+export declare function handleBrowserGetRedirect(request: Request, config: OAuthPkceConfig): Promise<Response | null>;
+/** If user is already authenticated and has _vgi_return_to, redirect immediately. Returns null otherwise. */
+export declare function handleEarlyReturnTo(request: Request, config: OAuthPkceConfig): Response | null;
+export {};
+//# sourceMappingURL=oauth-pkce.d.ts.map

package/dist/http/oauth-pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-pkce.d.ts","sourceRoot":"","sources":["../../src/http/oauth-pkce.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AA2ChD,6EAA6E;AAC7E,wBAAgB,oBAAoB,IAAI,MAAM,CAG7C;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAMD,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAEnE;AAsBD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAsCR;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,MAAM,GAAE,MAAwB,GAC/B,mBAAmB,CAwDrB;AAMD,MAAM,WAAW,aAAa;IAC5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAqBvF;AAMD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,yEAAyE;AACzE,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,EACrB,UAAU,CAAC,EAAE,OAAO,GACnB,OAAO,CAAC,mBAAmB,CAAC,CAwD9B;AAMD,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAsBvE;AAMD,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,CAsB1F;AAMD,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAYlE;AAED,UAAU,gBAAgB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;CACtC;AAED,wCAAwC;AACxC,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAQnG;AAUD,+CAA+C;AAC/C,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAwBpG;AAyCD,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOxD;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,cAAc,EAAE,UAAU,GAAE,MAAyB,GAAG,cAAc,CAgBnH;AAMD,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,UAAU,CAAC;IACvB,aAAa,EAAE,MAAM,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,kBAAkB,EAAE,cAAc,CAAC;IACnC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oBAAoB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAC9C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAKpB;AAED,mDAAmD;AACnD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,EAAE,SAAS,EAAE,cAAc,GAAG,eAAe,CAiBrG;AAuCD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAmFxG;AAMD,wFAAwF;AACxF,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6HtG;AAMD,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,GAAG,QAAQ,CAetF;AAMD,2GAA2G;AAC3G,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA+DlH;AAMD,6GAA6G;AAC7G,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,GAAG,QAAQ,GAAG,IAAI,CAmC9F"}

package/dist/http/pages.d.ts

@@ -3,6 +3,9 @@
  * Matches the styling of the Python and Go implementations.
  */
 import type { MethodDefinition } from "../types.js";
+export declare const LOGO_URL = "https://vgi-rpc-python.query.farm/assets/logo-hero.png";
+export declare const FONTS = "<link rel=\"preconnect\" href=\"https://fonts.googleapis.com\">\n<link rel=\"preconnect\" href=\"https://fonts.gstatic.com\" crossorigin>\n<link href=\"https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&family=JetBrains+Mono:wght@400;600&display=swap\" rel=\"stylesheet\">";
+export declare const ERROR_PAGE_STYLE = "<style>\nbody { font-family: 'Inter', system-ui, -apple-system, sans-serif; max-width: 600px;\n       margin: 0 auto; padding: 60px 20px 0; color: #2c2c1e; text-align: center;\n       background: #faf8f0; }\n.logo { margin-bottom: 24px; }\n.logo img { width: 120px; height: 120px; border-radius: 50%;\n             box-shadow: 0 4px 24px rgba(0,0,0,0.12); }\nh1 { color: #2d5016; margin-bottom: 8px; font-weight: 700; }\ncode { font-family: 'JetBrains Mono', monospace; background: #f0ece0;\n        padding: 2px 6px; border-radius: 3px; font-size: 0.9em; color: #2c2c1e; }\na { color: #2d5016; text-decoration: none; }\na:hover { color: #4a7c23; }\np { line-height: 1.7; color: #6b6b5a; }\n.detail { margin-top: 12px; padding: 12px 16px; background: #f0ece0;\n           border-radius: 6px; font-size: 0.9em; color: #6b6b5a; }\nfooter { margin-top: 48px; padding: 20px 0; border-top: 1px solid #f0ece0;\n          color: #6b6b5a; font-size: 0.85em; line-height: 1.8; }\nfooter a { color: #2d5016; font-weight: 600; }\nfooter a:hover { color: #4a7c23; }\n</style>";
 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;

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

@@ -1 +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"}
+{"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;AAEpD,eAAO,MAAM,QAAQ,2DAA2D,CAAC;AAEjF,eAAO,MAAM,KAAK,kSAE6H,CAAC;AAEhJ,eAAO,MAAM,gBAAgB,4iCAmBpB,CAAC;AAwBV,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,CAwB9E;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/sticky.d.ts

@@ -0,0 +1,124 @@
+/** Seal a sticky-session token. Returns the base64url-encoded value for the
+ *  `VGI-Session` header. */
+export declare function sealSessionToken(serverId: string, sessionId: Uint8Array, expiresAt: number, tokenKey: Uint8Array, aad: Uint8Array, now?: number): string;
+export interface OpenedSessionToken {
+    serverId: string;
+    sessionId: Uint8Array;
+    expiresAt: number;
+}
+/** Open a sticky-session token. Raises {@link SessionLostError} on any failure
+ *  — wrong AAD (cross-principal replay) is indistinguishable from garbage. */
+export declare function openSessionToken(token: string, tokenKey: Uint8Array, aad: Uint8Array): OpenedSessionToken;
+/** Minimal promise-based mutex. The HTTP handler awaits `acquire()` before
+ *  dispatching on a resumed session and calls the returned release in a
+ *  `finally` so concurrent calls on the same session run sequentially. */
+declare class AsyncMutex {
+    private locked;
+    private waiters;
+    acquire(): Promise<() => void>;
+    private release;
+}
+/** A live session in the per-worker registry. */
+export interface SessionEntry {
+    state: unknown;
+    expiresAt: number;
+    principalKey: string;
+    lock: AsyncMutex;
+}
+/**
+ * Derive the registry partition key for a request principal.
+ *
+ * Both the dispatch path and the `DELETE /__session__` teardown path MUST
+ * compute this identically — otherwise a session opened on one path can't
+ * be looked up on the other. The NUL separator (rather than a space)
+ * keeps `{domain:"a", principal:"b "}` from colliding with
+ * `{domain:"a ", principal:"b"}`. Anonymous requests collapse to a
+ * single sentinel.
+ *
+ * `domain` / `principal` are the authenticated identity fields, or
+ * null/undefined for anonymous.
+ */
+export declare function sessionPrincipalKey(authenticated: boolean, domain: string | null | undefined, principal: string | null | undefined): string;
+/** Hex-encode a session_id Uint8Array (24-char lowercase hex). */
+export declare function sessionIdHex(sessionId: Uint8Array): string;
+/** Per-worker in-process map of live sticky sessions. */
+export declare class SessionRegistry {
+    readonly defaultTtl: number;
+    private entries;
+    private _draining;
+    constructor(defaultTtl: number);
+    get draining(): boolean;
+    setDraining(value: boolean): void;
+    /** Register a session. Throws {@link ServerDrainingError} when draining. */
+    open(state: unknown, ttl: number | undefined, principalKey: string): {
+        sessionId: Uint8Array;
+        expiresAt: number;
+    };
+    /** Look up a session. Returns null on miss, expiry, or principal mismatch.
+     *  Expired entries are evicted in-line (and `state.close?.()` invoked). */
+    get(sessionId: Uint8Array, principalKey: string): SessionEntry | null;
+    /** Remove a session and invoke `state.close?.()`. Returns true on hit. */
+    close(sessionId: Uint8Array): boolean;
+    /** Evict every entry past its TTL. Returns the eviction count. */
+    drainExpired(now?: number): number;
+    /** Invoke `state.close?.()` on every live session and clear the registry. */
+    shutdown(): void;
+    get size(): number;
+}
+/** Start a periodic reaper that evicts expired sessions. Returns a stop fn.
+ *  Uses `setInterval().unref()` where available so the reaper does not keep
+ *  the process alive. */
+export declare function startSessionReaper(registry: SessionRegistry, tickMs?: number): () => void;
+/** Per-request handle that the HTTP handler installs on the OutputCollector.
+ *  `CallContext.openSession` / `closeSession` / `session` read and mutate
+ *  this object; the handler then emits the resulting headers on the
+ *  response. */
+export interface StickySink {
+    /** True iff the request carried `VGI-Session-Accept: true`. */
+    acceptOpens: boolean;
+    /** Live session state (resumed or just-opened). Null until `openSession`
+     *  or a successful resume populates it. */
+    state: unknown | null;
+    /** Hex session_id for the access log. Populated on resume + open;
+     *  preserved across `closeSession` so close records still carry the id. */
+    sessionId: string | null;
+    /** Set by `openSession` so `process_response` emits `VGI-Session: <token>`. */
+    mintToken: string | null;
+    /** Set by `closeSession` so `process_response` emits `VGI-Session-Close: true`. */
+    closed: boolean;
+    /** Sticky-session lifecycle action observed during dispatch — one of
+     *  "none" / "resume" / "open" / "close". Surfaced on the access log. */
+    action: "none" | "resume" | "open" | "close";
+    /** Bound by the handler: registers `state` in the registry, mints the
+     *  AEAD-sealed token, and stamps `mintToken` + `sessionId`. */
+    _open(state: unknown, ttl: number | undefined): void;
+    /** Bound by the handler: removes the registry entry + invokes
+     *  `state.close?.()`. Idempotent. */
+    _close(): void;
+}
+/** Build a `StickySink` for a request without sticky support — `_open` /
+ *  `_close` throw the same RuntimeError shape as Python's implementation so
+ *  call sites get a clear message. */
+export declare function unavailableStickySink(): StickySink;
+/** Operator-facing handle returned by `createHttpHandler` (when sticky is
+ *  enabled) so SIGTERM hooks / worker-exit hooks can drain in-flight
+ *  sessions cleanly. Mirrors Python's `DrainHandle`. */
+export interface DrainHandle {
+    /** Flip the registry's drain flag — subsequent `ctx.openSession` raises
+     *  {@link ServerDrainingError}. Existing sessions continue. */
+    drain(): void;
+    /** Invoke `state.close?.()` on every live session and clear the registry. */
+    shutdown(): void;
+    /** Return whether `drain()` has been invoked. */
+    isDraining(): boolean;
+    /** Test-only / advanced: flip the drain flag back. Production deployments
+     *  only ever drain in one direction; conformance tests use this to clean
+     *  up the fixture between tests. */
+    setDraining(value: boolean): void;
+}
+/** Build a {@link DrainHandle} for *registry*. `stopReaper`, when supplied,
+ *  is invoked by `shutdown()` so the periodic reaper interval is cleared and
+ *  the handle fully releases its resources. */
+export declare function makeDrainHandle(registry: SessionRegistry, stopReaper?: () => void): DrainHandle;
+export {};
+//# sourceMappingURL=sticky.d.ts.map

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

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

package/dist/http/token.d.ts

@@ -1,24 +1,55 @@
 /**
- * Pack a state token matching the Python v2 wire format.
+ * Build the AEAD associated data that binds a state token to its issuing
+ * principal. Anonymous and authenticated tokens produce distinct AAD
+ * strings, so an anonymous token cannot be opened by a named identity
+ * (and vice versa).
+ */
+export declare function computeAad(principal: string | null | undefined): Uint8Array;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(b64: string): Uint8Array;
+/**
+ * Seal a state token with XChaCha20-Poly1305 AEAD (v4 wire format).
+ *
+ * Layout (base64-encoded):
  *
- * Layout:
- *   [1B version=2]
- *   [8B created_at uint64 LE (seconds since epoch)]
- *   [4B state_len uint32 LE] [state_len bytes]
- *   [4B schema_len uint32 LE] [schema_len bytes]
- *   [4B input_schema_len uint32 LE] [input_schema_len bytes]
- *   [32B HMAC-SHA256(signing_key, all above bytes)]
+ * ```
+ *   [1B  version=4]
+ *   [24B XChaCha20-Poly1305 nonce (random)]
+ *   [..  ciphertext + 16B Poly1305 tag]
+ *        plaintext:
+ *          [8B  created_at uint64 LE]
+ *          [4B  state_len uint32 LE]   [state_len bytes]
+ *          [4B  schema_len uint32 LE]  [schema_len bytes]
+ *          [4B  input_schema_len LE]   [input_schema_len bytes]
+ * ```
+ *
+ * `created_at` lives inside the ciphertext so TTL enforcement runs after
+ * authenticity. The version byte is informational (a self-describing
+ * format marker); a tampered version byte still fails decryption because
+ * we use the matching algorithm for that version. `principal` is bound
+ * via AEAD associated data so a token minted for one identity fails
+ * decryption when presented by another.
  */
-export declare function packStateToken(stateBytes: Uint8Array, schemaBytes: Uint8Array, inputSchemaBytes: Uint8Array, signingKey: Uint8Array, createdAt?: number): string;
+export declare function packStateToken(stateBytes: Uint8Array, schemaBytes: Uint8Array, inputSchemaBytes: Uint8Array, tokenKey: Uint8Array, principal: string | null | undefined, createdAt?: number): string;
+/** Decrypted payload of a state token, as returned by {@link unpackStateToken}. */
 export interface UnpackedToken {
+    /** Serialized stream-state bytes carried by the token. */
     stateBytes: Uint8Array;
+    /** Serialized output-schema IPC bytes. */
     schemaBytes: Uint8Array;
+    /** Serialized input-schema IPC bytes (exchange streams). */
     inputSchemaBytes: Uint8Array;
+    /** Unix epoch seconds at which the token was minted (used for TTL checks). */
     createdAt: number;
 }
 /**
- * Unpack and verify a state token.
- * Throws on tampered, expired, or malformed tokens.
+ * Open and verify a state token. Decryption (which checks the Poly1305
+ * tag) authenticates the payload; any tampering, wrong key, or AAD
+ * mismatch (e.g. cross-principal replay) surfaces as a uniform
+ * "signature verification failed" error so callers cannot distinguish
+ * failure modes via timing or message content.
+ *
+ * Throws on tampered, expired, malformed, or unknown-version tokens.
  */
-export declare function unpackStateToken(tokenBase64: string, signingKey: Uint8Array, tokenTtl: number): UnpackedToken;
+export declare function unpackStateToken(tokenBase64: string, tokenKey: Uint8Array, tokenTtl: number, principal: string | null | undefined): UnpackedToken;
 //# sourceMappingURL=token.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/http/token.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,UAAU,EACvB,gBAAgB,EAAE,UAAU,EAC5B,UAAU,EAAE,UAAU,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAsCR;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,UAAU,CAAC;IACxB,gBAAgB,EAAE,UAAU,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAiE7G"}
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/http/token.ts"],"names":[],"mappings":"AAWA;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,UAAU,CAU3E;AAMD,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAMvD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAKrD;AAiCD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,UAAU,EACvB,gBAAgB,EAAE,UAAU,EAC5B,QAAQ,EAAE,UAAU,EACpB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CA8BR;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,UAAU,EAAE,UAAU,CAAC;IACvB,0CAA0C;IAC1C,WAAW,EAAE,UAAU,CAAC;IACxB,4DAA4D;IAC5D,gBAAgB,EAAE,UAAU,CAAC;IAC7B,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACnC,aAAa,CAuEf"}