@query-farm/vgi 0.39.0 → 0.41.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";
@@ -318,6 +344,7 @@ export type { RpcClient, StreamSession, LogMessage } from "@query-farm/vgi-rpc";
 // GrantRefusedError to decline a grant.
 export {
   buildRpcServer,
+  grantKeysFromArgv,
   INTROSPECT_PRINCIPALS_ENV,
   type BuildRpcServerOptions,
   type HostingOptions,
@@ -325,6 +352,7 @@ export {
 } from "./rpc-server.js";
 export {
   AuthUnavailableError,
+  GrantKeys,
   GrantRefusedError,
   IdentityUnavailableError,
   StatusError,

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/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
@@ -22,12 +25,15 @@
 // exactly as it would against a single-protocol server.
 
 import {
+  GrantKeys,
   type GrantMinter,
   IdentityImpl,
   type Protocol,
   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
@@ -117,6 +123,20 @@ export interface HostingOptions {
   /** Maximum age of the caller's authentication for `issue_grant`, in
    *  seconds. vgi-rpc's default when omitted. */
   maxAuthAge?: number;
+
+  /**
+   * Sealed-grant keys (vgi-rpc `GrantKeys`), turning on the framework's own
+   * grants on HTTP: `issue_grant` mints `vgig1.` tokens (unless
+   * {@link mintGrant} is supplied) and the worker's HTTP authentication accepts
+   * them back as bearer credentials, as the grant's owner. When omitted,
+   * `VGI_RPC_GRANT_KEYS` (comma-separated base64, exactly 32 bytes each, first
+   * mints, all verify), `VGI_RPC_GRANT_AUDIENCE` and
+   * `VGI_RPC_GRANT_MAX_TTL_SECONDS` are read; `serveVgiWorker` also accepts
+   * `--grant-key KEY` (repeatable). Unset everywhere, nothing changes. A
+   * malformed key refuses to start. `null` turns grants off regardless of the
+   * environment.
+   */
+  grantKeys?: GrantKeys | null;
 }
 
 /** Server-level options passed through to `VgiRpcServer`. */
@@ -128,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;
+  };
 }
 
 /**
@@ -151,11 +184,23 @@ 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,
     identity,
+    // Resolved here, per transport, rather than by vgi-rpc's own environment
+    // default: identity (and so grants) is hosted on HTTP only.
+    grantKeys: null,
   });
 }
 
@@ -221,13 +266,16 @@ 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;
-  if (!resolveToken && !mintGrant) return undefined;
+  if (!resolveToken && !mintGrant && !grantKeys) return undefined;
   return new IdentityImpl({
     resolveToken,
+    // Absent with grant keys configured, vgi-rpc mints sealed grants itself.
     mintGrant,
+    grantKeys: grantKeys ?? undefined,
     // Only meaningful for `introspect_token`; a worker that mints but resolves
     // nothing is not an oracle and needs no allowlist.
     introspectPrincipals: resolveToken ? resolveIntrospectPrincipals(hosting.introspectPrincipals, env) : undefined,
@@ -235,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.
  *
@@ -271,3 +339,34 @@ function resolveIntrospectPrincipals(
   }
   return principals;
 }
+
+function processEnv(): Record<string, string | undefined> | undefined {
+  return (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;
+}
+
+/**
+ * Collect `--grant-key KEY` / `--grant-key=KEY` (repeatable, first mints) from
+ * an argv, as a `GrantKeys` -- or `undefined` when none was passed, so the
+ * environment still applies. Audience and lifetime come from
+ * `VGI_RPC_GRANT_AUDIENCE` / `VGI_RPC_GRANT_MAX_TTL_SECONDS`.
+ *
+ * @throws Error A malformed key: a worker refuses to start.
+ */
+export function grantKeysFromArgv(
+  argv: readonly string[],
+  env: Record<string, string | undefined> | undefined = processEnv(),
+): GrantKeys | undefined {
+  const keys: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--grant-key") {
+      if (i + 1 >= argv.length) throw new Error("--grant-key requires a value");
+      keys.push(argv[++i]);
+    } else if (a.startsWith("--grant-key=")) {
+      keys.push(a.slice("--grant-key=".length));
+    }
+  }
+  if (keys.length === 0) return undefined;
+  const fromEnv = GrantKeys.fromEnv({ ...(env ?? {}), VGI_RPC_GRANT_KEYS: keys.join(",") });
+  return fromEnv ?? undefined;
+}

package/src/serve-entry.ts

@@ -29,10 +29,11 @@ import {
   observePeerIdentity,
   peerIdentityPrimary,
   type AuthenticateFn,
+  GrantKeys,
   type PeerResolutionOptions,
 } from "@query-farm/vgi-rpc";
 import { createVgiFetch } from "./http/fetch.js";
-import type { HostingOptions } from "./rpc-server.js";
+import { grantKeysFromArgv, type HostingOptions } from "./rpc-server.js";
 
 /** Environment variables `serveVgiWorker` reads. Injectable for testing. */
 export interface ServeEnv {
@@ -40,6 +41,14 @@ export interface ServeEnv {
   VGI_SIGNING_KEY?: string;
   VGI_TOKEN_TTL?: string;
   CORS_ORIGINS?: string;
+  /** Sealed-grant keys: comma-separated base64, exactly 32 bytes each, first mints. */
+  VGI_RPC_GRANT_KEYS?: string;
+  /** Audience bound into sealed grants. */
+  VGI_RPC_GRANT_AUDIENCE?: string;
+  /** Sealed-grant lifetime ceiling, seconds (default 7 days). */
+  VGI_RPC_GRANT_MAX_TTL_SECONDS?: string;
+  /** Principals allowed to call `introspect_token`, comma-separated. */
+  VGI_INTROSPECT_PRINCIPALS?: string;
 }
 
 export const DEFAULT_PORT = 8787;
@@ -94,6 +103,10 @@ export interface ServeVgiWorkerOptions extends HostingOptions {
   quiet?: boolean;
   /** Environment source (default `process.env`). */
   env?: ServeEnv;
+  /** Command-line arguments to read `--grant-key KEY` (repeatable, first mints)
+   *  from. Default `process.argv.slice(2)`. A key here takes precedence over
+   *  `VGI_RPC_GRANT_KEYS`; an explicit {@link grantKeys} over both. */
+  argv?: readonly string[];
   /** Authenticates each request, returning the caller's `AuthContext`.
    *  Omit for an anonymous worker (the default). */
   authenticate?: AuthenticateFn;
@@ -211,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
@@ -228,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,
@@ -247,6 +264,11 @@ export function createVgiWorkerFetch(
     mintGrant: opts.mintGrant,
     introspectPrincipals: opts.introspectPrincipals,
     maxAuthAge: opts.maxAuthAge,
+    grantKeys:
+      opts.grantKeys !== undefined
+        ? opts.grantKeys
+        : (grantKeysFromArgv(opts.argv ?? process.argv.slice(2), env as Record<string, string | undefined>) ??
+          GrantKeys.fromEnv(env as Record<string, string | undefined>)),
   });
 }
 

package/src/worker-cf-entry.ts

@@ -18,6 +18,7 @@ export type { VgiFetchOptions } from "./http/fetch.js";
 export type { HostingOptions } from "./rpc-server.js";
 export {
   AuthUnavailableError,
+  GrantKeys,
   GrantRefusedError,
   IdentityUnavailableError,
   StatusError,

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`);