@query-farm/vgi 0.39.0 → 0.40.0

package/README.md

@@ -615,6 +615,37 @@ never return `null` for one: both read as a definitive answer. Return `null` onl
 when the store answered and the credential is unknown; throw `GrantRefusedError` to
 decline a grant.
 
+### Sealed grants: minted credentials that log their owner in
+
+`issue_grant` mints a credential meant for unattended automation to present later
+as an ordinary bearer. Configure **grant keys** and the worker both mints and
+accepts them, with no storage and no code:
+
+```console
+$ VGI_RPC_GRANT_KEYS="$(openssl rand -base64 32)" bun run scripts/serve.ts
+# or: bun run scripts/serve.ts --grant-key "$(openssl rand -base64 32)"
+```
+
+- `VGI_RPC_GRANT_KEYS`: comma-separated standard base64, exactly 32 bytes each. The
+  first mints; every key verifies. Rotate by adding the new key first and removing
+  the old one once its grants have expired. `--grant-key KEY` (repeatable) on
+  `serveVgiWorker`, or the `grantKeys` option (`GrantKeys.parse([...])`, required on
+  Cloudflare Workers, where there is no process environment) work too.
+- Optional `VGI_RPC_GRANT_AUDIENCE` (bind grants to this deployment) and
+  `VGI_RPC_GRANT_MAX_TTL_SECONDS` (default 7 days).
+- With keys set, HTTP hosts `issue_grant` (minted by the framework unless you supply
+  `mintGrant`) and the worker's HTTP authentication accepts `vgig1.` grants after
+  your own `authenticate`, as the grant's owner (domain `grant`). A caller
+  authenticated by a grant has no `auth_time`, so it cannot mint another grant.
+- A worker that supplies `resolveToken` also has bearers your `authenticate` did not
+  accept resolved through it (domain `token`); an `AuthUnavailableError` from the hook
+  is a 503 with `Retry-After`, never a 401.
+- Your `authenticate` must throw (not return anonymous) for a bearer it does not
+  recognise, or the chain ends before grants are tried.
+- No key set, nothing changes. A malformed key stops the worker at startup.
+- Sealed grants are not individually revocable: keep the lifetime short; removing a
+  key revokes every grant it minted.
+
 ## Runtimes & entry points
 
 The package ships a backend-agnostic Arrow facade and selects an implementation at

package/dist/index.core.d.ts

@@ -43,7 +43,7 @@ export type { VgiClientOptions, TableFunctionOptions, ScalarFunctionOptions, Tab
 export { str, bytes, int, int32, float, float32, bool, toSchema, OutputCollector, AuthContext } from "@query-farm/vgi-rpc";
 export { subprocessConnect, httpConnect, tcpConnect } from "@query-farm/vgi-rpc";
 export type { RpcClient, StreamSession, LogMessage } from "@query-farm/vgi-rpc";
-export { buildRpcServer, INTROSPECT_PRINCIPALS_ENV, type BuildRpcServerOptions, type HostingOptions, type ServerTransport, } from "./rpc-server.js";
-export { AuthUnavailableError, GrantRefusedError, IdentityUnavailableError, StatusError, } from "@query-farm/vgi-rpc";
+export { buildRpcServer, grantKeysFromArgv, INTROSPECT_PRINCIPALS_ENV, type BuildRpcServerOptions, type HostingOptions, type ServerTransport, } from "./rpc-server.js";
+export { AuthUnavailableError, GrantKeys, GrantRefusedError, IdentityUnavailableError, StatusError, } from "@query-farm/vgi-rpc";
 export type { GrantMinter, IssuedGrant, TokenIdentity, TokenResolver } from "@query-farm/vgi-rpc";
 export { normalizeSchemaPath, schemaPathDisplay, schemaPathKey, schemaPathsEqual, type SchemaPath } from "./schema-path.js";

package/dist/index.js

@@ -13722,6 +13722,7 @@ import { subprocessConnect, httpConnect, tcpConnect } from "@query-farm/vgi-rpc"
 
 // src/rpc-server.ts
 import {
+  GrantKeys,
   IdentityImpl,
   VgiRpcServer
 } from "@query-farm/vgi-rpc";
@@ -13738,7 +13739,8 @@ function buildRpcServer(primary, hosting, options) {
   return new VgiRpcServer(primary, {
     serverId: options.serverId,
     protocols,
-    identity
+    identity,
+    grantKeys: null
   });
 }
 function validatedHostedProtocols(hosting, primary) {
@@ -13781,11 +13783,13 @@ function validatedHostedProtocols(hosting, primary) {
 }
 function buildIdentity(hosting, env) {
   const { resolveToken, mintGrant } = hosting;
-  if (!resolveToken && !mintGrant)
+  const grantKeys = hosting.grantKeys === undefined ? GrantKeys.fromEnv(env ?? processEnv()) : hosting.grantKeys;
+  if (!resolveToken && !mintGrant && !grantKeys)
     return;
   return new IdentityImpl({
     resolveToken,
     mintGrant,
+    grantKeys: grantKeys ?? undefined,
     introspectPrincipals: resolveToken ? resolveIntrospectPrincipals(hosting.introspectPrincipals, env) : undefined,
     maxAuthAge: hosting.maxAuthAge
   });
@@ -13806,10 +13810,31 @@ function resolveIntrospectPrincipals(explicit, env) {
   }
   return principals;
 }
+function processEnv() {
+  return globalThis.process?.env;
+}
+function grantKeysFromArgv(argv, env = processEnv()) {
+  const keys = [];
+  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;
+  const fromEnv = GrantKeys.fromEnv({ ...env ?? {}, VGI_RPC_GRANT_KEYS: keys.join(",") });
+  return fromEnv ?? undefined;
+}
 
 // src/index.core.ts
 import {
   AuthUnavailableError,
+  GrantKeys as GrantKeys2,
   GrantRefusedError,
   IdentityUnavailableError,
   StatusError
@@ -14042,6 +14067,7 @@ export {
   FunctionStorageSqlite,
   FunctionType,
   GROUP_COLUMN_NAME,
+  GrantKeys2 as GrantKeys,
   GrantRefusedError,
   INTROSPECT_PRINCIPALS_ENV,
   IdentityUnavailableError,
@@ -14163,6 +14189,7 @@ export {
   fromBrandedBigInt,
   fromBrandedNumber,
   storage as functionStorage,
+  grantKeysFromArgv,
   httpConnect,
   int3 as int,
   int162 as int16,
@@ -14250,4 +14277,4 @@ export {
   utf82 as utf8
 };
 
-//# debugId=03676B1C4ED9A21664756E2164756E21
+//# debugId=E43EFCB3DEBB959264756E2164756E21