@@ -392,6 +392,8 @@ 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.
+
 **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.
 
 The same enrichment applies to OTel spans when `VGI_OTEL_ENABLED=1` — both backends read from the same `VgiTracer.set_current_span_attributes()` call sites in `vgi/otel.py`. Either, neither, or both can be active in a process.
 
@@ -246,6 +246,42 @@ class MyCatalog(CatalogInterface):
 
 ---
 
+## Declaring Attach Options
+
+A worker declares the options its catalogs accept at `ATTACH` time in an `AttachOptions` inner class. Each option is advertised to clients at discovery (`CatalogInfo.attach_option_specs`), so DuckDB can cast and validate it, and frontends can render an options form.
+
+```python test="skip"
+from typing import Annotated
+from vgi import Worker
+from vgi.catalog.attach_option import AttachOption
+
+class MyWorker(Worker):
+    class AttachOptions:
+        region: Annotated[str, AttachOption(desc="AWS region")] = "us-east-1"
+        # A credential: required, secret, and with no default.
+        api_key: Annotated[str, AttachOption(desc="API key", required=True, secret=True)]
+```
+
+| Flag | Meaning |
+|------|---------|
+| `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:
+
+```sql
+CREATE SECRET (TYPE vgi_attach, SCOPE 'https://worker.example.com', api_key '...');
+ATTACH 'mydb' AS mydb (TYPE vgi, LOCATION 'https://worker.example.com');
+```
+
+`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.
+
+On the wire, `required` and `secret` are nullable boolean columns appended after the four shared spec columns (`name`, `description`, `type`, `default_value`), in that order. Readers look columns up by name, so a spec from a peer that predates either column reads it as `false`, and older peers ignore columns they don't know.
+
+`secret` does not change what the worker itself logs: attach options are never logged unless the catalog opts in through `loggable_attach_options()` (below), which must never return a secret option.
+
+---
+
 ## Logging Attach Options Safely
 
 The worker emits structured `_logger.info` records and Sentry breadcrumbs for catalog lifecycle events (`catalog.attach`, `catalog.detach`, `catalog.create`, `catalog.transaction.begin`, `catalog.transaction.commit`, `catalog.transaction.rollback`). `attach_opaque_data` and `transaction_opaque_data` are short-hashed (12-char SHA-256 prefixes) before they reach the log record, the breadcrumb data, or the Sentry scope tags — the raw values never appear in observability output, since they may carry secrets. An operator correlates the short hash back to the catalog via these breadcrumbs.
 
@@ -1,6 +1,6 @@
 # Copyright 2025, 2026 Query Farm LLC - https://query.farm
 
-"""Tests for the AttachOption descriptor, its ``required`` flag, and validation."""
+"""Tests for the AttachOption descriptor, its ``required`` and ``secret`` flags, and validation."""
 
 from typing import Annotated
 
@@ -25,7 +25,11 @@ class _Options:
 
     region: Annotated[str, AttachOption(desc="AWS region")] = "us-east-1"
     # No class-level assignment: nothing to fall back to, so the caller must supply it.
-    api_key: Annotated[str, AttachOption(desc="API key", required=True)]
+    api_key: Annotated[str, AttachOption(desc="API key", required=True, secret=True)]
+    # A credential that may be omitted, with no default (the recommended shape).
+    token: Annotated[str | None, AttachOption(desc="Optional token", arrow_type=pa.string(), secret=True)] = None
+    # Allowed, though discouraged: a secret option with a default.
+    password: Annotated[str, AttachOption(desc="Password", secret=True)] = "changeme"
 
 
 def _roundtrip(spec: AttachOptionSpec) -> AttachOptionSpec:
@@ -83,6 +87,7 @@ def test_setting_wire_format_unchanged(self) -> None:
             "type",
             "default_value",
             "required",
+            "secret",
         ]
 
     def test_reads_batch_without_required_column(self) -> None:
@@ -124,6 +129,120 @@ def test_null_required_reads_as_false(self) -> None:
         assert AttachOptionSpec.deserialize(restored).required is False
 
 
+class TestSecretExtraction:
+    """Extraction of the ``secret`` flag from Annotated declarations."""
+
+    def test_defaults_to_false(self) -> None:
+        """An option that isn't declared secret isn't secret."""
+        specs = {s.name: s for s in extract_attach_option_specs(_Options)}
+        assert specs["region"].secret is False
+
+    def test_secret_with_required(self) -> None:
+        """``secret`` and ``required`` combine: a credential the caller must supply."""
+        specs = {s.name: s for s in extract_attach_option_specs(_Options)}
+        assert specs["api_key"].secret is True
+        assert specs["api_key"].required is True
+        assert specs["api_key"].default is None
+
+    def test_secret_without_required(self) -> None:
+        """A secret option need not be required."""
+        specs = {s.name: s for s in extract_attach_option_specs(_Options)}
+        assert specs["token"].secret is True
+        assert specs["token"].required is False
+
+    def test_secret_with_default_allowed(self) -> None:
+        """A secret option may declare a default (discouraged, but not an error)."""
+        specs = {s.name: s for s in extract_attach_option_specs(_Options)}
+        assert specs["password"].secret is True
+        assert specs["password"].default == "changeme"
+
+    def test_secret_required_and_default_still_rejected(self) -> None:
+        """``secret`` doesn't relax the required + default contradiction."""
+        with pytest.raises(ValueError, match="required but also declares a default"):
+            AttachOptionSpec(name="k", desc="", type=pa.string(), default="x", required=True, secret=True)
+
+
+class TestSecretWireFormat:
+    """Serialization of the added ``secret`` column."""
+
+    @pytest.mark.parametrize("secret", [True, False], ids=["secret", "plain"])
+    def test_roundtrip_preserves_secret(self, secret: bool) -> None:
+        """``secret`` survives an Arrow IPC round trip in both states."""
+        spec = AttachOptionSpec(name="api_key", desc="API key", type=pa.string(), default=None, secret=secret)
+        restored = _roundtrip(spec)
+        assert restored.secret is secret
+        assert restored.required is False
+
+    @pytest.mark.parametrize(
+        ("required", "secret"),
+        [(True, True), (True, False), (False, True), (False, False)],
+    )
+    def test_roundtrip_required_and_secret_independent(self, required: bool, secret: bool) -> None:
+        """The two flags occupy separate columns and never bleed into each other."""
+        spec = AttachOptionSpec(
+            name="api_key", desc="API key", type=pa.string(), default=None, required=required, secret=secret
+        )
+        restored = _roundtrip(spec)
+        assert (restored.required, restored.secret) == (required, secret)
+
+    def test_secret_column_follows_required(self) -> None:
+        """``secret`` is a nullable bool appended after ``required``."""
+        schema = AttachOptionSpec.ARROW_SCHEMA
+        assert schema.get_field_index("secret") == schema.get_field_index("required") + 1
+        assert schema.get_field_index("secret") == len(schema) - 1
+        field = schema.field("secret")
+        assert field.type == pa.bool_()
+        assert field.nullable
+
+    def test_reads_batch_without_secret_column(self) -> None:
+        """A peer that has ``required`` but predates ``secret`` yields ``secret=False``."""
+        type_bytes = pa.schema([pa.field("value", pa.string())]).serialize().to_pybytes()
+        older_schema = pa.schema([*_SpecBase.ARROW_SCHEMA, pa.field("required", pa.bool_(), nullable=True)])
+        older = pa.RecordBatch.from_pylist(
+            [{"name": "api_key", "description": "", "type": type_bytes, "default_value": None, "required": True}],
+            schema=older_schema,
+        )
+        restored_batch, _ = deserialize_record_batch(serialize_record_batch_bytes(older))
+        restored = AttachOptionSpec.deserialize(restored_batch)
+        assert restored.secret is False
+        assert restored.required is True
+
+    def test_reads_four_column_batch_as_not_secret(self) -> None:
+        """A peer that predates both columns reads as neither required nor secret."""
+        type_bytes = pa.schema([pa.field("value", pa.string())]).serialize().to_pybytes()
+        legacy = pa.RecordBatch.from_pylist(
+            [{"name": "region", "description": "", "type": type_bytes, "default_value": None}],
+            schema=_SpecBase.ARROW_SCHEMA,
+        )
+        restored = AttachOptionSpec.deserialize(legacy)
+        assert (restored.required, restored.secret) == (False, False)
+
+    def test_null_secret_reads_as_false(self) -> None:
+        """An explicit null in the nullable column means "not secret"."""
+        type_bytes = pa.schema([pa.field("value", pa.string())]).serialize().to_pybytes()
+        batch = pa.RecordBatch.from_pylist(
+            [
+                {
+                    "name": "region",
+                    "description": "",
+                    "type": type_bytes,
+                    "default_value": None,
+                    "required": None,
+                    "secret": None,
+                }
+            ],
+            schema=AttachOptionSpec.ARROW_SCHEMA,
+        )
+        restored, _ = deserialize_record_batch(serialize_record_batch_bytes(batch))
+        assert AttachOptionSpec.deserialize(restored).secret is False
+
+    def test_older_reader_ignores_secret_column(self) -> None:
+        """A four-column reader still reads a six-column batch (forward compatible)."""
+        spec = AttachOptionSpec(name="api_key", desc="", type=pa.string(), default=None, required=True, secret=True)
+        batch, _ = deserialize_record_batch(spec.serialize())
+        assert SettingSpec.deserialize(batch).name == "api_key"
+
+
 class TestValidateRequiredAttachOptions:
     """The shared validation helper."""
 
 
@@ -23,9 +23,10 @@
     Table,
     View,
 )
-from vgi.catalog.attach_option import AttachOption, extract_attach_option_specs
+from vgi.catalog.attach_option import AttachOption, AttachOptionSpec, extract_attach_option_specs
 from vgi.http.worker_page import (
     WorkerPageResource,
+    _build_attach_options_table,
     _display_function_type,
     build_worker_page,
 )
@@ -542,6 +543,20 @@ def test_options_render_with_types_and_defaults(self) -> None:
         # Defaults render via repr() and HTML-escape the quotes.
         assert "&#x27;hello&#x27;" in html
 
+    def test_required_and_secret_flags_render(self) -> None:
+        """Required/secret options are flagged, and a secret's default is never shown."""
+        specs = (
+            AttachOptionSpec(name="api_key", desc="", type=pa.string(), default=None, required=True, secret=True),
+            AttachOptionSpec(name="password", desc="", type=pa.string(), default="hunter2", secret=True),
+            AttachOptionSpec(name="region", desc="", type=pa.string(), default="us-east-1"),
+        )
+        html = _build_attach_options_table(specs)
+        assert ">required</span>" in html
+        assert ">secret</span>" in html
+        assert "hunter2" not in html
+        assert "<em>hidden</em>" in html
+        assert "&#x27;us-east-1&#x27;" in html
+
 
 class TestVersionDisplay:
     """Implementation chip + Data version input."""
 
@@ -123,7 +123,7 @@ class RequiredAttachOptions:
 
     # No class-level assignment: there is no default to fall back on, so the
     # caller has to supply it.
-    api_key: Annotated[str, AttachOption(desc="API key", required=True)]
+    api_key: Annotated[str, AttachOption(desc="API key", required=True, secret=True)]
     region: Annotated[str, AttachOption(desc="Region")] = "us-east-1"
 
 
 
@@ -10,7 +10,7 @@
 names and behaviour are unchanged.
 
 A subclass may widen its wire format with additional columns — `AttachOption`
-adds ``required`` — via :meth:`_SpecBase._extra_row` /
+adds ``required`` and ``secret`` — via :meth:`_SpecBase._extra_row` /
 :meth:`_SpecBase._extra_kwargs` and :meth:`_DescriptorBase.extra_spec_kwargs`.
 Because both directions read by column name, the widening is compatible in both
 directions: a reader ignores columns it doesn't know, and a reader whose peer
 
@@ -9,6 +9,14 @@
 The declaration mirrors ``vgi.catalog.setting.Setting`` — same Arrow IPC spec
 format, same Python type → Arrow mapping, same extractor shape — so both share
 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::
+
+    CREATE SECRET (TYPE vgi_attach, SCOPE 'https://worker.example.com', api_key '...');
+    ATTACH 'mydb' AS mydb (TYPE vgi, LOCATION 'https://worker.example.com');
 """
 
 from dataclasses import dataclass
@@ -42,18 +50,31 @@ class AttachOptionSpec(_SpecBase):
             rather than surfacing a failure that reads like an empty catalog.
             Mutually exclusive with ``default`` — an option that falls back to
             a value is by definition satisfiable without the caller.
-        ARROW_SCHEMA: The shared four columns plus ``required``.
+        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.
+            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.
+        ARROW_SCHEMA: The shared four columns plus ``required`` and ``secret``.
 
     """
 
     required: bool = False
+    secret: bool = False
 
     ARROW_SCHEMA: ClassVar[pa.Schema] = pa.schema(
         [
             *_SpecBase.ARROW_SCHEMA,
-            # Nullable, and appended last: a peer that predates this column
+            # Nullable, and appended after the shared columns: a peer that predates this column
             # reads the batch by name and simply doesn't see it.
             pa.field("required", pa.bool_(), nullable=True),
+            # Same rules as ``required``: nullable, appended after it, and an
+            # absent column reads as False.
+            pa.field("secret", pa.bool_(), nullable=True),
         ]
     )
 
@@ -67,12 +88,16 @@ def __post_init__(self) -> None:
             )
 
     def _extra_row(self) -> dict[str, Any]:
-        return {"required": self.required}
+        return {"required": self.required, "secret": self.secret}
 
     @classmethod
     def _extra_kwargs(cls, row: dict[str, object]) -> dict[str, Any]:
-        # Absent column (older peer) and explicit null both mean "not required".
-        return {"required": bool(row.get("required") or False)}
+        # Absent column (older peer) and explicit null both mean "not required"
+        # / "not secret".
+        return {
+            "required": bool(row.get("required") or False),
+            "secret": bool(row.get("secret") or False),
+        }
 
 
 @dataclass
@@ -90,18 +115,26 @@ class AttachOption(_DescriptorBase):
 
         class AttachOptions:
             region: Annotated[str, AttachOption(desc="AWS region")] = "us-east-1"
-            api_key: Annotated[str, AttachOption(desc="API key", required=True)]
+            api_key: Annotated[str, AttachOption(desc="API key", required=True, secret=True)]
+
+    Credential options (API keys, tokens, passwords) MUST be declared
+    ``secret=True``; see `AttachOptionSpec.secret`.
 
     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.
 
     """
 
     required: bool = False
+    secret: bool = False
 
     def extra_spec_kwargs(self) -> dict[str, Any]:
-        """Carry ``required`` through to the `AttachOptionSpec`."""
-        return {"required": self.required}
+        """Carry ``required`` and ``secret`` through to the `AttachOptionSpec`."""
+        return {"required": self.required, "secret": self.secret}
 
 
 class MissingAttachOptionsError(ValueError):
 
@@ -544,7 +544,8 @@ <h1 id="worker-name">—</h1>
       name: s.name, type: typeStr(s.type),
       default: s.default == null ? '' : String(s.default),
       description: s.description || '',
-      required: !!s.required
+      required: !!s.required,
+      secret: !!s.secret
     }));
   } catch (e) { /* keep the card; drop unreadable specs */ }
 
@@ -792,7 +793,8 @@ <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>':'')+
-      '</td><td class="o-type">'+esc(o.type)+'</td><td class="o-def">'+esc(o.default||'—')+'</td><td class="o-desc">'+esc(o.description||'')+'</td></tr>').join('')+
+      (o.secret?'<span class="o-req" title="A credential: supply it from a vgi_attach DuckDB secret rather than the ATTACH text">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>';
 }
 function renderConnect(){