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.

feat(connect): let ServerKit Cloud set where this server backs up

Juan Denis8fe469e1fe7e
diff --git a/backend/app/api/backups.py b/backend/app/api/backups.py
index 54172344..a00b3182 100644
--- a/backend/app/api/backups.py
+++ b/backend/app/api/backups.py
@@ -531,6 +531,13 @@ def remove_schedule(schedule_id):
def get_storage_config():
"""Get storage provider configuration (secrets masked)."""
config = StorageProviderService.get_config_masked()
+ # A destination ServerKit Cloud set is read-only here:
+ # two places writing the same config would race, and the operator should
+ # be told where it came from rather than watch their edit disappear.
+ config['managed_by_cloud'] = bool(config.get('managed_by_cloud'))
+ if config['managed_by_cloud']:
+ config['managed_note'] = ('This destination is managed by ServerKit Cloud. Change it '
+ 'under Backups in Cloud, or unassign it there to edit it here.')
return jsonify(config), 200
@@ -542,6 +549,11 @@ def update_storage_config():
if not data:
return jsonify({'error': 'No data provided'}), 400
+ if StorageProviderService.get_config().get('managed_by_cloud'):
+ return jsonify({'error': 'This backup destination is managed by ServerKit Cloud. '
+ 'Unassign it there to set it here — backups keep running '
+ 'either way.'}), 409
+
result = StorageProviderService.save_config(data)
return jsonify(result), 200 if result['success'] else 400
diff --git a/backend/app/services/connect_client.py b/backend/app/services/connect_client.py
index 28899f12..93620f63 100644
--- a/backend/app/services/connect_client.py
+++ b/backend/app/services/connect_client.py
@@ -37,8 +37,9 @@ import requests
from app import paths
from app.services import connect_keys
+from app.services import connect_commands, connect_storage
from app.services.connect_metrics import MetricsPublisher
-from app.services.connect_updates import UpdateCheck, check_and_apply
+from app.services.connect_updates import UpdateCheck, check_and_apply, fetch_jwks
logger = logging.getLogger(__name__)
@@ -52,6 +53,22 @@ STATES = ('unpaired', 'pairing', 'paired_offline', 'online', 'degraded', 'revoke
HTTP_TIMEOUT_S = 20
DEFAULT_PAIR_TIMEOUT_S = 15 * 60 # generous: the user may walk away to log in
POLL_INTERVAL_S = 3.0
+# How often the Storage Hub snapshot goes out unasked.
+# Backup destinations change when a backup runs, not every minute; Cloud can
+# ask for one immediately with the storage.report command.
+STORAGE_INTERVAL_S = 300.0
+
+
+def _peek_command_id(token) -> str:
+ """The cmd_id out of an unverified command, used only to report *why* the
+ command was refused. Nothing is run on the strength of it."""
+ if not token:
+ return ''
+ try:
+ import jwt
+ return str(jwt.decode(token, options={'verify_signature': False}).get('cmd_id') or '')
+ except Exception:
+ return ''
class ConnectError(Exception):
@@ -600,6 +617,13 @@ class RelayClient:
# Release feed check: asked on reconnect, at most
# once an hour, and acted on only when this install can update itself.
self._update = UpdateCheck()
+ # Signed commands and the Storage Hub's status
+ # stream. The JWKS is fetched once per connection: a
+ # command is verified against the keys Cloud published, and a key
+ # Cloud rotates is picked up on the next reconnect.
+ self._jwks = None
+ self._storage_stream = 0
+ self._storage_next_at = 0.0
# -- lifecycle -----------------------------------------------------
@@ -724,15 +748,19 @@ class RelayClient:
logger.info('Connect relay: online via ws (instance %s)',
self.relay_instance)
self._check_for_update(cfg)
+ self._load_jwks(cfg)
+ self._publish_storage(ws)
while self.running:
try:
raw = ws.recv(timeout=PING_INTERVAL_S)
except TimeoutError:
ws.send('{"t":"ping"}')
self._publish_metrics(ws)
+ self._publish_storage(ws)
continue
self._handle_frame(ws, raw)
self._publish_metrics(ws)
+ self._publish_storage(ws)
return 'stopped'
except Exception as exc:
from websockets.exceptions import ConnectionClosed
@@ -852,14 +880,109 @@ class RelayClient:
self._metrics.requeue(self._metrics_inflight.pop(stream_id, []))
return
if frame.get('t') == 'open':
- # M2 has no streams yet: refuse honestly (mirrors the relay).
+ if frame.get('k') == 'command':
+ self._run_command(ws, frame)
+ return
+ # Anything else is a stream this client version does not speak.
+ # Refusing honestly is what stops the relay holding it open.
ws.send(json.dumps({
's': frame.get('s'),
't': 'close',
'reason': 'unsupported',
- 'detail': 'streams arrive with the next Connect release',
+ 'detail': 'this ServerKit version does not speak that stream',
}))
+ # -- signed commands --------------------------------
+
+ def _load_jwks(self, cfg):
+ """Cloud's public signing keys, read once per connection. Without them
+ no command runs — an unverified command is not a command."""
+ try:
+ self._jwks = fetch_jwks(cfg['cloud_url'])
+ except Exception:
+ self._jwks = None
+ logger.debug('Connect commands: could not read the JWKS', exc_info=True)
+
+ def _run_command(self, ws, frame):
+ """Verify, acknowledge, run, report.
+
+ Verification is synchronous so a bad command is refused on the socket
+ it arrived on. The work itself runs on its own thread: a backup that
+ takes four minutes must not stop the heartbeat.
+ """
+ payload = frame.get('p') or {}
+ cfg = _read_connect_file()
+ try:
+ claims = connect_commands.verify(
+ payload.get('jwt'), self._jwks, cfg.get('device_id'),
+ granted_scopes=None)
+ except connect_commands.CommandRejected as exc:
+ cmd_id = _peek_command_id(payload.get('jwt'))
+ logger.warning('Connect command refused: %s', exc)
+ if cmd_id:
+ self._send(ws, connect_commands.result_frame(
+ cmd_id, 'failed', {'ok': False, 'code': 403, 'summary': str(exc)}))
+ else:
+ self._send(ws, {'s': frame.get('s'), 't': 'close',
+ 'reason': 'unsupported', 'detail': str(exc)})
+ return
+
+ cmd_id = claims.get('cmd_id')
+ self._send(ws, connect_commands.result_frame(cmd_id, 'running'))
+ threading.Thread(
+ target=self._command_worker, args=(claims,), daemon=True,
+ name=f'connect-cmd-{cmd_id}').start()
+
+ def _command_worker(self, claims):
+ result = connect_commands.run(claims, self.app)
+ state = 'succeeded' if result.get('ok') else 'failed'
+ self._send(self._ws, connect_commands.result_frame(
+ claims.get('cmd_id'), state, result))
+
+ def _send(self, ws, frame) -> bool:
+ """One frame, best effort. A dropped socket is not an error worth
+ raising here: ServerKit Cloud times the command out and says so, and the panel
+ reports again on reconnect."""
+ if ws is None:
+ return False
+ try:
+ ws.send(json.dumps(frame))
+ return True
+ except Exception:
+ logger.debug('Connect: could not send frame', exc_info=True)
+ return False
+
+ # -- the storage stream ------------------------------
+
+ def publish_storage(self, snapshot=None) -> bool:
+ """Send one storage snapshot now. Used by the storage.report command."""
+ ws = self._ws
+ if ws is None:
+ return False
+ snapshot = snapshot if snapshot is not None else connect_storage.build_status(self.app)
+ if snapshot is None:
+ return False
+ self._storage_stream += 1
+ return self._send(ws, connect_storage.status_frame(
+ f'sto{self._storage_stream}', snapshot))
+
+ def _publish_storage(self, ws):
+ """Where backups go and how they went, on its own slow cadence: this
+ changes when a backup runs, not every minute."""
+ now = time.monotonic()
+ if now < self._storage_next_at:
+ return
+ self._storage_next_at = now + STORAGE_INTERVAL_S
+ try:
+ snapshot = connect_storage.build_status(self.app)
+ except Exception:
+ logger.debug('Connect storage: could not build a snapshot', exc_info=True)
+ return
+ if snapshot is None:
+ return
+ self._storage_stream += 1
+ self._send(ws, connect_storage.status_frame(f'sto{self._storage_stream}', snapshot))
+
# -- long-poll fallback ----------------------------------------------
def _poll_session(self, cfg, ws_retry_at) -> str:
diff --git a/backend/app/services/connect_commands.py b/backend/app/services/connect_commands.py
new file mode 100644
index 00000000..880d5da0
--- /dev/null
+++ b/backend/app/services/connect_commands.py
@@ -0,0 +1,183 @@
+"""Running the signed commands ServerKit Cloud sends.
+
+A command arrives as one `open` frame with kind `command`, carrying a JWT
+ServerKit Cloud signed with its Ed25519 command key. Before anything runs, this module
+checks four things, in this order and with no shortcuts:
+
+1. **Signature.** Against the JWKS the panel already trusts for the release
+ feed. An unsigned or wrongly signed command is not a command.
+2. **Audience.** The `device_id` claim is this panel and nobody else, so a
+ command minted for another server cannot be replayed here.
+3. **Freshness and replay.** `exp` must be in the future and the `nonce` must
+ be one we have not seen. A command runs at most once.
+4. **Scope.** The action's consent scope must be in the JWT's signed `scopes`
+ claim. ServerKit Cloud checks the customer's grant before it signs; this is the
+ second check, on the machine that would do the work.
+
+Only then is the action looked up in HANDLERS. An action this client version
+does not implement fails with that sentence rather than silently succeeding —
+the operator sees "this server's ServerKit is too old for that" in Cloud,
+which is true and actionable.
+
+Results go back as a `command_result` ingest frame: one `running` ack as work
+starts, one terminal frame with the outcome.
+"""
+import logging
+import threading
+import time
+
+logger = logging.getLogger(__name__)
+
+# How long a nonce is remembered. ServerKit Cloud's commands live an hour by default, so
+# an hour and a half covers every command that could still be valid.
+NONCE_TTL_S = 5400
+# A handler that has not finished by then is abandoned and reported failed;
+# ServerKit Cloud gives up at the command's own timeout anyway.
+DEFAULT_TIMEOUT_S = 600
+
+# action -> the consent scope that must be granted for it (ServerKit Cloud's
+# backend/commands.py ACTION_SCOPES; the storage actions share one consent).
+ACTION_SCOPES = {
+ 'storage.assign': 'storage.manage',
+ 'storage.unassign': 'storage.manage',
+ 'storage.test': 'storage.manage',
+ 'storage.report': 'storage.manage',
+}
+
+
+def scope_for(action: str) -> str:
+ return ACTION_SCOPES.get(action, action)
+
+
+class CommandRejected(Exception):
+ """The command never ran and never will. Carries the sentence Cloud shows."""
+
+
+class _Nonces:
+ """Seen nonces with an expiry. Small, in-process, and rebuilt on restart —
+ a restart cannot replay a command because `exp` still has to hold."""
+
+ def __init__(self):
+ self._seen = {}
+ self._lock = threading.Lock()
+
+ def check_and_add(self, nonce: str, now: float = None) -> bool:
+ now = now if now is not None else time.time()
+ with self._lock:
+ for key, at in list(self._seen.items()):
+ if now - at > NONCE_TTL_S:
+ self._seen.pop(key, None)
+ if nonce in self._seen:
+ return False
+ self._seen[nonce] = now
+ return True
+
+
+NONCES = _Nonces()
+
+
+# ==================== verification ====================
+
+
+def verify(token: str, jwks: dict, device_id: str, granted_scopes=None,
+ now: float = None) -> dict:
+ """Return the command claims, or raise CommandRejected with the reason."""
+ import base64
+
+ import jwt
+ from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+ if not token:
+ raise CommandRejected('The command carried no signature.')
+ if not jwks or not (jwks.get('keys') or []):
+ raise CommandRejected('This panel could not read ServerKit Cloud\'s signing keys, '
+ 'so it did not run the command.')
+ try:
+ header = jwt.get_unverified_header(token)
+ key = next((k for k in jwks['keys'] if k.get('kid') == header.get('kid')), None)
+ if key is None or key.get('crv') != 'Ed25519':
+ raise CommandRejected('The command was signed with a key this panel does not trust.')
+ raw = base64.urlsafe_b64decode(key['x'] + '=' * (-len(key['x']) % 4))
+ claims = jwt.decode(token, Ed25519PublicKey.from_public_bytes(raw),
+ algorithms=['EdDSA'], options={'verify_exp': False})
+ except CommandRejected:
+ raise
+ except Exception as exc:
+ raise CommandRejected(f'The command signature did not verify ({exc}).')
+
+ if claims.get('device_id') != device_id:
+ raise CommandRejected('The command was addressed to a different server.')
+
+ now = now if now is not None else time.time()
+ exp = claims.get('exp')
+ if not exp or float(exp) < now:
+ raise CommandRejected('The command had already expired when it arrived.')
+
+ nonce = claims.get('nonce')
+ if not nonce or not NONCES.check_and_add(nonce, now):
+ raise CommandRejected('This command has already been run once.')
+
+ action = claims.get('action') or ''
+ needed = scope_for(action)
+ signed = claims.get('scopes') or []
+ if needed not in signed:
+ raise CommandRejected(f'The command did not carry the {needed!r} consent scope.')
+ if granted_scopes is not None and needed not in granted_scopes:
+ raise CommandRejected(f'{needed!r} is not granted on this panel. Grant it in ServerKit '
+ f'Cloud and nothing needs to be re-paired.')
+ return claims
+
+
+# ==================== the handler registry ====================
+
+HANDLERS = {}
+
+
+def handler(action: str):
+ def register(fn):
+ HANDLERS[action] = fn
+ return fn
+ return register
+
+
+def run(claims: dict, app=None) -> dict:
+ """Execute one verified command. Returns {ok, summary, code, output}.
+
+ A handler that raises is a failure with its own words, never a crash that
+ leaves Cloud waiting for a result that never comes.
+ """
+ action = claims.get('action') or ''
+ fn = HANDLERS.get(action)
+ if fn is None:
+ return {'ok': False, 'code': 501,
+ 'summary': f'This server\'s ServerKit does not know how to run {action}. '
+ f'Update it and try again.'}
+ try:
+ out = fn(claims.get('args') or {}, app)
+ except Exception as exc:
+ logger.warning('Connect command %s failed: %s', action, exc, exc_info=True)
+ return {'ok': False, 'code': 500, 'summary': f'{type(exc).__name__}: {exc}'}
+ if not isinstance(out, dict):
+ return {'ok': True, 'code': 0, 'summary': str(out)[:2000] if out else None}
+ return {
+ 'ok': bool(out.get('ok', True)),
+ 'code': out.get('code', 0 if out.get('ok', True) else 1),
+ 'summary': (str(out['summary'])[:2000] if out.get('summary') else None),
+ 'output': out.get('output'),
+ }
+
+
+def result_frame(cmd_id: str, state: str, result: dict = None, stream: str = None) -> dict:
+ """The command_result ingest frame the relay forwards to ServerKit Cloud."""
+ payload = {'cmd_id': cmd_id, 'state': state}
+ if result:
+ payload['result_code'] = result.get('code')
+ payload['result_summary'] = result.get('summary')
+ if result.get('output'):
+ payload['output'] = result['output']
+ return {'s': stream or f'res_{cmd_id}', 't': 'open', 'k': 'command_result', 'p': payload}
+
+
+# Importing the handler modules is what registers them. Kept at the bottom so
+# a handler module may import this one for @handler.
+from app.services import connect_storage # noqa: E402,F401
diff --git a/backend/app/services/connect_storage.py b/backend/app/services/connect_storage.py
new file mode 100644
index 00000000..0b28c6aa
--- /dev/null
+++ b/backend/app/services/connect_storage.py
@@ -0,0 +1,246 @@
+"""The Storage Hub on the panel side.
+
+ServerKit Cloud holds one set of object-storage credentials and hands each
+server its own prefix in the bucket. This module is the whole panel half of
+that: four command handlers, and the snapshot the panel sends back on the
+`storage` stream.
+
+What it deliberately does not do is re-implement anything. The destination
+lands in `storage.json` through `StorageProviderService.save_config`, which
+every upload, list and verify path in the panel already reads — including
+`path_prefix`, which those paths have always honoured. Cloud is therefore
+just another way of filling in the form on Backups > Storage, and a backup
+run does not know or care which one was used.
+
+While a destination is managed by Cloud, `managed_by_cloud` is set in
+storage.json and the local form is read-only: two places writing the same
+config would race, and the operator should be told where it is coming from
+rather than watching their edit disappear.
+"""
+import logging
+from datetime import datetime, timezone
+
+from app.services.connect_commands import handler
+from app.services.storage_provider_service import StorageProviderService
+
+logger = logging.getLogger(__name__)
+
+# ServerKit Cloud sends an S3 shape whatever the provider is (B2 through its
+# S3-compatible endpoint, R2, Wasabi and the rest), so the panel keeps one
+# client and writes one provider block.
+PANEL_PROVIDER = 's3'
+
+
+def _iso(value):
+ if value is None:
+ return None
+ if isinstance(value, str):
+ return value
+ if isinstance(value, datetime):
+ if value.tzinfo is None:
+ value = value.replace(tzinfo=timezone.utc)
+ return value.isoformat()
+ return None
+
+
+# ==================== commands ====================
+
+
+@handler('storage.assign')
+def assign(args: dict, app=None) -> dict:
+ """Write the destination Cloud sent, then prove it works before saying so.
+
+ The reply is what flips the assignment to `ok` in Cloud, so it must be the
+ result of a real `test_connection` and not the fact that a file was
+ written.
+ """
+ if args.get('error') == 'connection_gone':
+ return {'ok': False, 'summary': 'ServerKit Cloud no longer has that storage connection, '
+ 'so nothing was changed here.'}
+ missing = [k for k in ('bucket', 'key_id', 'secret', 'prefix') if not args.get(k)]
+ if missing:
+ return {'ok': False, 'summary': f'The destination was incomplete: no {", ".join(missing)}.'}
+
+ previous = StorageProviderService.get_config()
+ # Merge, never replace: auto_upload, keep_local_copy and everything else
+ # the operator set on this panel is theirs and stays.
+ config = dict(previous)
+ config.update({
+ 'provider': PANEL_PROVIDER,
+ 'managed_by_cloud': True,
+ 'managed_prefix': args['prefix'],
+ 's3': {
+ 'bucket': args['bucket'],
+ 'region': args.get('region') or 'auto',
+ 'endpoint_url': args.get('endpoint') or '',
+ 'access_key': args['key_id'],
+ 'secret_key': args['secret'],
+ 'path_prefix': args['prefix'].rstrip('/'),
+ },
+ })
+
+ test = StorageProviderService.test_connection(config)
+ if not test.get('success'):
+ # Nothing is saved: a destination the panel cannot reach would stop
+ # the next offsite copy without anybody being told why.
+ return {'ok': False,
+ 'summary': test.get('error') or 'The panel could not reach that destination.'}
+
+ StorageProviderService.save_config(config)
+ logger.info('Connect storage: destination set by ServerKit Cloud (%s/%s)',
+ args['bucket'], args['prefix'])
+ return {'ok': True,
+ 'summary': f'Writing offsite backups to {args["bucket"]}/{args["prefix"]}',
+ 'output': _previous_note(previous)}
+
+
+def _previous_note(previous: dict) -> str | None:
+ """What the destination used to be, for the command's stored output. The
+ operator can see what Cloud replaced without us keeping a second copy of
+ the old credentials anywhere."""
+ if not previous or previous.get('provider') in (None, 'local'):
+ return 'Previous destination: local only.'
+ block = previous.get(previous.get('provider'), {}) or {}
+ bucket = block.get('bucket')
+ return f'Previous destination: {previous.get("provider")}:{bucket or "unnamed bucket"}.'
+
+
+@handler('storage.unassign')
+def unassign(args: dict, app=None) -> dict:
+ """Hand the destination back to this panel.
+
+ Backups keep running; the offsite copy stops. Nothing in the bucket is
+ touched — deleting a customer's objects is not something a command from
+ Cloud is allowed to do.
+ """
+ config = StorageProviderService.get_config()
+ if not config.get('managed_by_cloud'):
+ return {'ok': True, 'summary': 'This panel\'s storage was not managed by Cloud; '
+ 'nothing was changed.'}
+ # The credential came from Cloud and the operator never typed it, so it
+ # goes with the assignment. Their own settings stay.
+ config = {k: v for k, v in config.items() if k != PANEL_PROVIDER}
+ config.update({'provider': 'local', 'managed_by_cloud': False, 'managed_prefix': None})
+ StorageProviderService.save_config(config)
+ logger.info('Connect storage: destination handed back to this panel')
+ return {'ok': True, 'summary': 'Backups are local-only again. Nothing in the bucket was '
+ 'deleted; set a destination here to start copying offsite.'}
+
+
+@handler('storage.test')
+def test(args: dict, app=None) -> dict:
+ result = StorageProviderService.test_connection()
+ if result.get('success'):
+ return {'ok': True, 'summary': result.get('message') or 'Destination reachable.'}
+ return {'ok': False, 'summary': result.get('error') or 'The destination could not be reached.'}
+
+
+@handler('storage.report')
+def report(args: dict, app=None) -> dict:
+ """Send a snapshot now. The frame itself goes out through the relay client;
+ here we only prove we can build one."""
+ snapshot = build_status(app)
+ if snapshot is None:
+ return {'ok': False, 'summary': 'This panel has no storage status to report yet.'}
+ client = _relay_client()
+ if client is None or not client.publish_storage(snapshot):
+ return {'ok': False, 'summary': 'The panel is not connected to the relay right now, '
+ 'so the snapshot could not be sent. It goes out on the '
+ 'next connection.'}
+ return {'ok': True, 'summary': 'Storage status sent.'}
+
+
+def _relay_client():
+ try:
+ from app.services import connect_client
+ return connect_client.get_client()
+ except Exception:
+ return None
+
+
+# ==================== the storage stream ====================
+
+
+def build_status(app=None) -> dict | None:
+ """One snapshot of where this panel's backups go and how they went.
+
+ Every field is something the panel actually knows. Anything it cannot
+ read is left out rather than sent as a zero: "0 bytes stored" and "we
+ could not list the bucket" are different answers.
+ """
+ config = StorageProviderService.get_config()
+ provider = config.get('provider') or 'local'
+ block = config.get(provider, {}) if provider != 'local' else {}
+ prefix = config.get('managed_prefix') or block.get('path_prefix') or None
+ bucket = block.get('bucket')
+
+ payload = {
+ 'type': 'status',
+ 'destination': f'{bucket}/{prefix}' if bucket else None,
+ 'prefix': f'{prefix.rstrip("/")}/' if prefix else None,
+ 'managed_by_cloud': bool(config.get('managed_by_cloud')),
+ }
+
+ if provider != 'local':
+ try:
+ stats = StorageProviderService.get_remote_stats()
+ payload['remote_bytes'] = stats.get('remote_size')
+ payload['remote_objects'] = stats.get('remote_count')
+ except Exception as exc:
+ payload['error'] = f'Could not list the destination: {exc}'
+
+ policies, last_run, last_ok = _policy_rows(app)
+ if policies is not None:
+ payload['policies'] = policies
+ payload['last_backup_at'] = _iso(last_run)
+ payload['last_backup_ok'] = last_ok
+ return payload
+
+
+def _policy_rows(app=None):
+ """(rows, newest run time, whether it succeeded) from the panel's own
+ backup policies. Returns (None, None, None) when there is no app context
+ to read them in — the snapshot still carries the destination."""
+ try:
+ from app.models.backup_policy import BackupPolicy
+ except Exception:
+ return None, None, None
+
+ def collect():
+ rows = []
+ newest = None
+ newest_ok = None
+ for p in BackupPolicy.query.all():
+ rows.append({
+ 'name': f'{p.target_type}:{p.target_id}',
+ 'last_run_at': _iso(p.last_run_at),
+ 'status': p.last_status,
+ 'size': int(p.last_size) if p.last_size is not None else None,
+ 'remote_copy': bool(p.remote_copy),
+ })
+ if p.last_run_at is not None and (newest is None or p.last_run_at > newest):
+ newest = p.last_run_at
+ newest_ok = (p.last_status == 'success')
+ return rows, newest, newest_ok
+
+ try:
+ if app is not None:
+ with app.app_context():
+ return collect()
+ return collect()
+ except Exception as exc:
+ logger.debug('Connect storage: could not read backup policies (%s)', exc)
+ return None, None, None
+
+
+def status_frame(stream_id: str, snapshot: dict) -> dict:
+ return {'s': stream_id, 't': 'open', 'k': 'storage', 'p': snapshot}
+
+
+def is_managed_by_cloud() -> bool:
+ """True while ServerKit Cloud owns this panel's backup destination. The
+ local Backups > Storage form reads this and goes read-only."""
+ try:
+ return bool(StorageProviderService.get_config().get('managed_by_cloud'))
+ except Exception:
+ return False
diff --git a/backend/tests/test_connect_storage.py b/backend/tests/test_connect_storage.py
new file mode 100644
index 00000000..2a01bb30
--- /dev/null
+++ b/backend/tests/test_connect_storage.py
@@ -0,0 +1,279 @@
+"""The panel half of the Storage Hub and the signed-command
+runner it rides on. No network: commands are signed with a real
+Ed25519 key and verified against a JWKS built from it, and the S3 client is
+replaced by the test.
+"""
+import base64
+import json
+import time
+
+import jwt
+import pytest
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from app.services import connect_commands, connect_storage
+from app.services.storage_provider_service import StorageProviderService
+
+DEVICE = 'dev_abc123'
+
+
+def signer():
+ """(sign(claims) -> token, jwks) for a throwaway command key."""
+ key = Ed25519PrivateKey.generate()
+ raw = key.public_key().public_bytes_raw()
+ jwks = {'keys': [{'kty': 'OKP', 'crv': 'Ed25519', 'kid': 'k1',
+ 'x': base64.urlsafe_b64encode(raw).decode().rstrip('=')}]}
+ pem = key.private_bytes_raw()
+
+ from cryptography.hazmat.primitives import serialization
+ private_pem = key.private_bytes(
+ encoding=serialization.Encoding.PEM,
+ format=serialization.PrivateFormat.PKCS8,
+ encryption_algorithm=serialization.NoEncryption(),
+ )
+ assert pem # the raw form is what ServerKit Cloud stores; the PEM is what PyJWT signs with
+
+ def sign(**claims):
+ body = {'cmd_id': 'cmd_1', 'device_id': DEVICE, 'action': 'storage.test',
+ 'args': {}, 'scopes': ['storage.manage'], 'nonce': f'n{time.time_ns()}',
+ 'iat': int(time.time()), 'exp': int(time.time()) + 600}
+ body.update(claims)
+ return jwt.encode(body, private_pem, algorithm='EdDSA', headers={'kid': 'k1'})
+
+ return sign, jwks
+
+
[email protected](autouse=True)
+def storage_file(tmp_path, monkeypatch):
+ """storage.json in a temp dir; every test starts with no destination."""
+ monkeypatch.setattr(StorageProviderService, 'CONFIG_FILE',
+ str(tmp_path / 'storage.json'))
+ connect_commands.NONCES._seen.clear()
+ return tmp_path
+
+
+# ---------- verification ----------
+
+
+def test_a_valid_command_verifies(signer):
+ sign, jwks = signer
+ claims = connect_commands.verify(sign(), jwks, DEVICE)
+ assert claims['action'] == 'storage.test'
+
+
+def test_a_command_for_another_server_is_refused(signer):
+ sign, jwks = signer
+ with pytest.raises(connect_commands.CommandRejected) as e:
+ connect_commands.verify(sign(device_id='dev_someone_else'), jwks, DEVICE)
+ assert 'different server' in str(e.value)
+
+
+def test_an_expired_command_is_refused(signer):
+ sign, jwks = signer
+ with pytest.raises(connect_commands.CommandRejected) as e:
+ connect_commands.verify(sign(exp=int(time.time()) - 5), jwks, DEVICE)
+ assert 'expired' in str(e.value)
+
+
+def test_a_command_runs_at_most_once(signer):
+ sign, jwks = signer
+ token = sign()
+ connect_commands.verify(token, jwks, DEVICE)
+ with pytest.raises(connect_commands.CommandRejected) as e:
+ connect_commands.verify(token, jwks, DEVICE)
+ assert 'already been run' in str(e.value)
+
+
+def test_a_command_signed_by_a_stranger_is_refused(signer):
+ _, jwks = signer
+ other = Ed25519PrivateKey.generate()
+ from cryptography.hazmat.primitives import serialization
+ pem = other.private_bytes(encoding=serialization.Encoding.PEM,
+ format=serialization.PrivateFormat.PKCS8,
+ encryption_algorithm=serialization.NoEncryption())
+ token = jwt.encode({'cmd_id': 'c', 'device_id': DEVICE, 'action': 'storage.test',
+ 'scopes': ['storage.manage'], 'nonce': 'n1',
+ 'exp': int(time.time()) + 60},
+ pem, algorithm='EdDSA', headers={'kid': 'k1'})
+ with pytest.raises(connect_commands.CommandRejected) as e:
+ connect_commands.verify(token, jwks, DEVICE)
+ assert 'did not verify' in str(e.value)
+
+
+def test_a_command_without_its_consent_scope_is_refused(signer):
+ sign, jwks = signer
+ with pytest.raises(connect_commands.CommandRejected) as e:
+ connect_commands.verify(sign(scopes=['metrics.read']), jwks, DEVICE)
+ assert 'storage.manage' in str(e.value)
+
+
+def test_with_no_jwks_nothing_runs(signer):
+ sign, _ = signer
+ with pytest.raises(connect_commands.CommandRejected) as e:
+ connect_commands.verify(sign(), None, DEVICE)
+ assert 'signing keys' in str(e.value)
+
+
+def test_an_unknown_action_fails_with_a_sentence_the_operator_can_act_on():
+ out = connect_commands.run({'action': 'policy.apply', 'args': {}})
+ assert out['ok'] is False
+ assert 'does not know how to run policy.apply' in out['summary']
+
+
+def test_a_handler_that_raises_becomes_a_failed_result():
+ @connect_commands.handler('test.explode')
+ def _boom(args, app=None):
+ raise RuntimeError('disk on fire')
+ try:
+ out = connect_commands.run({'action': 'test.explode', 'args': {}})
+ assert out['ok'] is False
+ assert 'disk on fire' in out['summary']
+ finally:
+ connect_commands.HANDLERS.pop('test.explode', None)
+
+
+# ---------- storage.assign ----------
+
+
+def _cloud_args(prefix='serverkit/dev_abc123/'):
+ return {'bucket': 'sk-backups', 'region': 'auto', 'endpoint': 'https://acct.example.com',
+ 'key_id': 'AKIA', 'secret': 'shh', 'prefix': prefix, 'provider': 'r2'}
+
+
+def test_assign_writes_the_destination_only_after_the_test_passes(monkeypatch):
+ monkeypatch.setattr(StorageProviderService, 'test_connection',
+ classmethod(lambda cls, config=None: {'success': True, 'message': 'ok'}))
+ out = connect_storage.assign(_cloud_args())
+ assert out['ok'] is True
+ config = StorageProviderService.get_config()
+ assert config['provider'] == 's3'
+ assert config['managed_by_cloud'] is True
+ assert config['s3']['bucket'] == 'sk-backups'
+ assert config['s3']['path_prefix'] == 'serverkit/dev_abc123'
+
+
+def test_a_destination_the_panel_cannot_reach_is_not_saved(monkeypatch):
+ monkeypatch.setattr(StorageProviderService, 'test_connection',
+ classmethod(lambda cls, config=None: {'success': False,
+ 'error': 'AccessDenied'}))
+ out = connect_storage.assign(_cloud_args())
+ assert out['ok'] is False
+ assert 'AccessDenied' in out['summary']
+ assert StorageProviderService.get_config().get('managed_by_cloud') is not True
+
+
+def test_assign_keeps_the_operators_own_settings(monkeypatch):
+ StorageProviderService.save_config({'provider': 'local', 'auto_upload': True,
+ 'keep_local_copy': False})
+ monkeypatch.setattr(StorageProviderService, 'test_connection',
+ classmethod(lambda cls, config=None: {'success': True}))
+ connect_storage.assign(_cloud_args())
+ config = StorageProviderService.get_config()
+ assert config['auto_upload'] is True
+ assert config['keep_local_copy'] is False
+
+
+def test_an_incomplete_destination_is_refused_with_what_is_missing():
+ args = _cloud_args()
+ del args['secret']
+ out = connect_storage.assign(args)
+ assert out['ok'] is False
+ assert 'secret' in out['summary']
+
+
+def test_a_deleted_cloud_connection_changes_nothing_here():
+ out = connect_storage.assign({'error': 'connection_gone'})
+ assert out['ok'] is False
+ assert StorageProviderService.get_config().get('managed_by_cloud') is not True
+
+
+# ---------- storage.unassign ----------
+
+
+def test_unassign_hands_the_destination_back_and_drops_the_cloud_credential(monkeypatch):
+ monkeypatch.setattr(StorageProviderService, 'test_connection',
+ classmethod(lambda cls, config=None: {'success': True}))
+ connect_storage.assign(_cloud_args())
+ out = connect_storage.unassign({})
+ assert out['ok'] is True
+ config = StorageProviderService.get_config()
+ assert config['provider'] == 'local'
+ assert not config.get('managed_by_cloud')
+ assert 's3' not in config
+ assert 'deleted' in out['summary']
+
+
+def test_unassigning_something_we_never_managed_changes_nothing():
+ StorageProviderService.save_config({'provider': 's3', 's3': {'bucket': 'mine'}})
+ out = connect_storage.unassign({})
+ assert out['ok'] is True
+ assert StorageProviderService.get_config()['s3']['bucket'] == 'mine'
+
+
+# ---------- the status snapshot ----------
+
+
+def test_the_snapshot_carries_the_destination_and_what_is_stored(monkeypatch):
+ monkeypatch.setattr(StorageProviderService, 'test_connection',
+ classmethod(lambda cls, config=None: {'success': True}))
+ monkeypatch.setattr(StorageProviderService, 'get_remote_stats',
+ classmethod(lambda cls: {'remote_size': 4096, 'remote_count': 7}))
+ connect_storage.assign(_cloud_args())
+ snap = connect_storage.build_status()
+ assert snap['type'] == 'status'
+ assert snap['destination'] == 'sk-backups/serverkit/dev_abc123/'
+ assert snap['prefix'] == 'serverkit/dev_abc123/'
+ assert snap['remote_bytes'] == 4096
+ assert snap['remote_objects'] == 7
+ assert snap['managed_by_cloud'] is True
+
+
+def test_a_destination_that_cannot_be_listed_says_so_rather_than_reporting_zero(monkeypatch):
+ monkeypatch.setattr(StorageProviderService, 'test_connection',
+ classmethod(lambda cls, config=None: {'success': True}))
+
+ def boom(cls):
+ raise RuntimeError('NoSuchBucket')
+ monkeypatch.setattr(StorageProviderService, 'get_remote_stats', classmethod(boom))
+ connect_storage.assign(_cloud_args())
+ snap = connect_storage.build_status()
+ assert 'remote_bytes' not in snap
+ assert 'NoSuchBucket' in snap['error']
+
+
+def test_a_local_only_panel_still_reports():
+ snap = connect_storage.build_status()
+ assert snap['type'] == 'status'
+ assert snap['destination'] is None
+ assert snap['managed_by_cloud'] is False
+
+
+def test_the_status_frame_is_the_storage_stream():
+ frame = connect_storage.status_frame('sto1', {'type': 'status'})
+ assert frame == {'s': 'sto1', 't': 'open', 'k': 'storage', 'p': {'type': 'status'}}
+
+
+def test_is_managed_by_cloud_tracks_the_config(monkeypatch):
+ assert connect_storage.is_managed_by_cloud() is False
+ monkeypatch.setattr(StorageProviderService, 'test_connection',
+ classmethod(lambda cls, config=None: {'success': True}))
+ connect_storage.assign(_cloud_args())
+ assert connect_storage.is_managed_by_cloud() is True
+
+
+# ---------- result frames ----------
+
+
+def test_the_result_frame_is_what_cloud_ingests():
+ frame = connect_commands.result_frame('cmd_9', 'succeeded',
+ {'ok': True, 'code': 0, 'summary': 'done'})
+ assert frame['k'] == 'command_result'
+ assert frame['p'] == {'cmd_id': 'cmd_9', 'state': 'succeeded',
+ 'result_code': 0, 'result_summary': 'done'}
+
+
+def test_the_running_ack_carries_no_result():
+ frame = connect_commands.result_frame('cmd_9', 'running')
+ assert frame['p'] == {'cmd_id': 'cmd_9', 'state': 'running'}
+ assert json.dumps(frame)
diff --git a/frontend/src/pages/Backups.jsx b/frontend/src/pages/Backups.jsx
index 33d43d42..3a6ed989 100644
--- a/frontend/src/pages/Backups.jsx
+++ b/frontend/src/pages/Backups.jsx
@@ -883,6 +883,21 @@ const Backups = () => {
<h3>{t('app.backups.configureDestination', 'Configure destination')}</h3>
</div>
<div className="card-body">
+ {/* While ServerKit Cloud owns this
+ destination the form here is read-only, and says
+ where the setting comes from and how to take it
+ back. Backups keep running either way. */}
+ {storageConfig?.managed_by_cloud && (
+ <div className="alert alert-info" role="status">
+ <i className="ph ph-cloud" />
+ <span>
+ {storageConfig.managed_note
+ || t('app.backups.storageManagedByCloud',
+ 'This destination is managed by ServerKit Cloud. Change it under Backups in Cloud, or unassign it there to edit it here.')}
+ </span>
+ </div>
+ )}
+ <fieldset disabled={!!storageConfig?.managed_by_cloud} className="bk-storage-fieldset">
<form onSubmit={handleSaveStorageConfig}>
<FormField label={t('app.backups.storageProvider', 'Storage Provider')} hint={t('app.backups.s3CompatibleWorksWithAwsS3', 'S3-Compatible works with AWS S3, MinIO and Wasabi.')}>
<SegControl
@@ -1065,6 +1080,7 @@ const Backups = () => {
)}
</div>
</form>
+ </fieldset>
</div>
</div>
</>
diff --git a/frontend/src/styles/pages/_backups.scss b/frontend/src/styles/pages/_backups.scss
index 48cbbd4c..8fbe6ddf 100644
--- a/frontend/src/styles/pages/_backups.scss
+++ b/frontend/src/styles/pages/_backups.scss
@@ -1160,3 +1160,16 @@
border-radius: $radius-lg;
padding: $space-4;
}
+
+/* A destination ServerKit Cloud manages is read-only here.
+ The fieldset is the disable mechanism; it must not look like a box. */
+.bk-storage-fieldset {
+ border: 0;
+ padding: 0;
+ margin: 0;
+ min-width: 0;
+}
+
+.bk-storage-fieldset:disabled {
+ opacity: 0.65;
+}