feature(ssh-tunnel): backend service and client API routes (Part 3 / Steps 1-3 + 4a)

[CodeLieutenant]

Context

This PR implements Part 3 of the SSH Tunnel design (docs/plans/ssh-tunnel-design.md) — the server-side foundation that must be in place before any client-side work (Steps 5/6) or proxy-host provisioning (Steps 4c/7b) can be tested end-to-end.

The goal of this stage: a client can POST a public key to Argus and receive proxy tunnel connection details in return; the proxy host can GET all valid public keys at any time via AuthorizedKeysCommand.

---

What's in this PR

Step 1 + 2 — DB models (argus/backend/models/ssh_key.py)

Two new CQLEngine models added to USED_MODELS (auto-created by sync_models/test startup, no manual CQL migration needed):

SSHTunnelKey
Stores a client-registered public key scoped to a (user_id, tunnel_id) pair.

• Inserted with a ScyllaDB TTL (default 24 h, overridable via ttl_seconds). Expired rows are auto-deleted — no cleanup job needed.
• expires_at is stored as an informational timestamp so clients know when to re-register.
• fingerprint is computed server-side (SHA256 of raw key bytes, SHA256:<base64> format) — the private key never touches the server.

ProxyTunnelConfig
Stores the connection details of an SSH proxy tunnel server (host, port, proxy_user, target_host, target_port, host_key_fingerprint, service_user_id, is_active).
Only one config has is_active=True at a time.

---

Step 3 — Backend service (argus/backend/service/tunnel_service.py)

TunnelService with the following methods:

Method	Purpose
register_tunnel(user, public_key, tunnel_id?, ttl_seconds?)	Validate + fingerprint key, store SSHTunnelKey with TTL, return proxy connection dict + expires_at
get_authorized_keys(tunnel_id?)	Return all non-expired keys as OpenSSH authorized_keys text — called by proxy host via AuthorizedKeysCommand
list_keys(tunnel_id?)	Key inventory (used by admin panel in a later PR)
delete_key(key_id)	Immediate revocation
get_proxy_tunnel_config(tunnel_id?)	Read active or specific config
save_proxy_tunnel_config(payload)	Create new config, deactivate the old active one, create a dedicated service user (proxy-tunnel-<host>) with a fresh API token for the proxy host

TunnelServiceException covers all expected business errors (no active config, invalid key, missing fields, not found).

---

Step 4a — Client API routes (argus/backend/controller/ssh_api.py)

New ssh_api Blueprint registered as a sub-blueprint of client_api → final URLs under /api/v1/client/ssh/:

POST /api/v1/client/ssh/tunnel    @api_login_required

Register a public key, receive proxy connection details.
Request body: { "public_key": "ssh-ed25519 ...", "ttl_seconds": 86400, "tunnel_id": "<uuid>" }
Response: { "status": "ok", "response": { "key_id", "tunnel_id", "proxy_host", "proxy_port", "proxy_user", "target_host", "target_port", "host_key_fingerprint", "expires_at" } }

GET /api/v1/client/ssh/keys    @api_login_required

Returns all non-expired public keys as text/plain (authorized_keys format, one key per line).
Optional query param: ?tunnel_id=<uuid> to scope to a specific proxy host.
Called by the proxy host's AuthorizedKeysCommand via argus-cli ssh-keys (Step 7b).

---

Tests (argus/backend/tests/tunnel/)

All tests are @pytest.mark.docker_required and use the shared ScyllaDB Docker fixture from conftest.py.

test_tunnel_service.py — 14 unit tests:

• register_tunnel: happy path, custom TTL, no active config raises, invalid key, missing key, explicit tunnel_id
• get_authorized_keys: OpenSSH format validation, tunnel scoping
• delete_key: row removed, nonexistent raises
• save_proxy_tunnel_config: service user created, old config deactivated, missing fields raises
• get_proxy_tunnel_config: returns active, by id, None when none active

test_ssh_api.py — 10 integration tests via Flask test client:

• POST /ssh/tunnel: success, ttl_seconds, explicit tunnel_id, missing key, invalid key, malformed UUID (400), unauthenticated (403)
• GET /ssh/keys: success + key in output, tunnel scoping, malformed UUID (400), unauthenticated (403), empty when no keys

---

No new dependencies

cryptography is already a transitive dependency via PyJWT[crypto].

---

How to test

# Run all tunnel tests (Docker required)
uv run pytest argus/backend/tests/tunnel/ -m docker_required -v

To exercise the API manually after the server is running:

# Register a key as a client:
curl -X POST http://localhost:5000/api/v1/client/ssh/tunnel \
  -H "Authorization: token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"public_key": "ssh-ed25519 AAAA..."}'

# Fetch authorized keys (as the proxy host would via AuthorizedKeysCommand):
curl http://localhost:5000/api/v1/client/ssh/keys \
  -H "Authorization: token <proxy_service_user_token>"

Note: a ProxyTunnelConfig row must exist with is_active=True before POST /ssh/tunnel will work. That can be inserted directly via a Python shell until Step 4b (admin API) lands.

---

What is NOT in this PR (follow-up)

Step	Description
4b	Admin API endpoints for proxy tunnel config + key management
4c	Proxy host provisioning Jinja template
4d	Admin Panel UI — ProxyTunnelManager.svelte
5/6	argus-client tunnel module + base.py integration
7/7b	CLI --use-tunnel flag + argus-cli ssh-keys command