rusackas · Apr 6, 2026 · Apr 6, 2026 · Apr 6, 2026 · Apr 6, 2026 · Apr 6, 2026
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -139,7 +139,7 @@ repos:
             BASE=$(git merge-base origin/"$TARGET_BRANCH" HEAD 2>/dev/null) || BASE="HEAD"
             files=$(git diff --name-only --diff-filter=ACM "$BASE"..HEAD 2>/dev/null | grep '^superset/.*\.py$' || true)
             if [ -n "$files" ]; then
-              pylint --rcfile=.pylintrc --load-plugins=superset.extensions.pylint --reports=no $files
+              PYTHONPATH="${PYTHONPATH:+$PYTHONPATH:}$(pwd)" pylint --rcfile=.pylintrc --load-plugins=superset.extensions.pylint --reports=no $files
             else
               echo "No Python files to lint."
             fi

diff --git a/UPDATING.md b/UPDATING.md
@@ -32,6 +32,36 @@ The Deck.gl MapBox chart's **Opacity**, **Default longitude**, **Default latitud
 
 **To restore fit-to-data behavior:** Open the chart in Explore, clear the **Default longitude**, **Default latitude**, and **Zoom** fields in the Viewport section, and re-save the chart.
 
+### Tier-3 Extension Storage: `ExtensionStorage` model + `ExtensionStorageDAO`
+
+A generic `extension_storage` table now provides extensions with scoped,
+encrypted persistent key-value storage without requiring extensions to
+contribute model code to core Superset.
+
+Three storage scopes are supported:
+
+| Scope    | Description |
+|----------|-------------|
+| **Global** | Shared across all users of an extension |
+| **User**   | Isolated per authenticated user |
+| **Resource** | Tied to a specific Superset resource (dashboard, chart, …) by type + UUID |
+
+REST API (all endpoints under `/api/v1/extensions/{publisher}/{name}/`):
+
+```
+GET/PUT/DELETE .../storage/persistent/global/{key}
+GET            .../storage/persistent/global/         (paginated)
+GET/PUT/DELETE .../storage/persistent/user/{key}
+GET            .../storage/persistent/user/           (paginated, ?category=…)
+GET/PUT/DELETE .../storage/persistent/resources/{type}/{uuid}/{key}
+GET            .../storage/persistent/resources/{type}/{uuid}/  (paginated)
+```
+
+Values may be stored encrypted at rest by including `"is_encrypted": true` in
+the PUT body. The DAO uses a Fernet key derived from the app `SECRET_KEY`.
+Key rotation is supported via `EXTENSION_STORAGE_ENCRYPTION_KEYS` in config
+and the `superset rotate-extension-storage-keys` CLI command.
+
 ### ClickHouse minimum driver version bump
 
 The minimum required version of `clickhouse-connect` has been raised to `>=0.13.0`. If you are using the ClickHouse connector, please upgrade your `clickhouse-connect` package. The `_mutate_label` workaround that appended hash suffixes to column aliases has also been removed, as it is no longer needed with modern versions of the driver.

@@ -0,0 +1,235 @@
+---
+title: Persistent Storage
+sidebar_position: 3
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Persistent Storage (Tier 3)
+
+Extensions can store arbitrary key-value data in Superset's database without
+contributing model code to the core codebase. The storage layer supports three
+**scopes**, optional **category** filtering for cheap listing, optional
+**at-rest encryption**, and **key rotation** with zero downtime.
+
+## Storage Scopes
+
+| Scope | When to use | `user_fk` | `resource_type` |
+|---|---|---|---|
+| **Global** | Configuration shared across all users of the extension | `null` | `null` |
+| **User** | Per-user preferences or saved artefacts | set | `null` |
+| **Resource** | State tied to a specific Superset resource (dashboard, chart, …) | any | set |
+
+## REST API
+
+All endpoints live under:
+
+```
+/api/v1/extensions/{publisher}/{name}/storage/persistent/
+```
+
+### Global scope
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `.../global/` | List entries (`?page=0&page_size=25&category=…`) |
+| `GET` | `.../global/{key}` | Read a value (response body is the raw bytes) |
+| `PUT` | `.../global/{key}` | Create or update |
+| `DELETE` | `.../global/{key}` | Delete |
+
+### User scope
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `.../user/` | List the authenticated user's entries |
+| `GET` | `.../user/{key}` | Read a value |
+| `PUT` | `.../user/{key}` | Create or update |
+| `DELETE` | `.../user/{key}` | Delete |
+
+### Resource scope
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `.../resources/{type}/{uuid}/` | List entries for the resource |
+| `GET` | `.../resources/{type}/{uuid}/{key}` | Read a value |
+| `PUT` | `.../resources/{type}/{uuid}/{key}` | Create or update |
+| `DELETE` | `.../resources/{type}/{uuid}/{key}` | Delete |
+
+## PUT request body
+
+All write endpoints accept a JSON body:
+
+```json
+{
+  "value": "<string or base64 bytes>",
+  "value_type": "application/json",
+  "category": "my-category",
+  "description": "Human-readable label for cheap listing",
+  "is_encrypted": false
+}
+```
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `value` | yes | `""` | The payload to store |
+| `value_type` | no | `application/json` | MIME type returned on GET |
+| `category` | no | `null` | Used to filter list results |
+| `description` | no | `null` | Returned in list results without fetching `value` |
+| `is_encrypted` | no | `false` | Encrypts `value` at rest with Fernet |
+
+## List response
+
+```json
+{
+  "count": 42,
+  "result": [
+    {
+      "key": "my-key",
+      "uuid": "...",
+      "value_type": "application/json",
+      "category": "my-category",
+      "description": "...",
+      "is_encrypted": false
+    }
+  ]
+}
+```
+
+The `value` blob is **not** included in list responses. Fetch individual keys
+to retrieve values.
+
+## Frontend usage
+
+From a TypeScript extension frontend, use standard `fetch` with the Superset
+CSRF token:
+
+```typescript
+const BASE = '/api/v1/extensions/acme/my-ext/storage/persistent/user';
+
+// Save
+await fetch(`${BASE}/my-key`, {
+  method: 'PUT',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-CSRFToken': await authentication.getCSRFToken(),
+  },
+  body: JSON.stringify({
+    value: JSON.stringify({ foo: 'bar' }),
+    value_type: 'application/json',
+    category: 'preferences',
+    description: 'My display name',  // shown in list without fetching value
+  }),
+});
+
+// List
+const { result } = await fetch(`${BASE}/?category=preferences`).then(r => r.json());
+
+// Read
+const raw = await fetch(`${BASE}/my-key`).then(r => r.text());
+const data = JSON.parse(raw);
+
+// Delete
+await fetch(`${BASE}/my-key`, { method: 'DELETE', headers: { 'X-CSRFToken': ... } });
+```
+
+## Backend usage (Python)
+
+Within extension backend code, use `ExtensionStorageDAO` directly:
+
+```python
+from superset_core.common.daos import ExtensionStorageDAO
+
+EXT_ID = "acme.my-ext"
+
+# Write
+ExtensionStorageDAO.set(EXT_ID, "config", b'{"theme":"dark"}', category="global-config")
+
+# Read
+value: bytes | None = ExtensionStorageDAO.get_value(EXT_ID, "config")
+
+# User-scoped
+ExtensionStorageDAO.set(EXT_ID, "prefs", b'{"lang":"fr"}', user_fk=user_id)
+value = ExtensionStorageDAO.get_value(EXT_ID, "prefs", user_fk=user_id)
+
+# Resource-scoped
+ExtensionStorageDAO.set(
+    EXT_ID, "state", payload,
+    resource_type="dashboard", resource_uuid=str(dashboard.uuid),
+)
+```
+
+:::note
+`ExtensionStorageDAO` methods call `db.session.flush()` but do **not** commit.
+The caller (or the `@transaction()` decorator on the API endpoint) owns the
+transaction.
+:::
+
+## Encryption at rest
+
+Set `"is_encrypted": true` in the PUT body (frontend) or `is_encrypted=True`
+in `ExtensionStorageDAO.set()` (backend). Values are encrypted with
+[Fernet](https://cryptography.io/en/latest/fernet/) using a key derived from
+`SECRET_KEY` (or the first entry of `EXTENSION_STORAGE_ENCRYPTION_KEYS` if
+configured). Decryption is transparent on read.
+
+### Key rotation
+
+To rotate encryption keys without downtime:
+
+1. **Prepend** the new key to `EXTENSION_STORAGE_ENCRYPTION_KEYS` in your
+   Superset config and **restart**. Existing encrypted rows are still readable
+   (old key is tried as a fallback); new writes use the new key.
+
+   ```python
+   # superset_config.py
+   EXTENSION_STORAGE_ENCRYPTION_KEYS = [
+       "new-strong-secret",   # used for new encryptions
+       "old-secret",          # still tried for decryption
+   ]
+   ```
+
+2. **Re-encrypt** all existing rows with the new key:
+
+   ```bash
+   superset rotate-extension-storage-keys
+   ```
+
+3. **Remove** the old key from the list and restart again.
+
+## Data model
+
+The `extension_storage` table schema:
+
+| Column | Type | Notes |
+|---|---|---|
+| `id` | integer PK | |
+| `uuid` | UUID | Unique, auto-generated |
+| `extension_id` | varchar(255) | `{publisher}.{name}` |
+| `user_fk` | integer FK | `null` = global or resource scope |
+| `resource_type` | varchar(64) | e.g. `dashboard`, `chart` |
+| `resource_uuid` | varchar(36) | UUID of the linked resource |
+| `key` | varchar(255) | Identifier within a scope |
+| `category` | varchar(64) | Optional grouping tag |
+| `description` | text | Summary for list endpoints |
+| `value` | binary (up to 16 MB) | The stored payload |
+| `value_type` | varchar(255) | MIME type, default `application/json` |
+| `is_encrypted` | boolean | Whether `value` is Fernet-encrypted |
+| `created_on`, `changed_on` | datetime | Audit fields |
+| `created_by_fk`, `changed_by_fk` | integer FK | Audit fields |
diff --git a/pyproject.toml b/pyproject.toml
@@ -243,6 +243,7 @@ multi_line_output = 3
 order_by_type = false
 
 [tool.mypy]
+python_version = "3.10"
 check_untyped_defs = true
 disallow_any_generics = true
 disallow_untyped_calls = true

diff --git a/superset/cli/update.py b/superset/cli/update.py
@@ -101,6 +101,54 @@ def update_api_docs() -> None:
         click.secho("API version not found", err=True)
 
 
+@click.command()
+@with_appcontext
+@transaction()
+def rotate_extension_storage_keys() -> None:
+    """Re-encrypt all encrypted extension storage rows with the current key.
+
+    Run this after prepending a new key to EXTENSION_STORAGE_ENCRYPTION_KEYS
+    in your Superset config.  MultiFernet.rotate() decrypts each token with
+    whichever old key succeeds, then re-encrypts it with the first (new) key.
+    Once all rows are rotated you can remove old keys from the config list.
+    """
+    # pylint: disable=import-outside-toplevel
+    from superset import db
+    from superset.extension_storage.daos import _fernet
+    from superset.extension_storage.models import ExtensionStorage
+
+    fernet = _fernet()
+    entries = (
+        db.session.query(ExtensionStorage)
+        .filter(ExtensionStorage.is_encrypted.is_(True))
+        .all()
+    )
+    if not entries:
+        click.secho("No encrypted entries found.", fg="yellow")
+        return
+    failed = 0
+    for entry in entries:
+        try:
+            entry.value = fernet.rotate(entry.value)
+        except Exception as exc:  # pylint: disable=broad-except
+            click.secho(
+                f"Failed to rotate key={entry.key} ext={entry.extension_id}: {exc}",
+                fg="red",
-        try:
-            entry.value = fernet.rotate(entry.value)
-        except Exception as exc:  # pylint: disable=broad-except
-            click.secho(
-                f"Failed to rotate key={entry.key} ext={entry.extension_id}: {exc}",
-                fg="red",
+        try:
+            entry.value = fernet.rotate(entry.value)
+        except (ValueError, TypeError) as exc:
+            click.secho(
+                f"Failed to rotate key={entry.key} ext={entry.extension_id}: {exc}",
+                fg="red",
-        try:
-            entry.value = fernet.rotate(entry.value)
-        except Exception as exc:  # pylint: disable=broad-except
-            click.secho(
-                f"Failed to rotate key={entry.key} ext={entry.extension_id}: {exc}",
-                fg="red",
+        try:
+            entry.value = fernet.rotate(entry.value)
+        except (ValueError, TypeError) as exc:
+            click.secho(
+                f"Failed to rotate key={entry.key} ext={entry.extension_id}: {exc}",
+                fg="red",
+                err=True,
+            )
+            failed += 1
+    rotated = len(entries) - failed
-    entries = (
-        db.session.query(ExtensionStorage)
-        .filter(ExtensionStorage.is_encrypted.is_(True))
-        .all()
-    )
-    if not entries:
-        click.secho("No encrypted entries found.", fg="yellow")
-        return
-    failed = 0
-    for entry in entries:
-        try:
-            entry.value = fernet.rotate(entry.value)
-        except Exception as exc:  # pylint: disable=broad-except
-            click.secho(
-                f"Failed to rotate key={entry.key} ext={entry.extension_id}: {exc}",
-                fg="red",
-                err=True,
-            )
-            failed += 1
-    rotated = len(entries) - failed
+    encrypted_count = (
+        db.session.query(ExtensionStorage.id)
+        .filter(ExtensionStorage.is_encrypted.is_(True))
+        .count()
+    )
+    if encrypted_count == 0:
+        click.secho("No encrypted entries found.", fg="yellow")
+        return
+    failed = 0
+    rotated = 0
+    for entry in (
+        db.session.query(ExtensionStorage)
+        .filter(ExtensionStorage.is_encrypted.is_(True))
+        .yield_per(100)
+    ):
+        try:
+            entry.value = fernet.rotate(entry.value)
+            db.session.flush()
+            db.session.expunge(entry)
+            rotated += 1
+        except Exception as exc:  # pylint: disable=broad-except
+            click.secho(
+                f"Failed to rotate key={entry.key} ext={entry.extension_id}: {exc}",
+                fg="red",
+                err=True,
+            )
+            failed += 1
-    entries = (
-        db.session.query(ExtensionStorage)
-        .filter(ExtensionStorage.is_encrypted.is_(True))
-        .all()
-    )
-    if not entries:
-        click.secho("No encrypted entries found.", fg="yellow")
-        return
-    failed = 0
-    for entry in entries:
-        try:
-            entry.value = fernet.rotate(entry.value)
-        except Exception as exc:  # pylint: disable=broad-except
-            click.secho(
-                f"Failed to rotate key={entry.key} ext={entry.extension_id}: {exc}",
-                fg="red",
-                err=True,
-            )
-            failed += 1
-    rotated = len(entries) - failed
+    encrypted_count = (
+        db.session.query(ExtensionStorage.id)
+        .filter(ExtensionStorage.is_encrypted.is_(True))
+        .count()
+    )
+    if encrypted_count == 0:
+        click.secho("No encrypted entries found.", fg="yellow")
+        return
+    failed = 0
+    rotated = 0
+    for entry in (
+        db.session.query(ExtensionStorage)
+        .filter(ExtensionStorage.is_encrypted.is_(True))
+        .yield_per(100)
+    ):
+        try:
+            entry.value = fernet.rotate(entry.value)
+            db.session.flush()
+            db.session.expunge(entry)
+            rotated += 1
+        except Exception as exc:  # pylint: disable=broad-except
+            click.secho(
+                f"Failed to rotate key={entry.key} ext={entry.extension_id}: {exc}",
+                fg="red",
+                err=True,
+            )
+            failed += 1
+    click.secho(
+        f"Rotated {rotated}/{len(entries)} entries"
+        + (
+            f" ({failed} failed — check EXTENSION_STORAGE_ENCRYPTION_KEYS)"
+            if failed
+            else ""
+        ),
+        fg="green" if not failed else "yellow",
+    )
+
+
 @click.command()
 @with_appcontext
 @click.option(

@@ -233,6 +233,14 @@ def _try_json_readsha(filepath: str, length: int) -> str | None:
 # a sufficiently random sequence, ex: openssl rand -base64 42"
 SECRET_KEY = os.environ.get("SUPERSET_SECRET_KEY") or CHANGE_ME_SECRET_KEY
 
+# Keys used to encrypt extension storage entries (Tier 3 persistent storage).
+# The first key in the list is used for new encryptions; all keys are tried
+# on decryption.  To rotate: prepend the new key, restart, then run
+# ``superset rotate-extension-storage-keys``.  Once all rows are re-encrypted
+# the old key(s) can be removed from the list.
+# Falls back to SECRET_KEY when not set.
+EXTENSION_STORAGE_ENCRYPTION_KEYS: list[str] = []
+
 # The SQLAlchemy connection string.
 SQLALCHEMY_DATABASE_URI = (
     f"""sqlite:///{os.path.join(DATA_DIR, "superset.db")}?check_same_thread=false"""

diff --git a/superset/core/api/core_api_injection.py b/superset/core/api/core_api_injection.py
@@ -58,6 +58,9 @@ def inject_dao_implementations() -> None:
     from superset.daos.tag import TagDAO as HostTagDAO
     from superset.daos.tasks import TaskDAO as HostTaskDAO
     from superset.daos.user import UserDAO as HostUserDAO
+    from superset.extension_storage.daos import (
+        ExtensionStorageDAO as HostExtensionStorageDAO,
+    )
 
     # Replace abstract classes in common.daos with concrete implementations
     core_common_dao_module.DatasetDAO = HostDatasetDAO  # type: ignore[assignment,misc]
@@ -67,6 +70,7 @@ def inject_dao_implementations() -> None:
     core_common_dao_module.UserDAO = HostUserDAO  # type: ignore[assignment,misc]
     core_common_dao_module.TagDAO = HostTagDAO  # type: ignore[assignment,misc]
     core_common_dao_module.KeyValueDAO = HostKeyValueDAO  # type: ignore[assignment,misc]
+    core_common_dao_module.ExtensionStorageDAO = HostExtensionStorageDAO  # type: ignore[assignment,misc]
 
     # Replace abstract classes in queries.daos
     core_queries_dao_module.QueryDAO = HostQueryDAO  # type: ignore[assignment,misc]
@@ -89,6 +93,9 @@ def inject_model_implementations() -> None:
     from flask_appbuilder.security.sqla.models import User as HostUser
 
     from superset.connectors.sqla.models import SqlaTable as HostDataset
+    from superset.extension_storage.models import (
+        ExtensionStorage as HostExtensionStorage,
+    )
     from superset.key_value.models import KeyValueEntry as HostKeyValue
     from superset.models.core import Database as HostDatabase
     from superset.models.dashboard import Dashboard as HostDashboard
@@ -105,6 +112,7 @@ def inject_model_implementations() -> None:
     core_common_models_module.User = HostUser  # type: ignore[misc]
     core_common_models_module.Tag = HostTag  # type: ignore[misc]
     core_common_models_module.KeyValue = HostKeyValue  # type: ignore[misc]
+    core_common_models_module.ExtensionStorage = HostExtensionStorage  # type: ignore[misc]
 
     # In-place replacement in queries.models
     core_queries_models_module.Query = HostQuery  # type: ignore[misc]