@query-farm/vgi 0.39.0 → 0.41.0

package/dist/rpc-server.d.ts

@@ -1,4 +1,5 @@
-import { type GrantMinter, type Protocol, type TokenResolver, VgiRpcServer } from "@query-farm/vgi-rpc";
+import { GrantKeys, type GrantMinter, type Protocol, type TokenResolver, VgiRpcServer } from "@query-farm/vgi-rpc";
+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
  *  than at each call site. `"iroh"` is the raw TCP upstream of a
@@ -71,6 +72,19 @@ 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`. */
 export interface BuildRpcServerOptions {
@@ -81,6 +95,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;
+    };
 }
 /**
  * Build the vgi-rpc server for a worker's `vgi.v2` protocol on `transport`.
@@ -95,3 +122,12 @@ export interface BuildRpcServerOptions {
  *   on HTTP with no introspector allowlist.
  */
 export declare function buildRpcServer(primary: Protocol, hosting: HostingOptions, options: BuildRpcServerOptions): VgiRpcServer;
+/**
+ * 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 declare function grantKeysFromArgv(argv: readonly string[], env?: Record<string, string | undefined> | undefined): GrantKeys | undefined;

package/dist/serve-entry.d.ts

@@ -1,13 +1,21 @@
 import type { CatalogInterface } from "./catalog/interface.js";
 import type { FunctionRegistry } from "./functions/registry.js";
 import { type AuthenticateFn, type PeerResolutionOptions } from "@query-farm/vgi-rpc";
-import type { HostingOptions } from "./rpc-server.js";
+import { type HostingOptions } from "./rpc-server.js";
 /** Environment variables `serveVgiWorker` reads. Injectable for testing. */
 export interface ServeEnv {
     PORT?: string;
     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 declare const DEFAULT_PORT = 8787;
 export declare const DEFAULT_TOKEN_TTL = 3600;
@@ -58,6 +66,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;