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

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

@@ -2,6 +2,61 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imperal-sdk
-Version: 4.2.1
+Version: 4.2.2
 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.2}/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.2"
 
 __all__ = [
     # Core

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

@@ -139,6 +139,71 @@ 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
+
+        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.2}/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.2/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.2/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.2/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.2/src/imperal_sdk/secrets/spec.py

@@ -0,0 +1,66 @@
+"""SecretSpec — declarative shape of one @ext.secret declaration."""
+import re
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+SECRET_NAME_RE = re.compile(r"^[a-z][a-z0-9_]{0,62}$")
+ALLOWED_WRITE_MODES = frozenset({"user", "extension", "both"})
+
+
+@dataclass(frozen=True)
+class SecretSpec:
+    """One secret an extension declares it needs.
+
+    Federal contract:
+    - ``name`` is snake_case; auth-gw stores it scoped under (user_id, ext_id, name)
+    - ``write_mode`` determines who can write the value: 'user' (Panel UI only),
+      'extension' (ctx.secrets.set only), or 'both'
+    - ``required=True`` triggers a dispatch-time gate — kernel blocks handler
+      and emits secret_missing_card chat message if value not set
+    - ``max_bytes`` caps both write payload and storage; hard ceiling 65536
+    """
+
+    name: str
+    description: str
+    required: bool = False
+    write_mode: Literal["user", "extension", "both"] = "user"
+    max_bytes: int = 4096
+    rotation_hint_days: Optional[int] = None
+
+    def __post_init__(self) -> None:
+        if not SECRET_NAME_RE.match(self.name):
+            raise ValueError(
+                f"SecretSpec.name {self.name!r} fails regex "
+                f"{SECRET_NAME_RE.pattern!r} (snake_case, start-letter, ≤63 chars)"
+            )
+        if self.write_mode not in ALLOWED_WRITE_MODES:
+            raise ValueError(
+                f"SecretSpec.write_mode {self.write_mode!r} must be one of "
+                f"{sorted(ALLOWED_WRITE_MODES)}"
+            )
+        if not (1 <= self.max_bytes <= 65536):
+            raise ValueError(
+                f"SecretSpec.max_bytes {self.max_bytes!r} must be in [1, 65536]"
+            )
+        if self.rotation_hint_days is not None and self.rotation_hint_days < 1:
+            raise ValueError(
+                f"SecretSpec.rotation_hint_days {self.rotation_hint_days!r} "
+                f"must be a positive integer or None"
+            )
+        if not self.description.strip():
+            raise ValueError(
+                "SecretSpec.description must be non-empty — Panel UI shows it "
+                "to the user when they're entering the value"
+            )
+
+    def to_manifest_dict(self) -> dict:
+        d = {
+            "name": self.name,
+            "description": self.description,
+            "required": self.required,
+            "write_mode": self.write_mode,
+            "max_bytes": self.max_bytes,
+        }
+        if self.rotation_hint_days is not None:
+            d["rotation_hint_days"] = self.rotation_hint_days
+        return d

{imperal_sdk-4.2.1 → imperal_sdk-4.2.2}/src/imperal_sdk/testing/__init__.py

@@ -13,6 +13,7 @@ from imperal_sdk.testing.mock_context import (
     MockStorage,
     MockStore,
 )
+from imperal_sdk.testing.mock_secrets import MockSecretStore
 
 __all__ = [
     "MockContext",
@@ -25,4 +26,5 @@ __all__ = [
     "MockHTTP",
     "MockConfig",
     "MockExtensions",
+    "MockSecretStore",
 ]

imperal_sdk-4.2.2/src/imperal_sdk/testing/mock_secrets.py

@@ -0,0 +1,76 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+"""MockSecretStore — pytest-friendly in-memory backend for ctx.secrets.
+
+Canonical pattern::
+
+    @pytest.fixture
+    def secrets():
+        return MockSecretStore({"openai_api_key": "sk-test"})
+
+    async def test_my_handler(ctx_factory, secrets):
+        ctx = ctx_factory(secrets=secrets)
+        ...
+"""
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class _Status:
+    name: str
+    description: str
+    is_set: bool
+    last_accessed_at: Optional[int]
+
+
+class MockSecretStore:
+    """Drop-in replacement for SecretClient in pytest. No HTTP, no Vault.
+
+    Validates name-not-declared semantics if ``declared`` set is passed
+    (raises ImportError-style ValueError to mirror SecretNotDeclaredError).
+    Otherwise accepts any name (looser default for fixture ergonomics).
+    """
+
+    def __init__(
+        self,
+        initial: dict[str, str] | None = None,
+        *,
+        declared: set[str] | None = None,
+    ):
+        self._store: dict[str, str] = dict(initial or {})
+        self._declared = declared  # if None, all names allowed
+
+    def _check_declared(self, name: str) -> None:
+        if self._declared is not None and name not in self._declared:
+            raise ValueError(
+                f"MockSecretStore: name {name!r} not in declared set "
+                f"(declared={sorted(self._declared)})"
+            )
+
+    async def get(self, name: str) -> Optional[str]:
+        self._check_declared(name)
+        return self._store.get(name)
+
+    async def set(self, name: str, value: str) -> None:
+        self._check_declared(name)
+        self._store[name] = value
+
+    async def delete(self, name: str) -> bool:
+        self._check_declared(name)
+        return self._store.pop(name, None) is not None
+
+    async def is_set(self, name: str) -> bool:
+        self._check_declared(name)
+        return name in self._store
+
+    async def list(self) -> list[_Status]:
+        return [
+            _Status(
+                name=n,
+                description="(mock)",
+                is_set=True,
+                last_accessed_at=None,
+            )
+            for n in self._store
+        ]