imperal-sdk 4.2.6__tar.gz → 4.2.8__tar.gz

{imperal_sdk-4.2.6 → imperal_sdk-4.2.8}/CHANGELOG.md

@@ -2,6 +2,119 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 4.2.8 — 2026-05-13
+
+**Fix: `secrets[]` finally in `Manifest` Pydantic schema**
+
+EXT-SECRETS-V1 manifest emitter has been writing `manifest["secrets"] = [...]`
+since v4.2.2, but the `Manifest` Pydantic model in `manifest_schema.py` had
+no matching field. With `model_config = ConfigDict(extra="forbid")`, this
+should have caused `validate_manifest_dict()` to reject every manifest that
+declared secrets — but publish-time validators didn't gate through this
+schema, so the drift lived silently for six PATCH releases.
+
+### Added
+
+- **`SecretDecl` Pydantic model** in `manifest_schema.py` — mirrors
+  `imperal_sdk.secrets.spec.SecretSpec.to_manifest_dict()`. Validates
+  `name` regex (`^[a-z][a-z0-9_]{0,62}$`), `write_mode` in
+  `{user, extension, both}`, `max_bytes` in `[1, 65536]`,
+  `rotation_hint_days >= 1` when present, non-empty `description`.
+- **`Manifest.secrets: Optional[List[SecretDecl]]`** field — additive,
+  back-compatible with manifests that don't declare any secrets.
+
+### Federal invariants
+
+| Invariant | What it pins |
+|---|---|
+| `I-MANIFEST-EMITTER-SCHEMA-SYMMETRIC` | (already declared in v4.1.6 canary roundtrip test) Now actually holds for `secrets[]` — emitter and schema agree. |
+
+### Migration notes
+
+- **No code change required** in any extension. Existing manifests with
+  `secrets[]` (emitted since v4.2.2) now pass strict Pydantic validation
+  instead of relying on validators that didn't gate through the schema.
+- Manifests with malformed secret entries (e.g. `name` with uppercase or
+  invalid `write_mode`) will now fail `validate_manifest_dict()` at
+  publish time. Previously they slipped through.
+
+## 4.2.7 — 2026-05-13
+
+**OAuth callback infrastructure + `ctx.webhook_url()` helper**
+
+Closes the architectural gap that made `@ext.webhook("/callback", method="GET")`
+non-functional for OAuth providers (Spotify, GitHub, Google). Before this
+release: hardcoded redirect URIs in `*_config.py` landed users on a Next.js
+404 (no nginx route for `/v1/ext/*`), and even if they reached auth-gw the
+`ext_router` was POST-only.
+
+### Added
+
+- **`Context.webhook_url(path)`** — builds the canonical public callback
+  URL from kernel-authoritative `_extension_id` (folder/manifest name, not
+  the drift-prone Python `Extension("X", ...)` value). Returns
+  `https://{IMPERAL_PUBLIC_HOST}/v1/ext/{app_id}/webhook/{path}` — default
+  host `panel.imperal.io`. Path leading slash is normalised. Use this
+  instead of hardcoding the URL in config files; hardcoded URLs are the
+  #1 cause of OAuth-callback drift bugs.
+
+- **Federal `ctx.secrets` inject moved to `ContextFactory._build_context`** —
+  every dispatch path (chat tool, panel, skeleton, schedule, webhook,
+  lifecycle, health check) now gets `ctx.secrets` uniformly. Previously
+  the inject lived in `pipeline/extension_runner.py` and only fired for
+  chat tool dispatch; panel handlers and others crashed with
+  `AttributeError` when reading `ctx.secrets` despite the documented
+  federal contract. `_HealthCheckCtx` gained a `_StubSecrets` graceful
+  no-op so `@ext.health_check` handlers that read `ctx.secrets` don't
+  crash with `AttributeError`.
+
+- **Kernel-authoritative `app_id` in `ctx.cache`** — `CacheClient` is now
+  constructed with `self._extension_id` (kernel parameter) instead of
+  `getattr(self._extension, "app_id", ...)` (Python runtime). Fixes the
+  401 class observed in production when an ext author writes
+  `Extension("X-extension", ...)` while the deployed folder/manifest is
+  `X` — auth-gw extcache row uses the deployed app_id and would never
+  authorise the drifted Python value.
+
+### Platform changes (live, not in the package)
+
+- **nginx** on `panel.imperal.io` now routes `/v1/ext/*` to Imperal Auth
+  Gateway (was: caught by Next.js catch-all → 404). Renamed config from
+  `sharelock-panel*` → `imperal-panel`.
+- **Auth-gw `ext_router`** accepts both `GET` (OAuth callbacks,
+  verification challenges) and `POST` (server-to-server hooks) on the
+  same `/v1/ext/{app_id}/webhook/{path}` endpoint.
+- **Auth-gw `marketplace/router.py`** new public endpoint
+  `GET /v1/marketplace/apps/{app_id}/webhooks` returns `[{path, method}]`
+  for each declared `@ext.webhook`. Strips `secret_header`.
+- **Imperal Panel** Secrets tab renders a blue info card listing every
+  webhook URL with Copy buttons so end-users know what to paste into
+  OAuth provider developer consoles.
+- **Dev Portal App Details** gained a Webhooks tab (`imperal-ext-developer`
+  v1.3.0) showing the per-app callback URLs with method badges.
+
+### Migration notes
+
+- Replace `SP_REDIRECT_URI = "https://..."` hardcodes with
+  `ctx.webhook_url("/callback")` at runtime. Existing hardcoded URLs that
+  match the canonical shape keep working — but new extensions should
+  prefer the helper. No SDK-blocking change in this release.
+- `@ext.health_check` handlers that call `await ctx.secrets.list()` /
+  `.get(...)` now receive a graceful no-op stub instead of
+  `AttributeError`. Reads return `None`/`[]`/`False`; writes raise
+  `RuntimeError` (health checks have no per-user context).
+- All shadow patches applied on 2026-05-13 to platform-worker and
+  session-worker venvs are superseded by this release. Run
+  `pip install --upgrade imperal-sdk==4.2.7` to clear them.
+
+### Federal invariants
+
+| Invariant | What it pins |
+|---|---|
+| `I-SECRETS-HANDLER-SCOPE-MEMORY` | Already pinned; the ContextFactory move preserves it — plaintext stays a local variable in the handler call. |
+| `I-EXT-CACHE-APP-ID-KERNEL-AUTHORITATIVE` | (new) `CacheClient.app_id` sourced from kernel `_extension_id`, never from Python `ext.app_id`. |
+| `I-WEBHOOK-URL-CANONICAL` | (new) `ctx.webhook_url(path)` returns `https://{IMPERAL_PUBLIC_HOST}/v1/ext/{kernel-authoritative-app_id}/webhook/{path}`. Source-inspection-friendly: env var lookup + no Python-instance attribute drift. |
+
 ## 4.2.6 — 2026-05-13
 
 **New: `ui.Password` primitive + `ui.Input(type=)` kwarg**

{imperal_sdk-4.2.6 → imperal_sdk-4.2.8}/PKG-INFO

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

{imperal_sdk-4.2.6 → imperal_sdk-4.2.8}/src/imperal_sdk/__init__.py

@@ -39,7 +39,7 @@ from imperal_sdk.secrets import (
     SecretValueTooLarge, SecretDeclarationConflict,
 )
 
-__version__ = "4.2.6"
+__version__ = "4.2.8"
 
 __all__ = [
     # Core

{imperal_sdk-4.2.6 → imperal_sdk-4.2.8}/src/imperal_sdk/context.py

@@ -218,7 +218,14 @@ class Context:
             try:
                 from imperal_sdk.cache.client import CacheClient
                 self._cache = CacheClient(
-                    app_id=getattr(self._extension, "app_id", self._extension_id),
+                    # 2026-05-13: kernel-authoritative app_id (folder/manifest
+                    # name passed by ContextFactory). ext.app_id is the Python
+                    # runtime value and can drift from the deployed app_id
+                    # (e.g. Extension("spotify-extension") in app.py while
+                    # /opt/extensions/spotify/ + Dev Portal row are "spotify"
+                    # — auth-gw extcache 401'd every request). Fall back to
+                    # ext.app_id only when factory didn't pass _extension_id.
+                    app_id=self._extension_id or getattr(self._extension, "app_id", ""),
                     user_id=self.user.imperal_id,
                     gw_url=gw,
                     service_token=svc,
@@ -289,6 +296,39 @@ class Context:
         logger = logging.getLogger(f"ext.{self._extension_id}")
         getattr(logger, level, logger.info)(message)
 
+    def webhook_url(self, path: str) -> str:
+        """Build the public OAuth/webhook callback URL for this extension.
+
+        Returns the URL the extension author must register in the OAuth
+        provider's developer console (Spotify, GitHub, Google, etc.).
+
+        Path is the same string passed to ``@ext.webhook("/path")``. Both
+        forms work — leading slash is normalised:
+
+            ctx.webhook_url("/callback")     # → .../webhook/callback
+            ctx.webhook_url("callback")      # → .../webhook/callback
+            ctx.webhook_url("/oauth/return") # → .../webhook/oauth/return
+
+        Host comes from the ``IMPERAL_PUBLIC_HOST`` env var (default
+        ``panel.imperal.io``). Path-component ``{app_id}`` comes from the
+        kernel-authoritative ``_extension_id`` (folder/manifest name),
+        not from ``ext.app_id`` (Python runtime, can drift).
+
+        Use this instead of hardcoding the URL in ``spotify_config.py``
+        et al. — that pattern is what caused the 2026-05-13 Spotify 401
+        class (auth-gw never saw the drifted `spotify-extension` row).
+        """
+        import os as _os_wh
+        host = _os_wh.environ.get("IMPERAL_PUBLIC_HOST", "panel.imperal.io")
+        clean_path = (path or "").lstrip("/")
+        app_id = self._extension_id or getattr(self._extension, "app_id", "")
+        if not app_id:
+            raise RuntimeError(
+                "ctx.webhook_url() called without an extension_id — "
+                "kernel must build ctx via ContextFactory."
+            )
+        return f"https://{host}/v1/ext/{app_id}/webhook/{clean_path}"
+
     def as_user(self, user_id: str) -> "Context":
         """Return scoped Context for target user_id.
 

{imperal_sdk-4.2.6 → imperal_sdk-4.2.8}/src/imperal_sdk/manifest_schema.py

@@ -240,6 +240,26 @@ class TrayDecl(BaseModel):
     tooltip: Optional[str] = None
 
 
+class SecretDecl(BaseModel):
+    """One entry in `manifest['secrets']` — EXT-SECRETS-V1 (v4.2.2+).
+
+    Mirrors :class:`imperal_sdk.secrets.spec.SecretSpec` after
+    ``to_manifest_dict()``. The Pydantic model exists so
+    :func:`validate_manifest_dict` round-trips the emitted shape — closes
+    the `I-MANIFEST-EMITTER-SCHEMA-SYMMETRIC` drift gap that lived
+    silently from v4.2.2 → v4.2.7.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(..., pattern=r"^[a-z][a-z0-9_]{0,62}$")
+    description: str = Field(..., min_length=1)
+    required: bool = False
+    write_mode: Literal["user", "extension", "both"] = "user"
+    max_bytes: int = Field(default=4096, ge=1, le=65536)
+    rotation_hint_days: Optional[int] = Field(default=None, ge=1)
+
+
 # === Root model =======================================================
 
 class Manifest(BaseModel):
@@ -290,6 +310,14 @@ class Manifest(BaseModel):
     # Reserved for first-party Imperal authors (validator V31).
     system: Optional[bool] = None
 
+    # Federal v4.2.2 — EXT-SECRETS-V1. Optional array of per-user encrypted
+    # credential declarations the extension reads via ``ctx.secrets.get()``.
+    # Closes the `I-MANIFEST-EMITTER-SCHEMA-SYMMETRIC` drift where the
+    # emitter wrote `secrets[]` from v4.2.2 onwards but this Pydantic model
+    # had no matching field (extra="forbid" would have rejected — but
+    # publish-time validators didn't gate through here).
+    secrets: Optional[List[SecretDecl]] = None
+
     # --- Marketplace merge (docs/imperal-cloud/developer-portal.md) ---
     name: Optional[str] = None
     description: Optional[str] = None