Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

refactor(crypto): EncryptedSecret adoption sweep + service-level crypto ratchet (plan 77 C1)

Juan Denisd2525717a808
diff --git a/backend/app/api/db_tuner.py b/backend/app/api/db_tuner.py
index 64dfd8a1..cb299489 100644
--- a/backend/app/api/db_tuner.py
+++ b/backend/app/api/db_tuner.py
@@ -42,8 +42,7 @@ def _build_target(target, data):
if not engine:
return None, (jsonify({'error': f'Unsupported engine: {managed.engine}'}), 400)
if not password and managed.admin_secret_encrypted:
- from app.utils.crypto import decrypt_secret_safe
- password = decrypt_secret_safe(managed.admin_secret_encrypted)
+ password = managed.admin_secret
return {
'container': managed.container_ref,
'engine': engine,
diff --git a/backend/app/models/container_registry.py b/backend/app/models/container_registry.py
index 43ab30fd..f2049212 100644
--- a/backend/app/models/container_registry.py
+++ b/backend/app/models/container_registry.py
@@ -1,6 +1,7 @@
from datetime import datetime
from app import db
+from app.models.mixins import EncryptedSecret
class ContainerRegistry(db.Model):
@@ -30,6 +31,7 @@ class ContainerRegistry(db.Model):
registry_url = db.Column(db.String(255), nullable=True)
username = db.Column(db.String(180), nullable=True)
secret_encrypted = db.Column(db.Text, nullable=True)
+ secret = EncryptedSecret('secret_encrypted', legacy_plaintext=True)
# Nullable FK — a registry can be scoped to one workspace, or global (NULL).
workspace_id = db.Column(db.Integer, db.ForeignKey('workspaces.id'), nullable=True, index=True)
created_by = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=True)
diff --git a/backend/app/models/linked_panel.py b/backend/app/models/linked_panel.py
index 383d2379..f3f89946 100644
--- a/backend/app/models/linked_panel.py
+++ b/backend/app/models/linked_panel.py
@@ -14,7 +14,7 @@ Managed/Observed trust levels.
from datetime import datetime
from app import db
-from app.utils.crypto import encrypt_secret, decrypt_secret_safe
+from app.models.mixins import EncryptedSecret
class LinkedPanelConfig(db.Model):
@@ -35,11 +35,15 @@ class LinkedPanelConfig(db.Model):
created_at = db.Column(db.DateTime, default=datetime.utcnow)
updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+ # One crypto path (plan 77 C1). legacy_plaintext: rows written before
+ # encryption-at-rest read back unchanged until rewritten.
+ api_secret = EncryptedSecret('api_secret_encrypted', legacy_plaintext=True)
+
def set_api_secret(self, plaintext: str):
- self.api_secret_encrypted = encrypt_secret(plaintext)
+ self.api_secret = plaintext
def get_api_secret(self):
- return decrypt_secret_safe(self.api_secret_encrypted)
+ return self.api_secret
def to_dict(self):
return {
diff --git a/backend/app/models/managed_database.py b/backend/app/models/managed_database.py
index 63c79f42..b4ae8f6b 100644
--- a/backend/app/models/managed_database.py
+++ b/backend/app/models/managed_database.py
@@ -1,6 +1,7 @@
from datetime import datetime
from app import db
+from app.models.mixins import EncryptedSecret
# Engines whose lifecycle ServerKit actually drives (Mongo stays read-first).
VALID_DB_ENGINES = ('mysql', 'postgresql', 'mongodb')
@@ -42,6 +43,7 @@ class ManagedDatabase(db.Model):
origin = db.Column(db.String(20), nullable=False, default='provisioned') # provisioned|adopted
admin_username = db.Column(db.String(180), nullable=True)
admin_secret_encrypted = db.Column(db.Text, nullable=True)
+ admin_secret = EncryptedSecret('admin_secret_encrypted', legacy_plaintext=True)
workspace_id = db.Column(db.Integer, db.ForeignKey('workspaces.id'), nullable=True, index=True)
created_at = db.Column(db.DateTime, default=datetime.utcnow, index=True)
updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
diff --git a/backend/app/models/mixins.py b/backend/app/models/mixins.py
index f04c1605..fe9f7ab5 100644
--- a/backend/app/models/mixins.py
+++ b/backend/app/models/mixins.py
@@ -110,9 +110,14 @@ class EncryptedSecret:
- Assigning ``None`` (or ``''``) clears the column.
"""
- def __init__(self, column_name: str):
+ def __init__(self, column_name: str, legacy_plaintext: bool = False):
self.column_name = column_name
self.attr_name = column_name # overwritten by __set_name__
+ # Columns that predate encryption-at-rest may still hold plaintext
+ # rows. legacy_plaintext=True mirrors utils.crypto.decrypt_secret_safe:
+ # an undecryptable value is returned unchanged instead of None, so
+ # not-yet-rewritten rows keep working until their next write.
+ self.legacy_plaintext = legacy_plaintext
def __set_name__(self, owner, name):
self.attr_name = f'{owner.__name__}.{name}'
@@ -127,6 +132,8 @@ class EncryptedSecret:
try:
return decrypt_secret(raw)
except Exception:
+ if self.legacy_plaintext:
+ return raw
logger.warning(
"Failed to decrypt %s (wrong key or corrupt ciphertext); returning None",
self.attr_name, exc_info=True,
diff --git a/backend/app/models/pending_agent.py b/backend/app/models/pending_agent.py
index df78fc53..097e1d1e 100644
--- a/backend/app/models/pending_agent.py
+++ b/backend/app/models/pending_agent.py
@@ -19,6 +19,7 @@ from datetime import datetime, timedelta
import bcrypt
from app import db
+from app.models.mixins import EncryptedSecret
# Pair code uses Crockford-ish base32 minus ambiguous chars (0/O, 1/I/L)
@@ -70,6 +71,7 @@ class PendingAgent(db.Model):
# When claimed, we stash credentials here briefly (Fernet-encrypted) so the
# next /poll call can deliver them to the agent. Cleared after retrieval.
claim_payload_encrypted = db.Column(db.Text, nullable=True)
+ claim_payload = EncryptedSecret('claim_payload_encrypted')
claimed_server = db.relationship('Server', foreign_keys=[claimed_server_id])
diff --git a/backend/app/models/registrar_connection.py b/backend/app/models/registrar_connection.py
index 1f71ce5f..676bec75 100644
--- a/backend/app/models/registrar_connection.py
+++ b/backend/app/models/registrar_connection.py
@@ -1,5 +1,6 @@
from datetime import datetime
from app import db
+from app.models.mixins import EncryptedSecret
class RegistrarConnection(db.Model):
@@ -18,6 +19,8 @@ class RegistrarConnection(db.Model):
name = db.Column(db.String(120), nullable=True) # user-facing label
api_key_encrypted = db.Column(db.Text, nullable=True)
api_secret_encrypted = db.Column(db.Text, nullable=True)
+ api_key = EncryptedSecret('api_key_encrypted', legacy_plaintext=True)
+ api_secret = EncryptedSecret('api_secret_encrypted', legacy_plaintext=True)
account_label = db.Column(db.String(180), nullable=True) # e.g. domain count / shopper id
config_json = db.Column(db.Text, nullable=True) # provider-specific non-secret extras (e.g. Namecheap username + client_ip)
last_synced_at = db.Column(db.DateTime, nullable=True)
diff --git a/backend/app/models/source_connection.py b/backend/app/models/source_connection.py
index a944bb2b..7546851e 100644
--- a/backend/app/models/source_connection.py
+++ b/backend/app/models/source_connection.py
@@ -1,6 +1,7 @@
from datetime import datetime
from app import db
+from app.models.mixins import EncryptedSecret
class SourceConnection(db.Model):
@@ -21,6 +22,7 @@ class SourceConnection(db.Model):
display_name = db.Column(db.String(180), nullable=True)
avatar_url = db.Column(db.String(500), nullable=True)
access_token_encrypted = db.Column(db.Text, nullable=False)
+ access_token = EncryptedSecret('access_token_encrypted', legacy_plaintext=True)
scope = db.Column(db.String(500), nullable=True)
created_at = db.Column(db.DateTime, default=datetime.utcnow, index=True)
updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
diff --git a/backend/app/services/container_registry_service.py b/backend/app/services/container_registry_service.py
index fa13be5f..8d7249c1 100644
--- a/backend/app/services/container_registry_service.py
+++ b/backend/app/services/container_registry_service.py
@@ -19,7 +19,6 @@ from datetime import datetime
from app import db
from app.utils.system import run_checked
from app.models.container_registry import ContainerRegistry
-from app.utils.crypto import encrypt_secret, decrypt_secret_safe
logger = logging.getLogger(__name__)
@@ -58,7 +57,7 @@ class ContainerRegistryService:
created_by=created_by,
)
if secret:
- reg.secret_encrypted = encrypt_secret(secret)
+ reg.secret = secret
db.session.add(reg)
db.session.commit()
return reg
@@ -77,7 +76,7 @@ class ContainerRegistryService:
# Only replace the secret when a new one is actually supplied, so an edit
# of the label/URL never wipes the stored credential.
if secret:
- registry.secret_encrypted = encrypt_secret(secret)
+ registry.secret = secret
db.session.commit()
return registry
@@ -98,7 +97,7 @@ class ContainerRegistryService:
return token
if not registry.secret_encrypted:
return None
- return decrypt_secret_safe(registry.secret_encrypted)
+ return registry.secret
# ── docker login / logout ──
@staticmethod
@@ -163,7 +162,7 @@ class ContainerRegistryService:
region = parts[idx + 1]
env = None
- secret = decrypt_secret_safe(registry.secret_encrypted or '')
+ secret = registry.secret
if secret and ':' in secret:
access_key, secret_key = secret.split(':', 1)
env = dict(os.environ)
diff --git a/backend/app/services/env_reference_service.py b/backend/app/services/env_reference_service.py
index a9d3e8c4..38996236 100644
--- a/backend/app/services/env_reference_service.py
+++ b/backend/app/services/env_reference_service.py
@@ -136,9 +136,7 @@ class EnvReferenceResolver:
if prop == 'username':
return managed.admin_username or '', None
if prop == 'password':
- from app.utils.crypto import decrypt_secret_safe
- return (decrypt_secret_safe(managed.admin_secret_encrypted) or '') \
- if managed.admin_secret_encrypted else '', None
+ return (managed.admin_secret or ''), None
return None, f'property `{prop}` not valid for a database service'
@classmethod
diff --git a/backend/app/services/managed_database_service.py b/backend/app/services/managed_database_service.py
index 0444a88b..4edc09e6 100644
--- a/backend/app/services/managed_database_service.py
+++ b/backend/app/services/managed_database_service.py
@@ -17,7 +17,6 @@ import logging
from app import db
from app.models.managed_database import ManagedDatabase
from app.services.database_service import DatabaseService
-from app.utils.crypto import encrypt_secret, decrypt_secret_safe
logger = logging.getLogger(__name__)
@@ -55,7 +54,7 @@ class ManagedDatabaseService:
if admin_username is not None:
managed.admin_username = admin_username
if admin_secret:
- managed.admin_secret_encrypted = encrypt_secret(admin_secret)
+ managed.admin_secret = admin_secret
if workspace_id is not None:
managed.workspace_id = workspace_id
@@ -115,7 +114,7 @@ class ManagedDatabaseService:
username = user or managed.admin_username
password = None
if managed.admin_secret_encrypted:
- password = decrypt_secret_safe(managed.admin_secret_encrypted) if reveal else '***'
+ password = managed.admin_secret if reveal else '***'
userinfo = ''
if username:
@@ -155,7 +154,7 @@ class ManagedDatabaseService:
'db_type': _ENGINE_TO_DBTYPE.get(managed.engine, managed.engine),
'db_name': managed.name,
'user': managed.admin_username,
- 'password': decrypt_secret_safe(managed.admin_secret_encrypted or '') or None,
+ 'password': managed.admin_secret or None,
'host': managed.host,
}
diff --git a/backend/app/services/managed_db_user_service.py b/backend/app/services/managed_db_user_service.py
index 3c3a1264..fe4d57dd 100644
--- a/backend/app/services/managed_db_user_service.py
+++ b/backend/app/services/managed_db_user_service.py
@@ -18,7 +18,6 @@ from datetime import datetime
from app import db
from app.models.managed_database_user import ManagedDatabaseUser # explicit import registers the table
from app.services import db_exec
-from app.utils.crypto import decrypt_secret_safe
logger = logging.getLogger(__name__)
@@ -42,7 +41,7 @@ class ManagedDbUserService:
Returns the ``{'success': bool, 'output': str, 'error': str|None}``
shape of ``DatabaseService`` executors.
"""
- secret = decrypt_secret_safe(managed.admin_secret_encrypted or '') or None
+ secret = managed.admin_secret or None
return db_exec.exec_sql(db_exec.target_from_managed(managed, password=secret), sql)
# ── validation / quoting helpers ──
diff --git a/backend/app/services/pairing_service.py b/backend/app/services/pairing_service.py
index 3f467f2e..ad231739 100644
--- a/backend/app/services/pairing_service.py
+++ b/backend/app/services/pairing_service.py
@@ -34,7 +34,6 @@ from app.models.pending_agent import (
DEFAULT_ENROLLMENT_TTL,
)
from app.models.server import Server
-from app.utils.crypto import encrypt_secret, decrypt_secret
logger = logging.getLogger(__name__)
@@ -270,7 +269,7 @@ def poll(enrollment_id: str, enrollment_secret: str,
if pending.is_claimed() and pending.claim_payload_encrypted:
try:
- payload = json.loads(decrypt_secret(pending.claim_payload_encrypted))
+ payload = json.loads(pending.claim_payload)
except Exception as e:
logger.exception("Failed to decrypt claim payload: %s", e)
raise PairingError("Internal pairing error")
@@ -398,7 +397,7 @@ def claim(operator_user_id: int, code: str, passphrase: str,
'api_key': api_key,
'api_secret': api_secret,
})
- pending.claim_payload_encrypted = encrypt_secret(payload)
+ pending.claim_payload = payload
pending.claimed_at = datetime.utcnow()
pending.claimed_server_id = server.id
pending.failed_attempts = 0
diff --git a/backend/app/services/registrar_service.py b/backend/app/services/registrar_service.py
index e42f38bf..c2dc91c2 100644
--- a/backend/app/services/registrar_service.py
+++ b/backend/app/services/registrar_service.py
@@ -15,7 +15,6 @@ import requests
from app import db
from app.models.registrar_connection import RegistrarConnection
-from app.utils.crypto import encrypt_secret, decrypt_secret
logger = logging.getLogger(__name__)
@@ -58,14 +57,14 @@ class RegistrarService:
conn = RegistrarConnection(
provider=provider,
name=(data.get('name') or '').strip() or cls.SUPPORTED[provider]['name'],
- api_key_encrypted=encrypt_secret(api_key),
user_id=user_id,
)
+ conn.api_key = api_key
if provider == 'godaddy':
api_secret = (data.get('api_secret') or '').strip()
if not api_secret:
raise ValueError('api_secret is required')
- conn.api_secret_encrypted = encrypt_secret(api_secret)
+ conn.api_secret = api_secret
elif provider == 'namecheap':
username = (data.get('username') or '').strip()
client_ip = (data.get('client_ip') or '').strip()
@@ -88,11 +87,11 @@ class RegistrarService:
@staticmethod
def _creds(conn):
- return decrypt_secret(conn.api_key_encrypted), decrypt_secret(conn.api_secret_encrypted)
+ return conn.api_key, conn.api_secret
@staticmethod
def _api_key(conn):
- return decrypt_secret(conn.api_key_encrypted) if conn.api_key_encrypted else ''
+ return conn.api_key or ''
# --- GoDaddy ---
diff --git a/backend/app/services/source_connection_service.py b/backend/app/services/source_connection_service.py
index 4cf3822a..c846f162 100644
--- a/backend/app/services/source_connection_service.py
+++ b/backend/app/services/source_connection_service.py
@@ -10,10 +10,10 @@ import requests
from flask import session
from app import db
+from app.utils.crypto import encrypt_secret
from app.models import SourceConnection
from app.services.repository_manifest_service import RepositoryManifestService
from app.services.settings_service import SettingsService
-from app.utils.crypto import encrypt_secret, decrypt_secret
class SourceConnectionService:
@@ -244,7 +244,7 @@ class SourceConnectionService:
connection.provider_username = profile.get('login') or ''
connection.display_name = profile.get('name') or profile.get('login') or ''
connection.avatar_url = profile.get('avatar_url') or ''
- connection.access_token_encrypted = encrypt_secret(access_token)
+ connection.access_token = access_token
connection.scope = token_data.get('scope') or ' '.join(cls.GITHUB_SCOPES)
connection.updated_at = datetime.utcnow()
connection.last_used_at = datetime.utcnow()
@@ -484,7 +484,7 @@ class SourceConnectionService:
connection.provider_username = profile.get('username') or ''
connection.display_name = profile.get('name') or profile.get('username') or ''
connection.avatar_url = profile.get('avatar_url') or ''
- connection.access_token_encrypted = encrypt_secret(access_token)
+ connection.access_token = access_token
connection.scope = token_data.get('scope') or ' '.join(cls.GITLAB_SCOPES)
connection.updated_at = datetime.utcnow()
connection.last_used_at = datetime.utcnow()
@@ -658,7 +658,7 @@ class SourceConnectionService:
connection.provider_username = profile.get('username') or ''
connection.display_name = profile.get('display_name') or profile.get('username') or ''
connection.avatar_url = (profile.get('links', {}).get('avatar', {}) or {}).get('href', '')
- connection.access_token_encrypted = encrypt_secret(access_token)
+ connection.access_token = access_token
connection.scope = ' '.join(token_data.get('scopes', [])) or ' '.join(cls.BITBUCKET_SCOPES)
connection.updated_at = datetime.utcnow()
connection.last_used_at = datetime.utcnow()
@@ -829,7 +829,7 @@ class SourceConnectionService:
@staticmethod
def _decrypt_connection_token(connection):
- token = decrypt_secret(connection.access_token_encrypted)
+ token = connection.access_token
if not token:
raise ValueError('GitHub token could not be decrypted')
return token
diff --git a/backend/tests/test_crypto_one_door_ratchet.py b/backend/tests/test_crypto_one_door_ratchet.py
new file mode 100644
index 00000000..071566a9
--- /dev/null
+++ b/backend/tests/test_crypto_one_door_ratchet.py
@@ -0,0 +1,61 @@
+"""Plan 77 C1 ratchet — services do not hand-roll crypto for model-owned
+``*_encrypted`` columns.
+
+Models that own an encrypted column expose it through the EncryptedSecret
+descriptor (app/models/mixins.py); service code assigns/reads the plaintext
+attribute and never calls encrypt_secret/decrypt_secret for those columns.
+
+The allowlist below is the frozen 2026-08-19 population of service/api files
+that import app.utils.crypto for NON-model-column material (settings-store
+values, credentials_json maps, the vault service itself). Shrinking it is
+progress; adding to it needs a reason that is not "the model has no
+accessor" — give the model a descriptor instead.
+"""
+import re
+from pathlib import Path
+
+APP = Path(__file__).resolve().parents[1] / 'app'
+
+ALLOWED = {
+ 'services/ai_service.py', # settings-store ai_api_key_encrypted
+ 'services/chat_webhook_service.py', # per-field maps inside credentials_json
+ 'services/connection_registry.py',
+ 'services/dns_provider_service.py',
+ 'services/dns_zone_service.py',
+ 'services/email_relay_service.py',
+ 'services/manifest_apply_service.py',
+ 'services/secret_vault_service.py', # owns SecretVault writes by design
+ 'services/settings_service.py',
+ 'services/storage_provider_service.py',
+ 'services/source_connection_service.py', # SettingsService-held PEM/webhook secret
+ 'api/ai.py',
+ 'api/system.py',
+}
+
+IMPORT_RE = re.compile(r'^\s*(from\s+app\.utils\.crypto\s+import|from\s+app\.utils\s+import\s+crypto|import\s+app\.utils\.crypto)', re.M)
+
+
+def _importers():
+ found = set()
+ for sub in ('services', 'api'):
+ for f in sorted((APP / sub).glob('*.py')):
+ if IMPORT_RE.search(f.read_text(encoding='utf-8', errors='replace')):
+ found.add(f'{sub}/{f.name}')
+ return found
+
+
+def test_no_new_service_level_crypto_callers():
+ found = _importers()
+ new = found - ALLOWED
+ assert not new, (
+ f"New app.utils.crypto importers in services/api: {sorted(new)}. "
+ "If this is for a model-owned *_encrypted column, add an "
+ "EncryptedSecret descriptor to the model instead (plan 77 C1)."
+ )
+
+
+def test_allowlist_does_not_go_stale():
+ """A file leaving the list should be removed so the ratchet stays tight."""
+ found = _importers()
+ stale = ALLOWED - found
+ assert not stale, f"Allowlist entries no longer importing crypto: {sorted(stale)} — delete them."