jaap-jan
9bc28f1c0f
Eight endpoints today, around sixty planned. The minimal-API shape — a static
class per area holding static local functions, route and policy and name
asserted in one fluent chain with the handler somewhere below it — has not hurt
yet, and would. A handler's dependencies are parameters rather than injected, a
group's RequireAuthorization sits far from the handler it governs, and there is
no type to hang an endpoint's own documentation on. FastEndpoints is one class
per endpoint, its route and authorization in Configure(), its handler a method
on the same type.
Nothing about the wire moves, and the evidence is that the 94 existing HTTP
tests pass with zero edits to any of them. Same routes, verbs, route
constraints, status codes, operation ids, and the same RFC 9457 bodies with the
same code values. Every place the idiomatic FastEndpoints answer would have
changed one of those, it was refused:
Endpoints are registered from an explicit List<Type>, not found by scanning.
ADR 0002 rejected reflection discovery by name, and the reason it gave is
sharper here than in general — under WebApplicationFactory the scan reaches the
test assembly, so an endpoint written in a test would be registered into the
host under test. The cost is a line per endpoint that can be forgotten, which is
what the endpoint-inventory test is for. That test is the one ADR 0002 promised
and never got.
Handlers still return Results<Ok<T>, NotFound, ProblemHttpResult> from
ExecuteAsync. The union executes as an ordinary IResult, which is what keeps
problem bodies going through the host's serialiser and IProblemDetailsService,
and what keeps the compile-time record of which statuses an endpoint can
produce. No Send.* call appears anywhere; the moment one does, a response has
left the host's serialiser.
Validation stays in the feature services. A Validator<T> short-circuits before
the handler and answers with FastEndpoints' own envelope, which carries no code
— and the code is the only part of an error the client branches on. Twenty-odd
tests assert a specific code on a 400. It is banned in BannedSymbols.txt rather
than merely avoided, because the framework's documentation leads straight to it
and it looks like an improvement.
Three defects arrived with the framework and were caught in review. All three
were green at the time, which is the part worth remembering. FastEndpoints maps
GET /_test_url_cache_ unconditionally, in every environment, with no policy and
no way to opt out; it answers with the whole endpoint-name-to-route table. It is
short-circuited to 404 — by asking routing which endpoint it selected, after the
first attempt compared the request path with Ordinal and was therefore bypassable
at /_TEST_URL_CACHE_, certified by a test that only ever tried one spelling. The
default request binder writes query-string values over the deserialised body,
which would have let ?identityProviderToken=... put an ID token in a URL and from
there into every proxy log on the path; every endpoint now binds from the body
alone. And a route value read with Route<T>() is invisible to ApiExplorer, so the
generated document named {vaultId} in a path template with nothing declaring it —
invalid OpenAPI, and unusable by the client generators the document exists for.
Two changes to the surface, both deliberate. A body that cannot be deserialised
now answers with a problem document carrying malformed-request, rather than an
empty 400: FastEndpoints' default announces application/problem+json while
sending something else, and names the failing .NET type on the wire, in a
codebase that sets IncludeErrorDetails = false to prevent exactly that. And the
route table above returns 404 where it would otherwise have answered any
authenticated caller.
Each of the three fixes has a regression test that was checked by reverting the
fix and watching it fail — four failures for the route table and the binder, four
for the document. That check is the whole reason to trust them, since all three
defects passed a full green suite on the way in.
950 tests green across 16 projects, 14 of them new and no existing test edited.
Zero warnings, format clean, locked restore clean. FluentValidation, JobQueues
and Messaging are in the graph now and none is used.
Not verified: the generated document's response schemas, which differ from
before — FastEndpoints contributes its own Produces metadata. Nothing consumes
the document yet, and MapOpenApi runs only in Development behind the fallback
policy. It needs pinning if ADR 0002's build-time artifacts/openapi/v1.json is
ever built.
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.