imperal-sdk 4.2.1__tar.gz → 4.2.3__tar.gz

{imperal_sdk-4.2.1 → imperal_sdk-4.2.3}/CHANGELOG.md

@@ -2,6 +2,94 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 4.2.3 — 2026-05-13
+
+**EXT-SECRETS-V1 UX polish — synthetic `secrets` panel auto-injected**
+
+When an extension declares one or more `@ext.secret(...)` entries, the SDK
+now auto-registers a synthetic `secrets` panel (slot=`right`, title=`Secrets`,
+icon=`KeyRound`) so the user-facing Secrets manager appears alongside the
+extension's own tabs without the author writing any panel code.
+
+### Added
+
+- **Auto-injected `secrets` panel**: `Extension.secret(...)` on first call
+  registers a built-in handler from `imperal_sdk.secrets.panel_handler`. The
+  handler reads declared secrets + live is_set state from `ctx.secrets.list()`
+  and renders `ui.Card` rows with status badges + a `Manage` button that
+  routes to the dedicated `/ext/{ext_id}/secrets` page.
+- The synthetic panel uses **slot=`right`** defensively — most extensions use
+  `left` (sidebar nav) and `center` (main content); `right` is rarely-used so
+  the panel-sync logic in `imperal-ext-developer` won't overwrite it. If your
+  extension already declares a `right`-slot panel, your panel wins; users
+  still reach the Secrets UI via the chat-top ribbon and the direct
+  `/ext/{ext_id}/secrets` route.
+- Panel idempotent — multiple `@ext.secret(...)` calls register the panel
+  only once.
+
+### Migration notes
+
+- **No code changes required** to receive the synthetic panel. Bump your
+  ext's SDK pin to `>= 4.2.3` and redeploy via Dev Portal.
+- Once your extension is on v4.2.3+, the chat-top ribbon (added in Panel for
+  v4.2.2 discoverability) becomes redundant for that ext — synthetic panel
+  appears in the `right` slot as a proper tab.
+
+## 4.2.2 — 2026-05-13
+
+### Added — EXT-SECRETS-V1 (closes ARCH-D1 in compliance-posture.md)
+
+- **`@ext.secret(name, description, ...)`** declarative decorator. Extensions
+  declare what user-supplied credentials they need (API keys, OAuth tokens,
+  webhook signing secrets). Each declaration carries `required`,
+  `write_mode` (`user` / `extension` / `both`), `max_bytes`, optional
+  `rotation_hint_days`. Manifest emits `secrets[]` as an additive optional
+  field (manifest schema v3 stays — back-compat).
+
+- **`ctx.secrets`** accessor on `KernelContext` (resolved kernel-side; SDK
+  ships `SecretClient` HTTP proxy to auth-gw `/v1/secrets/*`). Methods:
+  `get(name)` → plaintext or None; `set(name, value)` → raises
+  `SecretWriteForbidden` for `write_mode='user'`; `delete(name)`;
+  `is_set(name)` (cheap metadata, no audit); `list()` (descriptions +
+  is_set, never values).
+
+- **Dev mode** (`IMPERAL_DEV_MODE=true`): `get(name)` reads
+  `IMPERAL_SECRET_<UPPER_NAME>` env var; set/delete are no-ops with WARN
+  log. Manifest contract still enforced (I-SECRETS-CONTRACT-DECLARED —
+  undeclared names raise even in dev).
+
+- **`imperal_sdk.testing.MockSecretStore`** for pytest fixtures. Optional
+  `declared` set to mirror SecretNotDeclaredError semantics.
+
+- **Federal invariants enforced SDK-side**:
+  - `I-SECRETS-HANDLER-SCOPE-MEMORY` — no module/class-level plaintext
+    cache in `SecretClient`; source-inspection-friendly
+  - `I-SECRETS-CONTRACT-DECLARED` — runtime read/write of undeclared
+    name raises `SecretNotDeclaredError`; manifest is single source of truth
+  - `I-SECRETS-VAULT-DEPENDENCY` — auth-gw 503 → `SecretVaultUnavailable`
+
+- **Federal invariants enforced auth-gw-side** (live in production
+  whm-gateway since 2026-05-13):
+  - `I-SECRETS-USER-SCOPED` — cross-user 403
+  - `I-SECRETS-NEVER-LOGGED` — `action_ledger` row stores length +
+    sha256-prefix-8 only, never the value
+  - `I-SECRETS-EXT-SCOPED` — extension token's `ext_id` claim must
+    match URL `{ext_id}`
+  - `I-SECRETS-AUDIT-FOREVER` — every op writes
+    `retention_class='security_forever'`
+
+- **New JWT claims**: `actor_kind` (`'user'` or `'extension'`) and `ext_id`
+  (extension tokens only). `build_session_claims` and
+  `build_extension_claims` helpers in `app.auth.claims` on the auth-gw side.
+
+### Notes
+
+- Migration of existing plaintext-stored credentials (BYOLLM keys, OAuth
+  refresh tokens, etc.) is at extension-author pace; no automated migration.
+  The V32 publish-time validator blocks *new* extensions that read
+  credential-like fields without an `@ext.secret` declaration
+  (validator implementation deferred).
+
 ## 4.2.1 — 2026-05-11
 
 ### Fixed

{imperal_sdk-4.2.1 → imperal_sdk-4.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imperal-sdk
-Version: 4.2.1
+Version: 4.2.3
 Summary: SDK for building Imperal Cloud extensions
 Author: Valentin Scerbacov, Imperal, Inc.
 License-Expression: AGPL-3.0-or-later

{imperal_sdk-4.2.1 → imperal_sdk-4.2.3}/src/imperal_sdk/__init__.py

@@ -33,7 +33,13 @@ from imperal_sdk.validator_v1_6_0 import (
     validate_manifest_v1_6_0,
 )
 
-__version__ = "4.2.1"
+from imperal_sdk.secrets import (
+    SecretSpec, SecretClient, SecretStatus,
+    SecretNotDeclaredError, SecretWriteForbidden, SecretVaultUnavailable,
+    SecretValueTooLarge, SecretDeclarationConflict,
+)
+
+__version__ = "4.2.3"
 
 __all__ = [
     # Core

{imperal_sdk-4.2.1 → imperal_sdk-4.2.3}/src/imperal_sdk/extension.py

@@ -139,6 +139,98 @@ class Extension:
         self._panels: dict[str, dict] = {}
         self._tray: dict[str, "TrayDef"] = {}
         self._cache_models: dict[str, type] = {}
+        # EXT-SECRETS-V1 (v4.2.2) — declared secrets emitted into manifest.secrets[]
+        self._secrets: dict[str, "SecretSpec"] = {}
+
+    def secret(
+        self,
+        name: str,
+        description: str,
+        *,
+        required: bool = False,
+        write_mode: str = "user",
+        max_bytes: int = 4096,
+        rotation_hint_days: int | None = None,
+    ):
+        """Declare a secret the extension needs.
+
+        Federal EXT-SECRETS-V1 contract — manifest.secrets[] is the single
+        source of truth for what an extension may touch via ``ctx.secrets``.
+
+        Usage::
+
+            ext.secret(
+                name="spotify_api_key",
+                description="Your Spotify API key (from developer.spotify.com)",
+                required=True,
+                write_mode="user",       # user pastes in Panel UI
+                max_bytes=200,
+            )(lambda: None)
+
+            # OAuth refresh tokens are written by the ext after authorize
+            ext.secret(
+                name="spotify_refresh_token",
+                description="OAuth refresh token written by ext after authorize",
+                write_mode="extension",
+                rotation_hint_days=30,
+            )(lambda: None)
+
+        Returns an identity decorator — the wrapped target is unchanged.
+        The call itself registers the SecretSpec on the Extension.
+        """
+        from imperal_sdk.secrets.spec import SecretSpec
+        from imperal_sdk.secrets.exceptions import SecretDeclarationConflict
+
+        spec = SecretSpec(
+            name=name,
+            description=description,
+            required=required,
+            write_mode=write_mode,
+            max_bytes=max_bytes,
+            rotation_hint_days=rotation_hint_days,
+        )
+        if name in self._secrets:
+            raise SecretDeclarationConflict(
+                f"@ext.secret name={name!r} declared twice on app_id={self.app_id!r}"
+            )
+        self._secrets[name] = spec
+
+        # EXT-SECRETS-V1 (v4.2.3): auto-register synthetic 'secrets' panel
+        # on first @ext.secret call so the Secrets tab appears alongside
+        # the extension's own tabs without the author writing panel code.
+        # The handler is shipped in imperal_sdk.secrets.panel_handler.
+        # Subsequent @ext.secret calls are no-ops here — registration is
+        # idempotent.
+        #
+        # Slot choice: ``right`` is defensively chosen. Most extensions
+        # use ``left`` (sidebar nav) and ``center`` (main content); ``right``
+        # is rarely-used so the synthetic Secrets tab is least likely to be
+        # overwritten by the deploy-sync logic in imperal-ext-developer
+        # which currently keeps only one panel per slot. If your extension
+        # already uses ``right``, your panel wins; users can still reach
+        # the Secrets UI via the chat-top ribbon and at /ext/{ext_id}/secrets.
+        if "secrets" not in self._panels:
+            from imperal_sdk.secrets.panel_handler import (
+                builtin_secrets_panel_handler,
+            )
+            # Call self.panel(...) the same way an extension author would.
+            self.panel(
+                "secrets",
+                slot="right",
+                title="Secrets",
+                icon="KeyRound",
+                refresh="manual",
+            )(builtin_secrets_panel_handler)
+
+        def _decorator(target):
+            return target  # syntactic anchor only — decorator is a no-op wrapper
+
+        return _decorator
+
+    @property
+    def secrets(self) -> dict[str, "SecretSpec"]:
+        """Read-only view of declared secrets keyed by name."""
+        return dict(self._secrets)
 
     def tool(self, name: str, scopes: list[str] | None = None, description: str = ""):
         """Register a tool that the AI assistant can call."""

{imperal_sdk-4.2.1 → imperal_sdk-4.2.3}/src/imperal_sdk/manifest.py

@@ -176,6 +176,13 @@ def generate_manifest(ext: Extension) -> dict:
     if ext.config_defaults:
         manifest["config_defaults"] = ext.config_defaults
 
+    # EXT-SECRETS-V1 (v4.2.2) — emit declared secrets[]. Optional field;
+    # backwards-compatible (extensions without @ext.secret omit it).
+    if getattr(ext, "_secrets", None):
+        manifest["secrets"] = [
+            s.to_manifest_dict() for s in ext._secrets.values()
+        ]
+
     return manifest
 
 

imperal_sdk-4.2.3/src/imperal_sdk/secrets/__init__.py

@@ -0,0 +1,29 @@
+"""EXT-SECRETS-V1 — federal per-user per-extension encrypted secrets.
+
+User-facing surfaces:
+- ``@ext.secret(name, description, ...)`` declares a secret in the manifest.
+- ``ctx.secrets.get(name)`` reads plaintext (only inside handler scope).
+- ``ctx.secrets.set(name, value)`` writes (only when write_mode allows).
+
+See: superpowers/specs/2026-05-12-ext-secrets-v1-design.md
+"""
+from imperal_sdk.secrets.spec import SecretSpec
+from imperal_sdk.secrets.client import SecretClient, SecretStatus
+from imperal_sdk.secrets.exceptions import (
+    SecretNotDeclaredError,
+    SecretWriteForbidden,
+    SecretVaultUnavailable,
+    SecretValueTooLarge,
+    SecretDeclarationConflict,
+)
+
+__all__ = [
+    "SecretSpec",
+    "SecretClient",
+    "SecretStatus",
+    "SecretNotDeclaredError",
+    "SecretWriteForbidden",
+    "SecretVaultUnavailable",
+    "SecretValueTooLarge",
+    "SecretDeclarationConflict",
+]

imperal_sdk-4.2.3/src/imperal_sdk/secrets/client.py

@@ -0,0 +1,238 @@
+"""SecretClient — thin HTTP proxy from SDK to auth-gw /v1/secrets/*.
+
+Federal contract:
+- NEVER caches plaintext between calls (I-SECRETS-HANDLER-SCOPE-MEMORY).
+- Validates name against manifest declarations (I-SECRETS-CONTRACT-DECLARED).
+- Validates write_mode before PUT/DELETE/rotate.
+- Translates auth-gw 503 → SecretVaultUnavailable.
+- Returns None for 404 SECRET_NOT_SET (declared but no value yet).
+
+Dev mode (when ``IMPERAL_DEV_MODE=true``):
+- get(name) reads ``IMPERAL_SECRET_<UPPER_NAME>`` env var
+- set/delete/rotate are no-ops with a WARN log (manifest contract still enforced)
+- list() reflects env-var presence
+
+Pytest: inject a MockSecretStore via fixture; see imperal_sdk.testing.MockSecretStore.
+"""
+import logging
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+import httpx
+
+from imperal_sdk.secrets.exceptions import (
+    SecretNotDeclaredError,
+    SecretWriteForbidden,
+    SecretVaultUnavailable,
+    SecretValueTooLarge,
+)
+from imperal_sdk.secrets.spec import SecretSpec
+
+log = logging.getLogger(__name__)
+
+SDK_HTTP_TIMEOUT_S = 5.0
+
+
+@dataclass
+class SecretStatus:
+    """Returned by ``ctx.secrets.list()``. NEVER carries the value itself."""
+    name: str
+    description: str
+    is_set: bool
+    last_accessed_at: Optional[int]
+
+
+def _dev_mode_active() -> bool:
+    return os.getenv("IMPERAL_DEV_MODE", "").lower() in {"1", "true", "yes", "on"}
+
+
+def _dev_env_key(name: str) -> str:
+    return f"IMPERAL_SECRET_{name.upper()}"
+
+
+class SecretClient:
+    """Source-inspection contract: NO module-level cache, NO @lru_cache,
+    NO instance attribute holding plaintext between calls. Plaintext is
+    only ever a local variable in get()'s return path."""
+
+    def __init__(
+        self,
+        *,
+        ext_id: str,
+        imperal_id: str,
+        auth_gw_base: str,
+        session_token: str,
+        declared: dict[str, SecretSpec],
+    ):
+        self._ext_id = ext_id
+        self._imperal_id = imperal_id
+        self._base = auth_gw_base.rstrip("/")
+        self._token = session_token
+        self._declared = declared
+
+    def _headers(self, *, json: bool = False) -> dict:
+        h = {
+            "Authorization": f"Bearer {self._token}",
+            "X-Acting-User": self._imperal_id,
+            "X-Ext-Id": self._ext_id,
+        }
+        if json:
+            h["Content-Type"] = "application/json"
+        return h
+
+    def _ensure_declared(self, name: str) -> SecretSpec:
+        if name not in self._declared:
+            raise SecretNotDeclaredError(
+                f"secret name={name!r} not in manifest for ext_id={self._ext_id!r}"
+            )
+        return self._declared[name]
+
+    async def get(self, name: str) -> Optional[str]:
+        self._ensure_declared(name)
+
+        if _dev_mode_active():
+            return os.getenv(_dev_env_key(name))
+
+        try:
+            async with httpx.AsyncClient(timeout=SDK_HTTP_TIMEOUT_S) as c:
+                r = await c.get(
+                    f"{self._base}/v1/secrets/{self._ext_id}/{name}",
+                    headers=self._headers(),
+                )
+        except (httpx.ConnectError, httpx.TimeoutException, httpx.HTTPError) as e:
+            raise SecretVaultUnavailable(
+                f"auth-gw unreachable on get(name={name!r}): {type(e).__name__}"
+            ) from None
+        if r.status_code == 200:
+            return r.json().get("value")
+        if r.status_code == 404:
+            return None
+        if r.status_code == 503:
+            raise SecretVaultUnavailable(
+                f"auth-gw 503 on get(name={name!r})"
+            )
+        raise RuntimeError(
+            f"unexpected auth-gw status {r.status_code} on get(name={name!r})"
+        )
+
+    async def set(self, name: str, value: str) -> None:
+        spec = self._ensure_declared(name)
+        if spec.write_mode == "user":
+            raise SecretWriteForbidden(
+                f"secret name={name!r} has write_mode='user'; only Panel UI can "
+                f"write. Declare write_mode='extension' or 'both' to allow."
+            )
+        if len(value.encode("utf-8")) > spec.max_bytes:
+            raise SecretValueTooLarge(
+                f"value ({len(value.encode())} bytes) exceeds "
+                f"max_bytes={spec.max_bytes} for name={name!r}"
+            )
+        if _dev_mode_active():
+            log.warning(
+                "secret writes ignored in dev mode (name=%s, ext_id=%s)",
+                name, self._ext_id,
+            )
+            return
+
+        try:
+            async with httpx.AsyncClient(timeout=SDK_HTTP_TIMEOUT_S) as c:
+                r = await c.put(
+                    f"{self._base}/v1/secrets/{self._ext_id}/{name}",
+                    headers=self._headers(json=True),
+                    json={"value": value},
+                )
+        except (httpx.ConnectError, httpx.TimeoutException, httpx.HTTPError) as e:
+            raise SecretVaultUnavailable(
+                f"auth-gw unreachable on set(name={name!r}): {type(e).__name__}"
+            ) from None
+        if r.status_code == 200:
+            return
+        if r.status_code == 503:
+            raise SecretVaultUnavailable(f"auth-gw 503 on set(name={name!r})")
+        raise RuntimeError(
+            f"unexpected auth-gw status {r.status_code} on set(name={name!r})"
+        )
+
+    async def delete(self, name: str) -> bool:
+        spec = self._ensure_declared(name)
+        if spec.write_mode == "user":
+            raise SecretWriteForbidden(
+                f"secret name={name!r} write_mode='user' — only Panel can delete"
+            )
+        if _dev_mode_active():
+            log.warning("secret deletes ignored in dev mode (name=%s)", name)
+            return False
+
+        try:
+            async with httpx.AsyncClient(timeout=SDK_HTTP_TIMEOUT_S) as c:
+                r = await c.delete(
+                    f"{self._base}/v1/secrets/{self._ext_id}/{name}",
+                    headers=self._headers(),
+                )
+        except (httpx.ConnectError, httpx.TimeoutException, httpx.HTTPError) as e:
+            raise SecretVaultUnavailable(
+                f"auth-gw unreachable on delete(name={name!r}): {type(e).__name__}"
+            ) from None
+        if r.status_code == 200:
+            return bool(r.json().get("was_set", False))
+        raise RuntimeError(
+            f"unexpected auth-gw status {r.status_code} on delete(name={name!r})"
+        )
+
+    async def is_set(self, name: str) -> bool:
+        self._ensure_declared(name)
+        if _dev_mode_active():
+            return os.getenv(_dev_env_key(name)) is not None
+
+        try:
+            async with httpx.AsyncClient(timeout=SDK_HTTP_TIMEOUT_S) as c:
+                r = await c.get(
+                    f"{self._base}/v1/secrets/{self._ext_id}/{name}/meta",
+                    headers=self._headers(),
+                )
+        except (httpx.ConnectError, httpx.TimeoutException, httpx.HTTPError) as e:
+            raise SecretVaultUnavailable(
+                f"auth-gw unreachable on is_set(name={name!r}): {type(e).__name__}"
+            ) from None
+        if r.status_code == 200:
+            return bool(r.json().get("is_set", False))
+        if r.status_code == 404:
+            return False
+        raise RuntimeError(
+            f"unexpected auth-gw status {r.status_code} on is_set(name={name!r})"
+        )
+
+    async def list(self) -> list[SecretStatus]:
+        if _dev_mode_active():
+            return [
+                SecretStatus(
+                    name=n,
+                    description=s.description,
+                    is_set=os.getenv(_dev_env_key(n)) is not None,
+                    last_accessed_at=None,
+                )
+                for n, s in self._declared.items()
+            ]
+
+        try:
+            async with httpx.AsyncClient(timeout=SDK_HTTP_TIMEOUT_S) as c:
+                r = await c.get(
+                    f"{self._base}/v1/secrets/{self._ext_id}",
+                    headers=self._headers(),
+                )
+        except (httpx.ConnectError, httpx.TimeoutException, httpx.HTTPError) as e:
+            raise SecretVaultUnavailable(
+                f"auth-gw unreachable on list(): {type(e).__name__}"
+            ) from None
+        if r.status_code == 200:
+            return [
+                SecretStatus(
+                    name=item.get("name", ""),
+                    description=item.get("description", ""),
+                    is_set=bool(item.get("is_set", False)),
+                    last_accessed_at=item.get("last_accessed_at"),
+                )
+                for item in r.json()
+            ]
+        raise RuntimeError(f"unexpected auth-gw status {r.status_code} on list()")

imperal_sdk-4.2.3/src/imperal_sdk/secrets/exceptions.py

@@ -0,0 +1,34 @@
+"""Secret-related SDK exceptions. Federal rule: NEVER embed plaintext in messages."""
+
+
+class SecretNotDeclaredError(Exception):
+    """ctx.secrets.* called with a name not in the manifest's secrets[].
+
+    Manifest is the single source of truth for what an extension may touch
+    (I-SECRETS-CONTRACT-DECLARED).
+    """
+
+
+class SecretWriteForbidden(Exception):
+    """ctx.secrets.set() called for a secret with manifest write_mode='user'.
+
+    Only the Panel UI (user-attributable session) can write 'user'-mode
+    secrets. Extension code can write secrets declared with
+    write_mode='extension' or write_mode='both'.
+    """
+
+
+class SecretVaultUnavailable(Exception):
+    """auth-gw returned 503; Vault transit endpoint is down.
+
+    Per I-SECRETS-VAULT-DEPENDENCY, the SDK fails closed — no fallback
+    decryption, no cached plaintext.
+    """
+
+
+class SecretValueTooLarge(Exception):
+    """Written value exceeds the manifest's max_bytes for this secret."""
+
+
+class SecretDeclarationConflict(Exception):
+    """@ext.secret declared the same name twice for one Extension."""

imperal_sdk-4.2.3/src/imperal_sdk/secrets/panel_handler.py

@@ -0,0 +1,133 @@
+"""Built-in handler for the synthetic ``secrets`` panel.
+
+When an Extension declares one or more ``@ext.secret(...)`` entries, the SDK
+auto-registers a panel with ``panel_id='secrets'`` so the user-facing
+Secrets manager appears among the extension's other tabs (Overview /
+Analytics / Transactions / ...). The extension author doesn't write any
+panel code — the SDK provides this canonical handler.
+
+Federal contract: the handler renders a summary of declared secrets +
+links to the full /ext/{ext_id}/secrets page where Panel UI handles
+PUT/DELETE through type=password input + cleared-on-submit state. We
+do NOT inline the input form here because the canonical UI lives in
+Panel React (SecretManagerCard) — duplicating it in declarative ui.*
+primitives would split the federal contract (I-SECRETS-NEVER-LOGGED,
+no-echo, no-clipboard) across two implementations.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+async def builtin_secrets_panel_handler(ctx: Any, **_params: Any) -> dict:
+    """Render the synthetic secrets panel.
+
+    Returns a UINode dict (post-``.to_dict()``) that the kernel relays to
+    Imperal Panel. The panel shows one card per declared secret with
+    is_set status badge and a primary action that navigates to
+    /ext/{ext_id}/secrets — the full SecretManagerCard route.
+    """
+    # Import inside the handler to keep SDK init light and avoid
+    # circular imports if ui.* itself imports anything from secrets.
+    from imperal_sdk import ui
+
+    ext_id = getattr(ctx, "ext_id", "") or getattr(ctx, "extension_id", "") or ""
+
+    # Pull declared secrets from ctx if the kernel populated them; fall
+    # back to an empty list so the panel still renders cleanly.
+    declared = list(getattr(ctx, "_declared_secrets", {}).values()) if getattr(
+        ctx, "_declared_secrets", None
+    ) else []
+
+    # Try to fetch live is_set state per declared name (cheap meta read).
+    statuses: dict[str, dict] = {}
+    if hasattr(ctx, "secrets") and ctx.secrets is not None:
+        try:
+            live = await ctx.secrets.list()
+            for s in live:
+                # SecretStatus or dict — handle both.
+                name = getattr(s, "name", None) or (s.get("name") if isinstance(s, dict) else None)
+                if name is None:
+                    continue
+                statuses[name] = {
+                    "is_set": bool(getattr(s, "is_set", None) if not isinstance(s, dict) else s.get("is_set", False)),
+                    "last_accessed_at": (
+                        getattr(s, "last_accessed_at", None)
+                        if not isinstance(s, dict)
+                        else s.get("last_accessed_at")
+                    ),
+                }
+        except Exception:
+            statuses = {}
+
+    cards = []
+    for spec in declared:
+        name = getattr(spec, "name", None) or (spec.get("name") if isinstance(spec, dict) else None)
+        if not name:
+            continue
+        desc = getattr(spec, "description", "") or (spec.get("description", "") if isinstance(spec, dict) else "")
+        write_mode = (
+            getattr(spec, "write_mode", "user")
+            if not isinstance(spec, dict)
+            else spec.get("write_mode", "user")
+        )
+        status = statuses.get(name, {"is_set": False, "last_accessed_at": None})
+        is_set = bool(status.get("is_set"))
+        last_read = status.get("last_accessed_at")
+
+        # One card per secret with status + Manage button.
+        rows = [ui.Text(desc) if desc else None]
+        if is_set:
+            rows.append(ui.Badge("Set", color="green"))
+            if last_read:
+                rows.append(ui.Text(f"Last read: {last_read}", color="muted"))
+        else:
+            rows.append(ui.Badge("Not set", color="gray"))
+        if write_mode == "extension":
+            rows.append(ui.Text("(extension-write only — written after authorize)", color="muted"))
+
+        rows.append(ui.Button(
+            label="Manage" if is_set else "Set value",
+            variant="primary" if not is_set else "secondary",
+            on_click=ui.Navigate(path=f"/ext/{ext_id}/secrets#{name}"),
+        ))
+
+        cards.append(ui.Card(
+            title=name,
+            content=ui.Stack(children=[r for r in rows if r is not None]),
+        ))
+
+    if not cards:
+        cards.append(ui.Card(
+            title="No secrets declared",
+            content=ui.Stack(children=[
+                ui.Text(
+                    "This extension does not declare any secrets. If you are "
+                    "the developer, add an @ext.secret(...) declaration to "
+                    "your app.py and redeploy."
+                ),
+                ui.Link(
+                    text="Read @ext.secret reference →",
+                    href="https://docs.imperal.io/en/sdk/decorator-secret-reference/",
+                ),
+            ]),
+        ))
+
+    root = ui.Stack(children=[
+        ui.Heading(f"Secrets · {ext_id}", level=2),
+        ui.Text(
+            "Credentials this extension needs — API keys, OAuth tokens. "
+            "Stored encrypted in Vault; never visible to admins or in logs."
+        ),
+        *cards,
+        ui.Link(
+            text=f"Open full Secrets manager →",
+            href=f"/ext/{ext_id}/secrets",
+        ),
+    ])
+
+    # Match the wrapper contract from @ext.panel decorator — return .to_dict()
+    # of the root. The kernel wraps {"ui": ..., "panel_id": "secrets"}.
+    if hasattr(root, "to_dict"):
+        return root.to_dict()
+    return root