@query-farm/vgi 0.39.0 → 0.41.0

package/README.md

@@ -615,6 +615,81 @@ 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.
+
+### Attach tickets: reattach as a user without their options (`vgi.attach_tickets.v1`)
+
+A grant says *who* attaches; an **attach ticket** says *what*. While a user is
+attached and logged in, the client asks the worker to seal the options it attached
+with, secret ones included, into a ticket only this worker can open. A runner holding
+that user's grant later reattaches with one option and never sees the others:
+
+```sql
+-- as the runner, authenticated by `Authorization: Bearer <grant>`
+ATTACH 'ticket_probe' AS p (TYPE vgi, LOCATION 'https://worker.example.com',
+                            vgi_attach_ticket 'vgia1.…');
+```
+
+- **Hosting.** `seal_attach(request: SealAttachRequest) -> AttachTicket` is hosted on
+  **HTTP only**, and only when both halves of an unattended session can be issued:
+  `VGI_SIGNING_KEY` (or the `signingKey` option) is configured explicitly — the
+  generated fallback key never counts, since every ticket would die on restart — and
+  the worker can issue grants (grant keys configured, or its own `mintGrant`).
+  Otherwise the protocol is absent, so a client learns this from reflection.
+  `createVgiFetch` (Cloudflare Workers) requires its key and so counts it as
+  configured; pass `signingKeyConfigured: false` for a key you generate per isolate.
+- **Sealing.** The caller must be authenticated (anonymous is `action_denied`); no
+  fresh login is needed. Options are checked against the catalog's declared attach
+  options (`invalid_request` with one `BadRequest` violation per field). The lifetime
+  is capped at the grant maximum (`VGI_RPC_GRANT_MAX_TTL_SECONDS`, default 7 days with
+  grant keys); `ttl_seconds: 0` asks for the maximum.
+- **Redeeming.** `catalog_attach` redeems a `vgi_attach_ticket` option (any letter
+  case) before any catalog code runs: it must be the only option (`invalid_request`),
+  it opens only under the caller's principal and this worker's key
+  (`attach_ticket_invalid`) and only within its lifetime (`attach_ticket_expired`),
+  and the attach then proceeds exactly as the user typed it — the sealed catalog name,
+  options and version specs. A `CompositeCatalogInterface` routes on the sealed name.
+  The ticket binds the principal only, not the login domain, so a ticket sealed under
+  a JWT login opens under that user's grant.
+- **Reserved name.** No catalog may declare an attach option named
+  `vgi_attach_ticket` (any case); a worker that does refuses to serve.
+- Rotating `VGI_SIGNING_KEY` invalidates every ticket. A ticket carries no authority:
+  without a grant or login for the same principal it attaches nothing. Neither the
+  ticket nor a restored option is ever logged.
+
+Normative spec: vgi-python `docs/protocol/vgi-attach-tickets.md`. The example HTTP
+worker serves the cross-SDK `ticket_probe` fixture catalog and hosts tickets when
+started with both `VGI_SIGNING_KEY` and `VGI_RPC_GRANT_KEYS`.
+
 ## Runtimes & entry points
 
 The package ships a backend-agnostic Arrow facade and selects an implementation at

package/dist/attach-ticket.d.ts

@@ -0,0 +1,179 @@
+import { type AuthContext, Protocol } from "@query-farm/vgi-rpc";
+import type { CatalogInterface } from "./catalog/interface.js";
+/** Token prefix. The version is in the prefix, so an incompatible format is a
+ *  different prefix -- never half-parsed. */
+export declare const ATTACH_TICKET_PREFIX = "vgia1.";
+/** The reserved ATTACH option a runner presents a ticket in. */
+export declare const ATTACH_TICKET_OPTION = "vgi_attach_ticket";
+/** Wire name of the protocol hosting `seal_attach`. */
+export declare const ATTACH_TICKETS_PROTOCOL_NAME = "vgi.attach_tickets.v1";
+/** Its declared version. */
+export declare const ATTACH_TICKETS_PROTOCOL_VERSION = "1.0.0";
+/** The envelope's version byte, fixed by this format. */
+export declare const TICKET_ENVELOPE_VERSION = 1;
+/** Largest options record (serialized Arrow IPC bytes) a ticket may carry. */
+export declare const MAX_OPTIONS_BYTES: number;
+/** Longest ticket text considered at all. */
+export declare const MAX_TICKET_CHARS: number;
+/** Allowance for clocks disagreeing between the sealing and redeeming worker. */
+export declare const CLOCK_SKEW_SECONDS = 60;
+/**
+ * A `vgi_attach_ticket` this worker cannot accept.
+ *
+ * One type for every cause -- malformed, wrong prefix, non-canonical, wrong
+ * key, wrong principal, tampered, bad payload -- so a caller cannot tell a
+ * forged ticket from another user's. The message never contains the ticket.
+ */
+export declare class AttachTicketInvalidError extends Error {
+    static readonly errorKind = "attach_ticket_invalid";
+    readonly errorKind = "attach_ticket_invalid";
+    readonly errorCode = "INVALID_ARGUMENT";
+    readonly errorDetails: Record<string, unknown>[];
+    constructor(detail?: string);
+}
+/**
+ * An authentic ticket outside its lifetime. Only raised once the ticket has
+ * opened under the caller's principal, so it reveals nothing a forger could use.
+ */
+export declare class AttachTicketExpiredError extends Error {
+    static readonly errorKind = "attach_ticket_expired";
+    readonly errorKind = "attach_ticket_expired";
+    readonly errorCode = "FAILED_PRECONDITION";
+    readonly errorDetails: Record<string, unknown>[];
+    constructor(detail?: string);
+}
+/** `invalid_request` / `INVALID_ARGUMENT` with one `BadRequest` violation per bad field. */
+export declare class AttachTicketRequestError extends Error {
+    readonly errorKind = "invalid_request";
+    readonly errorCode = "INVALID_ARGUMENT";
+    readonly errorDetails: Record<string, unknown>[];
+    constructor(message: string, violations: ReadonlyArray<readonly [string, string]>);
+}
+/** `action_denied` / `PERMISSION_DENIED`, naming the refused action. */
+export declare class SealAttachDeniedError extends Error {
+    readonly errorKind = "action_denied";
+    readonly errorCode = "PERMISSION_DENIED";
+    readonly errorDetails: Record<string, unknown>[];
+    constructor(message: string);
+}
+/** What a ticket carries. */
+export interface AttachTicketClaims {
+    /** Seconds since the Unix epoch. */
+    issuedAt: number;
+    /** Seconds since the Unix epoch; `0` means no expiry. */
+    expiresAt: number;
+    /** 32 lowercase hex; a correlation handle, not a secret. */
+    ticketId: string;
+    catalogName: string;
+    /** `""` when the user gave none. */
+    dataVersionSpec: string;
+    /** `""` when the user gave none. */
+    implementationVersion: string;
+    /** Arrow IPC stream of the one-row options record; empty for none. */
+    optionsIpc: Uint8Array;
+}
+/** The ticket AAD: `"vgi.attach_ticket.v1" 0x00 || UTF-8(principal)`. */
+export declare function attachTicketAad(principal: string): Uint8Array;
+/** Encode a ticket payload (§2.1). Exported for the vectors' byte-exact
+ *  `payload_hex` check; not part of the public API. @internal */
+export declare function encodeAttachTicketPayload(c: AttachTicketClaims): Uint8Array;
+/** Inputs to {@link mintAttachTicket}. */
+export interface MintAttachTicketOptions {
+    principal: string;
+    catalogName: string;
+    optionsIpc: Uint8Array;
+    dataVersionSpec?: string;
+    implementationVersion?: string;
+    issuedAt: number;
+    expiresAt: number;
+    /** Override the random id -- for vectors only. */
+    ticketId?: string;
+    /** A fixed 24-byte nonce -- for vectors only. */
+    nonce?: Uint8Array;
+}
+/**
+ * Seal a ticket for `principal` under `signingKey` (the attach_opaque_data
+ * key; any length, normalized exactly as the attach envelope's is).
+ *
+ * @throws Error An empty principal or catalog, an empty lifetime, a bad
+ *   ticket id, or a field too long to encode.
+ */
+export declare function mintAttachTicket(signingKey: Uint8Array, opts: MintAttachTicketOptions): Promise<{
+    token: string;
+    claims: AttachTicketClaims;
+}>;
+/**
+ * Verify a ticket for the calling `principal` and return what it carries.
+ *
+ * Order, normative: prefix, length, canonical base64url, caller, AEAD open
+ * under the caller's principal, strict payload parse, then lifetime with a
+ * 60 s skew. The lifetime is inside the ciphertext, so it is trusted only
+ * after the tag verified.
+ *
+ * @param now Override the clock (seconds), for tests and vectors.
+ * @throws AttachTicketInvalidError Any cause but expiry.
+ * @throws AttachTicketExpiredError Authentic but outside its lifetime.
+ */
+export declare function openAttachTicket(signingKey: Uint8Array, token: string, principal: string | null | undefined, now?: number): Promise<AttachTicketClaims>;
+/** The catalog_attach request fields a ticket replaces. */
+export interface RestoredAttach {
+    name: string;
+    /** Raw Arrow IPC options bytes, or `null` for none. */
+    optionsIpc: Uint8Array | null;
+    /** The same options, decoded. */
+    options: Record<string, unknown>;
+    dataVersionSpec: string | null;
+    implementationVersion: string | null;
+}
+/** The caller's principal, or `null` for anonymous. */
+export declare function callerPrincipal(auth: AuthContext | undefined | null): string | null;
+/**
+ * Replace a ticket-carrying attach with the attach it seals.
+ *
+ * Returns `null` when `options` carries no `vgi_attach_ticket` (the request is
+ * untouched). Otherwise the ticket must be the only option
+ * ({@link AttachTicketRequestError} -- checked before the ticket is opened),
+ * must open under the caller's principal and `signingKey`
+ * ({@link AttachTicketInvalidError}; no key, as off HTTP, never opens one),
+ * and must be within its lifetime ({@link AttachTicketExpiredError}).
+ * Never logs the ticket or a restored option.
+ */
+export declare function redeemAttachTicket(options: Record<string, unknown>, signingKey: Uint8Array | undefined | null, auth: AuthContext | undefined | null, now?: number): Promise<RestoredAttach | null>;
+/** `SealAttachRequest`, field for field with vgi-python. */
+export declare const SEAL_ATTACH_REQUEST_SCHEMA: import("./index.core.js").VgiSchema;
+/** `AttachTicket`, field for field with vgi-python. */
+export declare const ATTACH_TICKET_SCHEMA: import("./index.core.js").VgiSchema;
+/**
+ * The ticket lifetime ceiling: the worker's grant maximum, or `null`.
+ *
+ * With grant keys configured it is their `maxTtlSeconds`. Otherwise (a worker
+ * minting its own grants) `VGI_RPC_GRANT_MAX_TTL_SECONDS` when set, else none.
+ *
+ * @throws Error The environment value is not a positive integer.
+ */
+export declare function resolveTicketMaxTtl(grantKeys: {
+    readonly maxTtlSeconds: number;
+} | null | undefined, env: Record<string, string | undefined> | undefined): number | null;
+/** What `seal_attach` needs from the worker. */
+export interface AttachTicketsConfig {
+    /** The worker's signing key -- the key that seals attach_opaque_data. */
+    signingKey: Uint8Array;
+    /** The catalog(s) the worker serves; validation reads their declared attach options. */
+    catalogInterface: CatalogInterface | undefined;
+    /** Lifetime ceiling in seconds, or `null` for no maximum. */
+    maxTtlSeconds: number | null;
+    /** Clock override (seconds), for tests. */
+    now?: () => number;
+}
+/** Validate and seal; the body of `seal_attach`. */
+export declare function sealAttach(config: AttachTicketsConfig, request: Record<string, unknown>, auth: AuthContext | undefined): Promise<{
+    ticket: string;
+    expires_at: number;
+}>;
+/**
+ * Build `vgi.attach_tickets.v1`: one unary method, `seal_attach(request:
+ * SealAttachRequest) -> AttachTicket`, each carried as serialized Arrow IPC
+ * in a single binary column -- the same wire, and protocol hash, as
+ * vgi-python's.
+ */
+export declare function buildAttachTicketsProtocol(config: AttachTicketsConfig): Protocol;

package/dist/catalog/attach-option.d.ts

@@ -60,6 +60,18 @@ 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 declare 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 declare function assertNoReservedAttachOption(specs: Iterable<Pick<AttachOptionSpec, "name">>): void;
 /**
  * Serialize an AttachOptionSpec to the wire format the extension expects
  * (one IPC-serialized RecordBatch with a single row).
@@ -99,3 +111,21 @@ export declare class MissingAttachOptionsError extends Error {
  * @throws {MissingAttachOptionsError} If a required option was not supplied.
  */
 export declare function validateRequiredAttachOptions(catalogName: string, specs: Iterable<AttachOptionSpec>, options: Record<string, unknown>): void;
+/** Raised when a catalog declares the reserved attach option name. */
+export declare class ReservedAttachOptionError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function checkReservedAttachOptions(catalog: {
+    catalogsInfo?(): unknown;
+} | undefined): Promise<void>;

package/dist/client-entry.js

@@ -4640,4 +4640,4 @@ export {
   typeSignature
 };
 
-//# debugId=A700197CD6EACFA764756E2164756E21
+//# debugId=62AEFEFC6DBD059D64756E2164756E21