steid
Sign in

@jamesgill /

steid

steid/plans/progress.md
7.2 KBCode·Blame·Raw
1# Progress
2
3## This attempt (#3, Topcoat)
4
587 tests. Active milestone in [current.md](current.md).
6
7### Milestone 0 — Skeleton · done
8
9Topcoat 0.5 app serving pages, `AppConfig` from `STEID_*` env, SQLite pool in app
10context. Split into a library plus a thin binary — the domain layer had no consumers
11yet and read as ~30 dead-code warnings in a bare binary, and it unlocks `tests/`.
12Topcoat's link-time page discovery works from a library; that was checked, not assumed.
13
14**Requires rustc ≥ 1.95.** On older toolchains `cargo add topcoat` silently resolves to
15an empty `topcoat v0.0.0` placeholder instead of failing.
16
17### Milestone 1 — Identity, thin · all but `/api/me`
18
19**Domain.** Typed IDs, `Email`, `PasswordHash`, `OrgName`, `Organization`, `User`,
20`Membership`, `Role`, `Actor`, `Session`, `SetupToken`, `DomainError`. Value objects
21pair `new()` (validates) with `from_trusted()` (skips, for rows already validated).
22
23**Application.** `claim_instance`, `login`, `resolve_actor`, `record_session`,
24`end_session`, `sweep_expired`. `PasswordHasher` port with Argon2 and a stub.
25
26**Infrastructure.** Migrations for orgs, users, memberships, sessions. In-memory and
27SQLite implementations of every port. Root layout, `/setup`, `/login`, `/logout`, home.
28
29**Verified in a browser and by curl:** wrong token refused with nothing written;
30correct token creates org + user + owner membership and signs the owner in; session
31authenticates; logout clears cookie and row; wrong password bounces; right one signs
32in; re-claiming a claimed instance is refused.
33
34#### Decisions worth remembering
35
36- **`Actor` is an enum with an explicit `Anonymous`**, not `Option<UserId>`. Attempt #2
37 used a placeholder `UserId("ssh-anonymous")` and it became a security hole. A variant
38 can't be forgotten the way a sentinel can.
39- **`login` verifies a dummy hash when no user matched.** Returning early on the
40 unknown-email path makes it measurably faster and leaks which addresses have
41 accounts. A test pins that the dummy stays parseable — if it stops being, `verify`
42 bails early and the defence dies silently.
43- **`SetupToken` compares in constant time.** An early-return comparison leaks how much
44 of the token is right, which recovers it a character at a time.
45- **The setup token is only in app context while unclaimed**, so a claimed instance has
46 nothing for a claim attempt to match.
47- **SQLite ignores foreign keys unless asked**, per connection. `foreign_keys(true)`
48 plus a test that a user pointing at a missing org is refused.
49- **`sqlx migrate add` stamps versions to the second** — three calls in one second
50 collide, leaving apply order ambiguous between tables that reference each other.
51- **An unparseable role surfaces as an error**, never as "no membership". The latter
52 silently downgrades an owner to no access.
53- **`Secure` session cookies over plain-HTTP localhost fail silently.** See
54 [runbook.md](runbook.md#steid_insecure_cookies--development-only). This one actually
55 bit, and it looked exactly like broken auth logic.
56
57---
58
59## Reference: what attempt #2 proved
60
61Not this repo's progress. This is a catalogue of what was built and **verified working**
62in `steid-backup-2026-07-31`, so the rebuild can crib rather than rediscover.
63
64Final state: single crate, ~4,200 LOC, 60 passing tests, five milestones.
65
66### Identity
67
68Domain model (User, Organization, Membership, Actor, Role), `Email` and
69`PasswordHash` value objects, typed IDs, `DomainError`, four repository ports with
70in-memory and SQLite implementations each. `RegistrationPolicy` (Personal / Invite /
71Open) driving which routes exist. Argon2 hashing behind a `PasswordHasher` port with a
72stub for tests. Use cases: `bootstrap_owner`, `register_user`, `login`, `create_invite`.
73Signed-cookie sessions via an `AuthUser` extractor.
74
75**Gotcha:** organizations must be saved before users — the FK runs that direction.
76Both `bootstrap_owner` and `register_user` had to be fixed for this.
77
78### Repo model
79
80`Repository` entity, `RepoId`, `Visibility` (Public/Private), `RepoRepository` port,
81migration `006_create_repositories.sql`. `create_repo` use case validates the name,
82rejects duplicates, and initialises the bare repo on disk in the same call. Bare repos
83live at `{data_dir}/{org}/{repo}.git`, `data_dir` defaulting to `./data`. Repos are
84created empty, no initial commit, like GitHub.
85
86### Git over SSH
87
88`GitStorage` port (`init_bare`, `repo_path`) with `DiskGitStorage` shelling out to
89`git init --bare`. `GitProtocolServer` port (`upload_pack`, `receive_pack`) with
90`GitBinary` spawning `git upload-pack` / `git receive-pack` via
91`tokio::process::Command` and pumping stdio with `tokio::io::copy`.
92
93`serve_clone` and `serve_push` use cases enforce visibility and actor checks **before
94any protocol byte flows** — that ordering is the whole point of putting them in the
95application layer.
96
97#### SSH channel bridging
98
99The fiddly part, and worth re-reading before Milestone 3:
100
101- Store `Channel<Msg>` per `ChannelId` in the handler's map on `channel_open_session`
102- On `exec_request`, take the channel, split it with `into_stream()` +
103 `tokio::io::split`
104- Take stderr via `make_writer_ext(Some(1))` **before** `into_stream()` — that call
105 consumes the channel, so the order is not optional
106- No `data()` or `channel_eof()` handlers needed once the streams are split
107
108An earlier iteration used mpsc channels, custom `ChannelReader`/`ChannelWriter`, and a
109`spawn_blocking` thread. All of it was deleted and the result was simpler.
110
111### SSH key auth and authorization
112
113`SshKey { id, user_id, name, fingerprint, openssh }` + port, migration
114`007_create_ssh_keys.sql` (`fingerprint` UNIQUE). Fingerprints are SHA256 via
115`russh::keys::ssh_key::PublicKey::fingerprint(HashAlg::Sha256)`, stored as `SHA256:…`.
116`add_ssh_key` parses the openssh blob, dedupes on fingerprint, and re-encodes to a
117canonical form before storing.
118
119`auth_none` rejects. `auth_publickey` fingerprints the offered key, looks it up, and
120on a match stores `user_id` on the handler; `exec_request` builds the real `Actor`
121from it.
122
123Authorization rules as shipped:
124
125| Operation | Requirement |
126|---|---|
127| Clone, public repo | open |
128| Clone, private repo | any membership in the repo's org |
129| Push | `Role::Owner` membership in the repo's org |
130
131Web UI at `/{owner}/keys` — owner-only, lists fingerprints, accepts openssh via
132textarea, revokes per-row.
133
134**Verified end-to-end:** clone with an unregistered key → `Permission denied` (exit
135128); register via web UI → clone and push both succeed; second unregistered key →
136rejected at auth; revoke via web UI → subsequent clone rejected at auth.
137
138### Security notes
139
140Attempt #2 ran with a **named, deliberate backdoor** between milestones: SSH accepted
141any connection and passed a placeholder `Actor` (`UserId("ssh-anonymous")`), leaving
142push open to anyone who could reach the port. It was recorded with an explicit
143tightening point (`ssh.rs::exec_request`) and a closing milestone, and it did close.
144
145That practice is worth keeping. When this attempt opens a hole to make progress, name
146it, name the line that closes it, and name the milestone.
147
148### Never built
149
150Repo browsing (tree/blob/log), HTTP smart protocol, personal access tokens, flash
151messages, issues, PRs, blogs, pages, project showcases. Milestones 5–8 in
152[ROADMAP.md](ROADMAP.md) are all greenfield.