docs(attach): drop vgi_attach secrets; credentials pass inline as secret options

The DuckDB extension will not ship a vgi_attach secret type. Secret attach
options are passed inline; the extension redacts them from
duckdb_databases(), keeps only a salted hash in its cache key and never logs
them. To keep a credential out of the SQL text, write the option as an
expression, e.g. api_key getenv('SALES_API_KEY'). Credential options must
still be declared secret=True. No behaviour change.

Also exempt the C++ location_policy and attach_secrets integration areas in
the conformance directory-parity check: both are enforced inside the
extension, and the Python side of secret options is covered by
tests/catalog/test_attach_option.py.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: rustyconover

CLAUDE.md

@@ -392,7 +392,7 @@ Set `SENTRY_DSN` (and install `vgi[sentry]`) to forward unhandled exceptions to
 
 **Attach options redaction:** by default *no* options are logged in the `catalog.attach` / `catalog.create` breadcrumbs because options routinely carry credentials. Implementers opt in via `CatalogInterface.loggable_attach_options(options) -> Mapping`, which returns a redacted, safe-to-log subset (host, region, bucket — never password/token/secret). When the override returns an empty mapping (the default), the `options` field is omitted from the breadcrumb entirely. See `docs/catalog-interface.md` for details.
 
-**Secret attach options:** credential options (API keys, tokens, passwords) MUST be declared `AttachOption(..., secret=True)`. `AttachOptionSpec.secret` rides as a nullable `bool` column named `secret` appended after `required` (an absent column reads as `False`); clients and the DuckDB extension mask such options, keep them out of cache keys and logs, and can supply them from a `vgi_attach` DuckDB secret (`CREATE SECRET (TYPE vgi_attach, SCOPE '<worker url>', api_key '…')`). Secret + required is fine; secret + default is allowed but discouraged.
+**Secret attach options:** credential options (API keys, tokens, passwords) MUST be declared `AttachOption(..., secret=True)`. `AttachOptionSpec.secret` rides as a nullable `bool` column named `secret` appended after `required` (an absent column reads as `False`); they are passed inline at ATTACH; clients mask them, and the DuckDB extension redacts them from `duckdb_databases()`, keeps only a salted hash of them in its cache key, and never logs them. Keep a credential out of the SQL text with an expression: `ATTACH 'sales' (TYPE vgi, LOCATION '…', api_key getenv('SALES_API_KEY'))`. Secret + required is fine; secret + default is allowed but discouraged.
 
 **Releases.** `vgi-serve` populates `release` from `SENTRY_RELEASE` if set, otherwise from `importlib.metadata.version("vgi-python")`. Production deploys should set `SENTRY_RELEASE=$(git rev-parse HEAD)` (or a tagged release identifier) so Sentry's commit-tracking and regression-detection features can correlate events to specific commits. Publishing GitHub releases makes the release-comparison UI more useful.
 

docs/catalog-interface.md

@@ -267,11 +267,10 @@ class MyWorker(Worker):
 | `required=True` | The caller must supply the option. Declare it with no class-level default; `required` plus a default is rejected. |
 | `secret=True` | The option carries a credential. |
 
-**Credential options (API keys, tokens, passwords) MUST be declared `secret=True`.** Clients and the DuckDB extension then mask the value, keep it out of result-cache keys and logs, and can supply it from a `vgi_attach` DuckDB secret, so the `ATTACH` statement never carries it:
+**Credential options (API keys, tokens, passwords) MUST be declared `secret=True`.** The caller passes them inline as attach options. Clients mask secret options, and the DuckDB extension redacts them from `duckdb_databases()`, keeps only a salted hash of them in its result-cache key, and never logs them. To keep a credential out of the SQL text (shell history, scripts, shared links), write the option as an expression:
 
 ```sql
-CREATE SECRET (TYPE vgi_attach, SCOPE 'https://worker.example.com', api_key '...');
-ATTACH 'mydb' AS mydb (TYPE vgi, LOCATION 'https://worker.example.com');
+ATTACH 'mydb' (TYPE vgi, LOCATION 'https://worker.example.com', api_key getenv('MYDB_API_KEY'));
 ```
 
 `secret` combines with `required`. It is allowed together with a default, but a secret option should normally have none: the default is advertised in plain text to every client at discovery.

tests/conformance/test_directory_parity.py

@@ -79,6 +79,19 @@
         "(it spawns the Python worker as a subprocess); the Python client never "
         "exercises the launcher surface."
     ),
+    "attach_secrets": (
+        "Masking, redaction from duckdb_databases() and cache-key hashing of secret "
+        "attach options happen inside the C++ extension. The Python side is the "
+        "AttachOptionSpec.secret wire column, covered by "
+        "tests/catalog/test_attach_option.py (round trip, absent column, interaction "
+        "with required)."
+    ),
+    "location_policy": (
+        "LOCATION transport policy (vgi_allowed_transports, enable_external_access) "
+        "is enforced by the C++ extension before it starts or connects to a worker; "
+        "it is a DuckDB setting with no counterpart in the Python client, which is "
+        "handed a transport directly."
+    ),
     "simple_writable": (
         "INSERT/UPDATE/DELETE/RETURNING write paths are mirrored by "
         "test_writable.py, which drives the same operations against the writable "

vgi/catalog/attach_option.py

@@ -11,12 +11,12 @@
 the machinery in ``vgi.catalog._descriptor_spec``.
 
 Credential options (API keys, tokens, passwords) MUST be declared
-``secret=True``. Clients and the DuckDB extension then mask the value, keep it
-out of result-cache keys and logs, and can supply it from a ``vgi_attach``
-DuckDB secret instead of the ``ATTACH`` text::
+``secret=True``. The caller passes them inline as attach options; the DuckDB
+extension redacts them from ``duckdb_databases()``, keeps only a salted hash of
+them in its result-cache key, and never logs them. To keep a credential out of
+the SQL text, write the option as an expression::
 
-    CREATE SECRET (TYPE vgi_attach, SCOPE 'https://worker.example.com', api_key '...');
-    ATTACH 'mydb' AS mydb (TYPE vgi, LOCATION 'https://worker.example.com');
+    ATTACH 'mydb' (TYPE vgi, LOCATION 'https://worker.example.com', api_key getenv('MYDB_API_KEY'));
 """
 
 from dataclasses import dataclass
@@ -51,11 +51,12 @@ class AttachOptionSpec(_SpecBase):
             Mutually exclusive with ``default`` — an option that falls back to
             a value is by definition satisfiable without the caller.
         secret: The option carries a credential (an API key, token or
-            password). Clients and the DuckDB extension mask its value, keep it
-            out of result-cache keys and logs, and can supply it from a
-            ``vgi_attach`` DuckDB secret
-            (``CREATE SECRET (TYPE vgi_attach, SCOPE '<worker url>', api_key '...')``)
-            rather than the ``ATTACH`` text. Credential options MUST set this.
+            password). It is still passed inline at ``ATTACH``, but clients
+            mask it, and the DuckDB extension redacts it from
+            ``duckdb_databases()``, keeps only a salted hash of it in its
+            result-cache key, and never logs it. Keep it out of the SQL text
+            with an expression, e.g. ``api_key getenv('MYDB_API_KEY')``.
+            Credential options MUST set this.
             Compatible with ``required``. Allowed alongside a ``default``, but a
             secret option should normally have none: a default credential is
             advertised in plain text to every client at discovery.
@@ -123,9 +124,8 @@ class AttachOptions:
     Attributes:
         required: The caller must supply this option at ``ATTACH`` time.
         secret: The option carries a credential. Clients and the DuckDB
-            extension mask it, keep it out of cache keys and logs, and can
-            supply it from a ``vgi_attach`` DuckDB secret. Should normally have
-            no default.
+            extension mask it, keep only a salted hash of it in cache keys, and
+            never log it. Should normally have no default.
 
     """
 

vgi/http/landing.html

@@ -793,7 +793,7 @@ <h1 id="worker-name">—</h1>
     '<table class="opts"><thead><tr><th>Option</th><th>Type</th><th>Default</th><th>Description</th></tr></thead><tbody>'+
     opts.map(o=>'<tr><td class="o-name">'+esc(o.name)+
       (o.required?'<span class="o-req" title="Must be supplied at ATTACH time">required</span>':'')+
-      (o.secret?'<span class="o-req" title="A credential: supply it from a vgi_attach DuckDB secret rather than the ATTACH text">secret</span>':'')+
+      (o.secret?'<span class="o-req" title="A credential: redacted and never logged. Keep it out of the SQL text with an expression such as getenv()">secret</span>':'')+
       '</td><td class="o-type">'+esc(o.type)+'</td><td class="o-def">'+esc(o.secret&&o.default?'hidden':(o.default||'—'))+'</td><td class="o-desc">'+esc(o.description||'')+'</td></tr>').join('')+
     '</tbody></table></details>';
 }

vgi/http/worker_page.py

@@ -597,8 +597,8 @@ def _build_attach_options_table(specs: tuple[AttachOptionSpec, ...]) -> str:
             flags += ' <span class="o-flag" title="Must be supplied at ATTACH time">required</span>'
         if spec.secret:
             flags += (
-                ' <span class="o-flag" title="A credential: supply it from a vgi_attach DuckDB secret '
-                'rather than the ATTACH text">secret</span>'
+                ' <span class="o-flag" title="A credential: redacted and never logged. Keep it out of '
+                'the SQL text with an expression such as getenv()">secret</span>'
             )
         parts.append(
             f"<tr><td><code>{_esc(spec.name)}</code>{flags}</td>"