databricks-tellr 0.4.3.dev12__tar.gz → 0.4.3.dev13__tar.gz

{databricks_tellr-0.4.3.dev12 → databricks_tellr-0.4.3.dev13}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: databricks-tellr
-Version: 0.4.3.dev12
+Version: 0.4.3.dev13
 Summary: Tellr deployment tooling for Databricks Apps
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: databricks-sdk>=0.85.0
 Requires-Dist: psycopg2-binary>=2.9.0
 Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: requests>=2.31.0
 
 # databricks-tellr
 

{databricks_tellr-0.4.3.dev12 → databricks_tellr-0.4.3.dev13}/databricks_tellr/_templates/app.yaml.template

@@ -67,3 +67,4 @@ env:
   # Set to "0" if you want to force-disable the fast path entirely.
   - name: HUASHU_PIPELINE_ENABLED
     value: "1"
+${ENCRYPTION_SECRET_ENV_BLOCK}

{databricks_tellr-0.4.3.dev12 → databricks_tellr-0.4.3.dev13}/databricks_tellr/deploy.py

@@ -30,6 +30,7 @@ from databricks.sdk.service.apps import (
 from databricks.sdk.service.database import DatabaseInstance
 from databricks.sdk.service.workspace import ImportFormat
 
+from databricks_tellr import secret_key
 from databricks_tellr.identifiers import validate_client_id, validate_schema_name
 
 # Autoscaling imports (Lakebase next-gen)
@@ -198,6 +199,8 @@ def create(
     profile: str | None = None,
     config_yaml_path: str | None = None,
     mlflow_tracing: dict[str, str] | None = None,
+    encryption_secret_scope: str | None = None,
+    encryption_secret_key: str = secret_key.DEFAULT_SECRET_KEY,
 ) -> dict[str, Any]:
     """Deploy Tellr to Databricks Apps.
 
@@ -232,6 +235,11 @@ def create(
             ``config_yaml_path``, YAML ``mlflow_tracing`` applies first; non-empty
             entries here override. Empty slots can be filled from deploy-time env
             vars ``TELLR_DEPLOY_MLFLOW_*``.
+        encryption_secret_scope: Opt in to the secret-backed Fernet key. When set,
+            the key is stored in this Databricks secret scope and attached to the
+            app as a secret resource instead of living in the encryption_keys
+            Lakebase table. When omitted, the Lakebase-backed path is used.
+        encryption_secret_key: Secret key name within that scope.
 
     Returns:
         Dictionary with deployment info:
@@ -259,6 +267,8 @@ def create(
         config_yaml_path=config_yaml_path,
         seed_databricks_defaults=False,
         mlflow_tracing=mlflow_tracing,
+        encryption_secret_scope=encryption_secret_scope,
+        encryption_secret_key=encryption_secret_key,
     )
 
 
@@ -273,6 +283,8 @@ def update(
     profile: str | None = None,
     encryption_key: str | None = None,
     mlflow_tracing: dict[str, str] | None = None,
+    encryption_secret_scope: str | None = None,
+    encryption_secret_key: str = secret_key.DEFAULT_SECRET_KEY,
 ) -> dict[str, Any]:
     """Deploy a new version of an existing Tellr app.
 
@@ -293,6 +305,11 @@ def update(
         mlflow_tracing: Optional overrides for UC tracing env vars (same keys as ``create``).
             Values from deployment YAML are not loaded on update; use this argument or
             ``TELLR_DEPLOY_MLFLOW_*`` environment variables.
+        encryption_secret_scope: Databricks secret scope that holds the Fernet
+            master key (opt-in secret mode). When set, the key is stored in and
+            read from this scope rather than Lakebase.
+        encryption_secret_key: Name of the secret within *encryption_secret_scope*.
+            Defaults to ``DEFAULT_SECRET_KEY`` ("tellr-encryption-key").
 
     Returns:
         Dictionary with deployment info
@@ -312,6 +329,8 @@ def update(
         seed_databricks_defaults=False,
         encryption_key=encryption_key,
         mlflow_tracing=mlflow_tracing,
+        encryption_secret_scope=encryption_secret_scope,
+        encryption_secret_key=encryption_secret_key,
     )
 
 
@@ -334,6 +353,8 @@ def _create_databricks(
     config_yaml_path: str | None = None,
     seed_databricks_defaults: bool = True,
     mlflow_tracing: dict[str, str] | None = None,
+    encryption_secret_scope: str | None = None,
+    encryption_secret_key: str = secret_key.DEFAULT_SECRET_KEY,
 ) -> dict[str, Any]:
     """Deploy Tellr to Databricks Apps with configurable seeding.
     
@@ -377,6 +398,25 @@ def _create_databricks(
         app_file_workspace_path = config.get("app_file_workspace_path")
         lakebase_compute = config.get("lakebase_compute", lakebase_compute)
         app_compute = config.get("app_compute", app_compute)
+        encryption_secret_scope = encryption_secret_scope or config.get(
+            "encryption_secret_scope"
+        )
+        encryption_secret_key = (
+            config.get("encryption_secret_key") or encryption_secret_key
+        )
+
+    # Preflight before anything is created, so a failure leaves nothing behind.
+    resolved_key: str | None = None
+    if encryption_secret_scope:
+        print(f"Secret-backed encryption key: {encryption_secret_scope}/{encryption_secret_key}")
+        secret_key.preflight_scope(ws, encryption_secret_scope)
+        resolved_key = secret_key.resolve_key_for_create(
+            ws, encryption_secret_scope, encryption_secret_key
+        )
+
+    encryption_secret_resource_key = (
+        secret_key.RESOURCE_KEY if encryption_secret_scope else None
+    )
 
     mlflow_subs = _mlflow_substitutions_for_app_yaml(
         deployment_flat=deployment_flat_for_mlflow,
@@ -417,6 +457,7 @@ def _create_databricks(
                 seed_databricks_defaults=seed_databricks_defaults,
                 lakebase_result=lakebase_result,
                 mlflow_tracing=mlflow_subs,
+                encryption_secret_resource_key=encryption_secret_resource_key,
             )
             print("   Generated app.yaml")
 
@@ -435,6 +476,8 @@ def _create_databricks(
             compute_size=app_compute,
             lakebase_name=lakebase_name,
             lakebase_type=lakebase_type,
+            encryption_secret_scope=encryption_secret_scope,
+            encryption_secret_key=encryption_secret_key,
         )
         print("   App registered")
         print()
@@ -489,9 +532,11 @@ def _update_databricks(
     seed_databricks_defaults: bool = True,
     encryption_key: str | None = None,
     mlflow_tracing: dict[str, str] | None = None,
+    encryption_secret_scope: str | None = None,
+    encryption_secret_key: str = secret_key.DEFAULT_SECRET_KEY,
 ) -> dict[str, Any]:
     """Deploy a new version of an existing Tellr app with configurable seeding.
-    
+
     Internal function with full control over seeding behavior.
 
     Args:
@@ -508,6 +553,11 @@ def _update_databricks(
             the encryption_keys table. Default: read from the deployed
             app.yaml. The key is no longer written to app.yaml.
         mlflow_tracing: Optional overrides for UC tracing placeholders in ``app.yaml``.
+        encryption_secret_scope: Databricks secret scope that holds the Fernet
+            master key (opt-in secret mode). When set, the key is stored in and
+            read from this scope rather than Lakebase.
+        encryption_secret_key: Name of the secret within *encryption_secret_scope*.
+            Defaults to ``DEFAULT_SECRET_KEY`` ("tellr-encryption-key").
 
     Returns:
         Dictionary with deployment info
@@ -519,6 +569,24 @@ def _update_databricks(
 
     ws = _get_workspace_client(client, profile)
 
+    app_already_secret = secret_key.app_is_secret_mode(ws, app_name)
+    if not encryption_secret_scope and app_already_secret:
+        if encryption_key:
+            raise DeploymentError(
+                f"App {app_name} uses a secret-backed encryption key, so passing "
+                f"encryption_key would recreate the Lakebase key row this app was "
+                f"migrated off — and a mismatched value would silently orphan "
+                f"stored credentials. Re-run with "
+                f"encryption_secret_scope=... instead."
+            )
+        print("   Secret-backed encryption key retained (app resource unchanged)")
+
+    encryption_secret_resource_key = (
+        secret_key.RESOURCE_KEY
+        if (encryption_secret_scope or app_already_secret)
+        else None
+    )
+
     mlflow_subs = _mlflow_substitutions_for_app_yaml(
         deployment_flat={},
         overrides=mlflow_tracing,
@@ -545,11 +613,32 @@ def _update_databricks(
             print(f"   Schema '{schema_name}' reset (tables will be recreated on app startup)")
             print()
 
-        # CRITICAL-3 migration: relocate the legacy app.yaml key into the
-        # encryption_keys table BEFORE the new (keyless) app.yaml overwrites
-        # it. Runs at most once per install: after it succeeds, the deployed
-        # app.yaml has no key entry and encryption_key is None on re-runs.
-        if encryption_key:
+        if encryption_secret_scope:
+            # Secret mode: relocate into the secret; never seed Lakebase.
+            validate_schema_name(schema_name)  # defense-in-depth: interpolated into SQL below
+            secret_key.preflight_scope(ws, encryption_secret_scope)
+            mig_conn, _ = _get_lakebase_connection(
+                ws, lakebase_name, lakebase_result=lakebase_result
+            )
+            try:
+                with mig_conn.cursor() as cur:
+                    secret_key.preflight_lakebase_privileges(cur, schema_name)
+                    lakebase_key = secret_key.read_lakebase_key(cur, schema_name)
+            finally:
+                mig_conn.close()
+
+            _, wrote = secret_key.resolve_key_for_update(
+                ws, encryption_secret_scope, encryption_secret_key,
+                lakebase_key, encryption_key,
+            )
+            if wrote:
+                print("   Key written to the secret and verified")
+            secret_key.attach_secret_resource(
+                ws, app_name, encryption_secret_scope, encryption_secret_key
+            )
+            print("   Secret resource attached")
+        elif encryption_key:
+            # Legacy CRITICAL-3 relocation into Lakebase — unchanged.
             print("Relocating encryption key into Lakebase (encryption_keys)...")
             app_for_grant = ws.apps.get(name=app_name)
             grant_client_id = _get_app_client_id(app_for_grant)
@@ -577,6 +666,7 @@ def _update_databricks(
                 seed_databricks_defaults=seed_databricks_defaults,
                 lakebase_result=lakebase_result,
                 mlflow_tracing=mlflow_subs,
+                encryption_secret_resource_key=encryption_secret_resource_key,
             )
             _upload_files(ws, staging, app_file_workspace_path)
             print("   Files updated")
@@ -591,6 +681,35 @@ def _update_databricks(
         if app.url:
             print(f"   URL: {app.url}")
 
+        if encryption_secret_scope:
+            if not app.url:
+                print("   WARNING: no app URL — cannot confirm the key source; "
+                      "leaving the Lakebase key row in place")
+            elif secret_key.app_reports_secret_source(ws, app.url):
+                del_conn = None
+                try:
+                    del_conn, _ = _get_lakebase_connection(
+                        ws, lakebase_name, lakebase_result=lakebase_result
+                    )
+                    with del_conn.cursor() as cur:
+                        if secret_key.read_lakebase_key(cur, schema_name):
+                            secret_key.delete_lakebase_key_row(cur, schema_name)
+                            print("   Lakebase key row deleted — the secret is now "
+                                  "the only copy")
+                        else:
+                            print("   No Lakebase key row to remove")
+                except Exception as exc:  # noqa: BLE001 — deploy already succeeded
+                    print(f"   WARNING: could not delete the Lakebase key row: {exc}")
+                    print(f'   Run manually: DELETE FROM "{schema_name}".'
+                          f"encryption_keys WHERE id = 1;")
+                finally:
+                    if del_conn is not None:
+                        del_conn.close()
+            else:
+                print("   WARNING: the deployed app does not report the secret as "
+                      "its key source. Leaving the Lakebase key row in place. This "
+                      "is expected if the app version predates secret-mode support.")
+
         return {
             "url": app.url,
             "app_name": app_name,
@@ -616,6 +735,12 @@ def delete(
 
     Note: This does not delete the Lakebase instance by default.
 
+    Deliberately does NOT touch secrets or secret scopes. A devloop fork shares
+    the production app's secret scope and key by design (so it can decrypt
+    inherited ciphertext), which means deleting the secret here would destroy
+    production's Fernet master key during a fork teardown. Only the app and its
+    Lakebase branch are removed. Do not "clean up" the secret here.
+
     Args:
         app_name: Name of the app to delete
         lakebase_name: Lakebase instance name (required if reset_database=True)
@@ -888,6 +1013,8 @@ def _load_deployment_config(config_yaml_path: str) -> dict[str, str]:
         "lakebase_name": lakebase_config.get("database_name"),
         "schema_name": lakebase_config.get("schema"),
         "lakebase_compute": lakebase_config.get("capacity"),
+        "encryption_secret_scope": env_config.get("encryption_secret_scope"),
+        "encryption_secret_key": env_config.get("encryption_secret_key"),
         **ml_flat,
     }
 
@@ -1367,6 +1494,7 @@ def _write_app_yaml(
     seed_databricks_defaults: bool = False,
     lakebase_result: dict[str, Any] | None = None,
     mlflow_tracing: dict[str, str] | None = None,
+    encryption_secret_resource_key: str | None = None,
 ) -> None:
     """Generate app.yaml with environment variables.
 
@@ -1381,6 +1509,11 @@ def _write_app_yaml(
         lakebase_result: Result dict from _get_or_create_lakebase() with type info.
         mlflow_tracing: Resolved template keys for UC tracing (four entries). If
             omitted, values are taken only from ``TELLR_DEPLOY_MLFLOW_*`` env vars.
+        encryption_secret_resource_key: When set, add an ``env:`` entry mapping
+            this Apps secret resource key into the environment. The resource
+            declaration alone does not inject anything — the ``valueFrom`` entry
+            is required (verified live). No key material is written; this is a
+            resource reference only. Leave None for the Lakebase-backed path.
     """
     # Build init_database call - only show seed_databricks_defaults when True
     if seed_databricks_defaults:
@@ -1397,6 +1530,15 @@ def _write_app_yaml(
     if mlflow_tracing is None:
         mlflow_tracing = _mlflow_substitutions_for_app_yaml()
 
+    if encryption_secret_resource_key:
+        # The Apps secret resource supplies the value; this only names it.
+        secret_env_block = (
+            f"  - name: {encryption_secret_resource_key}\n"
+            f'    valueFrom: "{encryption_secret_resource_key}"\n'
+        )
+    else:
+        secret_env_block = ""
+
     template_content = _load_template("app.yaml.template")
     content = Template(template_content).substitute(
         LAKEBASE_INSTANCE=lakebase_name,
@@ -1414,6 +1556,7 @@ def _write_app_yaml(
         TELLR_MLFLOW_UC_TABLE_PREFIX=mlflow_tracing.get(
             "TELLR_MLFLOW_UC_TABLE_PREFIX", ""
         ),
+        ENCRYPTION_SECRET_ENV_BLOCK=secret_env_block,
     )
     (staging_dir / "app.yaml").write_text(content)
 
@@ -1485,6 +1628,8 @@ def _create_app(
     compute_size: str,
     lakebase_name: str,
     lakebase_type: str = "provisioned",
+    encryption_secret_scope: str | None = None,
+    encryption_secret_key: str | None = None,
 ) -> App:
     """Create Databricks App with database resource (without deploying).
 
@@ -1514,6 +1659,15 @@ def _create_app(
         app_resources = []
         logger.info("Autoscaling mode: skipping AppResourceDatabase (using env vars)")
 
+    # Both branches: autoscaling builds an empty resource list, so appending
+    # after the branch covers provisioned and autoscaling alike.
+    if encryption_secret_scope:
+        app_resources.append(
+            secret_key.build_secret_resource(
+                encryption_secret_scope, encryption_secret_key
+            )
+        )
+
     app = App(
         name=app_name,
         description=description,

databricks_tellr-0.4.3.dev13/databricks_tellr/secret_key.py

@@ -0,0 +1,336 @@
+"""Secret-backed Fernet master key helpers for the Tellr deploy tool.
+
+The Lakebase-backed path (SDR-4437 CRITICAL-3) remains the default; everything
+here serves the opt-in path that stores the key in a Databricks secret and
+attaches it to the app as a secret resource. Design and the live-verified
+platform behaviour this relies on:
+docs/superpowers/specs/2026-08-20-secret-backed-fernet-key-design.md
+
+Deliberately a separate module: deploy.py is already very large, and keeping
+these helpers here makes them unit-testable without mocking a whole deployment.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import time
+from typing import Any
+
+import requests
+from cryptography.fernet import Fernet
+from databricks.sdk.service.apps import (
+    App,
+    AppResource,
+    AppResourceSecret,
+    AppResourceSecretSecretPermission,
+)
+from databricks.sdk.service.workspace import ScopeBackendType
+
+logger = logging.getLogger(__name__)
+
+#: Apps secret-resource key, and therefore the injected env var name. Verified
+#: that uppercase-underscore resource keys are accepted.
+RESOURCE_KEY = "TELLR_ENCRYPTION_KEY"
+
+#: Default secret key name. Spaces are actually accepted by the API, but a
+#: hyphenated name keeps it consistent with the resource key.
+DEFAULT_SECRET_KEY = "tellr-encryption-key"
+
+
+class SecretKeyError(Exception):
+    """Raised for any recoverable secret-mode setup failure."""
+
+
+def preflight_scope(ws: Any, scope: str) -> None:
+    """Ensure *scope* exists and is usable, before any key material is written.
+
+    Runs before the app is created or updated so a failure leaves nothing
+    half-done. Creates the scope when absent, with ``initial_manage_principal``
+    omitted so the creator is sole manager — explicitly NOT ``"users"``, which
+    would grant every workspace user MANAGE on the scope holding the key.
+    """
+    existing = {s.name: s for s in ws.secrets.list_scopes()}
+    if scope in existing:
+        backend = existing[scope].backend_type
+        if backend is not None and backend != ScopeBackendType.DATABRICKS:
+            raise SecretKeyError(
+                f"Secret scope '{scope}' is {backend} backed. Secret mode writes "
+                f"the key and reads it back to verify; Key Vault backed scopes are "
+                f"written and read through Key Vault, not this API. Use a "
+                f"Databricks-backed scope."
+            )
+        return
+
+    try:
+        ws.secrets.create_scope(scope=scope)
+    except Exception as exc:  # noqa: BLE001 — mapped to actionable guidance below
+        text = str(exc).upper()
+        manual = f"databricks secrets create-scope {scope}"
+        if "LIMIT" in text:
+            raise SecretKeyError(
+                f"Cannot create secret scope '{scope}': this workspace is at its "
+                f"secret-scope limit (1,000 by default, raisable on request). Pass "
+                f"an existing scope via encryption_secret_scope instead."
+            ) from exc
+        if "UNAUTHORIZED" in text or "PERMISSION" in text or "BAD_REQUEST" in text:
+            raise SecretKeyError(
+                f"Not permitted to create secret scope '{scope}'. Ask a workspace "
+                f"admin to run `{manual}` and grant you MANAGE on it, then re-run."
+            ) from exc
+        raise SecretKeyError(
+            f"Could not create secret scope '{scope}': {exc}. Create it manually "
+            f"with `{manual}` and re-run."
+        ) from exc
+    logger.info("Created secret scope %s (creator is sole manager)", scope)
+
+
+def preflight_lakebase_privileges(cur: Any, schema_name: str) -> None:
+    """Verify the deploying human can read and delete the encryption_keys row.
+
+    On installs where the app SP created the table and ``REASSIGN OWNED`` rehomed
+    it to ``tellr_app_owners``, a deployer outside ``databricks_superuser`` has
+    neither privilege. Without this probe a denied SELECT would be indistinguishable
+    from "no row", and the relocate ladder would mint a fresh key over live
+    ciphertext.
+    """
+    table = f"{schema_name}.encryption_keys"
+    missing = []
+    for priv in ("SELECT", "DELETE"):
+        cur.execute(
+            "SELECT has_table_privilege(current_user, %s, %s)", (table, priv)
+        )
+        row = cur.fetchone()
+        if not row or not row[0]:
+            missing.append(priv)
+    if missing:
+        raise SecretKeyError(
+            f"The deploying identity lacks {' and '.join(missing)} on {table}, so "
+            f"the key cannot be safely relocated out of Lakebase. Grant those "
+            f"privileges (or run the deploy as an identity in databricks_superuser) "
+            f"and re-run. Nothing has been changed."
+        )
+
+
+def _looks_absent(exc: Exception) -> bool:
+    return "RESOURCE_DOES_NOT_EXIST" in str(exc).upper()
+
+
+def read_secret_key(ws: Any, scope: str, key: str) -> str | None:
+    """Return the Fernet key stored at *(scope, key)*, or None if truly absent.
+
+    ``GetSecretResponse.value`` is base64 (the API returns the value "in its byte
+    representation"), so it must be decoded. Any error other than a genuine
+    not-found is raised: treating a permission denial as absence would let the
+    caller overwrite a secret that is already protecting live ciphertext.
+    """
+    try:
+        resp = ws.secrets.get_secret(scope=scope, key=key)
+    except Exception as exc:  # noqa: BLE001
+        if _looks_absent(exc):
+            return None
+        raise SecretKeyError(
+            f"Could not read secret {scope}/{key}: {exc}. This is not a "
+            f"'not found' error, so it is most likely a permission problem — "
+            f"refusing to continue rather than risk overwriting a key that may "
+            f"already protect stored credentials."
+        ) from exc
+
+    if resp is None or not resp.value:
+        return None
+    value = base64.b64decode(resp.value).decode()
+    try:
+        Fernet(value.encode())
+    except (ValueError, TypeError) as exc:
+        raise SecretKeyError(
+            f"Secret {scope}/{key} exists but is not a valid Fernet key. Refusing "
+            f"to use or overwrite it — inspect it manually and resolve."
+        ) from exc
+    return value
+
+
+def write_and_verify_secret_key(ws: Any, scope: str, key: str, value: str) -> None:
+    """Write *value* to *(scope, key)* and confirm it reads back identically.
+
+    The read-back is the gate that later permits deleting the Lakebase row: no
+    key material is removed from Lakebase until the secret has been proven
+    present and correct.
+    """
+    ws.secrets.put_secret(scope=scope, key=key, string_value=value)
+    stored = read_secret_key(ws, scope, key)
+    if stored != value:
+        raise SecretKeyError(
+            f"Secret {scope}/{key} failed read-back verification after write. "
+            f"The Lakebase key row has NOT been touched. Resolve the secret "
+            f"store problem and re-run."
+        )
+    logger.info("Secret %s/%s written and verified", scope, key)
+
+
+def build_secret_resource(scope: str, key: str) -> AppResource:
+    """Build the Apps secret resource that injects the key.
+
+    No ``put_acl`` is needed anywhere: attaching this resource auto-grants the
+    app's service principal READ on the scope (verified live). Adding one would
+    require MANAGE on the scope, which is what made fork creation unworkable.
+    """
+    return AppResource(
+        name=RESOURCE_KEY,
+        secret=AppResourceSecret(
+            scope=scope, key=key,
+            permission=AppResourceSecretSecretPermission.READ,
+        ),
+    )
+
+
+def resolve_key_for_create(ws: Any, scope: str, key: str) -> str:
+    """Return the key a fresh install should use, writing one if none exists."""
+    existing = read_secret_key(ws, scope, key)
+    if existing:
+        logger.info("Reusing the existing Fernet key at %s/%s", scope, key)
+        return existing
+    generated = Fernet.generate_key().decode()
+    write_and_verify_secret_key(ws, scope, key, generated)
+    return generated
+
+
+def read_lakebase_key(cur: Any, schema_name: str) -> str | None:
+    """Read the existing Fernet key row, failing closed on anything but absence.
+
+    Only a genuinely missing table or row yields None. A permission error must
+    abort: on installs where the app SP owns the table, a deployer outside
+    ``databricks_superuser`` gets denied, and treating that as "no row" would walk
+    the ladder to case 4 and mint a fresh key over live ciphertext.
+    """
+    try:
+        cur.execute(
+            f'SELECT key_value FROM "{schema_name}".encryption_keys WHERE id = 1'
+        )
+    except Exception as exc:  # noqa: BLE001
+        text = str(exc).lower()
+        if "does not exist" in text and "relation" in text:
+            return None
+        raise SecretKeyError(
+            f"Could not read the existing key from {schema_name}.encryption_keys: "
+            f"{exc}. This is not a missing-table error, so it is most likely a "
+            f"permission problem. Refusing to continue — proceeding could generate "
+            f"a fresh key and orphan every stored Google credential."
+        ) from exc
+    row = cur.fetchone()
+    return row[0] if row and row[0] else None
+
+
+def resolve_key_for_update(
+    ws: Any,
+    scope: str,
+    key: str,
+    lakebase_key: str | None,
+    app_yaml_key: str | None,
+) -> tuple[str, bool]:
+    """Decide which key secret mode should hold. Returns (value, wrote_secret).
+
+    First hit wins:
+      1. A valid key already in the secret — authoritative, and hard-fails if it
+         disagrees with an existing Lakebase row (mirrors the guard in
+         ``_migrate_encryption_key_to_lakebase``).
+      2. The existing Lakebase row — the relocate case.
+      3. A legacy ``GOOGLE_OAUTH_ENCRYPTION_KEY`` still in the deployed app.yaml.
+      4. Nothing anywhere — generate fresh.
+    """
+    existing = read_secret_key(ws, scope, key)
+    if existing:
+        if lakebase_key and lakebase_key != existing:
+            raise SecretKeyError(
+                f"Secret {scope}/{key} holds a different key from "
+                f"encryption_keys. Refusing to continue: attaching the secret and "
+                f"deleting the row would orphan every credential encrypted under "
+                f"the other key. Resolve which key is correct, then re-run."
+            )
+        logger.info("Secret %s/%s already holds the key — reusing", scope, key)
+        return existing, False
+
+    value = lakebase_key or app_yaml_key or Fernet.generate_key().decode()
+    write_and_verify_secret_key(ws, scope, key, value)
+    return value, True
+
+
+def app_reports_secret_source(
+    ws: Any, app_url: str, attempts: int = 10, delay: float = 6.0
+) -> bool:
+    """Return True only if the live app reports it is reading from the secret.
+
+    This is the gate on deleting the Lakebase key row. It **fails closed**: a
+    missing field, an unparseable body, a non-200, or a network error all return
+    False, because every one of those is indistinguishable from "the deployed code
+    does not know about secret mode". An app pinned to a pre-feature version has
+    no ``encryption_key_source`` field at all, which is exactly the case that must
+    not delete the row.
+
+    Databricks Apps sit behind the workspace proxy, so the request carries
+    workspace credentials from ``ws.config.authenticate()``.
+    """
+    url = f"{app_url.rstrip('/')}/api/health"
+    for attempt in range(1, attempts + 1):
+        try:
+            resp = requests.get(url, headers=ws.config.authenticate(), timeout=15)
+            if resp.status_code == 200:
+                source = resp.json().get("encryption_key_source")
+                if source == "secret":
+                    return True
+                logger.info(
+                    "Health gate attempt %s/%s: key source is %r, not 'secret'",
+                    attempt, attempts, source,
+                )
+            else:
+                logger.info(
+                    "Health gate attempt %s/%s: HTTP %s", attempt, attempts,
+                    resp.status_code,
+                )
+        except Exception as exc:  # noqa: BLE001 — any failure means "not confirmed"
+            logger.info("Health gate attempt %s/%s failed: %s", attempt, attempts, exc)
+        if attempt < attempts and delay:
+            time.sleep(delay)
+    return False
+
+
+def attach_secret_resource(ws: Any, app_name: str, scope: str, key: str) -> None:
+    """Add or replace the secret resource on an existing app.
+
+    A GET-fetched ``App`` cannot be passed back: ``apps.update`` rejects it with
+    "Compute size updates are not supported in this update API" (verified). It is
+    also a full replace on the fields it does accept — omitting ``description``
+    blanks it and omitting ``user_api_scopes`` nulls it. So build a fresh App,
+    carry every mutable field explicitly, and omit ``compute_size``.
+    """
+    cur = ws.apps.get(name=app_name)
+    # Filter by name only: an app may legitimately carry other secret
+    # resources, and dropping those would silently break it.
+    kept = [r for r in (cur.resources or []) if r.name != RESOURCE_KEY]
+    kept.append(build_secret_resource(scope, key))
+    ws.apps.update(
+        name=app_name,
+        app=App(
+            name=app_name,
+            description=cur.description,
+            default_source_code_path=cur.default_source_code_path,
+            user_api_scopes=cur.user_api_scopes,
+            resources=kept,
+            # compute_size deliberately omitted — passing it is rejected.
+        ),
+    )
+    logger.info("Attached %s resource to app %s", RESOURCE_KEY, app_name)
+
+
+def delete_lakebase_key_row(cur: Any, schema_name: str) -> None:
+    """Remove the relocated key row. Only ever called behind the health gate."""
+    cur.execute(f'DELETE FROM "{schema_name}".encryption_keys WHERE id = 1')
+    logger.info("Deleted the relocated key row from %s.encryption_keys", schema_name)
+
+
+def app_is_secret_mode(ws: Any, app_name: str) -> bool:
+    """True when the app already carries the encryption-key secret resource."""
+    try:
+        app = ws.apps.get(name=app_name)
+    except Exception:  # noqa: BLE001 — absence is not secret mode
+        return False
+    return any(r.name == RESOURCE_KEY for r in (app.resources or []))

{databricks_tellr-0.4.3.dev12 → databricks_tellr-0.4.3.dev13}/databricks_tellr.egg-info/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: databricks-tellr
-Version: 0.4.3.dev12
+Version: 0.4.3.dev13
 Summary: Tellr deployment tooling for Databricks Apps
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: databricks-sdk>=0.85.0
 Requires-Dist: psycopg2-binary>=2.9.0
 Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: requests>=2.31.0
 
 # databricks-tellr
 

{databricks_tellr-0.4.3.dev12 → databricks_tellr-0.4.3.dev13}/databricks_tellr.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ pyproject.toml
 databricks_tellr/__init__.py
 databricks_tellr/deploy.py
 databricks_tellr/identifiers.py
+databricks_tellr/secret_key.py
 databricks_tellr.egg-info/PKG-INFO
 databricks_tellr.egg-info/SOURCES.txt
 databricks_tellr.egg-info/dependency_links.txt

{databricks_tellr-0.4.3.dev12 → databricks_tellr-0.4.3.dev13}/databricks_tellr.egg-info/requires.txt

@@ -1,3 +1,4 @@
 databricks-sdk>=0.85.0
 psycopg2-binary>=2.9.0
 pyyaml>=6.0.0
+requests>=2.31.0

{databricks_tellr-0.4.3.dev12 → databricks_tellr-0.4.3.dev13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "databricks-tellr"
-version = "0.4.3.dev12"
+version = "0.4.3.dev13"
 description = "Tellr deployment tooling for Databricks Apps"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -12,6 +12,7 @@ dependencies = [
     "databricks-sdk>=0.85.0",
     "psycopg2-binary>=2.9.0",
     "pyyaml>=6.0.0",
+    "requests>=2.31.0",
 ]
 
 [tool.setuptools.packages.find]