jaap-jan
f86791e817
ForgetDeviceAsync stopped this machine unlocking without a passphrase and left
the server's row exactly where it was, so the account went on listing a device
nobody could account for. ADR 0007 recorded that as a deliberate gap needing an
endpoint. This is the endpoint, and the two things that turned up behind it.
DELETE /api/v1/me/devices/{id}. The device row is not the dangerous half: a
kind=device wrap is the user's identity bundle sealed to a key somebody may be
holding, and that is what has to go. It goes on the foreign key's cascade rather
than a second statement, and RevokeDevice_TakesItsWrapWithIt asserts the cascade
rather than trusting the configuration to keep saying so.
Scoped to the caller's own account, which is the only authorisation check there
is. The id is an unguessable v7 GUID, but unguessable is not a permission —
without the scope one user could withdraw another's device key by pasting an id
they saw once, and the victim's next launch would ask for a passphrase with no
explanation. 404 rather than 403 for somebody else's device, so a stranger does
not learn the id exists.
Never refused for being the last device. ADR 0001 makes an enrolled device a
recovery path, so removing the last one does cost the user something — but the
machine being revoked is most likely the one they have just lost, and a server
that argued about it would be refusing the one request that has to work
immediately. The passphrase wrap is untouched either way, which
RevokeDevice_LeavesThePassphraseWrapAlone pins.
--- Two things found on the way ---
Registering twice from one machine left two devices on the account. The server
is idempotent on the public key, but the client generates a fresh key pair every
call and the keystore holds one — so the second registration orphaned a wrap
whose private half had just been overwritten, which is precisely the leftover
this change exists to remove. Registering now withdraws the previous device.
Found by a test that asserted the property and failed.
And the fakes were lying about it. FakeAccountServer's comment claimed the real
service's idempotence while handing back a fresh Guid on every call, which is
invisible until something revokes by id — at which point a test would be
revoking an id the server never issued, and passing. Both fakes now issue one id
per public key and drop the wrap with the device, as the cascade does.
--- Reachable at all ---
ForgetDeviceAsync had exactly one caller and it was a test, so "Stop unlocking
here" now sits in the account bar where "Use Windows Hello here" was. Its own
flag rather than the negation of that one: a machine with no TPM and a machine
that is already registered are both "cannot register", and only the second has
anything to take back.
No confirmation prompt, deliberately. The cost of pressing it by accident is one
passphrase and one re-registration; the cost of a dialog is a moment's
hesitation at the point somebody has realised a machine is in the wrong hands.
Offline it does the local half and says so rather than refusing. Whether this
machine may unlock itself is decided entirely by the local cache and the local
keystore — the unlock path never asks the server — so forgetting here is what
actually revokes, and "you are offline, so this machine will go on unlocking
itself" would be the worst available answer. DeviceRevocation.LocalOnly is what
the interface reports and the status line explains what is left to do.
The local half runs first for the same reason, and the keystore call is the
first thing in the method that can yield: on Windows it raises a consent dialog,
and a dialog wants the thread it was called from. That ordering is currently
load-bearing and shakier than it looks — see the open device-unlock hang.
Four mutations, all caught: dropping the user scope from the server query
(1 test), skipping the stale-device revoke on re-registration (2), skipping the
server call in ForgetDeviceAsync (2), and the earlier version of the client that
never called it at all.
930 tests green across 16 projects, 13 of them new. Zero warnings, format clean.
DodoSSH
A self-hosted, team-oriented SSH client with an end-to-end encrypted vault.
Manage hosts, credentials and keys in a desktop app; sync them across your devices and share them with teammates through a server you run yourself. The server stores ciphertext and never holds a key — the operator cannot read the credentials it stores.
Status: early development. See the milestone plan for what exists today.
Why
Teams either scatter SSH credentials across individual ~/.ssh directories with no sharing
story, or pay per-seat for a hosted product that holds their infrastructure credentials.
DodoSSH keeps the convenience of a synced, shareable vault while remaining self-hostable and
zero-knowledge.
Architecture
| Component | Choice |
|---|---|
| Backend | ASP.NET Core on .NET 10, PostgreSQL + EF Core |
| Client | Avalonia (C#) for Windows/Linux/macOS; terminal pane is a WebView running xterm.js |
| Auth | OIDC, provider-agnostic (Entra ID, Keycloak, Auth0, Authentik) |
| Vault | End-to-end encrypted; X25519 + Ed25519 + XChaCha20-Poly1305, Argon2id unlock |
| Connections | Client-direct SSH by default, with an optional raw-TCP server relay |
Three consequences worth knowing before you read further:
- Revocation is not retroactive. A removed member keeps what they already downloaded. The real remediation is rotating the SSH credential, so offboarding is built around a rotation checklist rather than a button that implies more than it delivers.
- No session recording in relay mode. The relay forwards SSH ciphertext, so it cannot see commands. That is the cost of the relay not being able to read your traffic.
- Locking the vault does not close your shells. Lock closes the vault and zeroes every key it held; a session that authenticated before it keeps running, because the remote host never consulted the vault and the credential was already spent. That is deliberate — you lock when you walk away from the machine, which is exactly when a long upgrade or transfer is most likely to be in flight, and an idle auto-lock that killed it would be worse than the exposure it removed. The honest reading is that locked describes the vault and not this machine's access to your hosts. The unlock screen therefore shows how many shells are still connected, and quitting DodoSSH is what ends them.
The reasoning behind each major decision is recorded in docs/adr/, starting with
the E2EE trust model.
Repository layout
src/
DodoSSH.Contracts DTOs shared with the client — the real API contract
DodoSSH.Crypto DSH1 envelope, AAD derivation, the key hierarchy
DodoSSH.Domain entities and invariants, no EF
DodoSSH.Infrastructure DbContext, configurations, migrations
DodoSSH.Api the server
DodoSSH.Client.Auth OIDC code+PKCE on a loopback redirect, and the key binding
DodoSSH.Client.Api the typed server client, and client-side enrollment
DodoSSH.Client.Domain the decrypted item model and the three-way merge — no I/O at all
DodoSSH.Client.Storage the local cache: ciphertext mirror, outbox, offline unlock material
DodoSSH.Client.Sync the pull/apply/push loop and the conflict policy
DodoSSH.Client.Session where a profile lives, unlocking it, and getting one in the first place
DodoSSH.Client.Ssh connections, PTY shells, host key trust
DodoSSH.Client.Terminal the loopback data plane and credit-based flow control
DodoSSH.Client.App Avalonia; the only project that knows about a UI toolkit
tests/ one test project per source project
docs/adr/ architecture decision records
Everything under src/DodoSSH.Client.* except App is deliberately free of Avalonia. That is the
seam that lets the SSH layer, the terminal's flow control and the OIDC flow be tested without a UI
toolkit or a browser engine — which is most of why they are testable at all.
Building
Requires the .NET SDK pinned in global.json (10.0.x).
dotnet build DodoSSH.slnx
dotnet test DodoSSH.slnx
The tests need a Docker daemon. Everything that touches the database, the identity provider or an SSH server uses Testcontainers rather than a stub or a shared instance, so there is nothing to start first and nothing to clean up after — but with no daemon those suites fail rather than skip.
Running it
Four commands, in order. The first two are once per machine.
1. The development dependencies — PostgreSQL and Keycloak, with the dodossh realm imported:
docker compose -f deploy/docker-compose.dev.yml up -d
2. The schema. The API never migrates anything: it fails readiness while a migration is pending, and
says which one. dotnet-ef is pinned in .config/dotnet-tools.json, so run dotnet tool restore first if
you have not:
dotnet ef database update --project src/DodoSSH.Infrastructure
With nothing else configured this targets the compose stack above. Set DODOSSH_DESIGN_CONNECTION to point
it at another database.
3. The server:
dotnet run --project src/DodoSSH.Api
It listens on http://localhost:5233, serving /healthz/live, /healthz/ready and — in
Development — /openapi/v1.json.
4. The desktop client:
dotnet run --project src/DodoSSH.Client.App
In the app, enter http://localhost:5233 as the server. Your browser opens for sign-in — the realm ships
alice / alice — then choose a vault passphrase and write down the recovery code, which cannot be
skipped and cannot be recovered from the server. You can then add a host and open a shell on it. Keycloak's
admin console is at http://localhost:18080 (admin / admin).
You can also add an SSH key, which is stored in the vault like a host and synced the same way: paste the private key, then edit a host and pick that key from its key dropdown. From then on that host authenticates with it — on every machine, since the choice travels inside the host's encrypted payload — and its password box disappears.
The first time you connect to a host you are asked to check its key fingerprint. That decision is stored in the vault, so it is asked once per host rather than once per launch and it reaches your other machines with the next sync. If a server is legitimately rebuilt and offers a new key, the connection is refused outright with no way to continue from the warning — edit the host and choose Forget host key, which is deliberately somewhere you have to go on purpose.
Two of M1's known gaps are visible immediately, so they are worth expecting rather than diagnosing: password authentication asks for the password every time, because nothing in the interface can create a vault credential yet (they do sync — there is just no editor for one); and unlock asks for the passphrase on every launch, because no device key is registered.
End-to-end verification
One suite runs against a real server rather than a stub. It needs a Docker daemon and nothing else, so it is part of the ordinary test run:
dotnet test tests/DodoSSH.SystemTests
It brings up PostgreSQL, Keycloak and an OpenSSH server in containers, applies the committed migrations,
starts the API as a child process out of its own build output, and then drives the real client: sign in
through Keycloak, enroll, unlock, create an SSH key and a host bound to it, sync them, open a shell on the
sshd and approve its host key at the real first-contact refusal, then read all three back on a second
simulated machine and unlock again with no network. Roughly 25 seconds once the images are pulled.
What makes it worth its weight is that it consumes the artefacts that ship — the realm file from
deploy/keycloak, the EF migrations, the API's own appsettings — rather than a fixture written to match
them. On its first run it found a loopback redirect URI the realm registered in a form Keycloak rejects,
and a JSON configuration gap that made the whole sync surface unreachable from the real client while every
other test passed. Both are the same class of bug: two sides of a stub agreeing with each other about
something the specification never said.
The one value it cannot take from a committed file is Oidc:Authority, since the container's port is
assigned at start. Everything that authority points at is still the real realm.
Development and testing are currently Windows-only. Anything known or suspected to differ on
Linux and macOS is tracked in docs/platform-flags.md, along with the
deployment gotchas that have already cost time once. Read it before assuming something works
off-Windows.
Conventions the build enforces
- Warnings are errors.
dotnet format --verify-no-changesgates CI. - Package versions are centralised in
Directory.Packages.props;packages.lock.jsonis committed and CI restores in locked mode. BannedSymbols.txtbansDateTime.UtcNow(useTimeProvider),Guid.NewGuid(useCreateVersion7), sync-over-async, MD5/SHA1 and PBKDF2.- Public members of
DodoSSH.Contractsmust be declared inPublicAPI.Unshipped.txt, so a contract change is a build error rather than a client-side surprise.
Milestones
-
M0 — foundation. Repo structure, build conventions, CI, ADRs. Done.
-
M1 — vertical slice. OIDC login → enroll → create a host → open a shell. Server done: the DSH1 crypto core, the data model, sync push/pull for hosts,
/me, and enrollment with the identity-provider key binding. Client done: the key hierarchy, the OIDC flow with the key binding, SSH connections with host key trust, the terminal data plane, the encrypted local cache with the sync client — offline unlock, an outbox and a field-level three-way merge, conflict matrix green — and an Avalonia shell that is vault-backed: server URL → browser sign-in → enroll → unlock → host list → terminal. The shell's state machine is covered by tests against an in-memory server, so the states that matter most (the recovery code that cannot be skipped, the unlock that needs no network) are checked rather than remembered.Its layout is not covered by anything, and that gap has already cost a shipped defect: the setup and unlock screens were layered over the terminal's WebView, which on Windows is a native child window that cannot be covered, so they rendered sliced with their buttons unclickable. No test in this repository loads a
.axamlfile, and a headless one could not have caught this — there is no native window in headless, so it would have rendered perfectly and confirmed the wrong belief. Screens get looked at, or they are unverified. Verified end to end:tests/DodoSSH.SystemTestsdrives the whole slice against a real Keycloak, a real API, a real PostgreSQL and a realsshd— sign-in, the identity-provider key binding, enrollment, offline unlock, a host and an SSH key through the vault to a second machine, an interactive shell, and the host key approved at that shell's prompt reaching the second machine as well. See End-to-end verification.Known gaps in the client, stated rather than implied by the interface: nothing in the interface can create a vault credential yet, so password authentication still asks for the password each time — SSH keys are editable, and binding one to a host is the way to connect without typing anything; and no device key is registered, so the passphrase is needed on every launch until the OS keystore is wired.
Host key trust is in the vault, which is what makes trust-on-first-use worth having: a fingerprint approved on one machine is approved on all of them and survives a restart, and the server cannot drop a pin to force a fresh first-use decision without the item visibly going missing. A changed host key stays a hard refusal with no way past it; withdrawing a pin is a separate, deliberate act in the host's editor.
Binding a key introduced the first payload schema version bump, and it is worth knowing how it behaves: a host is written at the lowest schema version that can represent it, so only hosts that actually bind a key are written at version 2 and become read-only on an older build. Hosts that do not are still written at version 1, byte-identically to before the field existed — which is what keeps upgrading one machine from making a team's whole vault uneditable everywhere else.
-
M2 — full personal vault, robust sync, relay.
-
M3 — teams, sharing, ACLs.
-
M4 — hardening and ops, packaging, self-hosting guide.
-
M5 — multi-provider OIDC, key rotation, per-item content keys.
Licence
MIT.