@query-farm/vgi 0.36.3 → 0.37.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.36.3",
+  "version": "0.37.1",
   "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)",

package/src/catalog/attach-option.ts

@@ -22,6 +22,9 @@
 //                                that predates the column reads the batch by
 //                                name and simply doesn't see it; absent and
 //                                explicit-null both mean "not required".
+//     secret: Bool nullable -- the option carries a credential. Appended AFTER
+//                              `required` under the same rule: readers look it
+//                              up by name, and absent or null reads as false.
 //
 // The extension reads the outer `attach_option_specs: list<binary>` column
 // from CatalogInfo and validates user-supplied ATTACH options against the
@@ -75,6 +78,34 @@ export interface AttachOptionSpec {
    * is by definition satisfiable without the caller.
    */
   required?: boolean;
+  /**
+   * The option carries a credential: an API key, a token, a password, or
+   * anything else that must not be shown, stored or logged in plain text.
+   *
+   * Credential options **MUST** be declared `secret: true`. The value is still
+   * passed inline as an ordinary ATTACH option; the flag tells the DuckDB
+   * extension to redact it from `duckdb_databases()`, keep only a salted hash
+   * of it in its result-cache key, and never log it. Clients use the flag to
+   * mask the field and keep the value out of shared links and exported
+   * configuration.
+   *
+   * To keep the credential out of the SQL text itself, pass it as an
+   * expression:
+   *
+   * ```sql
+   * ATTACH 'sales' (TYPE vgi, LOCATION 'https://worker.example.com',
+   *                 api_key getenv('SALES_API_KEY'));
+   * ```
+   *
+   * Combines with `required` (a credential the catalog cannot attach without,
+   * which a client can then ask for before attaching). It is allowed together
+   * with `default`, but a secret option normally has none: a default would be
+   * a credential shipped in the catalog's own discovery metadata.
+   *
+   * Defaults to `false`. On the wire it is a nullable `secret` Bool column
+   * appended after `required`; a peer that predates it reads it as `false`.
+   */
+  secret?: boolean;
 }
 
 const SPEC_SCHEMA = makeSchema([
@@ -83,6 +114,7 @@ const SPEC_SCHEMA = makeSchema([
   field("type", binary(), false),
   field("default_value", binary(), true),
   field("required", bool(), true),
+  field("secret", bool(), true),
 ]);
 
 /**
@@ -126,6 +158,8 @@ export function serializeAttachOptionSpec(spec: AttachOptionSpec): Uint8Array {
       // Written explicitly rather than left null so a reader sees `false`, not
       // NULL, for an option that simply isn't required.
       required: [spec.required ?? false],
+      // Same reasoning: an ordinary option reads `false`, not NULL.
+      secret: [spec.secret ?? false],
     },
     SPEC_SCHEMA,
   );
@@ -145,8 +179,8 @@ export function serializeAttachOptionSpecs(
  * Deserialize one AttachOptionSpec from the wire format above.
  *
  * Reads by column name, so a spec written by a peer that predates the
- * `required` column deserializes with `required: false` rather than failing —
- * the same tolerance the Python and C++ readers have.
+ * `required` or `secret` column deserializes with that flag `false` rather
+ * than failing — the same tolerance the Python and C++ readers have.
  */
 export function deserializeAttachOptionSpec(
   bytes: Uint8Array,
@@ -181,6 +215,7 @@ export function deserializeAttachOptionSpec(
     type,
     ...(value === undefined || value === null ? {} : { default: value }),
     required: row.required === true,
+    secret: row.secret === true,
   };
 }