[cockpit] Add SSH-key onboarding step before VM-request UI (D-23) #4

New issue

Open

opened 2026-05-22 15:20:40 +00:00 by mik-tf · 0 comments

mik-tf commented

2026-05-22 15:20:40 +00:00

Owner

Context

Workspace decision D-23 locks: end-users own their SSH keys via forge.ourworld.tf themselves; deployer reads them at provision time and forwards openssh strings to ComputeService.deploy_vm (Track D D4 landed at s142). The deployer's provision_vm RPC errors with a clear -32602 + actionable URL if the user has zero SSH keys uploaded:

user 'alice' has no SSH keys uploaded to forge.ourworld.tf. Add at least one at https://forge.ourworld.tf/user/settings/keys before requesting a VM (D-23 — deployer never holds private keys).

That error message is the safety net. For onboarding UX, cockpit should catch this before the user clicks "Provision VM" rather than after.

Suggested scope

One-screen "Your SSH key" page in the cockpit onboarding flow, between "Set your Forge token" (already shipped per D-16) and "Request your VM":

Call the new ForgeClient::list_user_ssh_keys(username) (admin scope, deployer-side proxy, OR use the user's own cockpit/USER_FORGE_TOKEN against GET /user/keys) to check whether the user already has at least one pubkey.
If yes → green checkmark + key fingerprint(s) shown + "Continue to VM request" button.
If no → instructional copy + a clear "Add an SSH key on forge.ourworld.tf →" CTA opening https://forge.ourworld.tf/user/settings/keys in a new tab (Forgejo's XFO blocks iframe, same L-08 pattern we saw at s136).
On return → re-check + advance.

Why now

The D-23 alt-2 design assumes the user is competent with SSH and already has a key — true for ~99% of dev-targeted Hero OS users. The 1% bounce on the deployer error message; this onboarding gate would catch them ~30s earlier with friendlier copy + a direct link.

Not in scope:

Don't generate SSH keypairs client-side (web-crypto handling for private keys is v2+).
Don't store any private key in cockpit (D-23 lock).

D-23 — SSH key custody decision (workspace; deployer never holds private keys)
D-16 — cockpit BYO token landing (precedent for "Set on Forge, paste in cockpit" flow)
L-08 — cockpit /feedback iframe blocked by Forge XFO (same XFO constraint applies to /user/settings/keys; new-tab CTA is the supported path)
lhumina_code/home#235 — Track D demo-deployer arc

Not blocking. Filing for onboarding polish ahead of F1 (first deployer-provisioned VM with a real user).

— mik-tf

## Context Workspace decision [D-23](https://forge.ourworld.tf/lhumina_code/home/issues/235) locks: end-users own their SSH keys via forge.ourworld.tf themselves; deployer reads them at provision time and forwards openssh strings to `ComputeService.deploy_vm` (Track D D4 landed at s142). The deployer's `provision_vm` RPC errors with a clear -32602 + actionable URL if the user has zero SSH keys uploaded: > user 'alice' has no SSH keys uploaded to forge.ourworld.tf. Add at least one at https://forge.ourworld.tf/user/settings/keys before requesting a VM (D-23 — deployer never holds private keys). That error message is the safety net. For onboarding UX, cockpit should catch this before the user clicks "Provision VM" rather than after. ## Suggested scope One-screen "Your SSH key" page in the cockpit onboarding flow, between "Set your Forge token" (already shipped per D-16) and "Request your VM": 1. Call the new `ForgeClient::list_user_ssh_keys(username)` (admin scope, deployer-side proxy, OR use the user's own `cockpit/USER_FORGE_TOKEN` against `GET /user/keys`) to check whether the user already has at least one pubkey. 2. If yes → green checkmark + key fingerprint(s) shown + "Continue to VM request" button. 3. If no → instructional copy + a clear "Add an SSH key on forge.ourworld.tf →" CTA opening `https://forge.ourworld.tf/user/settings/keys` in a new tab (Forgejo's XFO blocks iframe, same L-08 pattern we saw at s136). 4. On return → re-check + advance. ## Why now The D-23 alt-2 design assumes the user is competent with SSH and already has a key — true for ~99% of dev-targeted Hero OS users. The 1% bounce on the deployer error message; this onboarding gate would catch them ~30s earlier with friendlier copy + a direct link. Not in scope: - Don't generate SSH keypairs client-side (web-crypto handling for private keys is v2+). - Don't store any private key in cockpit (D-23 lock). ## Related - D-23 — SSH key custody decision (workspace; deployer never holds private keys) - D-16 — cockpit BYO token landing (precedent for "Set on Forge, paste in cockpit" flow) - L-08 — cockpit /feedback iframe blocked by Forge XFO (same XFO constraint applies to /user/settings/keys; new-tab CTA is the supported path) - https://forge.ourworld.tf/lhumina_code/home/issues/235 — Track D demo-deployer arc Not blocking. Filing for onboarding polish ahead of F1 (first deployer-provisioned VM with a real user). — mik-tf