@query-farm/vgi-rpc 0.6.4 → 0.7.0

package/src/client/ipc.ts

@@ -7,18 +7,17 @@ import {
   DataType,
   Float64,
   Int64,
-  makeData,
-  RecordBatch,
+  type RecordBatch,
   RecordBatchReader,
   type Schema,
-  Struct,
   Utf8,
-  vectorFromArray,
 } from "@query-farm/apache-arrow";
+import { emptyBatchWithMetadata, singleRowBatchWithMetadata } from "#vgi-rpc-arrow";
 import {
   LOG_EXTRA_KEY,
   LOG_LEVEL_KEY,
   LOG_MESSAGE_KEY,
+  PROTOCOL_VERSION_KEY,
   REQUEST_VERSION,
   REQUEST_VERSION_KEY,
   RPC_METHOD_KEY,
@@ -79,38 +78,49 @@ function coerceForArrow(type: DataType, value: any): any {
 
 /**
  * Build a 1-row Arrow IPC request batch with method metadata.
+ *
+ * When `options.protocolVersion` is non-empty, the value is emitted as
+ * `vgi_rpc.protocol_version` so servers that declare a Protocol-level
+ * version validate the request at the dispatch boundary.
  */
-export function buildRequestIpc(schema: Schema, params: Record<string, any>, method: string): Uint8Array {
+export function buildRequestIpc(
+  schema: Schema,
+  params: Record<string, any>,
+  method: string,
+  options?: { protocolVersion?: string },
+): Uint8Array {
   const metadata = new Map<string, string>();
   metadata.set(RPC_METHOD_KEY, method);
   metadata.set(REQUEST_VERSION_KEY, REQUEST_VERSION);
+  if (options?.protocolVersion) {
+    metadata.set(PROTOCOL_VERSION_KEY, options.protocolVersion);
+  }
 
+  // Build the batch through the impl-agnostic #vgi-rpc-arrow layer so this
+  // works under both backends. `buildRequestIpc` previously constructed an
+  // apache-arrow RecordBatch directly and handed it to `serializeIpcStream`,
+  // which then dispatched to the backend's `serializeBatches`. Under the
+  // browser/worker condition that backend is flechette, and flechette's
+  // `tablesToIPC` cannot read apache-arrow's RecordBatch shape — the cross-
+  // impl mixing was silently broken (no browser tests cover this path; see
+  // test/client/ipc-cross-impl.test.ts). The abstract helpers produce a
+  // 0-row metadata-bearing batch for the empty-schema case (which servers
+  // accept identically to a 1-row × 0-col batch) and a 1-row batch with
+  // coerced field values otherwise.
   if (schema.fields.length === 0) {
-    const structType = new Struct(schema.fields);
-    const data = makeData({
-      type: structType,
-      length: 1,
-      children: [],
-      nullCount: 0,
-    });
-    const batch = new RecordBatch(schema, data, metadata);
+    const batch = emptyBatchWithMetadata(schema, metadata);
     return serializeIpcStream(schema, [batch]);
   }
 
-  const children = schema.fields.map((f) => {
-    const val = coerceForArrow(f.type, params[f.name]);
-    return vectorFromArray([val], f.type).data[0];
-  });
-
-  const structType = new Struct(schema.fields);
-  const data = makeData({
-    type: structType,
-    length: 1,
-    children,
-    nullCount: 0,
-  });
-
-  const batch = new RecordBatch(schema, data, metadata);
+  const coerced: Record<string, any> = {};
+  for (const f of schema.fields) {
+    const raw = params[f.name];
+    // Missing values must be sent as null. arrow-js's typed-array builders
+    // throw "Invalid argument type in ToBigInt" when handed `undefined` for
+    // an Int64 column; null builds a proper validity bitmap entry instead.
+    coerced[f.name] = raw === undefined ? null : coerceForArrow(f.type, raw);
+  }
+  const batch = singleRowBatchWithMetadata(schema, coerced, metadata);
   return serializeIpcStream(schema, [batch]);
 }
 

package/src/client/pipe.ts

@@ -125,17 +125,17 @@ export class PipeStreamSession implements StreamSession {
 
       if (batch.numRows === 0) {
         // Check for external location pointer batch
-        if (isExternalLocationBatch(batch)) {
-          return await resolveExternalLocation(batch, this._externalConfig);
+        if (isExternalLocationBatch(batch as any)) {
+          return (await resolveExternalLocation(batch as any, this._externalConfig)) as any;
         }
         // Check if it's a log/error batch. If so, dispatch and continue.
         // Otherwise it's a zero-row data batch — return it.
-        if (dispatchLogOrError(batch, this._onLog)) {
+        if (dispatchLogOrError(batch as any, this._onLog)) {
           continue;
         }
       }
 
-      return batch;
+      return batch as any;
     }
   }
 
@@ -389,6 +389,7 @@ export function pipeConnect(
   let readerPromise: Promise<IpcStreamReader> | null = null;
   let methodCache: Map<string, MethodInfo> | null = null;
   let protocolName = "";
+  let serverProtocolVersion = "";
   let _busy = false;
   let _drainPromise: Promise<void> | null = null;
   let closed = false;
@@ -458,8 +459,9 @@ export function pipeConnect(
         throw new Error("EOF reading __describe__ response");
       }
 
-      const desc = await parseDescribeResponse(response.batches, onLog);
+      const desc = await parseDescribeResponse(response.batches as any, onLog);
       protocolName = desc.protocolName;
+      serverProtocolVersion = desc.protocolVersion;
       methodCache = new Map(desc.methods.map((m) => [m.name, m]));
       return methodCache;
     } finally {
@@ -483,7 +485,7 @@ export function pipeConnect(
         const fullParams = { ...(info.defaults ?? {}), ...(params ?? {}) };
 
         // Send request
-        const body = buildRequestIpc(info.paramsSchema, fullParams, method);
+        const body = buildRequestIpc(info.paramsSchema, fullParams, method, { protocolVersion: serverProtocolVersion });
         writeFn(body);
 
         // Read response
@@ -494,7 +496,7 @@ export function pipeConnect(
 
         // Process batches: dispatch logs, resolve external pointers, find result
         let resultBatch: RecordBatch | null = null;
-        for (let batch of response.batches) {
+        for (let batch of response.batches as any[]) {
           if (batch.numRows === 0) {
             if (isExternalLocationBatch(batch)) {
               batch = await resolveExternalLocation(batch, externalConfig);
@@ -537,7 +539,7 @@ export function pipeConnect(
         const fullParams = { ...(info.defaults ?? {}), ...(params ?? {}) };
 
         // Send init request (params as a complete IPC stream)
-        const body = buildRequestIpc(info.paramsSchema, fullParams, method);
+        const body = buildRequestIpc(info.paramsSchema, fullParams, method, { protocolVersion: serverProtocolVersion });
         writeFn(body);
 
         // Read header if method has headerSchema
@@ -545,7 +547,7 @@ export function pipeConnect(
         if (info.headerSchema) {
           const headerStream = await r.readStream();
           if (headerStream) {
-            for (const batch of headerStream.batches) {
+            for (const batch of headerStream.batches as any[]) {
               if (batch.numRows === 0) {
                 dispatchLogOrError(batch, onLog);
                 continue;
@@ -597,6 +599,7 @@ export function pipeConnect(
       const methods = await ensureMethodCache();
       return {
         protocolName,
+        protocolVersion: serverProtocolVersion,
         methods: [...methods.values()],
       };
     },

package/src/client/stream.ts

@@ -9,8 +9,15 @@ import { ARROW_CONTENT_TYPE, serializeIpcStream } from "../http/common.js";
 import { dispatchLogOrError, extractBatchRows, inferArrowType, readResponseBatches } from "./ipc.js";
 import type { LogMessage, StreamSession } from "./types.js";
 
-type CompressFn = (data: Uint8Array, level: number) => Uint8Array;
-type DecompressFn = (data: Uint8Array) => Uint8Array;
+type CompressFn = (data: Uint8Array, level: number) => Promise<Uint8Array>;
+type DecompressFn = (data: Uint8Array) => Promise<Uint8Array>;
+
+/**
+ * Posts an Arrow IPC request body to *url*, transparently handling
+ * client-vended request externalization. Provided by the parent connection
+ * so a single capability cache can drive both unary and stream call paths.
+ */
+export type PostFn = (url: string, body: Uint8Array) => Promise<Response>;
 
 export class HttpStreamSession implements StreamSession {
   private _baseUrl: string;
@@ -28,6 +35,7 @@ export class HttpStreamSession implements StreamSession {
   private _decompressFn?: DecompressFn;
   private _authorization?: string;
   private _externalConfig?: ExternalLocationConfig;
+  private _postFn?: PostFn;
 
   constructor(opts: {
     baseUrl: string;
@@ -45,6 +53,7 @@ export class HttpStreamSession implements StreamSession {
     decompressFn?: DecompressFn;
     authorization?: string;
     externalConfig?: ExternalLocationConfig;
+    postFn?: PostFn;
   }) {
     this._baseUrl = opts.baseUrl;
     this._prefix = opts.prefix;
@@ -61,6 +70,16 @@ export class HttpStreamSession implements StreamSession {
     this._decompressFn = opts.decompressFn;
     this._authorization = opts.authorization;
     this._externalConfig = opts.externalConfig;
+    this._postFn = opts.postFn;
+  }
+
+  private async _post(url: string, body: Uint8Array): Promise<Response> {
+    if (this._postFn) return this._postFn(url, body);
+    return fetch(url, {
+      method: "POST",
+      headers: this._buildHeaders(),
+      body: (await this._prepareBody(body)) as unknown as BodyInit,
+    });
   }
 
   get header(): Record<string, any> | null {
@@ -71,8 +90,10 @@ export class HttpStreamSession implements StreamSession {
     const headers: Record<string, string> = {
       "Content-Type": ARROW_CONTENT_TYPE,
     };
-    if (this._compressionLevel != null) {
+    if (this._compressionLevel != null && this._compressFn) {
       headers["Content-Encoding"] = "zstd";
+    }
+    if (this._compressionLevel != null && this._decompressFn) {
       headers["Accept-Encoding"] = "zstd";
     }
     if (this._authorization) {
@@ -81,9 +102,9 @@ export class HttpStreamSession implements StreamSession {
     return headers;
   }
 
-  private _prepareBody(content: Uint8Array): Uint8Array {
+  private async _prepareBody(content: Uint8Array): Promise<Uint8Array> {
     if (this._compressionLevel != null && this._compressFn) {
-      return this._compressFn(content, this._compressionLevel);
+      return await this._compressFn(content, this._compressionLevel);
     }
     return content;
   }
@@ -91,7 +112,7 @@ export class HttpStreamSession implements StreamSession {
   private async _readResponse(resp: Response): Promise<Uint8Array<ArrayBuffer>> {
     let body = new Uint8Array(await resp.arrayBuffer());
     if (resp.headers.get("Content-Encoding") === "zstd" && this._decompressFn) {
-      body = new Uint8Array(this._decompressFn(body));
+      body = new Uint8Array(await this._decompressFn(body));
     }
     return body;
   }
@@ -159,11 +180,7 @@ export class HttpStreamSession implements StreamSession {
 
   private async _doExchange(schema: Schema, batches: RecordBatch[]): Promise<Record<string, any>[]> {
     const body = serializeIpcStream(schema, batches);
-    const resp = await fetch(`${this._baseUrl}${this._prefix}/${this._method}/exchange`, {
-      method: "POST",
-      headers: this._buildHeaders(),
-      body: this._prepareBody(body) as unknown as BodyInit,
-    });
+    const resp = await this._post(`${this._baseUrl}${this._prefix}/${this._method}/exchange`, body);
     if (resp.status === 401) {
       throw new RpcError("AuthenticationError", "Authentication required", "");
     }
@@ -218,7 +235,7 @@ export class HttpStreamSession implements StreamSession {
     for (let batch of this._pendingBatches) {
       if (batch.numRows === 0) {
         if (isExternalLocationBatch(batch)) {
-          batch = await resolveExternalLocation(batch, this._externalConfig);
+          batch = (await resolveExternalLocation(batch as any, this._externalConfig)) as any;
         } else {
           dispatchLogOrError(batch, this._onLog);
           continue;
@@ -233,7 +250,9 @@ export class HttpStreamSession implements StreamSession {
 
     // Follow continuation tokens
     while (true) {
-      const responseBody = await this._sendContinuation(this._stateToken);
+      const stateToken = this._stateToken;
+      if (stateToken === null) return;
+      const responseBody = await this._sendContinuation(stateToken);
       const { batches } = await readResponseBatches(responseBody);
 
       let gotContinuation = false;
@@ -248,7 +267,7 @@ export class HttpStreamSession implements StreamSession {
           }
           // Check for external location pointer
           if (isExternalLocationBatch(batch)) {
-            batch = await resolveExternalLocation(batch, this._externalConfig);
+            batch = (await resolveExternalLocation(batch as any, this._externalConfig)) as any;
           } else {
             // Log/error batch
             dispatchLogOrError(batch, this._onLog);
@@ -278,11 +297,7 @@ export class HttpStreamSession implements StreamSession {
     const batch = new RecordBatch(emptySchema, data, metadata);
     const body = serializeIpcStream(emptySchema, [batch]);
 
-    const resp = await fetch(`${this._baseUrl}${this._prefix}/${this._method}/exchange`, {
-      method: "POST",
-      headers: this._buildHeaders(),
-      body: this._prepareBody(body) as unknown as BodyInit,
-    });
+    const resp = await this._post(`${this._baseUrl}${this._prefix}/${this._method}/exchange`, body);
     if (resp.status === 401) {
       throw new RpcError("AuthenticationError", "Authentication required", "");
     }

package/src/client/uploadUrl.ts

@@ -0,0 +1,169 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Client-side request-body externalization.
+ *
+ * When a request body would exceed the server-advertised `maxRequestBytes`,
+ * we (1) call `{prefix}/__upload_url__/init` to get a pre-signed upload URL,
+ * (2) PUT the body to that URL, and (3) replace the inline body with a
+ * zero-row "pointer" IPC stream that carries the original RPC dispatch
+ * metadata plus `vgi_rpc.location: <download-url>`. The server then resolves
+ * the pointer and dispatches normally.
+ *
+ * Mirrors Python's `_externalize_via_upload_url()` and `request_upload_urls()`.
+ */
+
+import { Field, Int64, RecordBatchReader, Schema } from "@query-farm/apache-arrow";
+import { REQUEST_VERSION, REQUEST_VERSION_KEY, RPC_METHOD_KEY } from "../constants.js";
+import { RpcError } from "../errors.js";
+import { makeExternalLocationBatch } from "../external.js";
+import { ARROW_CONTENT_TYPE, serializeIpcStream } from "../http/common.js";
+import { buildRequestIpc } from "./ipc.js";
+
+const UPLOAD_URL_METHOD = "__upload_url__";
+const UPLOAD_URL_PARAMS_SCHEMA = new Schema([new Field("count", new Int64(), false)]);
+
+export interface UploadUrlPair {
+  uploadUrl: string;
+  downloadUrl: string;
+  expiresAt: Date;
+}
+
+/**
+ * POST `__upload_url__/init` and return the requested number of pre-signed
+ * URL pairs. Server must have an `uploadUrlProvider` configured; otherwise
+ * the route returns 404 and we surface that as `RpcError("NotSupported")`.
+ */
+export async function requestUploadUrls(
+  baseUrl: string,
+  prefix: string,
+  count: number,
+  authorization?: string,
+): Promise<UploadUrlPair[]> {
+  const body = buildRequestIpc(UPLOAD_URL_PARAMS_SCHEMA, { count: BigInt(count) }, UPLOAD_URL_METHOD);
+  const headers: Record<string, string> = { "Content-Type": ARROW_CONTENT_TYPE };
+  if (authorization) headers.Authorization = authorization;
+
+  const resp = await fetch(`${baseUrl}${prefix}/${UPLOAD_URL_METHOD}/init`, {
+    method: "POST",
+    headers,
+    body: body as unknown as BodyInit,
+  });
+  if (resp.status === 404) {
+    throw new RpcError("NotSupported", "Server does not support upload URLs", "");
+  }
+  if (resp.status === 401) {
+    throw new RpcError("AuthenticationError", "Authentication required", "");
+  }
+  if (!resp.ok) {
+    throw new RpcError("HttpError", `__upload_url__/init failed: HTTP ${resp.status}`, "");
+  }
+
+  const respBody = new Uint8Array(await resp.arrayBuffer());
+  const reader = await RecordBatchReader.from(respBody);
+  await reader.open();
+
+  const pairs: UploadUrlPair[] = [];
+  for (const batch of reader.readAll()) {
+    if (batch.numRows === 0) continue;
+    for (let r = 0; r < batch.numRows; r++) {
+      const uploadUrl = batch.getChildAt(0)?.get(r) as string;
+      const downloadUrl = batch.getChildAt(1)?.get(r) as string;
+      const expiresRaw = batch.getChildAt(2)?.get(r);
+      // Timestamp(us) → either a Date, a number (ms), or a bigint (us)
+      let expiresAt: Date;
+      if (expiresRaw instanceof Date) {
+        expiresAt = expiresRaw;
+      } else if (typeof expiresRaw === "bigint") {
+        expiresAt = new Date(Number(expiresRaw / 1000n));
+      } else if (typeof expiresRaw === "number") {
+        expiresAt = new Date(expiresRaw);
+      } else {
+        expiresAt = new Date();
+      }
+      pairs.push({ uploadUrl, downloadUrl, expiresAt });
+    }
+  }
+
+  if (pairs.length === 0) {
+    throw new RpcError("ProtocolError", "Server returned no upload URLs", "");
+  }
+  return pairs;
+}
+
+/**
+ * Build the externalized pointer body to send in place of *originalBody*.
+ *
+ * The pointer is a zero-row IPC stream whose first batch carries:
+ *   - same schema as the original request batch
+ *   - merged custom_metadata: original RPC dispatch keys + `vgi_rpc.location`
+ *
+ * The server's request reader honours the dispatch keys for routing, then
+ * resolves the pointer to fetch the inline batch for parameter extraction.
+ */
+async function buildPointerRequestBody(originalBody: Uint8Array, downloadUrl: string): Promise<Uint8Array> {
+  const reader = await RecordBatchReader.from(originalBody);
+  await reader.open();
+  const schema = reader.schema;
+  if (!schema) {
+    throw new RpcError("ProtocolError", "Original request body has no schema", "");
+  }
+  const batches = reader.readAll();
+  if (batches.length === 0) {
+    throw new RpcError("ProtocolError", "Original request body has no batches", "");
+  }
+  const original = batches[0];
+  const originalMeta = original.metadata ?? new Map<string, string>();
+
+  const pointer = makeExternalLocationBatch(schema, downloadUrl);
+  const merged = new Map<string, string>(pointer.metadata ?? new Map());
+  // Preserve the original RPC dispatch metadata so the server can route.
+  const method = originalMeta.get(RPC_METHOD_KEY);
+  const version = originalMeta.get(REQUEST_VERSION_KEY) ?? REQUEST_VERSION;
+  if (method) merged.set(RPC_METHOD_KEY, method);
+  merged.set(REQUEST_VERSION_KEY, version);
+  // Carry over any other keys (request id, state token for exchange, etc).
+  for (const [k, v] of originalMeta) {
+    if (!merged.has(k)) merged.set(k, v);
+  }
+
+  // Re-emit the pointer batch with merged metadata.
+  const { RecordBatch } = await import("@query-farm/apache-arrow");
+  const pointerWithMeta = new RecordBatch(schema as any, (pointer as any).data, merged);
+  return serializeIpcStream(schema, [pointerWithMeta]);
+}
+
+export interface ExternalizeOptions {
+  baseUrl: string;
+  prefix: string;
+  authorization?: string;
+  /** Optional per-URL validator; throw to reject. */
+  urlValidator?: ((url: string) => void) | null;
+}
+
+/**
+ * Upload *body* via a server-vended URL and return the pointer-batch body
+ * that should be sent in place of the original. Throws if the server does
+ * not advertise upload-URL support or the upload fails.
+ */
+export async function externalizeRequestBody(body: Uint8Array, opts: ExternalizeOptions): Promise<Uint8Array> {
+  const pairs = await requestUploadUrls(opts.baseUrl, opts.prefix, 1, opts.authorization);
+  const pair = pairs[0];
+
+  if (opts.urlValidator) {
+    opts.urlValidator(pair.uploadUrl);
+    opts.urlValidator(pair.downloadUrl);
+  }
+
+  const putResp = await fetch(pair.uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": ARROW_CONTENT_TYPE },
+    body: body as unknown as BodyInit,
+  });
+  if (!putResp.ok) {
+    throw new RpcError("ExternalUploadFailed", `PUT to upload URL failed: HTTP ${putResp.status}`, "");
+  }
+
+  return buildPointerRequestBody(body, pair.downloadUrl);
+}

package/src/constants.ts

@@ -15,11 +15,28 @@ export const REQUEST_ID_KEY = "vgi_rpc.request_id";
 
 export const PROTOCOL_NAME_KEY = "vgi_rpc.protocol_name";
 export const DESCRIBE_VERSION_KEY = "vgi_rpc.describe_version";
-export const DESCRIBE_VERSION = "3";
+export const PROTOCOL_HASH_KEY = "vgi_rpc.protocol_hash";
+export const DESCRIBE_VERSION = "4";
+
+/** Application protocol surface version. Carried on every request batch from
+ *  a client bound to a Protocol that declares `protocolVersion`; also emitted
+ *  in the __describe__ response metadata. Format: canonical semver
+ *  MAJOR.MINOR.PATCH. Enforced at the dispatch boundary on the server: exact
+ *  major+minor match required, patch ignored. Distinct from `REQUEST_VERSION`
+ *  (wire framing). Mirrors Python's `PROTOCOL_VERSION_KEY`. */
+export const PROTOCOL_VERSION_KEY = "vgi_rpc.protocol_version";
 
 export const DESCRIBE_METHOD_NAME = "__describe__";
 
 export const STATE_KEY = "vgi_rpc.stream_state#b64";
+export const CANCEL_KEY = "vgi_rpc.cancel";
 
 export const LOCATION_KEY = "vgi_rpc.location";
 export const LOCATION_SHA256_KEY = "vgi_rpc.location.sha256";
+
+export const RPC_ERROR_HEADER = "X-VGI-RPC-Error";
+
+/** Top-level metadata key on an EXCEPTION batch identifying the error category.
+ *  Hoisted by `buildErrorBatch` when the thrown error has a static or instance
+ *  `errorKind` property. Mirrors Python's `vgi_rpc.metadata.ERROR_KIND_KEY`. */
+export const ERROR_KIND_KEY = "vgi_rpc.error_kind";

package/src/crypto.ts

@@ -0,0 +1,95 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Generic AEAD seal/open primitives shared by stream-state and sticky-session
+ * tokens. Mirrors Python's `vgi_rpc.crypto` module: a tiny envelope around
+ * XChaCha20-Poly1305 with a leading version byte so future format bumps stay
+ * self-describing.
+ *
+ * Wire format (returned by {@link sealBytes}, accepted by {@link openBytes}):
+ *
+ * ```
+ *   [1B  version  (1..255)]
+ *   [24B nonce    (XChaCha20-Poly1305, random per envelope)]
+ *   [..  ciphertext + 16B Poly1305 tag]
+ * ```
+ *
+ * The plaintext frame is fully up to the caller — only the version + nonce +
+ * tag overhead is fixed. AAD (`aad`) is bound at the crypto layer so an
+ * envelope sealed for one identity fails decryption when presented by another.
+ */
+
+import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { randomBytes } from "./util/web-crypto.js";
+
+const NONCE_LEN = 24;
+const TAG_LEN = 16;
+const VERSION_LEN = 1;
+const MIN_ENVELOPE_LEN = VERSION_LEN + NONCE_LEN + TAG_LEN;
+
+/** Thrown by {@link openBytes} for any envelope it cannot open — malformed,
+ *  tampered, wrong key, wrong AAD, wrong version, truncated, all surface the
+ *  same way so callers cannot distinguish failure modes via error content. */
+export class SealError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SealError";
+  }
+}
+
+/** Normalise a key to 32 bytes by SHA-256 hashing when it isn't already 32B.
+ *  Mirrors Python's `normalize_key` so any callers can pass operator-provided
+ *  keys of arbitrary length without a separate stretching step. */
+export async function normalizeKey(key: Uint8Array): Promise<Uint8Array> {
+  if (key.length === 32) return key;
+  const digest = await crypto.subtle.digest("SHA-256", key as BufferSource);
+  return new Uint8Array(digest);
+}
+
+export interface SealOptions {
+  /** Associated data bound at the crypto layer — typically a principal or
+   *  request-scoped identifier. Must match between seal and open. */
+  aad: Uint8Array;
+  /** Envelope version byte. Defaults to 1; carry through to {@link openBytes}. */
+  version?: number;
+}
+
+/** Seal `plaintext` under `key` with AEAD, returning the wire envelope. */
+export function sealBytes(plaintext: Uint8Array, key: Uint8Array, opts: SealOptions): Uint8Array {
+  if (key.length !== 32) {
+    throw new Error("AEAD key must be 32 bytes — call normalizeKey() first");
+  }
+  const version = opts.version ?? 1;
+  if (version < 1 || version > 255) {
+    throw new Error(`AEAD envelope version must fit in one byte; got ${version}`);
+  }
+  const nonce = randomBytes(NONCE_LEN);
+  const ciphertext = xchacha20poly1305(key, nonce, opts.aad as Uint8Array).encrypt(plaintext);
+  const wire = new Uint8Array(VERSION_LEN + NONCE_LEN + ciphertext.length);
+  wire[0] = version;
+  wire.set(nonce, VERSION_LEN);
+  wire.set(ciphertext, VERSION_LEN + NONCE_LEN);
+  return wire;
+}
+
+/** Open and verify an envelope produced by {@link sealBytes}. */
+export function openBytes(envelope: Uint8Array, key: Uint8Array, opts: SealOptions): Uint8Array {
+  if (key.length !== 32) {
+    throw new Error("AEAD key must be 32 bytes — call normalizeKey() first");
+  }
+  if (envelope.length < MIN_ENVELOPE_LEN) {
+    throw new SealError("envelope truncated");
+  }
+  const expectedVersion = opts.version ?? 1;
+  if (envelope[0] !== expectedVersion) {
+    throw new SealError(`unsupported envelope version: ${envelope[0]}`);
+  }
+  const nonce = envelope.subarray(VERSION_LEN, VERSION_LEN + NONCE_LEN);
+  const ciphertext = envelope.subarray(VERSION_LEN + NONCE_LEN);
+  try {
+    return xchacha20poly1305(key, nonce, opts.aad as Uint8Array).decrypt(ciphertext);
+  } catch {
+    throw new SealError("envelope verification failed");
+  }
+}