# Current

> Keep this file short. One active step, one ordered backlog. Completed work moves to
> [progress.md](progress.md). If this file starts reading like a changelog, it has
> drifted — that's exactly what went wrong last time.

## Active: Milestone 4b — Push and tokens

**Goal:** `git push` works over HTTP for someone who may write, and a private repository
is clonable by someone who may read it. Authentication is personal access tokens over
HTTP Basic, per [0001](decisions/0001-git-over-http-not-ssh.md).

**Out of scope:** SSH, token scopes beyond whatever the Open questions settle, OAuth,
and anything to do with browsing a tree (Milestone 5).

### Steps

Provisional below the first two — the rest depend on the Open decisions.

- [ ] Domain: `PersonalAccessToken`, `TokenId`, `TokenHash`, and the repository port
- [ ] Infrastructure: in-memory + SQLite implementations, migration
- [ ] Application: `issue_token`, `list_tokens`, `revoke_token`
- [ ] Application: `authenticate_token` — resolves a Basic credential into an `Actor`
- [ ] Web: HTTP Basic on the git routes, and the 401 challenge that makes a client
      send credentials at all
- [ ] Application: let `serve_git` authorize writes rather than refusing them
- [ ] Web: token management UI under `/{handle}/settings`
- [ ] Verify: push to a public repo, clone a private one, and check a revoked token
      stops working

### Done when

A token issued through the UI lets `git push` succeed against a repository its owner may
write, and lets `git clone` succeed against a private repository its owner may read.
Revoking the token stops both. An anonymous clone of a public repository still works
exactly as it does today.

### Open

These are decisions, not unknowns — each needs an answer before the step that depends on
it.

- **How tokens are hashed.** Sessions already hash their token with SHA-256
  (`SessionTokenHash`), which suits a high-entropy random value; Argon2 would be the
  password answer and is far too slow for something presented on every git request, of
  which a single clone makes several. Recommendation: copy the session approach, store a
  display prefix alongside so the UI can name a token without holding it.
- **Whether tokens carry scopes.** Personal-first says no: a token acts as its user.
  Scopes are the kind of thing that is cheap to add later behind an unchanged port and
  expensive to design against no requirement.
- **401 versus 404 for a private repository.** Carried from 4a and now decidable. A git
  client only sends credentials *after* a 401, so answering 404 to an anonymous request
  for a private repository — which is what 4a does, and what `view_repo` does — makes
  authenticated private clone impossible. Answering 401 leaks that the repository
  exists. Gitea and GitHub both accept that leak. This is the one with a real cost
  either way.

### Carried over — small, unblocked

- **A client that disappears mid-request leaves the body-copy task waiting.** The copy
  into git's stdin runs in its own task and nothing cancels it if the connection drops.
  Bounded by the backend exiting and closing the pipe, but not by anything deliberate.
- **A subprocess per git request.** Unlike Milestone 3's once-per-creation, this is on a
  hot path and has not been measured. Milestone 5 is where that bill comes due.
- **Streaming is by construction, not by measurement.** The response body is never
  collected, but no clone large enough to prove it has been run.
- **An orphaned repo directory is possible** if the process dies between the record
  write and the filesystem write, and it then blocks re-creating that name. The durable
  fix is a reconciliation sweep on boot
  ([architecture.md](architecture.md#db-plus-filesystem-writes)); clearing one is a
  manual `rm` today, since repo deletion does not exist.
- **The duplicate-name check races.** The loser is caught by `init_bare` or the unique
  constraint, but surfaces as an opaque storage error rather than "name taken".
- **Bare repos created on macOS carry `ignorecase = true`.** A migration gotcha if the
  data directory ever moves to Linux.
- **Fonts are not loaded.** The theme names Geist and IBM Plex Mono; both fall back
  today. Topcoat's `font-fontsource` feature handles it.
- **Light mode is untested.** The palette defines it; nobody has looked at it.
- **No rate limiting** on `/auth/login` or `/auth/setup`.
- **`sweep_expired` is never called**, so expired session rows accumulate. Expiry is
  enforced on read, so this is tidiness, not a hole.
- **CSRF.** `SameSite=Lax` covers the common case. Forms now exist, so this is decidable
  rather than hypothetical.

## Backlog

Ordered. Pull from the top.

1. **Milestone 5 — Repo browsing.** Tree, blob, commit log. **Start with domain value
   objects** — `ObjectId`, `RefName`, `TreeEntry` — before any adapter. A query port
   returning `String`s is an anaemic pass-through that pushes validation into the page.
   Also the point to measure fork/exec cost per page view, and to reconsider `gix` for
   the read path ([0006](decisions/0006-git-binary-behind-narrow-ports.md)).
2. **Milestone 6 — Writing.** Posts, markdown, `/{handle}/posts/{slug}`. Still open
   whether writing or projects/showcases is the better first portfolio feature.

## Open questions

- **Topcoat is early** (v0.5.0, first released 2026-07-22, breaking changes expected
  by its own authors). Expect churn that isn't feature work.
- Topcoat ships Tailwind without Node, which reopens the design system attempt #1
  dropped purely to avoid an npm build step — see [ui.md](ui.md).

## Routing findings (Milestone 0)

- **Topcoat 0.5 requires rustc ≥ 1.95.** On an older toolchain `cargo add topcoat`
  silently resolves to an empty `topcoat v0.0.0` placeholder instead of failing. Local
  stable is now 1.97.1.
- `Router::builder().discover()` collects `#[page]`-annotated items **at link time**,
  so pages can live in any module. Layering is our choice, not the framework's.
- `module_router!` derives each URL from the module tree rather than a path string.
  Still deferred. Application routes now group cleanly (`auth/login`, `api/me`), but
  handles sit at the root ([0004](decisions/0004-root-handles-grouped-routes.md)), so a
  parameterised root segment still has to coexist with static ones. Worth checking how
  `module_router!` handles that before committing to it.
- Path and query params are read from `Cx` via `path_param!` / `#[query_params]`, not
  injected as handler arguments. Parses are memoized per request.
- Layouts wrap by path prefix and nest outermost-first, and a layout can catch a page's
  `NotFoundError` to render a branded 404.
- `HOST` / `PORT` configure the bind address, so `STEID_LISTEN_ADDR` is gone.
- `Body` is a boxed `http_body::Body` used for both requests and responses, with
  `into_data_stream()` to read and `Body::new()` to wrap a stream — pack data can
  stream both directions without buffering. This is what makes Milestone 4 viable.