@query-farm/vgi 0.39.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "TypeScript framework for extending DuckDB with user-defined functions via the Vector Gateway Interface (VGI) over Arrow IPC.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Query Farm LLC (https://query.farm)",
@@ -91,12 +91,12 @@
   },
   "peerDependencies": {
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.26.0"
+    "@query-farm/vgi-rpc": "^0.27.0"
   },
   "devDependencies": {
     "@duckdb/node-api": "^1.5.5-r.4",
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.26.0",
+    "@query-farm/vgi-rpc": "^0.27.0",
     "@types/bun": "latest",
     "typescript": "^7.0.2"
   },

package/src/index.core.ts

@@ -318,6 +318,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 +326,7 @@ export {
 } from "./rpc-server.js";
 export {
   AuthUnavailableError,
+  GrantKeys,
   GrantRefusedError,
   IdentityUnavailableError,
   StatusError,

package/src/rpc-server.ts

@@ -22,6 +22,7 @@
 // exactly as it would against a single-protocol server.
 
 import {
+  GrantKeys,
   type GrantMinter,
   IdentityImpl,
   type Protocol,
@@ -117,6 +118,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`. */
@@ -156,6 +171,9 @@ export function buildRpcServer(
     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,
   });
 }
 
@@ -224,10 +242,15 @@ function buildIdentity(
   env: Record<string, string | undefined> | undefined,
 ): IdentityImpl | undefined {
   const { resolveToken, mintGrant } = hosting;
-  if (!resolveToken && !mintGrant) return undefined;
+  // 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,
+    // 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,
@@ -271,3 +294,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;
@@ -247,6 +260,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,