@query-farm/vgi 0.40.0 → 0.42.0

package/src/catalog/attach-option.ts

@@ -108,6 +108,29 @@ export interface AttachOptionSpec {
   secret?: boolean;
 }
 
+/**
+ * Reserved for attach tickets: the framework reads an ATTACH option with this
+ * name as a `vgi_attach_ticket` before any catalog code runs, so no catalog may
+ * declare an attach option called this, compared case-insensitively.
+ */
+export const RESERVED_ATTACH_OPTION = "vgi_attach_ticket";
+
+/**
+ * Throw if any spec uses the reserved {@link RESERVED_ATTACH_OPTION} name.
+ *
+ * @throws Error naming the offending option.
+ */
+export function assertNoReservedAttachOption(specs: Iterable<Pick<AttachOptionSpec, "name">>): void {
+  for (const spec of specs) {
+    if (spec.name.toLowerCase() === RESERVED_ATTACH_OPTION) {
+      throw new Error(
+        `Attach option '${spec.name}' uses the reserved name '${RESERVED_ATTACH_OPTION}': the framework ` +
+          "reads it as an attach ticket before any catalog code runs. Rename the option.",
+      );
+    }
+  }
+}
+
 const SPEC_SCHEMA = makeSchema([
   field("name", utf8(), false),
   field("description", utf8(), false),
@@ -122,6 +145,7 @@ const SPEC_SCHEMA = makeSchema([
  * (one IPC-serialized RecordBatch with a single row).
  */
 export function serializeAttachOptionSpec(spec: AttachOptionSpec): Uint8Array {
+  assertNoReservedAttachOption([spec]);
   // Mirrors AttachOptionSpec.__post_init__ on the Python side: an option that
   // falls back to a value is always satisfiable without the caller, so the
   // combination is a declaration bug rather than a runtime condition.
@@ -260,6 +284,8 @@ export function validateRequiredAttachOptions(
   specs: Iterable<AttachOptionSpec>,
   options: Record<string, unknown>,
 ): void {
+  specs = Array.from(specs);
+  assertNoReservedAttachOption(specs);
   const supplied = new Set(Object.keys(options).map((key) => key.toLowerCase()));
   const missing = Array.from(specs)
     .filter((spec) => spec.required && !supplied.has(spec.name.toLowerCase()))
@@ -268,3 +294,52 @@ export function validateRequiredAttachOptions(
     throw new MissingAttachOptionsError(catalogName, missing);
   }
 }
+
+/** Raised when a catalog declares the reserved attach option name. */
+export class ReservedAttachOptionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ReservedAttachOptionError";
+  }
+}
+
+/**
+ * Startup check: refuse a catalog that declares an attach option named
+ * {@link RESERVED_ATTACH_OPTION}, reading the specs it advertises through
+ * `catalogsInfo()`.
+ *
+ * TypeScript has no declaration-time hook for a plain spec object, so the
+ * worker entry points run this before serving. Only the reserved-name refusal
+ * propagates (as {@link ReservedAttachOptionError}); any other failure reading
+ * `catalogsInfo()` -- a catalog whose discovery needs I/O that is not up yet
+ * -- is left for discovery itself to report.
+ */
+export async function checkReservedAttachOptions(catalog: {
+  catalogsInfo?(): unknown;
+} | undefined): Promise<void> {
+  if (!catalog?.catalogsInfo) return;
+  let infos: unknown;
+  try {
+    infos = await catalog.catalogsInfo();
+  } catch (e) {
+    if (e instanceof Error && e.message.includes(`reserved name '${RESERVED_ATTACH_OPTION}'`)) {
+      throw new ReservedAttachOptionError(e.message);
+    }
+    return;
+  }
+  for (const info of (infos ?? []) as Array<{ attach_option_specs?: unknown[] | null }>) {
+    for (const raw of info.attach_option_specs ?? []) {
+      let name: string;
+      try {
+        name = deserializeAttachOptionSpec(toUint8Array(raw as Uint8Array)).name;
+      } catch {
+        continue;
+      }
+      try {
+        assertNoReservedAttachOption([{ name }]);
+      } catch (e) {
+        throw new ReservedAttachOptionError((e as Error).message);
+      }
+    }
+  }
+}

package/src/catalog/composite.ts

@@ -24,6 +24,7 @@ import type {
   ViewInfo,
 } from "./interface.js";
 import { CatalogInterface } from "./interface.js";
+import { OpaqueDataRejectedError } from "../crypto.js";
 
 function bufferEquals(a: AttachOpaqueData, b: AttachOpaqueData): boolean {
   if (a.length !== b.length) return false;
@@ -52,7 +53,10 @@ export class CompositeCatalogInterface extends CatalogInterface {
     const idx = attachOpaqueData[ROUTE_BYTE];
     const route = this._backends[idx];
     if (!route) {
-      throw new Error(`CompositeCatalog: no backend at route-byte index ${idx} (have ${this._backends.length})`);
+      // Routing is a check too (vgi-opaque-data-sealing.md rule 4): an
+      // unroutable value gets the uniform refusal, never a description of
+      // what this worker serves.
+      throw new OpaqueDataRejectedError("attach_opaque_data");
     }
     return route;
   }

package/src/crypto.ts

@@ -44,7 +44,13 @@ const TRANSACTION_AAD_PREFIX = _UTF8.encode("vgi.transaction_opaque_data.v1\0");
  * this single error so a probing caller cannot distinguish them.
  */
 export class OpaqueDataRejectedError extends Error {
+  /** Canonical code (vgi-opaque-data-sealing.md rule 4): never `UNKNOWN`. */
+  readonly errorCode = "INVALID_ARGUMENT";
+  /** The classified kind a client branches on; identical for every cause. */
+  readonly errorKind = "opaque_data_not_recognized";
   constructor(field = "opaque data") {
+    // Exactly `<field> not recognized`, no details: a probing caller learns
+    // nothing about which check failed.
     super(`${field} not recognized`);
     this.name = "OpaqueDataRejectedError";
   }
@@ -108,8 +114,14 @@ export async function sealBytes(
   key: Uint8Array,
   aad: Uint8Array,
   version: number,
+  fixedNonce?: Uint8Array,
 ): Promise<Uint8Array> {
-  const nonce = crypto.getRandomValues(new Uint8Array(NONCE_LEN));
+  // A fixed nonce exists for byte-exact test vectors only; every real seal
+  // draws 24 fresh random bytes.
+  if (fixedNonce !== undefined && fixedNonce.length !== NONCE_LEN) {
+    throw new Error(`nonce must be ${NONCE_LEN} bytes`);
+  }
+  const nonce = fixedNonce ?? crypto.getRandomValues(new Uint8Array(NONCE_LEN));
   const ciphertext = xchacha20poly1305(await normalizeKey(key), nonce, aad).encrypt(payload);
   const out = new Uint8Array(1 + NONCE_LEN + ciphertext.length);
   out[0] = version & 0xff;

package/src/http/fetch.ts

@@ -27,6 +27,7 @@ import { buildVgiProtocol, type ProtocolConfig } from "../protocol/dispatch.js";
 import { createLandingRoutes, type LandingInfo } from "./landing.js";
 import { buildRpcServer, type HostingOptions } from "../rpc-server.js";
 import { setRequestAuthScope, type RequestAuthHolder } from "../request-auth.js";
+import { checkReservedAttachOptions } from "../catalog/attach-option.js";
 
 export interface VgiFetchOptions extends HostingOptions {
   /** Wire-protocol config (registry + catalogInterface). */
@@ -35,6 +36,12 @@ export interface VgiFetchOptions extends HostingOptions {
    *  (e.g. derived from a Wrangler secret). Required because Workers don't
    *  preserve in-memory state across requests/instances. */
   signingKey: Uint8Array;
+  /** Whether {@link signingKey} came from explicit configuration (a secret,
+   *  `VGI_SIGNING_KEY`) rather than being generated for this process. Only a
+   *  configured key hosts `vgi.attach_tickets.v1` (with the ability to issue
+   *  grants): tickets sealed under a generated key would die on restart.
+   *  Defaults to `true`, since this factory requires the key to be passed. */
+  signingKeyConfigured?: boolean;
   /** State-token TTL in seconds (default 3600). */
   tokenTtl?: number;
   /** URL path prefix for VGI requests (default "/vgi"). Pass "" to mount at
@@ -203,7 +210,21 @@ export function createVgiFetch(opts: VgiFetchOptions): (req: Request) => Promise
   // authenticates callers -- vgi_rpc.Identity.v1 when the worker opts in.
   // Built at construction, so a worker that opts into introspection without an
   // allowlist fails here rather than serving traffic.
-  const server = buildRpcServer(protocol, opts, { transport: "http", serverId });
+  const server = buildRpcServer(protocol, opts, {
+    transport: "http",
+    serverId,
+    attachTickets: {
+      signingKey: opts.signingKey,
+      signingKeyConfigured: opts.signingKeyConfigured ?? true,
+      catalogInterface: opts.protocol.catalogInterface,
+    },
+  });
+  // A catalog declaring the reserved `vgi_attach_ticket` attach option must
+  // not serve. This factory is synchronous, so the check runs once up front
+  // and every request waits on it: a refusal fails each request (and is
+  // logged once) rather than letting a ticket be read as an ordinary option.
+  const reservedCheck = checkReservedAttachOptions(opts.protocol.catalogInterface);
+  reservedCheck.catch((e) => console.error(`VGI worker refused to serve: ${(e as Error).message}`));
 
   const handler = createHttpHandler(server, {
     prefix,
@@ -230,6 +251,7 @@ export function createVgiFetch(opts: VgiFetchOptions): (req: Request) => Promise
     enableLandingPage: false,
   });
   return async (req: Request) => {
+    await reservedCheck;
     const storage = await ensureRequestAuthStorage();
     // No AsyncLocalStorage on this host: serve exactly as before.
     if (!storage) return handler(req);

package/src/index.core.ts

@@ -166,7 +166,33 @@ export { createLandingRoutes } from "./http/landing.js";
 export { BindResultSchema, ScanFunctionResultSchema } from "./generated/vgi-protocol-schemas.js";
 
 // Attach-option specs (for catalogs that advertise typed ATTACH options).
-export { type AttachOptionSpec, serializeAttachOptionSpec, serializeAttachOptionSpecs, deserializeAttachOptionSpec, deserializeAttachOptionSpecs } from "./catalog/attach-option.js";
+export {
+  type AttachOptionSpec,
+  serializeAttachOptionSpec,
+  serializeAttachOptionSpecs,
+  deserializeAttachOptionSpec,
+  deserializeAttachOptionSpecs,
+  RESERVED_ATTACH_OPTION,
+  ReservedAttachOptionError,
+} from "./catalog/attach-option.js";
+export {
+  ATTACH_TICKET_OPTION,
+  ATTACH_TICKET_PREFIX,
+  ATTACH_TICKETS_PROTOCOL_NAME,
+  ATTACH_TICKETS_PROTOCOL_VERSION,
+  ATTACH_TICKET_SCHEMA,
+  SEAL_ATTACH_REQUEST_SCHEMA,
+  AttachTicketExpiredError,
+  AttachTicketInvalidError,
+  AttachTicketRequestError,
+  SealAttachDeniedError,
+  type AttachTicketClaims,
+  type RestoredAttach,
+  attachTicketAad,
+  mintAttachTicket,
+  openAttachTicket,
+  redeemAttachTicket,
+} from "./attach-ticket.js";
 
 // Column statistics (for inlining on TableInfo.column_statistics).
 export { type ColumnStatistics, serializeColumnStatistics } from "./util/statistics.js";

package/src/protocol/dispatch.ts

@@ -15,6 +15,7 @@ import { registerFunctionMethods } from "./handlers/function.js";
 import { registerAggregateMethods } from "./handlers/aggregate.js";
 import { registerTableBufferingMethods } from "./handlers/table-buffering.js";
 import { registerCatalogMethods } from "./handlers/catalog/index.js";
+import { registerUnimplementedMethods } from "./handlers/unimplemented.js";
 
 export interface ProtocolConfig {
   registry: FunctionRegistry;
@@ -56,6 +57,20 @@ export interface ProtocolConfig {
  */
 export const VGI_PROTOCOL_NAME = "vgi.v2";
 
+/**
+ * The `vgi.v2` protocol hash `vgi_rpc.Reflection.v1` must report for this
+ * worker: the reference's (vgi-python 0.43.0, 72 methods). Every SDK hosts
+ * every `vgi.v2` method with the reference's schemas, so the hash is one value
+ * across the ports; a method this SDK does not implement is still registered
+ * (handlers/unimplemented.ts). The hash covers method names, types and the
+ * params/result/header schemas only (WIRE_PROTOCOL.md §14).
+ *
+ * It changes only with vgi.v2's protocol version (currently 2.1.0). Asserted
+ * by src/protocol/__tests__/vgi-v2-hash.test.ts; if that test fails, the
+ * surface drifted from the reference -- fix the schemas, do not bump this.
+ */
+export const VGI_V2_PROTOCOL_HASH = "774cb80090d71ea76d09aa311b9cda4ca4c33c3bf72c43242eb6dc87b6f79ce5";
+
 export function buildVgiProtocol(config: ProtocolConfig): Protocol {
   const protocol = new Protocol(VGI_PROTOCOL_NAME, { protocolVersion: "2.1.0" });
 
@@ -67,6 +82,7 @@ export function buildVgiProtocol(config: ProtocolConfig): Protocol {
   registerAggregateMethods(protocol, config.registry);
   registerTableBufferingMethods(protocol, config.registry, config.signingKey);
   registerCatalogMethods(protocol, config.catalogInterface, config.catalogName, config.signingKey);
+  registerUnimplementedMethods(protocol);
 
   return protocol;
 }

package/src/protocol/handlers/catalog/admin.ts

@@ -45,6 +45,8 @@ import {
   CatalogVersionResultSchema,
 } from "../../../generated/vgi-protocol-schemas.js";
 import { toUint8Array } from "../../../util/bytes.js";
+import { redeemAttachTicket } from "../../../attach-ticket.js";
+import { currentRequestAuth } from "../../../request-auth.js";
 import { decodeDictValue } from "../../../util/arrow/index.js";
 import {
   REQUEST_PARAMS_SCHEMA,
@@ -98,7 +100,25 @@ export function registerCatalogAdminMethods(protocol: Protocol, getCatalog: GetC
       // RecordBatch of typed columns — one column per option. Deserialize
       // once here so workers see an ergonomic {name: value} dict instead of
       // raw bytes. Nullable / absent → {}.
-      const optionsDict = decodeOptionsBatch(innerParams.options);
+      let optionsDict = decodeOptionsBatch(innerParams.options);
+      // A `vgi_attach_ticket` is redeemed here, before any catalog code runs:
+      // the request becomes the attach the ticket seals (catalog name,
+      // options, version specs). A composite catalog therefore routes on the
+      // sealed name, not the request's. The ticket opens only under the
+      // caller's principal and this worker's signing key; neither it nor a
+      // restored option is ever logged.
+      const restored = await redeemAttachTicket(
+        optionsDict,
+        signingKey,
+        (ctx as CallContext | undefined)?.auth ?? currentRequestAuth(),
+      );
+      if (restored !== null) {
+        innerParams.name = restored.name;
+        innerParams.options = restored.optionsIpc;
+        innerParams.data_version_spec = restored.dataVersionSpec;
+        innerParams.implementation_version = restored.implementationVersion;
+        optionsDict = restored.options;
+      }
       const result = await cat.attach(
         innerParams.name,
         optionsDict,

package/src/protocol/handlers/unimplemented.ts

@@ -0,0 +1,74 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// vgi.v2 methods this SDK registers but does not implement.
+//
+// "The protocol is the unit of optionality": every SDK hosts EVERY vgi.v2
+// method with exactly the reference's schemas, so vgi_rpc.Reflection.v1
+// reports one vgi.v2 protocol hash everywhere (see VGI_V2_PROTOCOL_HASH in
+// ../dispatch.ts). A method this port has no implementation for is still
+// registered -- with the reference's params/result schemas -- and answers
+// every call with vgi-rpc's MethodNotImplementedError: error_code
+// UNIMPLEMENTED, error_kind method_not_implemented. Never a silent success.
+//
+// When one of these gains a real implementation, move it out of this list
+// into its handler module; the schemas must not change (the hash test fails
+// if they do).
+
+import { MethodNotImplementedError, type Protocol } from "@query-farm/vgi-rpc";
+import type { VgiSchema } from "../../arrow/index.js";
+import {
+  CatalogIndexCreateParamsSchema,
+  CatalogIndexDropParamsSchema,
+  CatalogTableColumnCommentSetParamsSchema,
+  CatalogTableDeleteFunctionGetParamsSchema,
+  CatalogTableInsertFunctionGetParamsSchema,
+  CatalogTableUpdateFunctionGetParamsSchema,
+} from "../../generated/vgi-protocol-schemas.js";
+import { REQUEST_PARAMS_SCHEMA, RESULT_BINARY_SCHEMA } from "./shared.js";
+import { emptyResultSchema } from "./catalog/shared.js";
+
+/** One unimplemented method: its wire name and the reference's schemas. */
+interface UnimplementedMethod {
+  readonly name: string;
+  readonly params: VgiSchema;
+  readonly result: VgiSchema;
+}
+
+/**
+ * The vgi.v2 methods (of the reference's 72) this SDK does not implement.
+ * Exported so a test can assert each one refuses with UNIMPLEMENTED.
+ */
+export const UNIMPLEMENTED_METHODS: readonly UnimplementedMethod[] = [
+  // Streaming and window aggregates: request/result are wrapped ASD blobs.
+  { name: "aggregate_streaming_open", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  { name: "aggregate_streaming_chunk", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  { name: "aggregate_streaming_close", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  { name: "aggregate_window_init", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  { name: "aggregate_window", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  { name: "aggregate_window_batch", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  { name: "aggregate_window_destructor", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  // Index DDL and per-column comments.
+  { name: "catalog_index_create", params: CatalogIndexCreateParamsSchema, result: emptyResultSchema },
+  { name: "catalog_index_drop", params: CatalogIndexDropParamsSchema, result: emptyResultSchema },
+  { name: "catalog_table_column_comment_set", params: CatalogTableColumnCommentSetParamsSchema, result: emptyResultSchema },
+  // Per-table DML function getters.
+  { name: "catalog_table_insert_function_get", params: CatalogTableInsertFunctionGetParamsSchema, result: RESULT_BINARY_SCHEMA },
+  { name: "catalog_table_update_function_get", params: CatalogTableUpdateFunctionGetParamsSchema, result: RESULT_BINARY_SCHEMA },
+  { name: "catalog_table_delete_function_get", params: CatalogTableDeleteFunctionGetParamsSchema, result: RESULT_BINARY_SCHEMA },
+];
+
+/** The message every unimplemented method answers with. */
+export function unimplementedMessage(method: string): string {
+  return `${method} is not implemented by this worker`;
+}
+
+export function registerUnimplementedMethods(protocol: Protocol): void {
+  for (const m of UNIMPLEMENTED_METHODS) {
+    protocol.unary(m.name, {
+      params: m.params,
+      result: m.result,
+      handler: async () => {
+        throw new MethodNotImplementedError(unimplementedMessage(m.name));
+      },
+    });
+  }
+}

package/src/rpc-server.ts

@@ -14,7 +14,10 @@
 //      transport.
 //   3. `vgi_rpc.Reflection.v1` -- on every transport.
 //   4. `vgi_rpc.Identity.v1` -- HTTP only, and only when the worker supplies
-//      `resolveToken` and/or `mintGrant`.
+//      `resolveToken` and/or `mintGrant` (or grant keys are configured).
+//   5. `vgi.attach_tickets.v1` -- HTTP only, and only when the signing key was
+//      configured explicitly (never a generated one) *and* the worker can
+//      issue grants. See `attach-ticket.ts`.
 //
 // Extra protocols cannot change `vgi.v2` behaviour: vgi-rpc routes every
 // request on its `vgi_rpc.protocol` key with no fallback to the primary, so a
@@ -29,6 +32,8 @@ import {
   type TokenResolver,
   VgiRpcServer,
 } from "@query-farm/vgi-rpc";
+import { buildAttachTicketsProtocol, resolveTicketMaxTtl } from "./attach-ticket.js";
+import type { CatalogInterface } from "./catalog/interface.js";
 
 /** The transport a server is being built for. Only `"http"` changes what is
  *  hosted (identity); the rest are recorded so the decision lives here rather
@@ -143,6 +148,19 @@ export interface BuildRpcServerOptions {
   /** Environment to read `VGI_INTROSPECT_PRINCIPALS` from. Default
    *  `process.env` where it exists (not on Cloudflare Workers). */
   env?: Record<string, string | undefined>;
+  /**
+   * HTTP only: what `vgi.attach_tickets.v1` needs. Hosted when
+   * `signingKeyConfigured` is true -- the key came from explicit
+   * configuration, not generated for this process, which would make every
+   * ticket die on restart -- and the worker can issue grants (grant keys
+   * configured, or its own `mintGrant`). Otherwise the protocol is absent,
+   * not hosted-and-refusing.
+   */
+  attachTickets?: {
+    signingKey: Uint8Array | undefined;
+    signingKeyConfigured: boolean;
+    catalogInterface: CatalogInterface | undefined;
+  };
 }
 
 /**
@@ -166,7 +184,16 @@ export function buildRpcServer(
     throw new Error(`Unknown transport ${JSON.stringify(options.transport)}; expected one of ${[...TRANSPORTS].join(", ")}.`);
   }
   const protocols = validatedHostedProtocols(hosting, primary);
-  const identity = IDENTITY_TRANSPORTS.has(options.transport) ? buildIdentity(hosting, options.env) : undefined;
+  let identity: IdentityImpl | undefined;
+  if (IDENTITY_TRANSPORTS.has(options.transport)) {
+    const env = options.env ?? processEnv();
+    // Explicit option, else the environment. Read at server build, so a
+    // malformed key stops the worker before it serves anything.
+    const grantKeys = hosting.grantKeys === undefined ? GrantKeys.fromEnv(env) : hosting.grantKeys;
+    identity = buildIdentity(hosting, grantKeys, options.env);
+    const tickets = buildAttachTickets(hosting, grantKeys, options.attachTickets, env);
+    if (tickets) protocols.push(tickets);
+  }
   return new VgiRpcServer(primary, {
     serverId: options.serverId,
     protocols,
@@ -239,12 +266,10 @@ function validatedHostedProtocols(hosting: HostingOptions, primary: Protocol): P
  *  hosting it and refusing every call. The two hooks are independent. */
 function buildIdentity(
   hosting: HostingOptions,
+  grantKeys: GrantKeys | null,
   env: Record<string, string | undefined> | undefined,
 ): IdentityImpl | undefined {
   const { resolveToken, mintGrant } = hosting;
-  // Explicit option, else the environment. Read at server build, so a
-  // malformed key stops the worker before it serves anything.
-  const grantKeys = hosting.grantKeys === undefined ? GrantKeys.fromEnv(env ?? processEnv()) : hosting.grantKeys;
   if (!resolveToken && !mintGrant && !grantKeys) return undefined;
   return new IdentityImpl({
     resolveToken,
@@ -258,6 +283,26 @@ function buildIdentity(
   });
 }
 
+/** Build `vgi.attach_tickets.v1`, or `undefined` when it must not be hosted.
+ *
+ *  Both halves of an unattended session have to be issuable: a ticket under a
+ *  generated per-process key would die on restart, and a ticket without a
+ *  grant attaches nothing. */
+function buildAttachTickets(
+  hosting: HostingOptions,
+  grantKeys: GrantKeys | null,
+  config: BuildRpcServerOptions["attachTickets"],
+  env: Record<string, string | undefined> | undefined,
+): Protocol | undefined {
+  if (!config || !config.signingKeyConfigured || !config.signingKey) return undefined;
+  if (!grantKeys && !hosting.mintGrant) return undefined;
+  return buildAttachTicketsProtocol({
+    signingKey: config.signingKey,
+    catalogInterface: config.catalogInterface,
+    maxTtlSeconds: resolveTicketMaxTtl(grantKeys, env),
+  });
+}
+
 /**
  * Resolve the introspector allowlist, or refuse to start.
  *

package/src/serve-entry.ts

@@ -224,6 +224,9 @@ export function createVgiWorkerFetch(
 ): (req: Request) => Promise<Response> {
   const env = opts.env ?? (process.env as ServeEnv);
   const signingKey = resolveSigningKey(opts.signingKey, env);
+  // Explicit option or `$VGI_SIGNING_KEY`: a key that survives a restart.
+  // The generated fallback never enables attach tickets.
+  const signingKeyConfigured = opts.signingKey !== undefined || !!env.VGI_SIGNING_KEY?.trim();
   const tokenTtl = resolveTokenTtl(opts.tokenTtl, env);
   // `null` disables CORS and must stay `null` through to createVgiFetch, which
   // now reads a bare `undefined` as "default to *" — passing `undefined` here to
@@ -241,6 +244,7 @@ export function createVgiWorkerFetch(
   return createVgiFetch({
     protocol: { registry: opts.registry, catalogInterface: opts.catalogInterface },
     signingKey,
+    signingKeyConfigured,
     tokenTtl,
     prefix: opts.prefix ?? "",
     serverId: opts.serverId ?? opts.name,

package/src/worker.ts

@@ -17,6 +17,7 @@ import type { Protocol } from "@query-farm/vgi-rpc";
 import { schemaDescriptorPath, type CatalogDescriptor } from "./catalog/descriptors.js";
 import type { CatalogInterface } from "./catalog/interface.js";
 import { ReadOnlyCatalogInterface } from "./catalog/read-only.js";
+import { checkReservedAttachOptions } from "./catalog/attach-option.js";
 
 /**
  * Startup/lifecycle tracing, off unless `VGI_DEBUG` is set to something other
@@ -180,6 +181,18 @@ export class Worker {
 
   run(argv: readonly string[] = process.argv.slice(2)): void {
     debug(() => `[worker] starting, pid=${process.pid}`);
+    // Refuse to serve a catalog that declares the reserved `vgi_attach_ticket`
+    // attach option, before anything is read off the transport.
+    checkReservedAttachOptions(this._catalogInterface).then(
+      () => this._serve(argv),
+      (err: Error) => {
+        process.stderr.write(`Worker init error: ${err.message}\n`);
+        process.exit(1);
+      },
+    );
+  }
+
+  private _serve(argv: readonly string[]): void {
     try {
       const protocol = this.buildProtocol();
       debug(() => `[worker] protocol built`);