@query-farm/vgi-rpc 0.3.4 → 0.6.0

package/src/http/mtls.ts

@@ -0,0 +1,298 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+import { createHash, X509Certificate } from "node:crypto";
+import { AuthContext } from "../auth.js";
+import type { AuthenticateFn } from "./auth.js";
+
+// ---------------------------------------------------------------------------
+// XFCC types and parser (no crypto needed)
+// ---------------------------------------------------------------------------
+
+/** 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>;
+
+function splitRespectingQuotes(text: string, delimiter: string): string[] {
+  const parts: string[] = [];
+  let current: string[] = [];
+  let inQuotes = false;
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '"') {
+      inQuotes = !inQuotes;
+      current.push(ch);
+    } else if (ch === "\\" && inQuotes && i + 1 < text.length) {
+      current.push(ch);
+      current.push(text[i + 1]);
+      i++;
+    } else if (ch === delimiter && !inQuotes) {
+      parts.push(current.join(""));
+      current = [];
+    } else {
+      current.push(ch);
+    }
+    i++;
+  }
+  parts.push(current.join(""));
+  return parts;
+}
+
+function unescapeQuoted(text: string): string {
+  return text.replace(/\\(.)/g, "$1");
+}
+
+/** Extract the CN value from an RFC 4514 or similar DN string. */
+function extractCn(subject: string): string {
+  for (const part of subject.split(/(?<!\\),/)) {
+    const trimmed = part.trim();
+    if (trimmed.toUpperCase().startsWith("CN=")) {
+      return trimmed.slice(3);
+    }
+  }
+  return "";
+}
+
+/**
+ * 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 function parseXfcc(headerValue: string): XfccElement[] {
+  const elements: XfccElement[] = [];
+  for (const rawElement of splitRespectingQuotes(headerValue, ",")) {
+    const trimmed = rawElement.trim();
+    if (!trimmed) continue;
+    const pairs = splitRespectingQuotes(trimmed, ";");
+    const fields: Record<string, string | string[]> = {};
+    for (const pair of pairs) {
+      const p = pair.trim();
+      if (!p) continue;
+      const eqIdx = p.indexOf("=");
+      if (eqIdx < 0) continue;
+      const key = p.slice(0, eqIdx).trim().toLowerCase();
+      let value = p.slice(eqIdx + 1).trim();
+      if (value.length >= 2 && value[0] === '"' && value[value.length - 1] === '"') {
+        value = unescapeQuoted(value.slice(1, -1));
+      }
+      if (key === "cert" || key === "uri" || key === "by") {
+        value = decodeURIComponent(value);
+      }
+      if (key === "dns") {
+        const existing = fields.dns;
+        if (Array.isArray(existing)) {
+          existing.push(value);
+        } else {
+          fields.dns = [value];
+        }
+      } else {
+        fields[key] = value;
+      }
+    }
+    const dns = Array.isArray(fields.dns) ? fields.dns : [];
+    elements.push({
+      hash: typeof fields.hash === "string" ? fields.hash : null,
+      cert: typeof fields.cert === "string" ? fields.cert : null,
+      subject: typeof fields.subject === "string" ? fields.subject : null,
+      uri: typeof fields.uri === "string" ? fields.uri : null,
+      dns,
+      by: typeof fields.by === "string" ? fields.by : null,
+    });
+  }
+  return elements;
+}
+
+/**
+ * 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 function mtlsAuthenticateXfcc(options?: {
+  validate?: XfccValidateFn;
+  domain?: string;
+  selectElement?: "first" | "last";
+}): AuthenticateFn {
+  const validate = options?.validate;
+  const domain = options?.domain ?? "mtls";
+  const selectElement = options?.selectElement ?? "first";
+
+  return async function authenticate(request: Request): Promise<AuthContext> {
+    const headerValue = request.headers.get("x-forwarded-client-cert");
+    if (!headerValue) {
+      throw new Error("Missing x-forwarded-client-cert header");
+    }
+    const elements = parseXfcc(headerValue);
+    if (elements.length === 0) {
+      throw new Error("Empty x-forwarded-client-cert header");
+    }
+    const element = selectElement === "first" ? elements[0] : elements[elements.length - 1];
+    if (validate) {
+      return validate(element);
+    }
+    const principal = element.subject ? extractCn(element.subject) : "";
+    const claims: Record<string, any> = {};
+    if (element.hash) claims.hash = element.hash;
+    if (element.subject) claims.subject = element.subject;
+    if (element.uri) claims.uri = element.uri;
+    if (element.dns.length > 0) claims.dns = [...element.dns];
+    if (element.by) claims.by = element.by;
+    return new AuthContext(domain, true, principal, claims);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// PEM-based factories (uses node:crypto X509Certificate)
+// ---------------------------------------------------------------------------
+
+function parseCertFromHeader(request: Request, header: string): X509Certificate {
+  const raw = request.headers.get(header);
+  if (!raw) {
+    throw new Error(`Missing ${header} header`);
+  }
+  const pemStr = decodeURIComponent(raw);
+  if (!pemStr.startsWith("-----BEGIN CERTIFICATE-----")) {
+    throw new Error("Header value is not a PEM certificate");
+  }
+  try {
+    return new X509Certificate(pemStr);
+  } catch (exc) {
+    throw new Error(`Failed to parse PEM certificate: ${exc}`);
+  }
+}
+
+function checkCertExpiry(cert: X509Certificate): void {
+  const now = new Date();
+  const notBefore = new Date(cert.validFrom);
+  const notAfter = new Date(cert.validTo);
+  if (now < notBefore) {
+    throw new Error("Certificate is not yet valid");
+  }
+  if (now > notAfter) {
+    throw new Error("Certificate has expired");
+  }
+}
+
+/**
+ * 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 function mtlsAuthenticate(options: {
+  validate: CertValidateFn;
+  header?: string;
+  checkExpiry?: boolean;
+}): AuthenticateFn {
+  const { validate, header = "X-SSL-Client-Cert", checkExpiry = false } = options;
+
+  return async function authenticate(request: Request): Promise<AuthContext> {
+    const cert = parseCertFromHeader(request, header);
+    if (checkExpiry) {
+      checkCertExpiry(cert);
+    }
+    return validate(cert);
+  };
+}
+
+const SUPPORTED_ALGORITHMS = new Set(["sha256", "sha1", "sha384", "sha512"]);
+
+/**
+ * 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 function mtlsAuthenticateFingerprint(options: {
+  fingerprints: ReadonlyMap<string, AuthContext> | Record<string, AuthContext>;
+  header?: string;
+  algorithm?: string;
+  domain?: string;
+  checkExpiry?: boolean;
+}): AuthenticateFn {
+  const { fingerprints, header, algorithm = "sha256", checkExpiry } = options;
+  if (!SUPPORTED_ALGORITHMS.has(algorithm)) {
+    throw new Error(`Unsupported hash algorithm: ${algorithm}`);
+  }
+  const entries: ReadonlyMap<string, AuthContext> =
+    fingerprints instanceof Map ? fingerprints : new Map(Object.entries(fingerprints));
+
+  function validate(cert: X509Certificate): AuthContext {
+    const fp = createHash(algorithm).update(cert.raw).digest("hex");
+    const ctx = entries.get(fp);
+    if (!ctx) {
+      throw new Error(`Unknown certificate fingerprint: ${fp}`);
+    }
+    return ctx;
+  }
+
+  return mtlsAuthenticate({ validate, header, checkExpiry });
+}
+
+/**
+ * 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 function mtlsAuthenticateSubject(options?: {
+  header?: string;
+  domain?: string;
+  allowedSubjects?: ReadonlySet<string> | null;
+  checkExpiry?: boolean;
+}): AuthenticateFn {
+  const { header, domain = "mtls", allowedSubjects = null, checkExpiry } = options ?? {};
+
+  function validate(cert: X509Certificate): AuthContext {
+    // Node's cert.subject is \n-separated "KEY=value" lines
+    const subjectParts = cert.subject
+      .split("\n")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const subjectDn = subjectParts.join(", ");
+
+    let cn = "";
+    for (const part of subjectParts) {
+      if (part.toUpperCase().startsWith("CN=")) {
+        cn = part.slice(3);
+        break;
+      }
+    }
+
+    if (allowedSubjects !== null && !allowedSubjects.has(cn)) {
+      throw new Error(`Subject CN '${cn}' not in allowed subjects`);
+    }
+
+    const serialHex = BigInt(`0x${cert.serialNumber}`).toString(16);
+    const notValidAfter = new Date(cert.validTo).toISOString();
+
+    return new AuthContext(domain, true, cn, {
+      subject_dn: subjectDn,
+      serial: serialHex,
+      not_valid_after: notValidAfter,
+    });
+  }
+
+  return mtlsAuthenticate({ validate, header, checkExpiry });
+}

package/src/http/pages.ts

@@ -0,0 +1,298 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * 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";
+
+const LOGO_URL = "https://vgi-rpc-python.query.farm/assets/logo-hero.png";
+
+const FONTS = `<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet">`;
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function arrowTypeToString(type: import("@query-farm/apache-arrow").DataType): string {
+  const id = type.typeId;
+  // Match the human-friendly type names used by the Python reference implementation
+  if (id === 5) return "str"; // Utf8
+  if (id === 4) return "bytes"; // Binary
+  if (id === 2) return "int"; // Int32/Int64
+  if (id === 3) return "float"; // Float32/Float64
+  if (id === 6) return "bool"; // Bool
+  if (id === 12) return "list"; // List
+  if (id === 17) return "map"; // Map
+  if (id === 24) return "enum"; // Dictionary
+  return type.toString();
+}
+
+// ---------------------------------------------------------------------------
+// Landing page
+// ---------------------------------------------------------------------------
+
+export function buildLandingPage(
+  protocolName: string,
+  serverId: string,
+  describePath: string | null,
+  repoUrl: string | null,
+): string {
+  const links: string[] = [];
+  if (describePath) {
+    links.push(`<a class="primary" href="${escapeHtml(describePath)}">View service API</a>`);
+  }
+  if (repoUrl) {
+    links.push(`<a href="${escapeHtml(repoUrl)}">Source repository</a>`);
+  }
+  links.push(`<a href="https://vgi-rpc.query.farm">Learn more about <code>vgi-rpc</code></a>`);
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(protocolName)} \u2014 vgi-rpc</title>
+${FONTS}
+<style>
+body { font-family: 'Inter', system-ui, -apple-system, sans-serif; max-width: 600px;
+       margin: 0 auto; padding: 60px 20px 0; color: #2c2c1e; text-align: center;
+       background: #faf8f0; }
+.logo { margin-bottom: 24px; }
+.logo img { width: 140px; height: 140px; border-radius: 50%;
+             box-shadow: 0 4px 24px rgba(0,0,0,0.12); }
+h1 { color: #2d5016; margin-bottom: 8px; font-weight: 700; }
+code { font-family: 'JetBrains Mono', monospace; background: #f0ece0;
+        padding: 2px 6px; border-radius: 3px; font-size: 0.9em; color: #2c2c1e; }
+a { color: #2d5016; text-decoration: none; }
+a:hover { color: #4a7c23; }
+p { line-height: 1.7; color: #6b6b5a; }
+.meta { font-size: 0.9em; color: #6b6b5a; }
+.links { margin-top: 28px; display: flex; flex-wrap: wrap; justify-content: center; gap: 8px; }
+.links a { display: inline-block; padding: 8px 18px; border-radius: 6px;
+            border: 1px solid #4a7c23; color: #2d5016; font-weight: 600;
+            font-size: 0.9em; transition: all 0.2s ease; }
+.links a:hover { background: #4a7c23; color: #fff; }
+.links a.primary { background: #2d5016; color: #fff; border-color: #2d5016; }
+.links a.primary:hover { background: #4a7c23; border-color: #4a7c23; }
+footer { margin-top: 48px; padding: 20px 0; border-top: 1px solid #f0ece0;
+          color: #6b6b5a; font-size: 0.85em; }
+footer a { color: #2d5016; font-weight: 600; }
+footer a:hover { color: #4a7c23; }
+</style>
+</head>
+<body>
+<div class="logo">
+  <img src="${LOGO_URL}" alt="vgi-rpc logo">
+</div>
+<h1>${escapeHtml(protocolName)}</h1>
+<p class="meta">Powered by <code>vgi-rpc</code> (TypeScript) &middot; server <code>${escapeHtml(serverId)}</code></p>
+<p>This is a <code>vgi-rpc</code> service endpoint.</p>
+<div class="links">
+${links.join("\n")}
+</div>
+<footer>
+  &copy; 2026 &#x1F69C; <a href="https://query.farm">Query.Farm LLC</a>
+</footer>
+</body>
+</html>`;
+}
+
+// ---------------------------------------------------------------------------
+// 404 page
+// ---------------------------------------------------------------------------
+
+export function buildNotFoundPage(prefix: string, protocolName: string): string {
+  const nameFragment = protocolName ? ` (<strong>${escapeHtml(protocolName)}</strong>)` : "";
+  const prefixDisplay = prefix || "/";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>404 \u2014 vgi-rpc endpoint</title>
+<style>
+body { font-family: system-ui, -apple-system, sans-serif; max-width: 600px;
+       margin: 60px auto; padding: 0 20px; color: #333; text-align: center; }
+.logo { margin-bottom: 24px; }
+.logo img { width: 120px; height: 120px; }
+h1 { color: #555; }
+code { background: #f4f4f4; padding: 2px 6px; border-radius: 3px; font-size: 0.95em; }
+a { color: #0066cc; }
+p { line-height: 1.6; }
+</style>
+</head>
+<body>
+<div class="logo">
+  <img src="${LOGO_URL}" alt="vgi-rpc logo">
+</div>
+<h1>404 \u2014 Not Found</h1>
+<p>This is a <code>vgi-rpc</code> service endpoint${nameFragment}.</p>
+<p>RPC methods are available under <code>${escapeHtml(prefixDisplay)}/&lt;method&gt;</code>.</p>
+<p>Learn more at <a href="https://vgi-rpc.query.farm">vgi-rpc.query.farm</a>.</p>
+</body>
+</html>`;
+}
+
+// ---------------------------------------------------------------------------
+// Describe / API reference page
+// ---------------------------------------------------------------------------
+
+function buildMethodCard(method: MethodDefinition): string {
+  const name = escapeHtml(method.name);
+  const isUnary = method.type === "unary";
+  const hasHeader = !!method.headerSchema;
+
+  // Badges — match Python reference (unary/stream/header only)
+  const badges: string[] = [];
+  badges.push(
+    isUnary ? `<span class="badge badge-unary">unary</span>` : `<span class="badge badge-stream">stream</span>`,
+  );
+  if (hasHeader) badges.push(`<span class="badge badge-header">header</span>`);
+
+  // Parameters table
+  let paramsHtml = "";
+  const paramsSchema = method.paramsSchema;
+  if (paramsSchema.fields.length > 0) {
+    const rows = paramsSchema.fields.map((f) => {
+      const paramName = escapeHtml(f.name);
+      const paramType = escapeHtml(arrowTypeToString(f.type));
+      const defaultVal =
+        method.defaults && f.name in method.defaults ? escapeHtml(JSON.stringify(method.defaults[f.name])) : "&mdash;";
+      return `<tr><td><code>${paramName}</code></td><td><code>${paramType}</code></td><td>${defaultVal}</td><td>&mdash;</td></tr>`;
+    });
+    paramsHtml = `<div class="section-label">Parameters</div>
+<table><tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
+${rows.join("\n")}
+</table>`;
+  } else {
+    paramsHtml = `<p class="no-params">No parameters</p>`;
+  }
+
+  // Returns table (unary only)
+  let returnsHtml = "";
+  if (isUnary && method.resultSchema.fields.length > 0) {
+    const rows = method.resultSchema.fields.map((f) => {
+      return `<tr><td><code>${escapeHtml(f.name)}</code></td><td><code>${escapeHtml(arrowTypeToString(f.type))}</code></td></tr>`;
+    });
+    returnsHtml = `<div class="section-label">Returns</div>
+<table><tr><th>Name</th><th>Type</th></tr>
+${rows.join("\n")}
+</table>`;
+  }
+
+  // Header table (streams with headers)
+  let headerHtml = "";
+  if (hasHeader && method.headerSchema && method.headerSchema.fields.length > 0) {
+    const rows = method.headerSchema.fields.map((f) => {
+      return `<tr><td><code>${escapeHtml(f.name)}</code></td><td><code>${escapeHtml(arrowTypeToString(f.type))}</code></td></tr>`;
+    });
+    headerHtml = `<div class="section-label">Stream Header</div>
+<table><tr><th>Name</th><th>Type</th></tr>
+${rows.join("\n")}
+</table>`;
+  }
+
+  // Docstring
+  const docHtml = method.doc ? `<p class="docstring">${escapeHtml(method.doc)}</p>` : "";
+
+  return `<div class="card">
+<div class="card-header">
+<span class="method-name">${name}</span>
+${badges.join("\n")}
+</div>
+${docHtml}
+${paramsHtml}
+${returnsHtml}
+${headerHtml}
+</div>`;
+}
+
+export function buildDescribePage(
+  protocolName: string,
+  serverId: string,
+  methods: Map<string, MethodDefinition>,
+  repoUrl: string | null,
+): string {
+  const sortedMethods = [...methods.entries()]
+    .filter(([name]) => name !== "__describe__")
+    .sort(([a], [b]) => a.localeCompare(b));
+
+  const cards = sortedMethods.map(([, method]) => buildMethodCard(method)).join("\n");
+
+  const repoLink = repoUrl ? ` &middot; <a href="${escapeHtml(repoUrl)}">Source</a>` : "";
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(protocolName)} API Reference \u2014 vgi-rpc</title>
+${FONTS}
+<style>
+body { font-family: 'Inter', system-ui, -apple-system, sans-serif; max-width: 900px;
+       margin: 0 auto; padding: 40px 20px 0; color: #2c2c1e; background: #faf8f0; }
+.header { text-align: center; margin-bottom: 40px; }
+.header .logo img { width: 80px; height: 80px; border-radius: 50%;
+                     box-shadow: 0 3px 16px rgba(0,0,0,0.10); }
+.header h1 { margin-bottom: 4px; color: #2d5016; font-weight: 700; }
+.header .subtitle { color: #6b6b5a; font-size: 1.1em; margin-top: 0; }
+.header .meta { color: #6b6b5a; font-size: 0.9em; }
+.header .meta a { color: #2d5016; font-weight: 600; }
+.header .meta a:hover { color: #4a7c23; }
+code { font-family: 'JetBrains Mono', monospace; background: #f0ece0;
+        padding: 2px 6px; border-radius: 3px; font-size: 0.85em; color: #2c2c1e; }
+a { color: #2d5016; text-decoration: none; }
+a:hover { color: #4a7c23; }
+.card { border: 1px solid #f0ece0; border-radius: 8px; padding: 20px;
+         margin-bottom: 16px; background: #fff; }
+.card:hover { border-color: #c8a43a; }
+.card-header { display: flex; align-items: center; gap: 10px; margin-bottom: 12px; }
+.method-name { font-family: 'JetBrains Mono', monospace; font-size: 1.1em; font-weight: 600;
+                color: #2d5016; }
+.badge { display: inline-block; padding: 2px 8px; border-radius: 4px;
+          font-size: 0.75em; font-weight: 600; text-transform: uppercase;
+          letter-spacing: 0.03em; }
+.badge-unary { background: #e8f5e0; color: #2d5016; }
+.badge-stream { background: #e0ecf5; color: #1a4a6b; }
+.badge-exchange { background: #f5e6f0; color: #6b234a; }
+.badge-producer { background: #e0f0f5; color: #1a5a6b; }
+.badge-header { background: #f5eee0; color: #6b4423; }
+.docstring { color: #6b6b5a; font-size: 0.9em; margin-top: 0; }
+table { width: 100%; border-collapse: collapse; font-size: 0.9em; }
+th { text-align: left; padding: 8px 10px; background: #f0ece0; color: #2c2c1e;
+      font-weight: 600; border-bottom: 2px solid #e0dcd0; }
+td { padding: 8px 10px; border-bottom: 1px solid #f0ece0; }
+td code { font-size: 0.85em; }
+.no-params { color: #6b6b5a; font-style: italic; font-size: 0.9em; }
+.section-label { font-size: 0.8em; font-weight: 600; text-transform: uppercase;
+                  letter-spacing: 0.05em; color: #6b6b5a; margin-top: 14px;
+                  margin-bottom: 6px; }
+footer { text-align: center; margin-top: 48px; padding: 20px 0;
+          border-top: 1px solid #f0ece0; color: #6b6b5a; font-size: 0.85em; }
+footer a { color: #2d5016; font-weight: 600; }
+footer a:hover { color: #4a7c23; }
+</style>
+</head>
+<body>
+<div class="header">
+  <div class="logo">
+    <img src="${LOGO_URL}" alt="vgi-rpc logo">
+  </div>
+  <h1>${escapeHtml(protocolName)}</h1>
+  <p class="subtitle">API Reference</p>
+  <p class="meta">Powered by <code>vgi-rpc</code> (TypeScript) &middot; server <code>${escapeHtml(serverId)}</code>${repoLink}</p>
+</div>
+${cards}
+<footer>
+  <a href="https://vgi-rpc.query.farm">Learn more about <code>vgi-rpc</code></a>
+  &middot;
+  &copy; 2026 &#x1F69C; <a href="https://query.farm">Query.Farm LLC</a>
+</footer>
+</body>
+</html>`;
+}

package/src/http/types.ts

@@ -1,9 +1,13 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
+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;
@@ -22,6 +26,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. */