docs/plans/2026-09-27-credentials-and-sessions.md
3568 lines · 115133 bytes
1# Credentials and sessions implementation plan
2
3> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
5**Goal:** Revocation of an SSH key takes effect on open connections
6(#256); an expiring credential cannot mint one that outlives it, and
7credentials record the token that made them (#257); SSH and deploy
8keys take an optional expiry and show their last use (#277); browser
9sessions end after 12 hours idle (#276); `web login` over SSH spends
10the login-link budget (#278).
11
12**Architecture:** The store announces revocations it commits
13(`Store.OnRevoke`); the SSH listener tracks which key opened each
14connection and cuts the ones a revocation names, killing a git
15transport's process group. A 15-second sweep catches revocations made
16by another process and keys that expire while connected. Every exec
17re-reads its key. `Command.MintsCredential` marks the commands that
18create credentials; `Dispatch` refuses them when `Ctx.Expires` is set.
19`api_tokens` and `ssh_keys` gain `created_by_token`; `ssh_keys` gains
20`expires_at`; `web_sessions` gains a sliding expiry under an absolute
21cap.
22
23**Tech stack:** Go, `golang.org/x/crypto/ssh`, SQLite (modernc), OpenSSH
24client for e2e.
25
26**Spec:** issues #256, #257, #276, #277, #278 on krz/gitbay (the
27decisions on #256 and #257 are recorded there, and the later ones in
28"Decisions" at the end of this plan).
29
30## Global constraints
31
32- Each MR on its own branch off `main`. Commits are signed (the repo
33 refuses unsigned), messages reference issues (`Ref #N`, and
34 `Closes #N` on the commit that finishes one). No attribution to any
35 assistant, model or AI anywhere: commits, MR bodies, comments.
36- MR: `gitbay mr create --source <branch> --target main --title "..."`;
37 merge with `gitbay mr merge <n> --strategy ff` once CI is green, then
38 delete the branch locally and on the remote. Behind main → rebase,
39 force-push, merge again.
40- Locally: `go build ./...`, `go vet ./...`, unit tests of touched
41 packages, and at most the one e2e test being written
42 (`go test ./e2e -run TestName -count=1`). CI on bay1 runs the full suite.
43- Registries that fail CI when a new thing lacks its row: top-level route
44 word in `internal/policy/names.go`; new page template in the width map
45 of `TestMainWidthClass` (`internal/web/web_test.go`); new `ReadOnly`
46 command in `readArgs` in `e2e/readonly_test.go`; new control command
47 needs a `pass()` entry in `cmd/gitbay/main.go` (coverage test);
48 a command reading stdin needs `ReadsStdin: true`. This plan adds no
49 route, template, command or read command; it changes flags and a
50 `Summary` of none, so `cmd/gitbay/summaries_gen.go` stays current.
51- Migrations: this plan owns 0060–0064 and uses 0060, 0061, 0062. Six
52 plans are written in parallel with pre-assigned ranges; whoever lands
53 second renumbers to the next free number at execution time.
54 Migrations come in `.up.sql`/`.down.sql` pairs. Hand-written SQL, no
55 ORM. `TestMigrateUpDown` (`internal/store/store_test.go`) exercises
56 every down script.
57- Secrets travel on stdin, never argv; never logged or echoed.
58- Wiki pages live in `.gitbay/wiki/` (Parity, API, Admin, Threat-Model,
59 CI, Users, Performance, and the `Architecture/` folder with its
60 Known-Gaps table and controls matrix). Update the page in the same MR
61 that changes the behaviour it describes, and remove the matching
62 row from `Architecture/10-Known-Gaps.org`.
63- Release notes go in `CHANGELOG.org` under the topmost heading that
64 has no tag yet. If the top heading is a released version, add
65 `* Unreleased` above it; whoever tags renames it.
66- Writing style: plain, direct, no hype; code comments match the
67 surrounding density. Comments and docs state facts, never
68 before/after narration.
69- Work in a worktree of `krz/gitbay`; the main checkout may hold
70 another session's edits.
71
72## Order and dependencies
73
74| # | Branch | Closes | Migration | Depends on |
75|---|---|---|---|---|
76| 1 | `revoke-closes-connections` | #256 | none | — |
77| 2 | `token-delegation` | #257 | 0060 | MR 1 (`Store.announce`, `fingerprint` e2e helper, `Exec` taking a key) |
78| 3 | `key-expiry` | #277 | 0061 | MR 1 (sweep, per-exec check), MR 2 (`KeyOrigin`, `Ctx.Expires`) |
79| 4 | `session-idle` | #276 | 0062 | — |
80| 5 | `weblogin-limit` | #278 | none | — |
81
82\#256 goes first. #257 and #277 both add columns to `ssh_keys`; both
83are nullable `ADD COLUMN`s with no table rebuild, so they compose in
84either order, and `KeyOrigin` (MR 2) is the one insert path both use.
85
86Other plans:
87
88- Plan 5 (web-ux) #264 depends on MR 2's `--scope read` default.
89- Plan 3 (server-hardening) touches the same code: #262 limits
90 concurrent git processes in `gitutil.Transport` / `sshd.runGit`
91 (MR 1 changes both signatures), #275 audits refused commands in
92 `control.Dispatch` (MR 2 adds a refusal there, which #275 should
93 audit like the others), #282 changes `hookd`. Whoever lands second
94 rebases; the conflicts are mechanical.
95
96## File map
97
98| File | MR | Responsibility |
99|---|---|---|
100| `internal/store/revoke.go` (create) | 1 | `Revoked`, `OnRevoke`, `announce`, `LiveSSHKeys` |
101| `internal/store/store.go` | 1 | subscriber fields on `Store` |
102| `internal/store/users.go` | 1, 2, 3 | removals announce; `KeyOrigin`, `AddSSHKeyFrom`; `expires_at` |
103| `internal/sshd/sshd.go` | 1, 3 | connection tracking, `cut`, sweep, per-exec check, `Exec(key)`; expired keys refused |
104| `internal/gitutil/gitutil.go`, `proc_unix.go`, `proc_other.go` | 1 | `Transport` takes a cancel channel, kills the process group |
105| `cmd/gitbayd/system.go` | 1, 3 | `Exec` call; expired keys in system mode |
106| `internal/control/control.go` | 2 | `MintsCredential`, `Ctx.TokenID`, `Ctx.Expires`, the refusal |
107| `internal/store/tokens.go` | 2 | token id, creator, chained revoke |
108| `internal/control/token.go` | 2, 3 | default read, creator, `revoke --created`; `ttlFlag` |
109| `internal/control/identity.go`, `deploykey.go`, `runnerrepo.go`, `adminhost.go`, `register.go`, `web.go` | 2, 3, 4, 5 | flags, creator, `--ttl`, list columns, login limit |
110| `internal/httpd/api.go` | 2 | token into `Ctx` |
111| `internal/store/sessions.go` | 4 | sliding session expiry |
112| `internal/control/loginlink.go` | 5 | comment |
113| `e2e/revoke_test.go` (create) | 1 | multiplexed connection cut |
114| `e2e/tokenorigin_test.go` (create) | 2 | expiring token refused, `revoke --created` |
115| `.gitbay/wiki/*`, `CHANGELOG.org` | all | docs in the MR that changes behaviour |
116
117---
118
119# MR 1: removing a key closes its connections (branch `revoke-closes-connections`, #256)
120
121Decision on the issue: revocation is immediate, running commands
122included. What that means here, stated in the Threat-Model page:
123
124- Every exec and every git transport session re-reads its key: gone,
125 moved to another account, or re-scoped takes effect on the next
126 command.
127- `keys remove`, `repo deploy-key remove`, `admin user disable`,
128 `admin user delete` and (MR 2) `token revoke --created` close every
129 connection opened by an affected key. A git transport on it is
130 killed with its process group. A control command in flight loses its
131 channel; one that watches `Done` (`build log --follow`) stops, one
132 already inside its store write finishes that write and its output is
133 lost.
134- A push cut before its pre-receive hook answers updates no refs. The
135 ref transaction that follows the hook is not interrupted mid-write in
136 practice; it is milliseconds long.
137- Revocations committed by another process (`gitbayd admin` on the
138 host) are found by a 15-second sweep.
139- System mode (`ssh.mode = "system"`) runs one process per exec, so
140 the per-exec check applies; a forced-command process already running
141 is not cut (open question 4).
142
143### Task 1.1: the store announces revocations and answers which keys are live
144
145**Files:**
146- Create: `internal/store/revoke.go`
147- Modify: `internal/store/store.go:23-30` (`Store` struct)
148- Modify: `internal/store/users.go` — `DeleteUser` (58-101), `SetUserDisabled` (171-194), `RemoveSSHKey` (291-309), `RemoveDeployKey` (534-554)
149- Test: `internal/store/revoke_test.go` (create)
150
151**Interfaces:**
152- Produces:
153 - `type Revoked struct { KeyIDs []int64; UserID int64 }`
154 - `func (s *Store) OnRevoke(f func(Revoked))`
155 - `func (s *Store) announce(r Revoked)` (package-private; MR 2 calls it)
156 - `func (s *Store) LiveSSHKeys(ids []int64) (map[int64]bool, error)`
157
158- [ ] **Step 1: Write the failing test**
159
160`internal/store/revoke_test.go`:
161
162```go
163package store
164
165import (
166 "slices"
167 "testing"
168)
169
170func revokeFixture(t *testing.T) (*Store, int64, *[]Revoked) {
171 t.Helper()
172 s := open(t)
173 if err := s.MigrateUp(); err != nil {
174 t.Fatal(err)
175 }
176 uid, err := s.CreateUser("alice", false)
177 if err != nil {
178 t.Fatal(err)
179 }
180 var got []Revoked
181 s.OnRevoke(func(r Revoked) { got = append(got, r) })
182 return s, uid, &got
183}
184
185func keyID(t *testing.T, s *Store, fp string) int64 {
186 t.Helper()
187 k, err := s.SSHKeyByFingerprint(fp)
188 if err != nil {
189 t.Fatal(err)
190 }
191 return k.ID
192}
193
194func TestRemovalsAnnounceTheirKeys(t *testing.T) {
195 s, uid, got := revokeFixture(t)
196 if err := s.AddSSHKey(uid, "SHA256:a", "ssh-ed25519", []byte("a"), "full", ""); err != nil {
197 t.Fatal(err)
198 }
199 if err := s.AddSSHKey(uid, "SHA256:d", "ssh-ed25519", []byte("d"), "deploy:7:ro", ""); err != nil {
200 t.Fatal(err)
201 }
202 a, d := keyID(t, s, "SHA256:a"), keyID(t, s, "SHA256:d")
203
204 if err := s.RemoveSSHKey(uid, "SHA256:a"); err != nil {
205 t.Fatal(err)
206 }
207 if err := s.RemoveDeployKey(7, "SHA256:d"); err != nil {
208 t.Fatal(err)
209 }
210 if err := s.SetUserDisabled(uid, true); err != nil {
211 t.Fatal(err)
212 }
213 if err := s.SetUserDisabled(uid, false); err != nil {
214 t.Fatal(err)
215 }
216 want := []Revoked{{KeyIDs: []int64{a}}, {KeyIDs: []int64{d}}, {UserID: uid}}
217 if !slices.EqualFunc(*got, want, func(x, y Revoked) bool {
218 return slices.Equal(x.KeyIDs, y.KeyIDs) && x.UserID == y.UserID
219 }) {
220 t.Fatalf("announced %+v, want %+v (enabling announces nothing)", *got, want)
221 }
222 // A removal that found nothing announces nothing.
223 if err := s.RemoveSSHKey(uid, "SHA256:a"); err != ErrNotFound {
224 t.Fatalf("second remove: %v", err)
225 }
226 if len(*got) != 3 {
227 t.Fatalf("a miss was announced: %+v", *got)
228 }
229}
230
231func TestDeleteUserAnnounces(t *testing.T) {
232 s, uid, got := revokeFixture(t)
233 if err := s.DeleteUser(uid); err != nil {
234 t.Fatal(err)
235 }
236 if len(*got) != 1 || (*got)[0].UserID != uid {
237 t.Fatalf("announced %+v", *got)
238 }
239}
240
241func TestLiveSSHKeys(t *testing.T) {
242 s, uid, _ := revokeFixture(t)
243 bob, err := s.CreateUser("bob", false)
244 if err != nil {
245 t.Fatal(err)
246 }
247 for _, k := range []struct {
248 uid int64
249 fp string
250 }{{uid, "SHA256:a"}, {bob, "SHA256:b"}} {
251 if err := s.AddSSHKey(k.uid, k.fp, "ssh-ed25519", []byte(k.fp), "full", ""); err != nil {
252 t.Fatal(err)
253 }
254 }
255 a, b := keyID(t, s, "SHA256:a"), keyID(t, s, "SHA256:b")
256 if _, err := s.DB.Exec("UPDATE users SET disabled = 1 WHERE id = ?", bob); err != nil {
257 t.Fatal(err)
258 }
259 live, err := s.LiveSSHKeys([]int64{a, b, 999})
260 if err != nil {
261 t.Fatal(err)
262 }
263 if !live[a] || live[b] || live[999] {
264 t.Fatalf("live = %v; want only %d", live, a)
265 }
266 if live, err := s.LiveSSHKeys(nil); err != nil || len(live) != 0 {
267 t.Fatalf("no ids: %v %v", live, err)
268 }
269}
270```
271
272- [ ] **Step 2: Run it and see it fail**
273
274Run: `go test ./internal/store -run 'TestRemovalsAnnounceTheirKeys|TestDeleteUserAnnounces|TestLiveSSHKeys' -count=1`
275Expected: FAIL to compile, `s.OnRevoke undefined`.
276
277- [ ] **Step 3: Add the subscriber fields**
278
279In `internal/store/store.go`, the `Store` struct becomes:
280
281```go
282type Store struct {
283 DB *sql.DB
284
285 // logWait holds one channel per build someone is following, closed
286 // by the next change to that build's row (BuildLogWait).
287 logMu sync.Mutex
288 logWait map[int64]chan struct{}
289
290 // onRevoke runs after each key revocation this process commits.
291 revokeMu sync.Mutex
292 onRevoke []func(Revoked)
293}
294```
295
296- [ ] **Step 4: Create `internal/store/revoke.go`**
297
298```go
299package store
300
301import (
302 "slices"
303 "strings"
304)
305
306// Revoked names SSH keys that stopped being valid: by id, or every key
307// of an account. The SSH listener closes the connections they opened.
308type Revoked struct {
309 KeyIDs []int64
310 UserID int64 // every key of this account; 0 for none
311}
312
313// OnRevoke registers f to run after each revocation this process
314// commits. Revocations committed by another process (gitbayd admin on
315// the host) are not announced; the listener's sweep finds those.
316func (s *Store) OnRevoke(f func(Revoked)) {
317 s.revokeMu.Lock()
318 defer s.revokeMu.Unlock()
319 s.onRevoke = append(s.onRevoke, f)
320}
321
322// announce runs the subscribers. Call it after the commit, outside any
323// transaction.
324func (s *Store) announce(r Revoked) {
325 s.revokeMu.Lock()
326 fs := slices.Clone(s.onRevoke)
327 s.revokeMu.Unlock()
328 for _, f := range fs {
329 f(r)
330 }
331}
332
333// LiveSSHKeys reports which of ids still name a registered key on an
334// account that is not disabled.
335func (s *Store) LiveSSHKeys(ids []int64) (map[int64]bool, error) {
336 live := map[int64]bool{}
337 if len(ids) == 0 {
338 return live, nil
339 }
340 args := make([]any, len(ids))
341 for i, id := range ids {
342 args[i] = id
343 }
344 rows, err := s.DB.Query(`SELECT k.id FROM ssh_keys k JOIN users u ON u.id = k.user_id
345 WHERE u.disabled = 0 AND k.id IN (?`+strings.Repeat(", ?", len(ids)-1)+`)`, args...)
346 if err != nil {
347 return nil, err
348 }
349 defer rows.Close()
350 for rows.Next() {
351 var id int64
352 if err := rows.Scan(&id); err != nil {
353 return nil, err
354 }
355 live[id] = true
356 }
357 return live, rows.Err()
358}
359```
360
361- [ ] **Step 5: Announce from the four removals**
362
363`RemoveSSHKey` in `internal/store/users.go`:
364
365```go
366// RemoveSSHKey removes a key owned by userID, bumps the key epoch, and
367// announces the revocation.
368func (s *Store) RemoveSSHKey(userID int64, fingerprint string) error {
369 tx, err := s.DB.Begin()
370 if err != nil {
371 return err
372 }
373 defer tx.Rollback()
374 var id int64
375 err = tx.QueryRow("DELETE FROM ssh_keys WHERE user_id = ? AND fingerprint = ? RETURNING id", userID, fingerprint).Scan(&id)
376 if errors.Is(err, sql.ErrNoRows) {
377 return ErrNotFound
378 }
379 if err != nil {
380 return err
381 }
382 if err := bumpKeyEpoch(tx); err != nil {
383 return err
384 }
385 if err := tx.Commit(); err != nil {
386 return err
387 }
388 s.announce(Revoked{KeyIDs: []int64{id}})
389 return nil
390}
391```
392
393`RemoveDeployKey`:
394
395```go
396// RemoveDeployKey removes a deploy key from a repository by fingerprint;
397// any repo admin may remove it regardless of who added it.
398func (s *Store) RemoveDeployKey(repoID int64, fingerprint string) error {
399 tx, err := s.DB.Begin()
400 if err != nil {
401 return err
402 }
403 defer tx.Rollback()
404 var id int64
405 err = tx.QueryRow(
406 "DELETE FROM ssh_keys WHERE fingerprint = ? AND scope LIKE 'deploy:' || ? || ':%' RETURNING id",
407 fingerprint, repoID).Scan(&id)
408 if errors.Is(err, sql.ErrNoRows) {
409 return ErrNotFound
410 }
411 if err != nil {
412 return err
413 }
414 if err := bumpKeyEpoch(tx); err != nil {
415 return err
416 }
417 if err := tx.Commit(); err != nil {
418 return err
419 }
420 s.announce(Revoked{KeyIDs: []int64{id}})
421 return nil
422}
423```
424
425`SetUserDisabled`, the tail from `if disabled {`:
426
427```go
428 if disabled {
429 // A pending login link is a session in waiting, so it goes with
430 // the sessions and API tokens. Re-enabling means minting again.
431 for _, table := range []string{"web_sessions", "api_tokens", "login_tokens"} {
432 if _, err := s.DB.Exec("DELETE FROM "+table+" WHERE user_id = ?", userID); err != nil {
433 return err
434 }
435 }
436 s.announce(Revoked{UserID: userID})
437 }
438 return nil
439}
440```
441
442Update its doc comment's last clause to: "and leaves the SSH keys registered but refused at every entry point until re-enabled; connections they opened are closed."
443
444`DeleteUser`, the tail:
445
446```go
447 res, err := s.DB.Exec("DELETE FROM users WHERE id = ?", id)
448 if err != nil {
449 return err
450 }
451 if n, _ := res.RowsAffected(); n == 0 {
452 return ErrNotFound
453 }
454 s.announce(Revoked{UserID: id})
455 return nil
456}
457```
458
459- [ ] **Step 6: Run the tests**
460
461Run: `go test ./internal/store -count=1`
462Expected: PASS.
463
464- [ ] **Step 7: Commit**
465
466```bash
467git add internal/store/revoke.go internal/store/revoke_test.go internal/store/store.go internal/store/users.go
468git commit -S -m "store: announce key revocations; LiveSSHKeys
469
470Ref #256"
471```
472
473### Task 1.2: `gitutil.Transport` can be cancelled
474
475**Files:**
476- Modify: `internal/gitutil/gitutil.go:39-56`
477- Create: `internal/gitutil/proc_unix.go`, `internal/gitutil/proc_other.go`
478- Test: `internal/gitutil/transport_test.go` (create)
479
480**Interfaces:**
481- Produces: `func Transport(service, repoPath string, stdin io.Reader, stdout, errW io.Writer, extraEnv []string, maxPack int64, cancel <-chan struct{}) error` — closing `cancel` kills the git process and its children; a nil `cancel` never fires.
482
483- [ ] **Step 1: Write the failing test**
484
485`internal/gitutil/transport_test.go`:
486
487```go
488package gitutil
489
490import (
491 "io"
492 "os/exec"
493 "strings"
494 "testing"
495 "time"
496)
497
498// Closing cancel kills the transport; it does not wait for the client
499// to hang up. Stdin ends only after the kill, as a cut connection's
500// does, so a clean exit here would mean the kill never happened.
501func TestTransportCancelKillsGit(t *testing.T) {
502 dir := t.TempDir()
503 if out, err := exec.Command("git", "init", "-q", "--bare", dir).CombinedOutput(); err != nil {
504 t.Fatalf("git init: %v\n%s", err, out)
505 }
506 in, w := io.Pipe()
507 cancel := make(chan struct{})
508 errc := make(chan error, 1)
509 go func() { errc <- Transport("git-upload-pack", dir, in, io.Discard, io.Discard, nil, 0, cancel) }()
510 close(cancel)
511 time.AfterFunc(500*time.Millisecond, func() { w.Close() })
512 select {
513 case err := <-errc:
514 if err == nil || !strings.Contains(err.Error(), "killed") {
515 t.Fatalf("Transport returned %v, want the process killed", err)
516 }
517 case <-time.After(5 * time.Second):
518 t.Fatal("Transport did not return after cancel")
519 }
520}
521```
522
523- [ ] **Step 2: Run it and see it fail**
524
525Run: `go test ./internal/gitutil -run TestTransportCancelKillsGit -count=1`
526Expected: FAIL to compile, too many arguments to `Transport`.
527
528- [ ] **Step 3: Process-group helpers**
529
530`internal/gitutil/proc_unix.go`:
531
532```go
533//go:build unix
534
535package gitutil
536
537import (
538 "os/exec"
539 "syscall"
540)
541
542// ownProcessGroup puts cmd in a process group of its own, so killTree
543// ends what it started too: receive-pack runs index-pack and the hooks.
544func ownProcessGroup(cmd *exec.Cmd) {
545 if cmd.SysProcAttr == nil {
546 cmd.SysProcAttr = &syscall.SysProcAttr{}
547 }
548 cmd.SysProcAttr.Setpgid = true
549}
550
551func killTree(cmd *exec.Cmd) {
552 if cmd.Process == nil {
553 return
554 }
555 if err := syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL); err != nil {
556 cmd.Process.Kill()
557 }
558}
559```
560
561`internal/gitutil/proc_other.go`:
562
563```go
564//go:build !unix
565
566package gitutil
567
568import "os/exec"
569
570func ownProcessGroup(cmd *exec.Cmd) {}
571
572func killTree(cmd *exec.Cmd) {
573 if cmd.Process != nil {
574 cmd.Process.Kill()
575 }
576}
577```
578
579- [ ] **Step 4: Transport**
580
581Replace `Transport` in `internal/gitutil/gitutil.go`:
582
583```go
584// Transport runs a git transport service against repoPath with the
585// client's streams. Closing cancel kills the service and everything it
586// started; a push killed before its pre-receive hook answers updates no
587// refs.
588func Transport(service, repoPath string, stdin io.Reader, stdout, errW io.Writer, extraEnv []string, maxPack int64, cancel <-chan struct{}) error {
589 var args []string
590 switch service {
591 case "git-upload-pack", "git-receive-pack", "git-upload-archive":
592 if service == "git-receive-pack" && maxPack > 0 {
593 args = []string{"-c", fmt.Sprintf("receive.maxInputSize=%d", maxPack)}
594 }
595 args = append(args, strings.TrimPrefix(service, "git-"), repoPath)
596 default:
597 return fmt.Errorf("unknown service %q", service)
598 }
599 cmd := exec.Command(toolpath.Look("git"), args...)
600 cmd.Env = append(os.Environ(), extraEnv...)
601 cmd.Stdin = stdin
602 cmd.Stdout = stdout
603 cmd.Stderr = errW
604 ownProcessGroup(cmd)
605 if err := cmd.Start(); err != nil {
606 return err
607 }
608 finished := make(chan struct{})
609 go func() {
610 select {
611 case <-cancel:
612 killTree(cmd)
613 case <-finished:
614 }
615 }()
616 err := cmd.Wait()
617 close(finished)
618 return err
619}
620```
621
622If the current doc comment above `Transport` (line 38 and up) says something different, keep its first sentence and replace the rest with the above.
623
624- [ ] **Step 5: Fix the caller so the tree builds**
625
626In `internal/sshd/sshd.go:464`, pass `nil` for now (Task 1.3 wires the channel):
627
628```go
629 if err := gitutil.Transport(service, dir, stdin, stdout, stderr, env, maxPack, nil); err != nil {
630```
631
632- [ ] **Step 6: Run the tests**
633
634Run: `go build ./... && go test ./internal/gitutil -count=1`
635Expected: PASS.
636
637- [ ] **Step 7: Commit**
638
639```bash
640git add internal/gitutil internal/sshd/sshd.go
641git commit -S -m "gitutil: Transport takes a cancel channel and kills its process group
642
643Ref #256"
644```
645
646### Task 1.3: sshd re-reads the key per exec and cuts revoked connections
647
648**Files:**
649- Modify: `internal/sshd/sshd.go` — `conn` (46-53), `New` (55-71), `Serve` (158-180), `handleConn` (214-238), `handleSession` (240-292), `runExec` (299-313), `Exec` (339-385), `runGit` (387-468)
650- Modify: `cmd/gitbayd/system.go:97`
651- Modify: `internal/sshd/sshd_test.go:20-87` (`followServer` split)
652- Test: `internal/sshd/revoke_test.go` (create)
653
654**Interfaces:**
655- Consumes: `store.Revoked`, `Store.OnRevoke`, `Store.LiveSSHKeys` (Task 1.1); `gitutil.Transport(..., cancel)` (Task 1.2).
656- Produces:
657 - `func Exec(cfg config.Config, st *store.Store, user store.User, key store.SSHKey, term control.Term, cmdline string, stdin io.Reader, stdout, stderr io.Writer, done, stopping, revoked <-chan struct{}) int` — scope and audit source come from `key`.
658 - `func (s *Server) sweepOnce()` (tests call it).
659 - Test helpers in package `sshd`: `type testServer struct{ srv *Server; st *store.Store; client *ssh.Client; uid, keyID int64; fp string }`, `newTestServer(t) testServer`, `withBuild(t, ts)`, `execStatus(client, cmd) (int, string)`, `waitClosed(t, client)`.
660
661- [ ] **Step 1: Split the test fixture**
662
663In `internal/sshd/sshd_test.go`, replace `followServer` (lines 20-87) with:
664
665```go
666// testServer is an embedded server over a fresh store holding alice
667// with one full-scope key, and a client connected with that key.
668type testServer struct {
669 srv *Server
670 st *store.Store
671 client *ssh.Client
672 uid int64
673 keyID int64
674 fp string
675}
676
677func newTestServer(t *testing.T) testServer {
678 t.Helper()
679 root := t.TempDir()
680 st, err := store.Open(filepath.Join(root, "gitbay.db"))
681 if err != nil {
682 t.Fatal(err)
683 }
684 t.Cleanup(func() { st.Close() })
685 if err := st.MigrateUp(); err != nil {
686 t.Fatal(err)
687 }
688 uid, err := st.CreateUser("alice", false)
689 if err != nil {
690 t.Fatal(err)
691 }
692 _, priv, err := ed25519.GenerateKey(rand.Reader)
693 if err != nil {
694 t.Fatal(err)
695 }
696 signer, err := ssh.NewSignerFromKey(priv)
697 if err != nil {
698 t.Fatal(err)
699 }
700 pub := signer.PublicKey()
701 fp := ssh.FingerprintSHA256(pub)
702 if err := st.AddSSHKey(uid, fp, pub.Type(), pub.Marshal(), "full", "test"); err != nil {
703 t.Fatal(err)
704 }
705 key, err := st.SSHKeyByFingerprint(fp)
706 if err != nil {
707 t.Fatal(err)
708 }
709
710 cfg := config.Default()
711 cfg.Server.Root = root
712 srv, err := New(cfg, st)
713 if err != nil {
714 t.Fatal(err)
715 }
716 ln, err := net.Listen("tcp", "127.0.0.1:0")
717 if err != nil {
718 t.Fatal(err)
719 }
720 go srv.Serve(ln)
721 t.Cleanup(func() { ln.Close() })
722
723 client, err := ssh.Dial("tcp", ln.Addr().String(), &ssh.ClientConfig{
724 User: "git",
725 Auth: []ssh.AuthMethod{ssh.PublicKeys(signer)},
726 HostKeyCallback: ssh.InsecureIgnoreHostKey(),
727 Timeout: 5 * time.Second,
728 })
729 if err != nil {
730 t.Fatal(err)
731 }
732 t.Cleanup(func() { client.Close() })
733 return testServer{srv: srv, st: st, client: client, uid: uid, keyID: key.ID, fp: fp}
734}
735
736// withBuild gives alice the public repo alice/app and a queued build 1
737// whose log has one line.
738func withBuild(t *testing.T, ts testServer) {
739 t.Helper()
740 repoID, err := ts.st.CreateRepo("user", ts.uid, "app", "public")
741 if err != nil {
742 t.Fatal(err)
743 }
744 id, err := ts.st.CreateBuild(repoID, "unit", "abc", "main", `["true"]`, "", "", true)
745 if err != nil {
746 t.Fatal(err)
747 }
748 if err := ts.st.AppendBuildLog(id, []byte("queued\n")); err != nil {
749 t.Fatal(err)
750 }
751}
752
753// followServer starts an embedded server holding alice, her public repo
754// alice/app and a queued build 1 whose log has one line, and returns it
755// with a client connected as alice.
756func followServer(t *testing.T) (*Server, *ssh.Client) {
757 t.Helper()
758 ts := newTestServer(t)
759 withBuild(t, ts)
760 return ts.srv, ts.client
761}
762```
763
764Run: `go test ./internal/sshd -count=1`
765Expected: PASS (behaviour unchanged).
766
767- [ ] **Step 2: Write the failing tests**
768
769`internal/sshd/revoke_test.go`:
770
771```go
772package sshd
773
774import (
775 "bytes"
776 "errors"
777 "strings"
778 "testing"
779 "time"
780
781 "golang.org/x/crypto/ssh"
782)
783
784// execStatus runs cmd on a new session and returns its exit status and
785// stderr; -1 when the session could not run.
786func execStatus(client *ssh.Client, cmd string) (int, string) {
787 sess, err := client.NewSession()
788 if err != nil {
789 return -1, err.Error()
790 }
791 defer sess.Close()
792 var stderr bytes.Buffer
793 sess.Stderr = &stderr
794 err = sess.Run(cmd)
795 var exit *ssh.ExitError
796 switch {
797 case err == nil:
798 return 0, stderr.String()
799 case errors.As(err, &exit):
800 return exit.ExitStatus(), stderr.String()
801 }
802 return -1, err.Error()
803}
804
805// waitClosed fails unless the server closes the client's connection
806// within five seconds.
807func waitClosed(t *testing.T, client *ssh.Client) {
808 t.Helper()
809 done := make(chan struct{})
810 go func() { client.Wait(); close(done) }()
811 select {
812 case <-done:
813 case <-time.After(5 * time.Second):
814 t.Fatal("the connection stayed open")
815 }
816}
817
818// Each exec reads the key again. The rows change behind the store's
819// back here, so no revocation is announced and the connection stays up:
820// what refuses the command is the per-exec check alone.
821func TestExecRevalidatesKey(t *testing.T) {
822 ts := newTestServer(t)
823 if code, errOut := execStatus(ts.client, "whoami"); code != 0 {
824 t.Fatalf("whoami: %d %s", code, errOut)
825 }
826 if _, err := ts.st.DB.Exec("UPDATE ssh_keys SET scope = 'git' WHERE id = ?", ts.keyID); err != nil {
827 t.Fatal(err)
828 }
829 if code, errOut := execStatus(ts.client, "whoami"); code != 4 || !strings.Contains(errOut, "does not allow control commands") {
830 t.Fatalf("whoami after re-scope: %d %q", code, errOut)
831 }
832 if _, err := ts.st.DB.Exec("DELETE FROM ssh_keys WHERE id = ?", ts.keyID); err != nil {
833 t.Fatal(err)
834 }
835 if code, errOut := execStatus(ts.client, "whoami"); code != 4 || !strings.Contains(errOut, "no longer registered") {
836 t.Fatalf("whoami after delete: %d %q", code, errOut)
837 }
838}
839
840// Removing the key cuts the connection, ending a command running on it.
841func TestRemoveKeyCutsConnection(t *testing.T) {
842 ts := newTestServer(t)
843 withBuild(t, ts)
844 var stderr bytes.Buffer
845 sess := startFollow(t, ts.client, &stderr)
846 if err := ts.st.RemoveSSHKey(ts.uid, ts.fp); err != nil {
847 t.Fatal(err)
848 }
849 waited := make(chan error, 1)
850 go func() { waited <- sess.Wait() }()
851 select {
852 case err := <-waited:
853 if err == nil {
854 t.Fatal("the follow exited cleanly after its key was removed")
855 }
856 case <-time.After(5 * time.Second):
857 t.Fatal("the follow outlived its key")
858 }
859 waitClosed(t, ts.client)
860}
861
862func TestDisableCutsConnection(t *testing.T) {
863 ts := newTestServer(t)
864 if err := ts.st.SetUserDisabled(ts.uid, true); err != nil {
865 t.Fatal(err)
866 }
867 waitClosed(t, ts.client)
868}
869
870// A revocation made by another process is not announced here; the
871// sweep finds it. A live key survives the sweep.
872func TestSweepCutsOutOfProcessRevocation(t *testing.T) {
873 ts := newTestServer(t)
874 ts.srv.sweepOnce()
875 if code, errOut := execStatus(ts.client, "whoami"); code != 0 {
876 t.Fatalf("the sweep cut a live key: %d %s", code, errOut)
877 }
878 if _, err := ts.st.DB.Exec("UPDATE users SET disabled = 1 WHERE id = ?", ts.uid); err != nil {
879 t.Fatal(err)
880 }
881 ts.srv.sweepOnce()
882 waitClosed(t, ts.client)
883}
884```
885
886- [ ] **Step 3: Run them and see them fail**
887
888Run: `go test ./internal/sshd -run 'TestExecRevalidatesKey|TestRemoveKeyCutsConnection|TestDisableCutsConnection|TestSweepCutsOutOfProcessRevocation' -count=1`
889Expected: FAIL to compile, `ts.srv.sweepOnce undefined`.
890
891- [ ] **Step 4: Track the key on each connection**
892
893In `internal/sshd/sshd.go` add `"slices"` to the imports. Replace `conn`:
894
895```go
896// conn is one accepted connection and how many sessions it is running.
897// A CLI's shared connection sits idle between commands; on shutdown an
898// idle connection is closed at once and only a session mid-command is
899// waited for (#141).
900type conn struct {
901 net net.Conn
902 active atomic.Int32
903 // keyID and userID are the key that authenticated the connection and
904 // its account: 0 before the handshake and for an unregistered key.
905 // Guarded by Server.mu.
906 keyID, userID int64
907 revoked chan struct{} // closed by cut
908 cutOnce sync.Once
909}
910
911// cut ends the connection because its key was revoked: a git transport
912// on it is killed, and every other command loses its channel.
913func (c *conn) cut() {
914 c.cutOnce.Do(func() { close(c.revoked) })
915 c.net.Close()
916}
917```
918
919In `New`, after `s.sshCfg = sc`:
920
921```go
922 st.OnRevoke(s.revoke)
923```
924
925`Serve` becomes:
926
927```go
928// Serve accepts connections on ln until it is closed.
929func (s *Server) Serve(ln net.Listener) error {
930 served := make(chan struct{})
931 defer close(served)
932 go s.sweep(served)
933 for {
934 nc, err := ln.Accept()
935 if err != nil {
936 return err
937 }
938 c := &conn{net: nc, revoked: make(chan struct{})}
939 s.mu.Lock()
940 s.conns[c] = struct{}{}
941 s.mu.Unlock()
942 s.sessions.Add(1)
943 go func() {
944 defer s.sessions.Done()
945 defer func() {
946 s.mu.Lock()
947 delete(s.conns, c)
948 s.mu.Unlock()
949 }()
950 s.handleConn(c)
951 }()
952 }
953}
954```
955
956Add after `Serve`:
957
958```go
959// revoke closes the connections opened by the keys r names.
960func (s *Server) revoke(r store.Revoked) {
961 s.mu.Lock()
962 defer s.mu.Unlock()
963 for c := range s.conns {
964 if c.keyID == 0 {
965 continue
966 }
967 if (r.UserID != 0 && c.userID == r.UserID) || slices.Contains(r.KeyIDs, c.keyID) {
968 c.cut()
969 }
970 }
971}
972
973// sweepInterval bounds how long a revocation this process was not told
974// about (gitbayd admin on the host) leaves a connection open.
975const sweepInterval = 15 * time.Second
976
977func (s *Server) sweep(served <-chan struct{}) {
978 t := time.NewTicker(sweepInterval)
979 defer t.Stop()
980 for {
981 select {
982 case <-t.C:
983 s.sweepOnce()
984 case <-served:
985 return
986 case <-s.stopping:
987 return
988 }
989 }
990}
991
992// sweepOnce cuts every connection whose key is no longer live. Only
993// connections whose key was asked about are judged: one that
994// authenticated while the query ran waits for the next sweep.
995func (s *Server) sweepOnce() {
996 asked := map[int64]bool{}
997 s.mu.Lock()
998 for c := range s.conns {
999 if c.keyID != 0 {
1000 asked[c.keyID] = true
1001 }
1002 }
1003 s.mu.Unlock()
1004 if len(asked) == 0 {
1005 return
1006 }
1007 live, err := s.st.LiveSSHKeys(slices.Collect(maps.Keys(asked)))
1008 if err != nil {
1009 slog.Error("ssh sweep: key lookup", "err", err)
1010 return
1011 }
1012 s.mu.Lock()
1013 defer s.mu.Unlock()
1014 for c := range s.conns {
1015 if asked[c.keyID] && !live[c.keyID] {
1016 c.cut()
1017 }
1018 }
1019}
1020```
1021
1022Add `"maps"` to the imports.
1023
1024In `handleConn`, after `defer sconn.Close()`:
1025
1026```go
1027 ext := sconn.Permissions.Extensions
1028 s.mu.Lock()
1029 c.keyID, _ = strconv.ParseInt(ext["key-id"], 10, 64)
1030 c.userID, _ = strconv.ParseInt(ext["user-id"], 10, 64)
1031 s.mu.Unlock()
1032```
1033
1034and pass `c` to the session: `s.handleSession(c, sconn, ch, chReqs)`.
1035
1036`handleSession` takes the connection:
1037
1038```go
1039func (s *Server) handleSession(c *conn, sconn *ssh.ServerConn, ch ssh.Channel, reqs <-chan *ssh.Request) {
1040```
1041
1042and its exec case calls `code := s.runExec(c, sconn, ch, term, payload.Command, done)`.
1043
1044- [ ] **Step 5: Re-read the key per exec**
1045
1046Replace `runExec`:
1047
1048```go
1049func (s *Server) runExec(c *conn, sconn *ssh.ServerConn, ch ssh.Channel, term control.Term, cmdline string, done <-chan struct{}) int {
1050 ext := sconn.Permissions.Extensions
1051 if blob := ext["anon-key"]; blob != "" {
1052 return s.runAnonymous(ch, blob, cmdline)
1053 }
1054 userID, _ := strconv.ParseInt(ext["user-id"], 10, 64)
1055 keyID, _ := strconv.ParseInt(ext["key-id"], 10, 64)
1056 // A connection outlives its commands, so the key is read again for
1057 // each one: what it may do is what it may do now (#256).
1058 key, err := s.st.SSHKeyByID(keyID)
1059 if errors.Is(err, store.ErrNotFound) || (err == nil && key.UserID != userID) {
1060 fmt.Fprintln(ch.Stderr(), "this key is no longer registered")
1061 return protocol.ExitDenied
1062 }
1063 if err != nil {
1064 slog.Error("ssh exec: key lookup", "err", err)
1065 fmt.Fprintln(ch.Stderr(), "authentication temporarily unavailable")
1066 return protocol.ExitFailure
1067 }
1068 user, err := s.st.UserByID(userID)
1069 if err != nil {
1070 fmt.Fprintln(ch.Stderr(), "account no longer exists")
1071 return protocol.ExitDenied
1072 }
1073 _ = s.st.TouchSSHKey(keyID)
1074 return Exec(s.cfg, s.st, user, key, term, cmdline, ch, ch, ch.Stderr(), done, s.stopping, c.revoked)
1075}
1076```
1077
1078- [ ] **Step 6: `Exec` takes the key; `runGit` takes the cancel channel**
1079
1080```go
1081// Exec runs one SSH exec command line for an authenticated key. It is the
1082// single dispatch path shared by the embedded listener and the system-sshd
1083// forced command (gitbayd shell). Closing revoked kills a git transport.
1084func Exec(cfg config.Config, st *store.Store, user store.User, key store.SSHKey, term control.Term, cmdline string,
1085 stdin io.Reader, stdout, stderr io.Writer, done, stopping, revoked <-chan struct{}) int {
1086```
1087
1088Inside `Exec`: `runGit(cfg, st, user, key.Scope, argv, stdin, stdout, stderr, revoked)`, `runLFSAuthenticate(cfg, st, user, key.Scope, argv, stdout, stderr)`, and in the `Ctx` literal `Scope: key.Scope, Source: key.Fingerprint`.
1089
1090`runGit` gains a last parameter `revoked <-chan struct{}` and passes it on:
1091
1092```go
1093func runGit(cfg config.Config, st *store.Store, user store.User, scope string, argv []string,
1094 stdin io.Reader, stdout, stderr io.Writer, revoked <-chan struct{}) int {
1095```
1096
1097```go
1098 if err := gitutil.Transport(service, dir, stdin, stdout, stderr, env, maxPack, revoked); err != nil {
1099```
1100
1101In `cmd/gitbayd/system.go:97`:
1102
1103```go
1104 code := sshd.Exec(cfg, st, user, key, control.ParseTerm(os.Getenv("GITBAY_TERM")), cmdline, os.Stdin, os.Stdout, os.Stderr, nil, nil, nil)
1105```
1106
1107- [ ] **Step 7: Run the tests**
1108
1109Run: `go build ./... && go vet ./... && go test ./internal/sshd ./internal/gitutil ./internal/store -count=1`
1110Expected: PASS.
1111
1112- [ ] **Step 8: Commit**
1113
1114```bash
1115git add internal/sshd cmd/gitbayd/system.go
1116git commit -S -m "sshd: re-read the key per exec; revocation cuts its connections
1117
1118Ref #256"
1119```
1120
1121### Task 1.4: e2e — a multiplexed connection is cut, a push in flight moves no ref
1122
1123**Files:**
1124- Create: `e2e/revoke_test.go`
1125
1126**Interfaces:**
1127- Produces (package `e2e`): `pkt(s string) string`, `readPkt(r *bufio.Reader) (string, error)`, `fingerprint(t *testing.T, pubPath string) string` — MR 2 uses `fingerprint`.
1128
1129- [ ] **Step 1: Write the test**
1130
1131```go
1132package e2e
1133
1134import (
1135 "bufio"
1136 "fmt"
1137 "io"
1138 "os"
1139 "os/exec"
1140 "path/filepath"
1141 "strconv"
1142 "strings"
1143 "testing"
1144 "time"
1145)
1146
1147// pkt frames one pkt-line.
1148func pkt(s string) string { return fmt.Sprintf("%04x%s", len(s)+4, s) }
1149
1150// readPkt reads one pkt-line; a flush reads as "".
1151func readPkt(r *bufio.Reader) (string, error) {
1152 var n [4]byte
1153 if _, err := io.ReadFull(r, n[:]); err != nil {
1154 return "", err
1155 }
1156 size, err := strconv.ParseUint(string(n[:]), 16, 16)
1157 if err != nil {
1158 return "", err
1159 }
1160 if size == 0 {
1161 return "", nil
1162 }
1163 buf := make([]byte, size-4)
1164 _, err = io.ReadFull(r, buf)
1165 return string(buf), err
1166}
1167
1168// fingerprint is the SHA256 fingerprint of a public key file.
1169func fingerprint(t *testing.T, pubPath string) string {
1170 t.Helper()
1171 out, err := exec.Command("ssh-keygen", "-lf", pubPath).Output()
1172 if err != nil {
1173 t.Fatalf("ssh-keygen -lf: %v", err)
1174 }
1175 return strings.Fields(string(out))[1]
1176}
1177
1178// Removing a key cuts the connections it opened: every session
1179// multiplexed on a ControlMaster, and a push in flight, which moves no
1180// ref (#256).
1181func TestRemovedKeyCutsMultiplexedConnection(t *testing.T) {
1182 t.Parallel()
1183 inst := startInstance(t)
1184 aliceKey := setupPublicRepo(t, inst, "alice/app")
1185 spare := inst.newKey(t, "spare")
1186 pub, err := os.ReadFile(spare + ".pub")
1187 if err != nil {
1188 t.Fatal(err)
1189 }
1190 if _, errOut, code := inst.ssh(t, aliceKey, string(pub), "keys", "add"); code != 0 {
1191 t.Fatalf("keys add: %s", errOut)
1192 }
1193
1194 // The control socket sits under the system temp dir: t.TempDir() on
1195 // macOS is long enough to pass the 104-byte socket path limit.
1196 cmDir, err := os.MkdirTemp("", "cm")
1197 if err != nil {
1198 t.Fatal(err)
1199 }
1200 t.Cleanup(func() { os.RemoveAll(cmDir) })
1201 muxArgs := []string{
1202 "-p", fmt.Sprint(inst.port),
1203 "-i", aliceKey,
1204 "-o", "IdentitiesOnly=yes",
1205 "-o", "StrictHostKeyChecking=no",
1206 "-o", "UserKnownHostsFile=" + filepath.Join(inst.sshDir, "known_hosts"),
1207 "-o", "BatchMode=yes",
1208 "-o", "ControlMaster=auto",
1209 "-o", "ControlPath=" + filepath.Join(cmDir, "%C"),
1210 "-o", "ControlPersist=60",
1211 }
1212 mux := func(args ...string) *exec.Cmd {
1213 return exec.Command("ssh", append(append([]string{}, muxArgs...), args...)...)
1214 }
1215 t.Cleanup(func() { mux("-O", "exit", "git@127.0.0.1").Run() })
1216
1217 if out, err := mux("git@127.0.0.1", "whoami").Output(); err != nil || strings.TrimSpace(string(out)) != "alice" {
1218 t.Fatalf("whoami over the master: %v %q", err, out)
1219 }
1220
1221 // A push held open mid-pack: the ref update is sent, the pack is not.
1222 push := mux("git@127.0.0.1", "git-receive-pack", "alice/app")
1223 stdin, err := push.StdinPipe()
1224 if err != nil {
1225 t.Fatal(err)
1226 }
1227 stdout, err := push.StdoutPipe()
1228 if err != nil {
1229 t.Fatal(err)
1230 }
1231 if err := push.Start(); err != nil {
1232 t.Fatal(err)
1233 }
1234 adv := bufio.NewReader(stdout)
1235 first, err := readPkt(adv)
1236 if err != nil || len(first) < 40 {
1237 t.Fatalf("advertisement: %q %v", first, err)
1238 }
1239 oldSHA := first[:40]
1240 for {
1241 line, err := readPkt(adv)
1242 if err != nil {
1243 t.Fatalf("advertisement: %v", err)
1244 }
1245 if line == "" {
1246 break
1247 }
1248 }
1249 newSHA := strings.Repeat("1", 40)
1250 io.WriteString(stdin, pkt(oldSHA+" "+newSHA+" refs/heads/main\x00report-status\n")+"0000")
1251 // A pack header announcing one object, and no object.
1252 stdin.Write([]byte("PACK\x00\x00\x00\x02\x00\x00\x00\x01"))
1253 exited := make(chan error, 1)
1254 go func() {
1255 io.Copy(io.Discard, adv)
1256 exited <- push.Wait()
1257 }()
1258
1259 if _, errOut, code := inst.ssh(t, spare, "", "keys", "remove", fingerprint(t, aliceKey+".pub")); code != 0 {
1260 t.Fatalf("keys remove: %s", errOut)
1261 }
1262 select {
1263 case err := <-exited:
1264 if err == nil {
1265 t.Fatal("the push exited cleanly after its key was removed")
1266 }
1267 case <-time.After(10 * time.Second):
1268 t.Fatal("the push outlived its key")
1269 }
1270
1271 // The master went with the connection; a new one authenticates
1272 // again, and the key is unknown.
1273 if out, err := mux("git@127.0.0.1", "whoami").CombinedOutput(); err == nil {
1274 t.Fatalf("whoami after removal succeeded: %s", out)
1275 }
1276 refs := mustGit(t, t.TempDir(), inst.gitEnv(spare), "ls-remote", inst.sshURL("alice/app"), "refs/heads/main")
1277 if !strings.HasPrefix(refs, oldSHA) {
1278 t.Fatalf("main moved: %s, want %s", refs, oldSHA)
1279 }
1280}
1281```
1282
1283- [ ] **Step 2: Run it**
1284
1285Run: `go test ./e2e -run TestRemovedKeyCutsMultiplexedConnection -count=1`
1286Expected: PASS. To see it fail, stash Task 1.3's `st.OnRevoke(s.revoke)` line: the push then hangs until the 10-second timeout.
1287
1288- [ ] **Step 3: Commit**
1289
1290```bash
1291git add e2e/revoke_test.go
1292git commit -S -m "e2e: removing a key cuts its multiplexed connection and a push in flight
1293
1294Ref #256"
1295```
1296
1297### Task 1.5: docs
1298
1299**Files:**
1300- Modify: `.gitbay/wiki/Architecture/10-Known-Gaps.org`, `09-Controls.org:28`, `05-Identity-and-Access.org:17-18`, `08-Operations.org:88-89`, `.gitbay/wiki/Threat-Model.org` (Trust boundaries), `.gitbay/wiki/Users.org` (after the keys block, ~line 70)
1301
1302- [ ] **Step 1: Edit the pages**
1303
1304`10-Known-Gaps.org`: delete the `#256` row. In the paragraph under the table, drop "#256 closes a removed key's connections, running commands included;" so it opens "Decisions already taken on these: #257 refuses ...".
1305
1306`09-Controls.org`, the revocation row becomes:
1307
1308```
1309| Revocation takes effect immediately | in place | removing a key or disabling an account closes its connections; every exec re-reads its key (=internal/sshd/sshd.go=) |
1310```
1311
1312`05-Identity-and-Access.org`, the SSH user key and deploy key rows' Revocation cells become `=keys remove= (own keys); closes its connections` and `=repo deploy-key remove= (repo admin); closes its connections`.
1313
1314`08-Operations.org`: delete the two lines "Open connections of a removed key keep working until they close; see #256."
1315
1316`Threat-Model.org`, add to "Trust boundaries" after the "SSH public key = identity" bullet:
1317
1318```
1319- *Revocation is immediate.* Every exec and every git transport session
1320 re-reads its key. Removing a key, removing a deploy key, disabling or
1321 deleting an account closes the connections the affected keys opened:
1322 a git transport is killed with its children, and a push killed before
1323 its pre-receive hook answers moves no ref. A control command already
1324 inside its database write finishes it; its output is lost. A
1325 revocation made by =gitbayd admin= on the host, another process, is
1326 found within 15 seconds. In =ssh.mode = "system"= each exec is its
1327 own process: the next exec is refused, one already running is not cut.
1328```
1329
1330`Users.org`, after the paragraph that ends "Labels are one line of up to 64 bytes.":
1331
1332```
1333Removing a key closes every connection it opened, including the CLI's
1334shared one; removing the key the current command runs on ends that
1335command's connection too.
1336```
1337
1338- [ ] **Step 2: Commit, open the MR**
1339
1340```bash
1341git add .gitbay/wiki
1342git commit -S -m "wiki: revocation closes open connections
1343
1344Closes #256"
1345git push -u origin revoke-closes-connections
1346gitbay mr create --source revoke-closes-connections --target main --title "sshd: removing a key closes its connections"
1347```
1348
1349Merge with `--strategy ff` once CI is green; delete the branch locally and on the remote.
1350
1351---
1352
1353# MR 2: expiring credentials cannot mint; credentials record their token (branch `token-delegation`, #257)
1354
1355Decisions on the issue: a token with an expiry is refused on every
1356credential-minting command, marked on `Command` and checked in
1357`Dispatch`; tokens and keys record the token that created them;
1358`token revoke` lists what the token created and can revoke it too;
1359`token create` defaults to `--scope read`.
1360
1361Commands marked `MintsCredential`: `token create`, `keys add`,
1362`repo deploy-key add`, `repo runner add` (attaches or creates a key
1363that can claim builds), `web login` (a login link opens a seven-day
1364session), `admin invite`, `admin user create` (with `--key` or a
1365verified address it is a way in), `email verify` and
1366`admin email verify` (a verified address receives login links). See
1367open question 2.
1368
1369`created_by_token` references `api_tokens(id) ON DELETE SET NULL`: a
1370revoked token's id is never reused for a live row, because SQLite
1371reuses the highest rowid after it is deleted and a dangling integer
1372would then name the wrong token. Revoking without `--created` lists
1373what the token made and then drops the link.
1374
1375### Task 2.1: migration 0060 and the store
1376
1377**Files:**
1378- Create: `internal/store/migrations/0060_credential_origin.up.sql`, `.down.sql`
1379- Modify: `internal/store/tokens.go` (whole file)
1380- Modify: `internal/store/users.go` — `SSHKey` (18-28), `AddSSHKey` (270-289), `ListSSHKeys` (335-353)
1381- Test: `internal/store/tokens_test.go` (create)
1382
1383**Interfaces:**
1384- Consumes: `Store.announce`, `Revoked` (MR 1).
1385- Produces:
1386 - `type APIToken struct { ID int64; Name, Scope, CreatedAt string; ExpiresAt, LastUsedAt *time.Time; CreatedBy string }` — `CreatedBy` is the creating token's name, "" for none.
1387 - `func (s *Store) CreateAPIToken(userID int64, name, tokenHash, scope string, expires *time.Time, createdByToken int64) error`
1388 - `func (s *Store) APITokenUser(tokenHash string) (User, APIToken, error)`
1389 - `type Created struct { Tokens []string; Keys []string }` — token names and key fingerprints.
1390 - `func (s *Store) RevokeAPIToken(userID int64, name string, withCreated bool) (Created, error)`
1391 - `type KeyOrigin struct { CreatedByToken int64 }` (MR 3 adds `ExpiresAt`)
1392 - `func (s *Store) AddSSHKeyFrom(userID int64, fingerprint, algo string, blob []byte, scope, label string, o KeyOrigin) error`; `AddSSHKey` keeps its signature and calls it with `KeyOrigin{}`.
1393 - `SSHKey.CreatedBy string` — filled by `ListSSHKeys` only.
1394
1395- [ ] **Step 1: Write the failing test**
1396
1397`internal/store/tokens_test.go`:
1398
1399```go
1400package store
1401
1402import (
1403 "slices"
1404 "testing"
1405 "time"
1406)
1407
1408func tokenID(t *testing.T, s *Store, hash string) int64 {
1409 t.Helper()
1410 _, tok, err := s.APITokenUser(hash)
1411 if err != nil {
1412 t.Fatal(err)
1413 }
1414 return tok.ID
1415}
1416
1417// parent made child, child made grandchild and a key; the key belongs
1418// to another account, as admin user create --key makes one.
1419func tokenChain(t *testing.T) (*Store, int64, *[]Revoked) {
1420 t.Helper()
1421 s, uid, got := revokeFixture(t)
1422 bob, err := s.CreateUser("bob", false)
1423 if err != nil {
1424 t.Fatal(err)
1425 }
1426 if err := s.CreateAPIToken(uid, "parent", "h-parent", "full", nil, 0); err != nil {
1427 t.Fatal(err)
1428 }
1429 if err := s.CreateAPIToken(uid, "child", "h-child", "full", nil, tokenID(t, s, "h-parent")); err != nil {
1430 t.Fatal(err)
1431 }
1432 child := tokenID(t, s, "h-child")
1433 if err := s.CreateAPIToken(uid, "grandchild", "h-grand", "read", nil, child); err != nil {
1434 t.Fatal(err)
1435 }
1436 if err := s.AddSSHKeyFrom(bob, "SHA256:k", "ssh-ed25519", []byte("k"), "full", "", KeyOrigin{CreatedByToken: child}); err != nil {
1437 t.Fatal(err)
1438 }
1439 return s, uid, got
1440}
1441
1442func TestTokenRecordsItsCreator(t *testing.T) {
1443 s, uid, _ := tokenChain(t)
1444 toks, err := s.ListAPITokens(uid)
1445 if err != nil {
1446 t.Fatal(err)
1447 }
1448 by := map[string]string{}
1449 for _, tk := range toks {
1450 by[tk.Name] = tk.CreatedBy
1451 }
1452 if by["parent"] != "" || by["child"] != "parent" || by["grandchild"] != "child" {
1453 t.Fatalf("created by: %v", by)
1454 }
1455 bob, _ := s.UserByUsername("bob")
1456 keys, err := s.ListSSHKeys(bob.ID)
1457 if err != nil || len(keys) != 1 || keys[0].CreatedBy != "child" {
1458 t.Fatalf("key created by: %+v %v", keys, err)
1459 }
1460}
1461
1462func TestRevokeAPITokenListsWhatItCreated(t *testing.T) {
1463 s, uid, got := tokenChain(t)
1464 c, err := s.RevokeAPIToken(uid, "parent", false)
1465 if err != nil {
1466 t.Fatal(err)
1467 }
1468 if !slices.Equal(c.Tokens, []string{"child", "grandchild"}) || !slices.Equal(c.Keys, []string{"SHA256:k"}) {
1469 t.Fatalf("created = %+v", c)
1470 }
1471 // Listed, not removed; the link to the revoked parent is gone.
1472 toks, _ := s.ListAPITokens(uid)
1473 if len(toks) != 2 || toks[0].Name != "child" || toks[0].CreatedBy != "" {
1474 t.Fatalf("tokens after revoke: %+v", toks)
1475 }
1476 if _, err := s.SSHKeyByFingerprint("SHA256:k"); err != nil {
1477 t.Fatalf("the key went: %v", err)
1478 }
1479 if len(*got) != 0 {
1480 t.Fatalf("announced %+v with nothing revoked but the token", *got)
1481 }
1482}
1483
1484func TestRevokeAPITokenWithCreated(t *testing.T) {
1485 s, uid, got := tokenChain(t)
1486 k, _ := s.SSHKeyByFingerprint("SHA256:k")
1487 if _, err := s.RevokeAPIToken(uid, "parent", true); err != nil {
1488 t.Fatal(err)
1489 }
1490 if toks, _ := s.ListAPITokens(uid); len(toks) != 0 {
1491 t.Fatalf("tokens left: %+v", toks)
1492 }
1493 if _, err := s.SSHKeyByFingerprint("SHA256:k"); err != ErrNotFound {
1494 t.Fatalf("key left: %v", err)
1495 }
1496 if len(*got) != 1 || !slices.Equal((*got)[0].KeyIDs, []int64{k.ID}) {
1497 t.Fatalf("announced %+v", *got)
1498 }
1499 if _, err := s.RevokeAPIToken(uid, "parent", true); err != ErrNotFound {
1500 t.Fatalf("second revoke: %v", err)
1501 }
1502}
1503
1504func TestAPITokenUserCarriesExpiry(t *testing.T) {
1505 s, uid, _ := revokeFixture(t)
1506 exp := time.Now().Add(time.Hour)
1507 if err := s.CreateAPIToken(uid, "brief", "h-brief", "full", &exp, 0); err != nil {
1508 t.Fatal(err)
1509 }
1510 _, tok, err := s.APITokenUser("h-brief")
1511 if err != nil || tok.ExpiresAt == nil || tok.Name != "brief" || tok.ID == 0 {
1512 t.Fatalf("token %+v %v", tok, err)
1513 }
1514}
1515```
1516
1517- [ ] **Step 2: Run it and see it fail**
1518
1519Run: `go test ./internal/store -run 'TestTokenRecordsItsCreator|TestRevokeAPIToken|TestAPITokenUserCarriesExpiry' -count=1`
1520Expected: FAIL to compile.
1521
1522- [ ] **Step 3: Migration**
1523
1524`internal/store/migrations/0060_credential_origin.up.sql`:
1525
1526```sql
1527-- The API token a credential was created through. NULL when it was not,
1528-- and once that token is revoked.
1529ALTER TABLE api_tokens ADD COLUMN created_by_token INTEGER REFERENCES api_tokens(id) ON DELETE SET NULL;
1530ALTER TABLE ssh_keys ADD COLUMN created_by_token INTEGER REFERENCES api_tokens(id) ON DELETE SET NULL;
1531```
1532
1533`internal/store/migrations/0060_credential_origin.down.sql`:
1534
1535```sql
1536ALTER TABLE ssh_keys DROP COLUMN created_by_token;
1537ALTER TABLE api_tokens DROP COLUMN created_by_token;
1538```
1539
1540- [ ] **Step 4: Tokens in the store**
1541
1542Replace `internal/store/tokens.go`:
1543
1544```go
1545package store
1546
1547import (
1548 "database/sql"
1549 "errors"
1550 "fmt"
1551 "strings"
1552 "time"
1553)
1554
1555type APIToken struct {
1556 ID int64
1557 Name string
1558 Scope string
1559 CreatedAt string
1560 ExpiresAt *time.Time
1561 LastUsedAt *time.Time
1562 CreatedBy string // name of the token that created this one; "" for none
1563}
1564
1565// nullID stores 0 as NULL.
1566func nullID(id int64) any {
1567 if id == 0 {
1568 return nil
1569 }
1570 return id
1571}
1572
1573// CreateAPIToken stores a token hash; expires nil means no expiry,
1574// createdByToken 0 means it was not created through a token.
1575func (s *Store) CreateAPIToken(userID int64, name, tokenHash, scope string, expires *time.Time, createdByToken int64) error {
1576 var exp any
1577 if expires != nil {
1578 exp = fmtTime(*expires)
1579 }
1580 _, err := s.DB.Exec(
1581 "INSERT INTO api_tokens (user_id, name, token_hash, scope, expires_at, created_by_token) VALUES (?, ?, ?, ?, ?, ?)",
1582 userID, name, tokenHash, scope, exp, nullID(createdByToken))
1583 if isUniqueErr(err) {
1584 return fmt.Errorf("you already have a token named %q", name)
1585 }
1586 return err
1587}
1588
1589// APITokenUser resolves a presented token to its user and the token;
1590// expired and unknown tokens fail identically.
1591func (s *Store) APITokenUser(tokenHash string) (User, APIToken, error) {
1592 var userID int64
1593 var t APIToken
1594 var exp sql.NullString
1595 err := s.DB.QueryRow(`
1596 SELECT user_id, id, name, scope, expires_at FROM api_tokens
1597 WHERE token_hash = ? AND (expires_at IS NULL OR expires_at > ?)`,
1598 tokenHash, fmtTime(time.Now())).Scan(&userID, &t.ID, &t.Name, &t.Scope, &exp)
1599 if errors.Is(err, sql.ErrNoRows) {
1600 return User{}, APIToken{}, ErrNotFound
1601 }
1602 if err != nil {
1603 return User{}, APIToken{}, err
1604 }
1605 t.ExpiresAt = parseTime(exp)
1606 s.DB.Exec("UPDATE api_tokens SET last_used_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE token_hash = ?", tokenHash)
1607 u, err := s.UserByID(userID)
1608 return u, t, err
1609}
1610
1611func (s *Store) ListAPITokens(userID int64) ([]APIToken, error) {
1612 rows, err := s.DB.Query(`
1613 SELECT t.id, t.name, t.scope, t.created_at, t.expires_at, t.last_used_at, COALESCE(p.name, '')
1614 FROM api_tokens t LEFT JOIN api_tokens p ON p.id = t.created_by_token
1615 WHERE t.user_id = ? ORDER BY t.name`, userID)
1616 if err != nil {
1617 return nil, err
1618 }
1619 defer rows.Close()
1620 var out []APIToken
1621 for rows.Next() {
1622 var t APIToken
1623 var exp, used sql.NullString
1624 if err := rows.Scan(&t.ID, &t.Name, &t.Scope, &t.CreatedAt, &exp, &used, &t.CreatedBy); err != nil {
1625 return nil, err
1626 }
1627 t.ExpiresAt = parseTime(exp)
1628 t.LastUsedAt = parseTime(used)
1629 out = append(out, t)
1630 }
1631 return out, rows.Err()
1632}
1633
1634// Created is what a token made, directly or through tokens it made:
1635// token names and SSH key fingerprints.
1636type Created struct {
1637 Tokens []string `json:"tokens"`
1638 Keys []string `json:"keys"`
1639}
1640
1641// chainCTE selects the token named by the first argument and every
1642// token created from it, at any depth.
1643const chainCTE = `WITH RECURSIVE chain(id) AS (
1644 SELECT ? UNION SELECT t.id FROM api_tokens t JOIN chain ON t.created_by_token = chain.id)`
1645
1646// RevokeAPIToken deletes the user's token by name and returns what it
1647// created. withCreated deletes those too; otherwise they stay and lose
1648// the link to the revoked token.
1649func (s *Store) RevokeAPIToken(userID int64, name string, withCreated bool) (Created, error) {
1650 tx, err := s.DB.Begin()
1651 if err != nil {
1652 return Created{}, err
1653 }
1654 defer tx.Rollback()
1655 var id int64
1656 err = tx.QueryRow("SELECT id FROM api_tokens WHERE user_id = ? AND name = ?", userID, name).Scan(&id)
1657 if errors.Is(err, sql.ErrNoRows) {
1658 return Created{}, ErrNotFound
1659 }
1660 if err != nil {
1661 return Created{}, err
1662 }
1663 var c Created
1664 rows, err := tx.Query(chainCTE+` SELECT name FROM api_tokens WHERE id IN (SELECT id FROM chain) AND id != ? ORDER BY name`, id, id)
1665 if err != nil {
1666 return Created{}, err
1667 }
1668 for rows.Next() {
1669 var n string
1670 if err := rows.Scan(&n); err != nil {
1671 rows.Close()
1672 return Created{}, err
1673 }
1674 c.Tokens = append(c.Tokens, n)
1675 }
1676 rows.Close()
1677 var keyIDs []int64
1678 rows, err = tx.Query(chainCTE+` SELECT id, fingerprint FROM ssh_keys WHERE created_by_token IN (SELECT id FROM chain) ORDER BY id`, id)
1679 if err != nil {
1680 return Created{}, err
1681 }
1682 for rows.Next() {
1683 var kid int64
1684 var fp string
1685 if err := rows.Scan(&kid, &fp); err != nil {
1686 rows.Close()
1687 return Created{}, err
1688 }
1689 keyIDs = append(keyIDs, kid)
1690 c.Keys = append(c.Keys, fp)
1691 }
1692 rows.Close()
1693
1694 if !withCreated {
1695 if _, err := tx.Exec("DELETE FROM api_tokens WHERE id = ?", id); err != nil {
1696 return Created{}, err
1697 }
1698 return c, tx.Commit()
1699 }
1700 if len(keyIDs) > 0 {
1701 args := make([]any, len(keyIDs))
1702 for i, k := range keyIDs {
1703 args[i] = k
1704 }
1705 if _, err := tx.Exec("DELETE FROM ssh_keys WHERE id IN (?"+strings.Repeat(", ?", len(keyIDs)-1)+")", args...); err != nil {
1706 return Created{}, err
1707 }
1708 if err := bumpKeyEpoch(tx); err != nil {
1709 return Created{}, err
1710 }
1711 }
1712 if _, err := tx.Exec(chainCTE+` DELETE FROM api_tokens WHERE id IN (SELECT id FROM chain)`, id); err != nil {
1713 return Created{}, err
1714 }
1715 if err := tx.Commit(); err != nil {
1716 return Created{}, err
1717 }
1718 if len(keyIDs) > 0 {
1719 s.announce(Revoked{KeyIDs: keyIDs})
1720 }
1721 return c, nil
1722}
1723```
1724
1725Before writing `nullID`, run `grep -rn "func nullID" internal/store`; if one exists, use it and drop this copy.
1726
1727- [ ] **Step 5: Keys in the store**
1728
1729In `internal/store/users.go`, add to `SSHKey` after `LastUsedAt`:
1730
1731```go
1732 CreatedBy string // name of the API token that added the key; "" for none. ListSSHKeys only.
1733```
1734
1735Replace `AddSSHKey`:
1736
1737```go
1738// KeyOrigin is how a key came to be.
1739type KeyOrigin struct {
1740 CreatedByToken int64 // the API token that added it; 0 for none
1741}
1742
1743// AddSSHKey registers a key and bumps the key epoch in one transaction.
1744func (s *Store) AddSSHKey(userID int64, fingerprint, algo string, blob []byte, scope, label string) error {
1745 return s.AddSSHKeyFrom(userID, fingerprint, algo, blob, scope, label, KeyOrigin{})
1746}
1747
1748// AddSSHKeyFrom is AddSSHKey recording where the key came from.
1749func (s *Store) AddSSHKeyFrom(userID int64, fingerprint, algo string, blob []byte, scope, label string, o KeyOrigin) error {
1750 tx, err := s.DB.Begin()
1751 if err != nil {
1752 return err
1753 }
1754 defer tx.Rollback()
1755 if _, err := tx.Exec(
1756 "INSERT INTO ssh_keys (user_id, fingerprint, algo, blob, scope, label, created_by_token) VALUES (?, ?, ?, ?, ?, ?, ?)",
1757 userID, fingerprint, algo, blob, scope, label, nullID(o.CreatedByToken)); err != nil {
1758 if isUniqueErr(err) {
1759 return ErrDuplicateKey
1760 }
1761 return err
1762 }
1763 if err := bumpKeyEpoch(tx); err != nil {
1764 return err
1765 }
1766 return tx.Commit()
1767}
1768```
1769
1770`ListSSHKeys`:
1771
1772```go
1773func (s *Store) ListSSHKeys(userID int64) ([]SSHKey, error) {
1774 rows, err := s.DB.Query(
1775 `SELECT k.id, k.user_id, k.fingerprint, k.algo, k.blob, k.scope, k.label, k.created_at,
1776 COALESCE(k.last_used_at, ''), COALESCE(t.name, '')
1777 FROM ssh_keys k LEFT JOIN api_tokens t ON t.id = k.created_by_token
1778 WHERE k.user_id = ? ORDER BY k.id`,
1779 userID)
1780 if err != nil {
1781 return nil, err
1782 }
1783 defer rows.Close()
1784 var keys []SSHKey
1785 for rows.Next() {
1786 var k SSHKey
1787 if err := rows.Scan(&k.ID, &k.UserID, &k.Fingerprint, &k.Algo, &k.Blob, &k.Scope, &k.Label, &k.CreatedAt, &k.LastUsedAt, &k.CreatedBy); err != nil {
1788 return nil, err
1789 }
1790 keys = append(keys, k)
1791 }
1792 return keys, rows.Err()
1793}
1794```
1795
1796- [ ] **Step 6: Run the store tests**
1797
1798Run: `go test ./internal/store -count=1`
1799Expected: PASS. (`go build ./...` fails until Task 2.2 updates the callers.)
1800
1801- [ ] **Step 7: Commit**
1802
1803```bash
1804git add internal/store
1805git commit -S -m "store: tokens and keys record the token that created them; chained revoke
1806
1807Ref #257"
1808```
1809
1810### Task 2.2: `MintsCredential`, `Ctx.Expires`, and the API wiring
1811
1812**Files:**
1813- Modify: `internal/control/control.go` — `Ctx` (21-57), `Command` (79-91), `Dispatch` (after line 161)
1814- Modify: `internal/httpd/api.go:30-78`, `:126-144`; `internal/httpd/apiread.go:26`
1815- Modify: registrations in `internal/control/token.go:16`, `identity.go:33`, `deploykey.go:16`, `runnerrepo.go:21`, `web.go:16`, `adminhost.go:24`, `:53`, `:58`, `register.go:38`
1816- Test: `internal/control/token_test.go` (create)
1817
1818**Interfaces:**
1819- Consumes: `store.APITokenUser` returning `APIToken` (Task 2.1).
1820- Produces:
1821 - `Command.MintsCredential bool`
1822 - `Ctx.TokenID int64` — the API token behind the request, 0 for none.
1823 - `Ctx.Expires *time.Time` — when the credential behind the request lapses; nil when it does not. MR 3 sets it for keys.
1824
1825- [ ] **Step 1: Write the failing tests**
1826
1827`internal/control/token_test.go`:
1828
1829```go
1830package control
1831
1832import (
1833 "bytes"
1834 "slices"
1835 "strings"
1836 "testing"
1837 "time"
1838
1839 "gitbay.org/gitbay/internal/protocol"
1840 "gitbay.org/gitbay/internal/store"
1841)
1842
1843// The minting commands, pinned: adding one to the list, or dropping
1844// one, is a decision this test makes someone take.
1845func TestMintingCommandsMarked(t *testing.T) {
1846 want := []string{
1847 "admin email verify", "admin invite", "admin user create", "email verify",
1848 "keys add", "repo deploy-key add", "repo runner add", "token create", "web login",
1849 }
1850 var got []string
1851 for _, cmd := range Commands() {
1852 if cmd.MintsCredential {
1853 got = append(got, joinPath(cmd.Path))
1854 }
1855 }
1856 slices.Sort(got)
1857 if !slices.Equal(got, want) {
1858 t.Fatalf("MintsCredential on %q, want %q", got, want)
1859 }
1860}
1861
1862// Dispatch refuses before the command runs, so no arguments are needed.
1863func TestExpiringCredentialCannotMint(t *testing.T) {
1864 exp := time.Now().Add(time.Hour)
1865 for _, cmd := range Commands() {
1866 if !cmd.MintsCredential {
1867 continue
1868 }
1869 var out, errOut bytes.Buffer
1870 c := &Ctx{User: store.User{ID: 1, Username: "root", IsAdmin: true}, Scope: "full", Expires: &exp, Stdout: &out, Stderr: &errOut}
1871 if code := Dispatch(c, cmd.Path); code != protocol.ExitDenied || !strings.Contains(errOut.String(), "expires") {
1872 t.Errorf("%s: exit %d %q, want %d and the reason", joinPath(cmd.Path), code, errOut.String(), protocol.ExitDenied)
1873 }
1874 }
1875}
1876
1877func TestTokenCreateDefaultsToReadAndRecordsCreator(t *testing.T) {
1878 st, _, uid := newQueueTestRepo(t)
1879 if err := st.CreateAPIToken(uid, "parent", "h-parent", "full", nil, 0); err != nil {
1880 t.Fatal(err)
1881 }
1882 _, parent, err := st.APITokenUser("h-parent")
1883 if err != nil {
1884 t.Fatal(err)
1885 }
1886 c, errOut := pruneCtx(st, t.TempDir(), store.User{ID: uid, Username: "alice"})
1887 c.Cfg.Limits.WriteRate = -1
1888 c.TokenID = parent.ID
1889 if code := Dispatch(c, []string{"token", "create", "--name", "child"}); code != protocol.ExitOK {
1890 t.Fatalf("exit %d: %s", code, errOut)
1891 }
1892 toks, err := st.ListAPITokens(uid)
1893 if err != nil {
1894 t.Fatal(err)
1895 }
1896 for _, tk := range toks {
1897 if tk.Name == "child" && (tk.Scope != "read" || tk.CreatedBy != "parent") {
1898 t.Fatalf("child: %+v", tk)
1899 }
1900 }
1901}
1902```
1903
1904- [ ] **Step 2: Run them and see them fail**
1905
1906Run: `go test ./internal/control -run 'TestMintingCommandsMarked|TestExpiringCredentialCannotMint|TestTokenCreateDefaultsToRead' -count=1`
1907Expected: FAIL to compile, `unknown field MintsCredential`.
1908
1909- [ ] **Step 3: `Ctx`, `Command`, `Dispatch`**
1910
1911In `Ctx`, after `Source string`:
1912
1913```go
1914 // TokenID is the API token behind this request, 0 for none. A
1915 // credential the request creates records it.
1916 TokenID int64
1917 // Expires is when the credential behind this request lapses; nil
1918 // when it does not. Dispatch refuses MintsCredential commands when
1919 // it is set.
1920 Expires *time.Time
1921```
1922
1923In `Command`, after `ReadOnly`:
1924
1925```go
1926 // MintsCredential marks a command that creates a credential or a way
1927 // to obtain one: tokens, keys, login links, invites, accounts,
1928 // verified addresses. An expiring credential may not run it.
1929 MintsCredential bool
1930```
1931
1932In `Dispatch`, after the `c.ReadOnly && !cmd.ReadOnly` check:
1933
1934```go
1935 // What an expiring credential creates would outlive it (#257).
1936 if cmd.MintsCredential && c.Expires != nil {
1937 return c.fail(protocol.ExitDenied,
1938 "%s creates a credential, and the one this request came with expires; use a token or key without an expiry", joinPath(cmd.Path))
1939 }
1940```
1941
1942- [ ] **Step 4: Mark the nine commands**
1943
1944Add `MintsCredential: true,` to each registration: `token create` (`token.go:16`), `keys add` (`identity.go:33`), `repo deploy-key add` (`deploykey.go:16`), `repo runner add` (`runnerrepo.go:21`), `web login` (`web.go:16`), `admin user create` (`adminhost.go:24`), `admin email verify` (`adminhost.go:53`), `admin invite` (`adminhost.go:58`), `email verify` (`register.go:38`). For example:
1945
1946```go
1947 register(Command{Path: []string{"web", "login"},
1948 Summary: "mint a one-time browser login URL",
1949 Usage: "web login",
1950 MintsCredential: true,
1951 Examples: []string{"web login"}, Run: runWebLogin})
1952```
1953
1954- [ ] **Step 5: The API passes the token**
1955
1956In `internal/httpd/api.go`, `apiAuth` returns the token:
1957
1958```go
1959// apiAuth resolves the bearer token; failures are uniform 401s.
1960func (s *Server) apiAuth(w http.ResponseWriter, r *http.Request) (store.User, store.APIToken, bool) {
1961 token, ok := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ")
1962 if !ok || token == "" {
1963 w.Header().Set("WWW-Authenticate", `Bearer realm="gitbay api"`)
1964 apiError(w, http.StatusUnauthorized, "missing bearer token; mint one over SSH: token create --name <n>")
1965 return store.User{}, store.APIToken{}, false
1966 }
1967 user, tok, err := s.st.APITokenUser(store.HashToken(strings.TrimSpace(token)))
1968 if err != nil {
1969 if errors.Is(err, store.ErrNotFound) {
1970 apiError(w, http.StatusUnauthorized, "invalid or expired token")
1971 return store.User{}, store.APIToken{}, false
1972 }
1973 apiError(w, http.StatusInternalServerError, "internal error")
1974 return store.User{}, store.APIToken{}, false
1975 }
1976 return user, tok, true
1977}
1978```
1979
1980In `apiCmd`: `user, tok, ok := s.apiAuth(w, r)`, and in the `Ctx` literal replace `ReadOnly: scope == "read",` with:
1981
1982```go
1983 ReadOnly: tok.Scope == "read",
1984 TokenID: tok.ID,
1985 Expires: tok.ExpiresAt,
1986```
1987
1988`apiRead` keeps `user, _, ok := s.apiAuth(w, r)`; it compiles unchanged.
1989
1990- [ ] **Step 6: Run the tests**
1991
1992Run: `go test ./internal/control -run 'TestMintingCommandsMarked|TestExpiringCredentialCannotMint' -count=1`
1993Expected: PASS. `TestTokenCreateDefaultsToRead...` still fails until Task 2.3.
1994
1995- [ ] **Step 7: Commit**
1996
1997```bash
1998git add internal/control/control.go internal/control/token_test.go internal/control/*.go internal/httpd/api.go
1999git commit -S -m "control: expiring credentials cannot run credential-minting commands
2000
2001Ref #257"
2002```
2003
2004### Task 2.3: commands record their token; `token create` defaults to read; `token revoke --created`
2005
2006**Files:**
2007- Modify: `internal/control/token.go` (registrations 16-34, `runTokenCreate` 49-88, `runTokenList` 90-122, `runTokenRevoke` 124-137)
2008- Modify: `internal/control/identity.go` — `runKeysList` (76-100), `runKeysAdd` (152)
2009- Modify: `internal/control/deploykey.go:71`, `internal/control/runnerrepo.go:60`, `internal/control/adminhost.go:125`
2010- Modify: `e2e/api_test.go:50`, `:266-282` (`mintToken`)
2011
2012**Interfaces:**
2013- Consumes: `Ctx.TokenID`, `store.KeyOrigin`, `Store.AddSSHKeyFrom`, `Store.RevokeAPIToken` (Tasks 2.1–2.2).
2014
2015- [ ] **Step 1: `token create`**
2016
2017Registration:
2018
2019```go
2020 register(Command{Path: []string{"token", "create"},
2021 Summary: "mint an API token (shown once)",
2022 Usage: "token create --name <n> [--scope read|full] [--ttl 30d|720h]",
2023 Flags: []Flag{
2024 {"--name", "<n>", "the token's name", ""},
2025 {"--scope", "read|full", "what the token may do; full is needed to change anything", "read"},
2026 {"--ttl", "30d|720h", "how long the token is valid; an expiring token cannot mint credentials", "never expires"},
2027 },
2028 Examples: []string{"token create --name laptop --ttl 30d", "token create --name phone --scope full"},
2029 MintsCredential: true,
2030 Run: runTokenCreate})
2031```
2032
2033In `runTokenCreate`: the `parseFlags` usage becomes `Usage: c.Cmd.Usage`; `name, scope, ttl := f.Value("--name"), "read", f.Value("--ttl")`; the store call:
2034
2035```go
2036 if err := c.Store.CreateAPIToken(c.User.ID, name, store.HashToken(token), scope, expires, c.TokenID); err != nil {
2037```
2038
2039- [ ] **Step 2: `token list` shows the creator in JSON**
2040
2041In `runTokenList`, the `out` struct gains `CreatedBy string `json:"created_by,omitempty"`` after `LastUsedAt`, and the append becomes `out{t.Name, t.Scope, t.CreatedAt, t.ExpiresAt, t.LastUsedAt, t.CreatedBy}`. Plain output is unchanged.
2042
2043- [ ] **Step 3: `token revoke [--created]`**
2044
2045Registration:
2046
2047```go
2048 register(Command{Path: []string{"token", "revoke"},
2049 Summary: "revoke an API token by name",
2050 Usage: "token revoke <name> [--created]",
2051 Flags: []Flag{
2052 {"--created", "", "also revoke the tokens and keys it created, at any depth", ""},
2053 },
2054 Examples: []string{"token revoke laptop", "token revoke laptop --created"},
2055 Run: runTokenRevoke})
2056```
2057
2058```go
2059func runTokenRevoke(c *Ctx, args []string) int {
2060 f, err := parseFlags(args, flagSpec{Bools: []string{"--created"}, MaxPos: 1, Usage: c.Cmd.Usage})
2061 if err != nil {
2062 return c.fail(protocol.ExitUsage, "%v", err)
2063 }
2064 name := f.pos(0)
2065 if name == "" {
2066 return c.usage()
2067 }
2068 withCreated := f.Has("--created")
2069 created, err := c.Store.RevokeAPIToken(c.User.ID, name, withCreated)
2070 if err != nil {
2071 if errors.Is(err, store.ErrNotFound) {
2072 return c.fail(protocol.ExitNotFound, "no token named %q", name)
2073 }
2074 return c.fail(protocol.ExitFailure, "%v", err)
2075 }
2076 type out struct {
2077 Revoked string `json:"revoked"`
2078 Created store.Created `json:"created"`
2079 CreatedRevoked bool `json:"created_revoked"`
2080 }
2081 d := out{name, created, withCreated}
2082 return c.emit(d, func(w io.Writer) {
2083 fmt.Fprintf(w, "revoked %s\n", name)
2084 if len(created.Tokens)+len(created.Keys) == 0 {
2085 return
2086 }
2087 if withCreated {
2088 fmt.Fprintln(w, "and what it created:")
2089 } else {
2090 fmt.Fprintln(w, "it created these, still in place:")
2091 }
2092 for _, n := range created.Tokens {
2093 fmt.Fprintf(w, " token %s\n", n)
2094 }
2095 for _, fp := range created.Keys {
2096 fmt.Fprintf(w, " key %s\n", fp)
2097 }
2098 })
2099}
2100```
2101
2102- [ ] **Step 4: Key-adding commands record the token**
2103
2104`identity.go`, `runKeysAdd`:
2105
2106```go
2107 if err := c.Store.AddSSHKeyFrom(c.User.ID, fp, pub.Type(), pub.Marshal(), scope, label, store.KeyOrigin{CreatedByToken: c.TokenID}); err != nil {
2108```
2109
2110`deploykey.go:71`:
2111
2112```go
2113 if err := c.Store.AddSSHKeyFrom(c.User.ID, fp, pub.Type(), pub.Marshal(), scope, label, store.KeyOrigin{CreatedByToken: c.TokenID}); err != nil {
2114```
2115
2116`runnerrepo.go:60`:
2117
2118```go
2119 if err := c.Store.AddSSHKeyFrom(c.User.ID, fp, pub.Type(), pub.Marshal(), "runner", label, store.KeyOrigin{CreatedByToken: c.TokenID}); err != nil {
2120```
2121
2122`adminhost.go:125`:
2123
2124```go
2125 if err := c.Store.AddSSHKeyFrom(uid, fp, pub.Type(), pub.Marshal(), "full", label, store.KeyOrigin{CreatedByToken: c.TokenID}); err != nil {
2126```
2127
2128`keys list` JSON: in `runKeysList` the `out` struct gains `CreatedBy string `json:"created_by,omitempty"`` and the append passes `k.CreatedBy`. Plain output is unchanged in this MR.
2129
2130- [ ] **Step 5: e2e callers that write with a default-scope token**
2131
2132`e2e/api_test.go:50`: `"token", "create", "--name", "ci", "--scope", "full", "--json"`.
2133`mintToken` (`e2e/api_test.go:268`): `"token", "create", "--name", name, "--scope", "full", "--json"`.
2134Then `grep -rn '"token", "create"' e2e` and check each remaining call: a token only used for reads, or for a refusal, needs nothing.
2135
2136- [ ] **Step 6: Run the tests**
2137
2138Run: `go build ./... && go vet ./... && go test ./internal/control ./internal/store ./internal/httpd -count=1`
2139Expected: PASS, including `TestHelpIsComplete` (every flag in the usage is described) and `TestTokenCreateDefaultsToReadAndRecordsCreator`.
2140
2141- [ ] **Step 7: Commit**
2142
2143```bash
2144git add internal/control e2e/api_test.go
2145git commit -S -m "token: default --scope read; record the creating token; revoke --created
2146
2147Ref #257"
2148```
2149
2150### Task 2.4: e2e — delegation over the API
2151
2152**Files:**
2153- Create: `e2e/tokenorigin_test.go`
2154
2155**Interfaces:**
2156- Consumes: `fingerprint` (MR 1, `e2e/revoke_test.go`), `inst.apiCall`.
2157
2158- [ ] **Step 1: Write the test**
2159
2160```go
2161package e2e
2162
2163import (
2164 "encoding/json"
2165 "fmt"
2166 "os"
2167 "strings"
2168 "testing"
2169)
2170
2171// An expiring token cannot mint a credential that outlives it, and
2172// revoking a token can take what it created with it (#257).
2173func TestTokenDelegation(t *testing.T) {
2174 t.Parallel()
2175 inst := startInstanceWith(t, "[api]\nenabled = true\n")
2176 aliceKey := inst.newKey(t, "alice")
2177 inst.admin(t, "admin", "user", "create", "alice", "--key", aliceKey+".pub")
2178
2179 mint := func(args ...string) (token, scope string) {
2180 t.Helper()
2181 out, errOut, code := inst.ssh(t, aliceKey, "", append([]string{"token", "create", "--json"}, args...)...)
2182 if code != 0 {
2183 t.Fatalf("token create %v: %s", args, errOut)
2184 }
2185 var env struct {
2186 Data struct {
2187 Token string `json:"token"`
2188 Scope string `json:"scope"`
2189 } `json:"data"`
2190 }
2191 if err := json.Unmarshal([]byte(out), &env); err != nil {
2192 t.Fatalf("token create output: %v %s", err, out)
2193 }
2194 return env.Data.Token, env.Data.Scope
2195 }
2196 if _, scope := mint("--name", "plain"); scope != "read" {
2197 t.Fatalf("default scope %q, want read", scope)
2198 }
2199 brief, _ := mint("--name", "brief", "--scope", "full", "--ttl", "1h")
2200 lasting, _ := mint("--name", "lasting", "--scope", "full")
2201
2202 spare := inst.newKey(t, "spare")
2203 pub, err := os.ReadFile(spare + ".pub")
2204 if err != nil {
2205 t.Fatal(err)
2206 }
2207 status, body := inst.apiCall(t, brief, []string{"keys", "add"}, string(pub))
2208 if status != 403 || !strings.Contains(fmt.Sprint(body["error"]), "expires") {
2209 t.Fatalf("expiring token added a key: %d %v", status, body)
2210 }
2211 if status, _ := inst.apiCall(t, brief, []string{"whoami"}, ""); status != 200 {
2212 t.Fatalf("expiring token refused a read: %d", status)
2213 }
2214 if status, body := inst.apiCall(t, lasting, []string{"keys", "add"}, string(pub)); status != 200 {
2215 t.Fatalf("keys add: %d %v", status, body)
2216 }
2217 if status, body := inst.apiCall(t, lasting, []string{"token", "create", "--name", "child"}, ""); status != 200 {
2218 t.Fatalf("token create: %d %v", status, body)
2219 }
2220 if _, errOut, code := inst.ssh(t, spare, "", "whoami"); code != 0 {
2221 t.Fatalf("the added key does not work: %s", errOut)
2222 }
2223
2224 out, errOut, code := inst.ssh(t, aliceKey, "", "token", "revoke", "lasting", "--created")
2225 if code != 0 || !strings.Contains(out, "token child") || !strings.Contains(out, fingerprint(t, spare+".pub")) {
2226 t.Fatalf("revoke --created: exit %d\n%s%s", code, out, errOut)
2227 }
2228 if _, _, code := inst.ssh(t, spare, "", "whoami"); code == 0 {
2229 t.Fatal("a key the revoked token created still works")
2230 }
2231 if out, _, _ := inst.ssh(t, aliceKey, "", "token", "list"); strings.Contains(out, "child") {
2232 t.Fatalf("the child token survived:\n%s", out)
2233 }
2234}
2235```
2236
2237- [ ] **Step 2: Run it**
2238
2239Run: `go test ./e2e -run TestTokenDelegation -count=1`
2240Expected: PASS.
2241
2242- [ ] **Step 3: Commit**
2243
2244```bash
2245git add e2e/tokenorigin_test.go
2246git commit -S -m "e2e: expiring tokens refused on minting; revoke --created
2247
2248Ref #257"
2249```
2250
2251### Task 2.5: docs and release note
2252
2253**Files:**
2254- Modify: `.gitbay/wiki/API.org:14-33` (Tokens), `.gitbay/wiki/Threat-Model.org` (Trust boundaries), `.gitbay/wiki/Architecture/05-Identity-and-Access.org:20`, `09-Controls.org:29`, `10-Known-Gaps.org`, `.gitbay/wiki/Parity.org:358`, `CHANGELOG.org`, `internal/web/templates/account.html:194`
2255
2256- [ ] **Step 1: Edit the pages**
2257
2258`API.org`, the Tokens section's first paragraph and code block become:
2259
2260```
2261Tokens are minted wherever the registry is reached: over SSH, on the
2262API, anywhere. =token create= makes a =read= token unless =--scope full=
2263is given; a read token runs only commands marked read-only. A full-scope
2264token can mint another, but a token with a =--ttl= cannot run any
2265command that creates a credential — =token create=, =keys add=,
2266=repo deploy-key add=, =repo runner add=, =web login=, =admin invite=,
2267=admin user create=, =email verify=, =admin email verify= — since what
2268it made would outlive it. Give a token the narrowest scope and shortest
2269TTL that does its job, and revoke it when the job is over.
2270
2271#+begin_src sh
2272gitbay auth token create --name ci [--scope read|full] [--ttl 30d]
2273gitbay auth token list
2274gitbay auth token revoke ci [--created]
2275#+end_src
2276
2277Tokens and keys record the token they were created through. =token
2278revoke= prints what the token created, at any depth; with =--created=
2279it revokes those too, and their SSH connections close. Without it they
2280stay and the link is dropped.
2281```
2282
2283`Threat-Model.org`, in Trust boundaries, replace "so a bearer token is worth exactly its scope and no more." with "so a bearer token is worth exactly its scope and no more, and a credential with an expiry cannot create one that outlives it."
2284
2285`05-Identity-and-Access.org`: the API token row's Scope cell becomes `=read= (default) or =full=; with an expiry, no credential-minting command`, and its Revocation cell `=token revoke [--created]=`.
2286
2287`09-Controls.org`:
2288
2289```
2290| Delegation bounded by the delegating credential | in place | expiring tokens refused on =MintsCredential= commands; credentials record their creating token (=internal/control/control.go=) |
2291```
2292
2293`10-Known-Gaps.org`: delete the `#257` row and the "#257 refuses credential creation ..." sentence, leaving the paragraph out if nothing remains in it.
2294
2295`Parity.org`, after the `API token mint` row:
2296
2297```
2298| API token revoke with what it created | yes | no | no |
2299```
2300
2301`account.html:194`: `gitbay auth token create --name laptop # API tokens, read-only unless --scope full`.
2302
2303`CHANGELOG.org`, under the unreleased heading (see Global constraints):
2304
2305```
2306*Upgrade note.* =token create= makes a =read= token unless given
2307=--scope full=. A script that mints a token and then writes with it
2308must add =--scope full=. Existing tokens keep their scope.
2309
2310- A token with a =--ttl= is refused on every command that creates a
2311 credential: tokens, keys, deploy keys, runner keys, login links,
2312 invites, accounts and verified addresses (#257).
2313- Tokens and SSH keys record the token they were created through.
2314 =token revoke <name>= lists what it created; =--created= revokes
2315 those too.
2316- Removing an SSH key, a deploy key, or disabling an account closes the
2317 connections the key opened, a push in flight included (#256).
2318```
2319
2320(The #256 line belongs to MR 1's changes; add it here if MR 1 did not touch the changelog.)
2321
2322- [ ] **Step 2: Commit, open the MR**
2323
2324```bash
2325git add .gitbay/wiki CHANGELOG.org internal/web/templates/account.html
2326git commit -S -m "wiki: token delegation, read default; release note
2327
2328Closes #257"
2329git push -u origin token-delegation
2330gitbay mr create --source token-delegation --target main --title "token: expiring tokens cannot mint credentials; record creator; default read scope"
2331```
2332
2333---
2334
2335# MR 3: optional expiry for SSH and deploy keys (branch `key-expiry`, #277)
2336
2337The issue says to consider this with #257. An expiring key is treated
2338like an expiring token: `Exec` sets `Ctx.Expires`, so `Dispatch` refuses
2339the minting commands to it (open question 1).
2340
2341### Task 3.1: migration 0061 and the store
2342
2343**Files:**
2344- Create: `internal/store/migrations/0061_ssh_key_expiry.up.sql`, `.down.sql`
2345- Modify: `internal/store/users.go` — `SSHKey`, `KeyOrigin`, `AddSSHKeyFrom`, `SSHKeyByFingerprint` (324-333), `SSHKeyByID` (502-511), `ListSSHKeys`, `ListDeployKeys` (514-532)
2346- Modify: `internal/store/revoke.go` — `LiveSSHKeys`
2347- Test: `internal/store/keyexpiry_test.go` (create)
2348
2349**Interfaces:**
2350- Produces:
2351 - `SSHKey.ExpiresAt *time.Time` — nil when the key never expires; filled by every key query.
2352 - `func (k SSHKey) Expired(now time.Time) bool`
2353 - `KeyOrigin.ExpiresAt *time.Time`
2354 - `LiveSSHKeys` also excludes expired keys.
2355
2356- [ ] **Step 1: Write the failing test**
2357
2358```go
2359package store
2360
2361import (
2362 "testing"
2363 "time"
2364)
2365
2366func TestKeyExpiry(t *testing.T) {
2367 s, uid, _ := revokeFixture(t)
2368 past, future := time.Now().Add(-time.Minute), time.Now().Add(time.Hour)
2369 for fp, exp := range map[string]*time.Time{"SHA256:old": &past, "SHA256:new": &future, "SHA256:ever": nil} {
2370 if err := s.AddSSHKeyFrom(uid, fp, "ssh-ed25519", []byte(fp), "full", "", KeyOrigin{ExpiresAt: exp}); err != nil {
2371 t.Fatal(err)
2372 }
2373 }
2374 now := time.Now()
2375 ids := map[string]int64{}
2376 for _, fp := range []string{"SHA256:old", "SHA256:new", "SHA256:ever"} {
2377 k, err := s.SSHKeyByFingerprint(fp)
2378 if err != nil {
2379 t.Fatal(err)
2380 }
2381 ids[fp] = k.ID
2382 byID, err := s.SSHKeyByID(k.ID)
2383 if err != nil || (byID.ExpiresAt == nil) != (k.ExpiresAt == nil) {
2384 t.Fatalf("%s by id: %+v %v", fp, byID, err)
2385 }
2386 if got, want := k.Expired(now), fp == "SHA256:old"; got != want {
2387 t.Errorf("%s Expired = %v, want %v", fp, got, want)
2388 }
2389 }
2390 live, err := s.LiveSSHKeys([]int64{ids["SHA256:old"], ids["SHA256:new"], ids["SHA256:ever"]})
2391 if err != nil {
2392 t.Fatal(err)
2393 }
2394 if live[ids["SHA256:old"]] || !live[ids["SHA256:new"]] || !live[ids["SHA256:ever"]] {
2395 t.Fatalf("live = %v", live)
2396 }
2397 keys, err := s.ListSSHKeys(uid)
2398 if err != nil || len(keys) != 3 || keys[2].ExpiresAt != nil {
2399 t.Fatalf("list: %+v %v", keys, err)
2400 }
2401}
2402```
2403
2404- [ ] **Step 2: Run it and see it fail**
2405
2406Run: `go test ./internal/store -run TestKeyExpiry -count=1`
2407Expected: FAIL to compile, `unknown field ExpiresAt in struct literal of type KeyOrigin`.
2408
2409- [ ] **Step 3: Migration**
2410
2411`0061_ssh_key_expiry.up.sql`:
2412
2413```sql
2414-- When the key stops authenticating; NULL for never.
2415ALTER TABLE ssh_keys ADD COLUMN expires_at TEXT;
2416```
2417
2418`0061_ssh_key_expiry.down.sql`:
2419
2420```sql
2421ALTER TABLE ssh_keys DROP COLUMN expires_at;
2422```
2423
2424- [ ] **Step 4: Store**
2425
2426`SSHKey` gains, after `CreatedBy`:
2427
2428```go
2429 ExpiresAt *time.Time // nil when the key never expires
2430```
2431
2432and the method:
2433
2434```go
2435// Expired reports whether the key has lapsed at now.
2436func (k SSHKey) Expired(now time.Time) bool {
2437 return k.ExpiresAt != nil && !k.ExpiresAt.After(now)
2438}
2439```
2440
2441`KeyOrigin`:
2442
2443```go
2444// KeyOrigin is how a key came to be.
2445type KeyOrigin struct {
2446 CreatedByToken int64 // the API token that added it; 0 for none
2447 ExpiresAt *time.Time // when it stops authenticating; nil for never
2448}
2449```
2450
2451`AddSSHKeyFrom`'s insert:
2452
2453```go
2454 var exp any
2455 if o.ExpiresAt != nil {
2456 exp = fmtTime(*o.ExpiresAt)
2457 }
2458 if _, err := tx.Exec(
2459 "INSERT INTO ssh_keys (user_id, fingerprint, algo, blob, scope, label, created_by_token, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
2460 userID, fingerprint, algo, blob, scope, label, nullID(o.CreatedByToken), exp); err != nil {
2461```
2462
2463`SSHKeyByFingerprint` and `SSHKeyByID` select `expires_at` last and scan it through a `sql.NullString`:
2464
2465```go
2466func (s *Store) SSHKeyByFingerprint(fingerprint string) (SSHKey, error) {
2467 var k SSHKey
2468 var exp sql.NullString
2469 err := s.DB.QueryRow(
2470 "SELECT id, user_id, fingerprint, algo, blob, scope, label, expires_at FROM ssh_keys WHERE fingerprint = ?",
2471 fingerprint).Scan(&k.ID, &k.UserID, &k.Fingerprint, &k.Algo, &k.Blob, &k.Scope, &k.Label, &exp)
2472 if errors.Is(err, sql.ErrNoRows) {
2473 return k, ErrNotFound
2474 }
2475 k.ExpiresAt = parseTime(exp)
2476 return k, err
2477}
2478```
2479
2480`SSHKeyByID` is the same with `WHERE id = ?` and `id`.
2481
2482`ListSSHKeys`: add `k.expires_at` after `COALESCE(t.name, '')`, scan into `var exp sql.NullString` declared per row, then `k.ExpiresAt = parseTime(exp)`.
2483
2484`ListDeployKeys`:
2485
2486```go
2487func (s *Store) ListDeployKeys(repoID int64) ([]SSHKey, error) {
2488 rows, err := s.DB.Query(
2489 `SELECT id, user_id, fingerprint, algo, blob, scope, label, COALESCE(last_used_at, ''), expires_at
2490 FROM ssh_keys WHERE scope LIKE 'deploy:' || ? || ':%' ORDER BY id`,
2491 repoID)
2492 if err != nil {
2493 return nil, err
2494 }
2495 defer rows.Close()
2496 var keys []SSHKey
2497 for rows.Next() {
2498 var k SSHKey
2499 var exp sql.NullString
2500 if err := rows.Scan(&k.ID, &k.UserID, &k.Fingerprint, &k.Algo, &k.Blob, &k.Scope, &k.Label, &k.LastUsedAt, &exp); err != nil {
2501 return nil, err
2502 }
2503 k.ExpiresAt = parseTime(exp)
2504 keys = append(keys, k)
2505 }
2506 return keys, rows.Err()
2507}
2508```
2509
2510`LiveSSHKeys` in `revoke.go`:
2511
2512```go
2513// LiveSSHKeys reports which of ids still name a registered, unexpired
2514// key on an account that is not disabled.
2515func (s *Store) LiveSSHKeys(ids []int64) (map[int64]bool, error) {
2516 live := map[int64]bool{}
2517 if len(ids) == 0 {
2518 return live, nil
2519 }
2520 args := []any{fmtTime(time.Now())}
2521 for _, id := range ids {
2522 args = append(args, id)
2523 }
2524 rows, err := s.DB.Query(`SELECT k.id FROM ssh_keys k JOIN users u ON u.id = k.user_id
2525 WHERE u.disabled = 0 AND (k.expires_at IS NULL OR k.expires_at > ?)
2526 AND k.id IN (?`+strings.Repeat(", ?", len(ids)-1)+`)`, args...)
2527 if err != nil {
2528 return nil, err
2529 }
2530 defer rows.Close()
2531 for rows.Next() {
2532 var id int64
2533 if err := rows.Scan(&id); err != nil {
2534 return nil, err
2535 }
2536 live[id] = true
2537 }
2538 return live, rows.Err()
2539}
2540```
2541
2542Add `"time"` to `revoke.go`'s imports.
2543
2544- [ ] **Step 5: Run the tests**
2545
2546Run: `go test ./internal/store -count=1`
2547Expected: PASS.
2548
2549- [ ] **Step 6: Commit**
2550
2551```bash
2552git add internal/store
2553git commit -S -m "store: ssh_keys.expires_at; expired keys are not live
2554
2555Ref #277"
2556```
2557
2558### Task 3.2: expired keys refused at authentication, per exec, and in system mode
2559
2560**Files:**
2561- Modify: `internal/sshd/sshd.go` — `authenticate` (after line 148), `runExec`, `Exec` (the `Ctx` literal)
2562- Modify: `cmd/gitbayd/system.go:45-48`, `:80-84`
2563- Test: `internal/sshd/revoke_test.go` (append)
2564
2565**Interfaces:**
2566- Consumes: `SSHKey.Expired`, `SSHKey.ExpiresAt` (Task 3.1); `Ctx.Expires` (MR 2); `newTestServer`, `execStatus`, `waitClosed` (MR 1).
2567
2568- [ ] **Step 1: Write the failing tests**
2569
2570Append to `internal/sshd/revoke_test.go`:
2571
2572```go
2573// A key that expires while connected: the next exec is refused, and
2574// the sweep closes the connection.
2575func TestExpiredKeyRefusedAndCut(t *testing.T) {
2576 ts := newTestServer(t)
2577 past := time.Now().Add(-time.Second).UTC().Format("2006-01-02T15:04:05.000Z")
2578 if _, err := ts.st.DB.Exec("UPDATE ssh_keys SET expires_at = ? WHERE id = ?", past, ts.keyID); err != nil {
2579 t.Fatal(err)
2580 }
2581 if code, errOut := execStatus(ts.client, "whoami"); code != 4 || !strings.Contains(errOut, "expired") {
2582 t.Fatalf("whoami with an expired key: %d %q", code, errOut)
2583 }
2584 ts.srv.sweepOnce()
2585 waitClosed(t, ts.client)
2586}
2587
2588// An expiring key may not mint.
2589func TestExpiringKeyCannotMint(t *testing.T) {
2590 ts := newTestServer(t)
2591 future := time.Now().Add(time.Hour).UTC().Format("2006-01-02T15:04:05.000Z")
2592 if _, err := ts.st.DB.Exec("UPDATE ssh_keys SET expires_at = ? WHERE id = ?", future, ts.keyID); err != nil {
2593 t.Fatal(err)
2594 }
2595 if code, errOut := execStatus(ts.client, "token create --name x"); code != 4 || !strings.Contains(errOut, "expires") {
2596 t.Fatalf("token create with an expiring key: %d %q", code, errOut)
2597 }
2598}
2599```
2600
2601And a handshake test, which needs its own key: add to `revoke_test.go`
2602
2603```go
2604func TestExpiredKeyRefusedAtAuth(t *testing.T) {
2605 ts := newTestServer(t)
2606 _, priv, err := ed25519.GenerateKey(rand.Reader)
2607 if err != nil {
2608 t.Fatal(err)
2609 }
2610 signer, err := ssh.NewSignerFromKey(priv)
2611 if err != nil {
2612 t.Fatal(err)
2613 }
2614 pub := signer.PublicKey()
2615 past := time.Now().Add(-time.Minute)
2616 if err := ts.st.AddSSHKeyFrom(ts.uid, ssh.FingerprintSHA256(pub), pub.Type(), pub.Marshal(), "full", "", store.KeyOrigin{ExpiresAt: &past}); err != nil {
2617 t.Fatal(err)
2618 }
2619 _, err = ssh.Dial("tcp", ts.client.RemoteAddr().String(), &ssh.ClientConfig{
2620 User: "git",
2621 Auth: []ssh.AuthMethod{ssh.PublicKeys(signer)},
2622 HostKeyCallback: ssh.InsecureIgnoreHostKey(),
2623 Timeout: 5 * time.Second,
2624 })
2625 if err == nil {
2626 t.Fatal("an expired key authenticated")
2627 }
2628}
2629```
2630
2631with `"crypto/ed25519"`, `"crypto/rand"` and `"gitbay.org/gitbay/internal/store"` in the imports.
2632
2633- [ ] **Step 2: Run them and see them fail**
2634
2635Run: `go test ./internal/sshd -run 'TestExpiredKey|TestExpiringKeyCannotMint' -count=1`
2636Expected: FAIL: the expired key authenticates and whoami exits 0.
2637
2638- [ ] **Step 3: sshd**
2639
2640In `authenticate`, after the `if err != nil { ... }` block that handles unknown keys and before `s.authLimiter.success(ip)`:
2641
2642```go
2643 if key.Expired(time.Now()) {
2644 s.st.Audit(key.UserID, "auth.expired", map[string]any{"ip": ip, "fingerprint": fp})
2645 return nil, fmt.Errorf("key %s has expired", fp)
2646 }
2647```
2648
2649In `runExec`, after the lookup's error handling and before `UserByID`:
2650
2651```go
2652 if key.Expired(time.Now()) {
2653 fmt.Fprintln(ch.Stderr(), "this key has expired; remove it and add a new one")
2654 return protocol.ExitDenied
2655 }
2656```
2657
2658In `Exec`, the `Ctx` literal gains `Expires: key.ExpiresAt,`.
2659
2660- [ ] **Step 4: System mode**
2661
2662`cmd/gitbayd/system.go`, `authorized-keys`:
2663
2664```go
2665 key, err := st.SSHKeyByFingerprint(ssh.FingerprintSHA256(pub))
2666 if err != nil || key.Expired(time.Now()) {
2667 return nil // unknown or expired key: no output, auth fails
2668 }
2669```
2670
2671`shell`, after the `SSHKeyByID` error check:
2672
2673```go
2674 if key.Expired(time.Now()) {
2675 fmt.Fprintln(os.Stderr, "this key has expired; remove it and add a new one")
2676 os.Exit(protocol.ExitDenied)
2677 }
2678```
2679
2680Add `"time"` to the imports.
2681
2682- [ ] **Step 5: Run the tests**
2683
2684Run: `go build ./... && go test ./internal/sshd -count=1`
2685Expected: PASS.
2686
2687- [ ] **Step 6: Commit**
2688
2689```bash
2690git add internal/sshd cmd/gitbayd/system.go
2691git commit -S -m "sshd: refuse expired keys at auth and per exec; expiring keys cannot mint
2692
2693Ref #277"
2694```
2695
2696### Task 3.3: `--ttl` on `keys add` and `repo deploy-key add`; lists show last use and expiry
2697
2698**Files:**
2699- Modify: `internal/control/token.go` (add `ttlFlag` after `parseTTL`)
2700- Modify: `internal/control/identity.go` — `keys add` registration (33-44), `runKeysList`, `runKeysAdd`
2701- Modify: `internal/control/deploykey.go` — registration (16-23), `runDeployKeyAdd` (36-80), `runDeployKeyList` (82-115)
2702- Modify: `e2e/ssh_test.go:267`, `:276`
2703- Test: `internal/control/keyexpiry_test.go` (create)
2704
2705**Interfaces:**
2706- Produces:
2707 - `func (c *Ctx) ttlFlag(f flags) (*time.Time, int)` — nil when `--ttl` is absent; code -1 when the caller may go on.
2708 - `func (c *Ctx) usedText(ts string) string`, `func expiresText(t *time.Time, now time.Time) string`
2709
2710- [ ] **Step 1: Write the failing test**
2711
2712`internal/control/keyexpiry_test.go`:
2713
2714```go
2715package control
2716
2717import (
2718 "bytes"
2719 "crypto/ed25519"
2720 "crypto/rand"
2721 "strings"
2722 "testing"
2723 "time"
2724
2725 "golang.org/x/crypto/ssh"
2726
2727 "gitbay.org/gitbay/internal/protocol"
2728 "gitbay.org/gitbay/internal/store"
2729)
2730
2731// authorizedKey is a fresh public key as an authorized_keys line.
2732func authorizedKey(t *testing.T, comment string) string {
2733 t.Helper()
2734 pub, _, err := ed25519.GenerateKey(rand.Reader)
2735 if err != nil {
2736 t.Fatal(err)
2737 }
2738 sp, err := ssh.NewPublicKey(pub)
2739 if err != nil {
2740 t.Fatal(err)
2741 }
2742 return strings.TrimSpace(string(ssh.MarshalAuthorizedKey(sp))) + " " + comment + "\n"
2743}
2744
2745func TestKeysAddTTLAndList(t *testing.T) {
2746 st, repo, uid := newQueueTestRepo(t)
2747 user := store.User{ID: uid, Username: "alice"}
2748 run := func(stdin string, argv ...string) (string, string, int) {
2749 c, errOut := pruneCtx(st, t.TempDir(), user)
2750 c.Cfg.Limits.WriteRate = -1
2751 c.Stdin = strings.NewReader(stdin)
2752 code := Dispatch(c, argv)
2753 return c.Stdout.(*bytes.Buffer).String(), errOut.String(), code
2754 }
2755 if _, errOut, code := run(authorizedKey(t, "laptop"), "keys", "add", "--ttl", "1h"); code != protocol.ExitOK {
2756 t.Fatalf("keys add --ttl: %d %s", code, errOut)
2757 }
2758 if _, errOut, code := run(authorizedKey(t, "ci"), "repo", "deploy-key", "add", repo.Path(), "--ttl", "2d"); code != protocol.ExitOK {
2759 t.Fatalf("deploy-key add --ttl: %d %s", code, errOut)
2760 }
2761 if _, _, code := run(authorizedKey(t, "x"), "keys", "add", "--ttl", "soon"); code != protocol.ExitUsage {
2762 t.Fatalf("bad ttl: exit %d", code)
2763 }
2764
2765 keys, err := st.ListSSHKeys(uid)
2766 if err != nil || len(keys) != 2 {
2767 t.Fatalf("keys: %+v %v", keys, err)
2768 }
2769 for _, k := range keys {
2770 if k.ExpiresAt == nil || k.ExpiresAt.Before(time.Now()) || k.ExpiresAt.After(time.Now().Add(49*time.Hour)) {
2771 t.Errorf("%s expires %v", k.Label, k.ExpiresAt)
2772 }
2773 }
2774 out, _, _ := run("", "keys", "list")
2775 if !strings.Contains(out, "\tlaptop\tnever used\texpires ") {
2776 t.Fatalf("keys list:\n%s", out)
2777 }
2778 out, _, _ = run("", "repo", "deploy-key", "list", repo.Path())
2779 if !strings.Contains(out, "\tci\tnever used\texpires ") {
2780 t.Fatalf("deploy-key list:\n%s", out)
2781 }
2782}
2783```
2784
2785- [ ] **Step 2: Run it and see it fail**
2786
2787Run: `go test ./internal/control -run TestKeysAddTTLAndList -count=1`
2788Expected: FAIL, `keys add --ttl` exits 2 (unknown flag).
2789
2790- [ ] **Step 3: Helpers**
2791
2792In `internal/control/token.go` after `parseTTL`:
2793
2794```go
2795// ttlFlag reads --ttl as an expiry; nil when the flag is absent. The
2796// code is -1 when the caller may go on.
2797func (c *Ctx) ttlFlag(f flags) (*time.Time, int) {
2798 if !f.Has("--ttl") {
2799 return nil, -1
2800 }
2801 d, err := parseTTL(f.Value("--ttl"))
2802 if err != nil || d <= 0 {
2803 return nil, c.fail(protocol.ExitUsage, "bad ttl %q: give a duration such as 30d or 720h", f.Value("--ttl"))
2804 }
2805 t := time.Now().Add(d)
2806 return &t, -1
2807}
2808```
2809
2810In `internal/control/identity.go` after `keyLabel`:
2811
2812```go
2813// usedText is a key's last use as a list shows it.
2814func (c *Ctx) usedText(ts string) string {
2815 switch {
2816 case ts == "":
2817 return "never used"
2818 case c.Term.Cols == 0:
2819 return "used " + stamp(ts)
2820 }
2821 return "used " + relAge(ts, termNow())
2822}
2823
2824// expiresText is a credential's expiry as a list shows it. It is
2825// absolute at a terminal too: relAge reads only the past.
2826func expiresText(t *time.Time, now time.Time) string {
2827 if t == nil {
2828 return "never expires"
2829 }
2830 s := stamp(t.UTC().Format(time.RFC3339Nano))
2831 if !t.After(now) {
2832 return "expired " + s
2833 }
2834 return "expires " + s
2835}
2836```
2837
2838Add `"time"` to `identity.go`'s imports.
2839
2840- [ ] **Step 4: `keys add --ttl`**
2841
2842Registration:
2843
2844```go
2845 register(Command{
2846 Path: []string{"keys", "add"},
2847 Summary: "register an SSH public key (authorized_keys format)",
2848 Usage: "keys add [--scope full|git|runner] [--label <text>] [--ttl 30d|720h] < key.pub",
2849 Flags: []Flag{
2850 {"--scope", "full|git|runner", "what the key may do", "full"},
2851 {"--label", "<text>", "a name for the key", ""},
2852 {"--ttl", "30d|720h", "how long the key authenticates; an expiring key cannot mint credentials", "never expires"},
2853 },
2854 Examples: []string{"keys add --label laptop < key.pub", "keys add --scope git --ttl 90d < ci.pub"},
2855 ReadsStdin: true,
2856 MintsCredential: true,
2857 Run: runKeysAdd,
2858 })
2859```
2860
2861In `runKeysAdd`: `parseFlags(args, flagSpec{Values: []string{"--scope", "--label", "--ttl"}, MaxPos: 0, Usage: c.Cmd.Usage})`; after the scope check:
2862
2863```go
2864 expires, code := c.ttlFlag(f)
2865 if code >= 0 {
2866 return code
2867 }
2868```
2869
2870the store call:
2871
2872```go
2873 if err := c.Store.AddSSHKeyFrom(c.User.ID, fp, pub.Type(), pub.Marshal(), scope, label, store.KeyOrigin{CreatedByToken: c.TokenID, ExpiresAt: expires}); err != nil {
2874```
2875
2876and the output:
2877
2878```go
2879 type out struct {
2880 Fingerprint string `json:"fingerprint"`
2881 Scope string `json:"scope"`
2882 Label string `json:"label"`
2883 ExpiresAt *time.Time `json:"expires_at,omitempty"`
2884 }
2885 d := out{fp, scope, label, expires}
2886 return c.emit(d, func(w io.Writer) {
2887 line := fmt.Sprintf("added %s (%s)", d.Fingerprint, d.Scope)
2888 if d.Label != "" {
2889 line += " " + d.Label
2890 }
2891 if d.ExpiresAt != nil {
2892 line += ", " + expiresText(d.ExpiresAt, time.Now())
2893 }
2894 fmt.Fprintln(w, line)
2895 })
2896```
2897
2898- [ ] **Step 5: `keys list` columns**
2899
2900```go
2901 type out struct {
2902 Fingerprint string `json:"fingerprint"`
2903 Algo string `json:"algo"`
2904 Scope string `json:"scope"`
2905 Label string `json:"label"`
2906 CreatedBy string `json:"created_by,omitempty"`
2907 LastUsedAt string `json:"last_used_at,omitempty"`
2908 ExpiresAt *time.Time `json:"expires_at,omitempty"`
2909 }
2910 var ds []out
2911 for _, k := range keys {
2912 ds = append(ds, out{k.Fingerprint, k.Algo, k.Scope, k.Label, k.CreatedBy, k.LastUsedAt, k.ExpiresAt})
2913 }
2914 now := time.Now()
2915 return c.emit(ds, func(w io.Writer) {
2916 tb := c.table(w, "FINGERPRINT", "ALGO", "SCOPE", "LABEL", "USED", "EXPIRES")
2917 for _, d := range ds {
2918 tb.row(cFlex(d.Fingerprint), cText(d.Algo), cState(d.Scope), cText(d.Label),
2919 cText(c.usedText(d.LastUsedAt)), cText(expiresText(d.ExpiresAt, now)))
2920 }
2921 tb.flush()
2922 })
2923```
2924
2925- [ ] **Step 6: `repo deploy-key add --ttl`, list columns**
2926
2927Registration:
2928
2929```go
2930 register(Command{Path: []string{"repo", "deploy-key", "add"},
2931 Summary: "bind a read-only (or --rw) key to one repository",
2932 Usage: "repo deploy-key add <owner/name> [--rw] [--ttl 30d|720h] < key.pub",
2933 Flags: []Flag{
2934 {"--rw", "", "the key may push, not just fetch", ""},
2935 {"--ttl", "30d|720h", "how long the key authenticates", "never expires"},
2936 },
2937 Examples: []string{"repo deploy-key add krz/gitbay < key.pub", "repo deploy-key add krz/gitbay --ttl 30d < key.pub"},
2938 ReadsStdin: true,
2939 MintsCredential: true,
2940 Run: runDeployKeyAdd})
2941```
2942
2943`runDeployKeyAdd`, replacing its argument loop (lines 37-52):
2944
2945```go
2946func runDeployKeyAdd(c *Ctx, args []string) int {
2947 f, err := parseFlags(args, flagSpec{Values: []string{"--ttl"}, Bools: []string{"--rw"}, MaxPos: 1, Usage: c.Cmd.Usage})
2948 if err != nil {
2949 return c.fail(protocol.ExitUsage, "%v", err)
2950 }
2951 path := f.pos(0)
2952 if path == "" {
2953 return c.usage()
2954 }
2955 mode := "ro"
2956 if f.Has("--rw") {
2957 mode = "rw"
2958 }
2959 expires, code := c.ttlFlag(f)
2960 if code >= 0 {
2961 return code
2962 }
2963 repo, code := resolveRepo(c, path, policy.CanAdmin)
2964 if code >= 0 {
2965 return code
2966 }
2967```
2968
2969The rest is as before except the store call and output:
2970
2971```go
2972 if err := c.Store.AddSSHKeyFrom(c.User.ID, fp, pub.Type(), pub.Marshal(), scope, label, store.KeyOrigin{CreatedByToken: c.TokenID, ExpiresAt: expires}); err != nil {
2973 if errors.Is(err, store.ErrDuplicateKey) {
2974 return c.failErr(err)
2975 }
2976 return c.fail(protocol.ExitFailure, "%v", err)
2977 }
2978 d := map[string]any{"fingerprint": fp, "mode": mode}
2979 if expires != nil {
2980 d["expires_at"] = expires
2981 }
2982 return c.emit(d, func(w io.Writer) {
2983 line := fmt.Sprintf("deploy key %s (%s) bound to %s", fp, mode, repo.Path())
2984 if expires != nil {
2985 line += ", " + expiresText(expires, time.Now())
2986 }
2987 fmt.Fprintln(w, line)
2988 })
2989```
2990
2991`runDeployKeyList`:
2992
2993```go
2994 type out struct {
2995 Fingerprint string `json:"fingerprint"`
2996 Algo string `json:"algo"`
2997 Mode string `json:"mode"`
2998 Label string `json:"label"`
2999 LastUsedAt string `json:"last_used_at,omitempty"`
3000 ExpiresAt *time.Time `json:"expires_at,omitempty"`
3001 }
3002 var ds []out
3003 for _, k := range keys {
3004 mode := "ro"
3005 if policy.DeployScopeAllows(k.Scope, repo.ID, true) {
3006 mode = "rw"
3007 }
3008 ds = append(ds, out{k.Fingerprint, k.Algo, mode, k.Label, k.LastUsedAt, k.ExpiresAt})
3009 }
3010 now := time.Now()
3011 return c.emit(ds, func(w io.Writer) {
3012 tb := c.table(w, "FINGERPRINT", "ALGO", "MODE", "LABEL", "USED", "EXPIRES")
3013 for _, d := range ds {
3014 tb.row(cFlex(d.Fingerprint), cText(d.Algo), cState(d.Mode), cText(d.Label),
3015 cText(c.usedText(d.LastUsedAt)), cText(expiresText(d.ExpiresAt, now)))
3016 }
3017 tb.flush()
3018 })
3019```
3020
3021Add `"time"` to `deploykey.go`'s imports.
3022
3023- [ ] **Step 7: The e2e rows that end at the label**
3024
3025`e2e/ssh_test.go:267`: `if !strings.Contains(out, "\tgit\talice2\t") {`
3026`e2e/ssh_test.go:276`: `if !strings.Contains(out, "\tgit\tbuild box\t") {`
3027
3028- [ ] **Step 8: Run the tests**
3029
3030Run: `go build ./... && go vet ./... && go test ./internal/control ./internal/store ./internal/sshd -count=1 && go test ./e2e -run TestSSHControlPlane -count=1`
3031
3032(Check the name of the test holding `e2e/ssh_test.go:255-276` with `grep -n "^func Test" e2e/ssh_test.go` and run that one.)
3033Expected: PASS.
3034
3035- [ ] **Step 9: Commit**
3036
3037```bash
3038git add internal/control e2e/ssh_test.go
3039git commit -S -m "keys: --ttl on keys add and repo deploy-key add; lists show last use and expiry
3040
3041Ref #277"
3042```
3043
3044### Task 3.4: docs
3045
3046**Files:**
3047- Modify: `.gitbay/wiki/Users.org` (keys block ~61-66 and the scopes paragraph), `.gitbay/wiki/Architecture/05-Identity-and-Access.org:17-18`, `09-Controls.org:27`, `10-Known-Gaps.org`, `.gitbay/wiki/Parity.org` (Accounts), `.gitbay/wiki/API.org` (the paragraph added in MR 2), `CHANGELOG.org`
3048
3049- [ ] **Step 1: Edit the pages**
3050
3051`Users.org`, add to the keys code block:
3052
3053```
3054gitbay auth keys add --scope git --ttl 90d < ~/.ssh/ci_key.pub
3055```
3056
3057and after the labels paragraph:
3058
3059```
3060=--ttl 90d= (or any Go duration, =720h=) makes a key stop
3061authenticating after that long; =repo deploy-key add= takes the same
3062flag. An expiring key cannot create credentials: tokens, keys, login
3063links. =keys list= shows when each key was last used and when it
3064expires, so a key nobody uses is easy to spot.
3065```
3066
3067`05-Identity-and-Access.org`: SSH user key and deploy key Expiry cells become `optional =--ttl=, refused at auth`.
3068
3069`09-Controls.org`:
3070
3071```
3072| Credential expiry | in place | optional =--ttl= on API tokens, SSH and deploy keys; checked at auth and per exec |
3073```
3074
3075`10-Known-Gaps.org`: delete the `#277` row.
3076
3077`Parity.org`, after `SSH key label`:
3078
3079```
3080| SSH key expiry and last use | yes | no | no |
3081```
3082
3083`API.org`: in the paragraph MR 2 added, "a token with a =--ttl= cannot run" becomes "a token or SSH key with a =--ttl= cannot run".
3084
3085`CHANGELOG.org`:
3086
3087```
3088- =keys add= and =repo deploy-key add= take =--ttl=; an expired key is
3089 refused at authentication, and an open connection on it closes within
3090 15 seconds. An expiring key cannot create credentials, like an
3091 expiring token. =keys list= and =repo deploy-key list= gain =USED= and
3092 =EXPIRES= columns, after the label (#277).
3093```
3094
3095- [ ] **Step 2: Commit, open the MR**
3096
3097```bash
3098git add .gitbay/wiki CHANGELOG.org
3099git commit -S -m "wiki: key expiry
3100
3101Closes #277"
3102git push -u origin key-expiry
3103gitbay mr create --source key-expiry --target main --title "keys: optional expiry for SSH and deploy keys"
3104```
3105
3106---
3107
3108# MR 4: idle timeout for browser sessions (branch `session-idle`, #276)
3109
3110A session lapses after 12 hours without a request and after seven
3111days regardless. `expires_at` holds the sliding expiry, so the auth
3112query and the retention sweep (`expires_at <= ?`,
3113`internal/store/retention.go:51`) need no change;
3114`absolute_expires_at` holds the cap. Renewal writes at most once a
3115minute per session. The cookie's `MaxAge` stays seven days.
3116
3117### Task 4.1: migration 0062 and the store
3118
3119**Files:**
3120- Create: `internal/store/migrations/0062_web_session_idle.up.sql`, `.down.sql`
3121- Modify: `internal/store/sessions.go:67-121`
3122- Test: `internal/store/sessions_test.go` (append)
3123
3124**Interfaces:**
3125- Produces:
3126 - `const WebSessionIdle = 12 * time.Hour`
3127 - `CreateWebSession(hash string, userID int64, ttl time.Duration) error` — unchanged signature; `ttl` is now the absolute cap.
3128 - `WebSessionUser(hash string) (User, error)` — unchanged signature; renews.
3129 - `WebSession.LastUsedAt string `json:"last_used_at"``
3130
3131- [ ] **Step 1: Write the failing tests**
3132
3133Append to `internal/store/sessions_test.go`:
3134
3135```go
3136func sessionFixture(t *testing.T) (*Store, int64) {
3137 t.Helper()
3138 s := open(t)
3139 if err := s.MigrateUp(); err != nil {
3140 t.Fatal(err)
3141 }
3142 uid, err := s.CreateUser("cmc", false)
3143 if err != nil {
3144 t.Fatal(err)
3145 }
3146 return s, uid
3147}
3148
3149func sessionTimes(t *testing.T, s *Store, hash string) (expires, absolute time.Time) {
3150 t.Helper()
3151 var e, a string
3152 if err := s.DB.QueryRow("SELECT expires_at, absolute_expires_at FROM web_sessions WHERE token_hash = ?", hash).Scan(&e, &a); err != nil {
3153 t.Fatal(err)
3154 }
3155 return *parseTime(sql.NullString{String: e, Valid: true}), *parseTime(sql.NullString{String: a, Valid: true})
3156}
3157
3158func TestWebSessionIdleExpiry(t *testing.T) {
3159 s, uid := sessionFixture(t)
3160 if err := s.CreateWebSession("h", uid, 7*24*time.Hour); err != nil {
3161 t.Fatal(err)
3162 }
3163 exp, abs := sessionTimes(t, s, "h")
3164 if d := time.Until(exp); d < WebSessionIdle-time.Minute || d > WebSessionIdle {
3165 t.Fatalf("a new session expires in %s, want %s", d, WebSessionIdle)
3166 }
3167 if d := time.Until(abs); d < 7*24*time.Hour-time.Minute {
3168 t.Fatalf("absolute cap in %s", d)
3169 }
3170 // Idle past the window: gone.
3171 old := fmtTime(time.Now().Add(-time.Second))
3172 s.DB.Exec("UPDATE web_sessions SET expires_at = ? WHERE token_hash = 'h'", old)
3173 if _, err := s.WebSessionUser("h"); err != ErrNotFound {
3174 t.Fatalf("idle session: %v", err)
3175 }
3176}
3177
3178func TestWebSessionRenewsUpToTheCap(t *testing.T) {
3179 s, uid := sessionFixture(t)
3180 if err := s.CreateWebSession("h", uid, 7*24*time.Hour); err != nil {
3181 t.Fatal(err)
3182 }
3183 // Last used two minutes ago, one minute left: a request renews it.
3184 s.DB.Exec("UPDATE web_sessions SET last_used_at = ?, expires_at = ? WHERE token_hash = 'h'",
3185 fmtTime(time.Now().Add(-2*time.Minute)), fmtTime(time.Now().Add(time.Minute)))
3186 if _, err := s.WebSessionUser("h"); err != nil {
3187 t.Fatal(err)
3188 }
3189 if exp, _ := sessionTimes(t, s, "h"); time.Until(exp) < WebSessionIdle-time.Minute {
3190 t.Fatalf("not renewed: expires in %s", time.Until(exp))
3191 }
3192 // Near the cap, renewal stops at it.
3193 capAt := time.Now().Add(time.Hour)
3194 s.DB.Exec("UPDATE web_sessions SET last_used_at = ?, absolute_expires_at = ? WHERE token_hash = 'h'",
3195 fmtTime(time.Now().Add(-2*time.Minute)), fmtTime(capAt))
3196 if _, err := s.WebSessionUser("h"); err != nil {
3197 t.Fatal(err)
3198 }
3199 if exp, _ := sessionTimes(t, s, "h"); exp.After(capAt) {
3200 t.Fatalf("renewed past the cap: %s > %s", exp, capAt)
3201 }
3202 list, err := s.ListWebSessions(uid)
3203 if err != nil || len(list) != 1 || list[0].LastUsedAt == "" {
3204 t.Fatalf("list: %+v %v", list, err)
3205 }
3206}
3207```
3208
3209Add `"database/sql"` to the file's imports.
3210
3211- [ ] **Step 2: Run them and see them fail**
3212
3213Run: `go test ./internal/store -run 'TestWebSession' -count=1`
3214Expected: FAIL to compile, `undefined: WebSessionIdle`.
3215
3216- [ ] **Step 3: Migration**
3217
3218`0062_web_session_idle.up.sql`:
3219
3220```sql
3221-- expires_at slides forward on use, never past absolute_expires_at.
3222-- Sessions open now keep their cap and get a full idle window from here.
3223ALTER TABLE web_sessions ADD COLUMN absolute_expires_at TEXT;
3224ALTER TABLE web_sessions ADD COLUMN last_used_at TEXT;
3225UPDATE web_sessions SET
3226 absolute_expires_at = expires_at,
3227 last_used_at = strftime('%Y-%m-%dT%H:%M:%fZ','now'),
3228 expires_at = min(expires_at, strftime('%Y-%m-%dT%H:%M:%fZ','now','+12 hours'));
3229```
3230
3231`0062_web_session_idle.down.sql`:
3232
3233```sql
3234UPDATE web_sessions SET expires_at = absolute_expires_at;
3235ALTER TABLE web_sessions DROP COLUMN last_used_at;
3236ALTER TABLE web_sessions DROP COLUMN absolute_expires_at;
3237```
3238
3239- [ ] **Step 4: Store**
3240
3241Replace `CreateWebSession` and `WebSessionUser`:
3242
3243```go
3244// WebSessionIdle is how long a browser session lasts without a request.
3245// Each use moves its expiry this far ahead, never past the cap it was
3246// created with. Migration 0062 repeats the value for sessions it
3247// converts.
3248const WebSessionIdle = 12 * time.Hour
3249
3250// CreateWebSession stores a session that lapses after WebSessionIdle
3251// without use, and after ttl regardless.
3252func (s *Store) CreateWebSession(hash string, userID int64, ttl time.Duration) error {
3253 now := time.Now()
3254 _, err := s.DB.Exec(
3255 "INSERT INTO web_sessions (token_hash, user_id, expires_at, absolute_expires_at, last_used_at) VALUES (?, ?, ?, ?, ?)",
3256 hash, userID, fmtTime(now.Add(min(ttl, WebSessionIdle))), fmtTime(now.Add(ttl)), fmtTime(now))
3257 return err
3258}
3259
3260// WebSessionUser resolves a session cookie hash to its user and renews
3261// the session's idle expiry. A session is written at most once a
3262// minute, so a burst of requests costs one UPDATE.
3263func (s *Store) WebSessionUser(hash string) (User, error) {
3264 now := time.Now()
3265 var userID int64
3266 err := s.DB.QueryRow(
3267 "SELECT user_id FROM web_sessions WHERE token_hash = ? AND expires_at > ?",
3268 hash, fmtTime(now)).Scan(&userID)
3269 if errors.Is(err, sql.ErrNoRows) {
3270 return User{}, ErrNotFound
3271 }
3272 if err != nil {
3273 return User{}, err
3274 }
3275 s.DB.Exec(`UPDATE web_sessions SET last_used_at = ?, expires_at = min(absolute_expires_at, ?)
3276 WHERE token_hash = ? AND last_used_at < ?`,
3277 fmtTime(now), fmtTime(now.Add(WebSessionIdle)), hash, fmtTime(now.Add(-time.Minute)))
3278 return s.UserByID(userID)
3279}
3280```
3281
3282`WebSession` and `ListWebSessions`:
3283
3284```go
3285type WebSession struct {
3286 ID string `json:"id"`
3287 CreatedAt string `json:"created_at"`
3288 ExpiresAt string `json:"expires_at"`
3289 LastUsedAt string `json:"last_used_at"`
3290}
3291
3292// ListWebSessions lists the user's unexpired browser sessions, newest first.
3293func (s *Store) ListWebSessions(userID int64) ([]WebSession, error) {
3294 rows, err := s.DB.Query(`SELECT substr(token_hash, 1, 12), created_at, expires_at, COALESCE(last_used_at, created_at)
3295 FROM web_sessions WHERE user_id = ? AND expires_at > ? ORDER BY created_at DESC`,
3296 userID, fmtTime(time.Now()))
3297 if err != nil {
3298 return nil, err
3299 }
3300 defer rows.Close()
3301 var out []WebSession
3302 for rows.Next() {
3303 var ws WebSession
3304 if err := rows.Scan(&ws.ID, &ws.CreatedAt, &ws.ExpiresAt, &ws.LastUsedAt); err != nil {
3305 return nil, err
3306 }
3307 out = append(out, ws)
3308 }
3309 return out, rows.Err()
3310}
3311```
3312
3313- [ ] **Step 5: Run the tests**
3314
3315Run: `go test ./internal/store -count=1`
3316Expected: PASS, including `TestSweepRemovesExpiredSessionsAndTokens` (a `-time.Hour` ttl still makes a dead session).
3317
3318- [ ] **Step 6: Commit**
3319
3320```bash
3321git add internal/store
3322git commit -S -m "store: web sessions lapse after 12 hours idle, under the absolute cap
3323
3324Ref #276"
3325```
3326
3327### Task 4.2: `web sessions list` shows last use; docs
3328
3329**Files:**
3330- Modify: `internal/control/web.go:33-54`
3331- Modify: `internal/httpd/accounts.go:147` (comment only)
3332- Modify: `.gitbay/wiki/Users.org:672-678`, `.gitbay/wiki/Architecture/05-Identity-and-Access.org:21`, `:36-38`, `09-Controls.org:26`, `10-Known-Gaps.org`, `CHANGELOG.org`
3333
3334- [ ] **Step 1: The list**
3335
3336```go
3337 return c.emit(sessions, func(w io.Writer) {
3338 tb := c.table(w, "ID", "SINCE", "UNTIL", "USED")
3339 for _, s := range sessions {
3340 since, until, used := s.CreatedAt, s.ExpiresAt, s.LastUsedAt
3341 if c.Term.Cols == 0 {
3342 since, until, used = stamp(since), stamp(until), stamp(used)
3343 } else {
3344 since, until, used = relAge(since, termNow()), relAge(until, termNow()), relAge(used, termNow())
3345 }
3346 tb.row(cRef(s.ID), cText("since "+since), cText("until "+until), cText("used "+used))
3347 }
3348 tb.flush()
3349 })
3350```
3351
3352- [ ] **Step 2: The call site says what the ttl is**
3353
3354`internal/httpd/accounts.go`, above line 147:
3355
3356```go
3357 // Seven days is the cap; the store ends it sooner after
3358 // store.WebSessionIdle without a request.
3359```
3360
3361- [ ] **Step 3: Run the tests**
3362
3363Run: `go build ./... && go test ./internal/control ./internal/httpd -count=1 && go test ./e2e -run TestWebSessionsListRevoke -count=1`
3364Expected: PASS.
3365
3366- [ ] **Step 4: Docs**
3367
3368`Users.org`, the Browser sessions paragraph:
3369
3370```
3371=gitbay web login= mints a one-time URL; the session it opens ends
3372after twelve hours without a request, and after seven days in any case.
3373=gitbay web sessions list= shows each of yours by a short id with its
3374creation, expiry and last use, and =gitbay web sessions revoke <id>=
3375or =--all= ends them from the terminal, which is where a lost laptop is
3376handled.
3377```
3378
3379`05-Identity-and-Access.org`: the Web session Expiry cell becomes `12 h idle, 7 days absolute`; in the paragraph under the table, "=MaxAge= 7 days" becomes "=MaxAge= 7 days (the session itself also ends after 12 hours idle)".
3380
3381`09-Controls.org`:
3382
3383```
3384| Session lifetime | in place | 12 hours idle, 7 days absolute (=internal/store/sessions.go=) |
3385```
3386
3387`10-Known-Gaps.org`: delete the `#276` row.
3388
3389`CHANGELOG.org`:
3390
3391```
3392- Browser sessions end after twelve hours without a request, and after
3393 seven days as before. Sessions open at upgrade get a fresh twelve
3394 hours. =web sessions list= shows when each was last used (#276).
3395```
3396
3397- [ ] **Step 5: Commit, open the MR**
3398
3399```bash
3400git add internal/control/web.go internal/httpd/accounts.go .gitbay/wiki CHANGELOG.org
3401git commit -S -m "web: sessions list shows last use; docs for the idle timeout
3402
3403Closes #276"
3404git push -u origin session-idle
3405gitbay mr create --source session-idle --target main --title "web: idle timeout for browser sessions"
3406```
3407
3408---
3409
3410# MR 5: `web login` over SSH spends the login-link budget (branch `weblogin-limit`, #278)
3411
3412### Task 5.1: the limit in `runWebLogin`
3413
3414**Files:**
3415- Modify: `internal/control/web.go:80-99`
3416- Modify: `internal/control/loginlink.go:12-19` (comment)
3417- Test: `internal/control/weblogin_test.go` (create)
3418- Modify: `.gitbay/wiki/Architecture/10-Known-Gaps.org`, `CHANGELOG.org`
3419
3420**Interfaces:**
3421- Consumes: `maxLoginLinksPerHour` (`loginlink.go:19`), `Store.CountLoginTokensSince`.
3422
3423- [ ] **Step 1: Write the failing test**
3424
3425```go
3426package control
3427
3428import (
3429 "strings"
3430 "testing"
3431
3432 "gitbay.org/gitbay/internal/protocol"
3433 "gitbay.org/gitbay/internal/store"
3434)
3435
3436// web login over SSH counts against the same hourly bound as the
3437// mailed links, since both insert into login_tokens (#278).
3438func TestWebLoginSharesTheLoginLinkLimit(t *testing.T) {
3439 st, _, uid := newQueueTestRepo(t)
3440 for i := 0; i <= maxLoginLinksPerHour; i++ {
3441 c, errOut := pruneCtx(st, t.TempDir(), store.User{ID: uid, Username: "alice"})
3442 c.Cfg.Web.Mode = "accounts"
3443 c.Cfg.Server.SiteURL = "https://gitbay.test"
3444 c.Cfg.Limits.WriteRate = -1
3445 code := Dispatch(c, []string{"web", "login"})
3446 switch {
3447 case i < maxLoginLinksPerHour && code != protocol.ExitOK:
3448 t.Fatalf("link %d: exit %d %s", i+1, code, errOut)
3449 case i == maxLoginLinksPerHour && (code != protocol.ExitDenied || !strings.Contains(errOut.String(), "login links")):
3450 t.Fatalf("link %d: exit %d %q, want refused", i+1, code, errOut)
3451 }
3452 }
3453}
3454```
3455
3456- [ ] **Step 2: Run it and see it fail**
3457
3458Run: `go test ./internal/control -run TestWebLoginSharesTheLoginLinkLimit -count=1`
3459Expected: FAIL, the sixth link exits 0.
3460
3461- [ ] **Step 3: Implement**
3462
3463In `runWebLogin`, after the web-mode check:
3464
3465```go
3466 n, err := c.Store.CountLoginTokensSince(c.User.ID, time.Now().Add(-time.Hour))
3467 if err != nil {
3468 return c.fail(protocol.ExitFailure, "%v", err)
3469 }
3470 if n >= maxLoginLinksPerHour {
3471 return c.fail(protocol.ExitDenied,
3472 "%d login links in the last hour is the most an account gets; use one of those, or wait", maxLoginLinksPerHour)
3473 }
3474```
3475
3476`loginlink.go`, the comment above `maxLoginLinksPerHour`:
3477
3478```go
3479// maxLoginLinksPerHour bounds what one account's address can be made to
3480// receive. It matches maxEmailAddsPerHour: enough for a person who mistypes
3481// and retries, nothing for a script. CountLoginTokensSince counts every row
3482// in login_tokens, so links minted with "web login" over SSH and links
3483// mailed from the login page share the budget, and both refuse past it.
3484```
3485
3486- [ ] **Step 4: Run the tests**
3487
3488Run: `go test ./internal/control -count=1`
3489Expected: PASS. Then `grep -c '\.login(t\|loginBrowser(t\|"web", "login"' e2e/*.go` and confirm no single e2e test logs one account in more than five times; `TestMRWebReviewLoop` logs alice in once and carol once, and each e2e test runs its own instance.
3490
3491- [ ] **Step 5: Docs**
3492
3493`10-Known-Gaps.org`: delete the `#278` row.
3494
3495`CHANGELOG.org`:
3496
3497```
3498- =web login= over SSH refuses a sixth link in an hour, the same bound
3499 the login page's mailed links have (#278).
3500```
3501
3502- [ ] **Step 6: Commit, open the MR**
3503
3504```bash
3505git add internal/control/web.go internal/control/loginlink.go internal/control/weblogin_test.go .gitbay/wiki CHANGELOG.org
3506git commit -S -m "web: login over SSH applies the login-link limit
3507
3508Closes #278"
3509git push -u origin weblogin-limit
3510gitbay mr create --source weblogin-limit --target main --title "web login over SSH applies the login-link rate limit"
3511```
3512
3513---
3514
3515## Decisions (2026-09-28)
3516
35171. **Expiring SSH keys and minting.** Confirmed: an expiring key is
3518 refused the minting commands like an expiring token (MR 3,
3519 Task 3.2).
35202. **Which commands mint.** Confirmed: the issue's five plus
3521 `repo runner add`, `admin user create`, `email verify` and
3522 `admin email verify`, pinned by `TestMintingCommandsMarked`.
35233. **LFS transfer tokens.** Filed as #285; not in this plan.
35244. **Removing the key you are on.** Confirmed: the session's own
3525 connection is cut after the removal commits.
35265. **Idle window.** A constant (`store.WebSessionIdle`, 12 h); make it
3527 configurable only when someone needs another value.
3528
3529Documented limits, stated on the Threat-Model page in MR 1:
3530
3531- With `ssh.mode = "system"` each exec is its own forced-command
3532 process; the per-exec check applies, a running one is not cut. bay1
3533 runs embedded.
3534- A control command already inside its store write when the key is
3535 revoked finishes the write and its output is lost; git transports are
3536 killed and commands watching `Done` stop.
3537
3538The `token list` future-expiry display is #286.
3539
3540## Self-review
3541
3542- **Coverage.** #256: per-exec re-read (Task 1.3 `runExec`), git
3543 transport session re-read (same path; `Exec` dispatches git),
3544 connection tracking and closing on keys remove / deploy-key remove /
3545 disable / delete (1.1, 1.3), cancelling running commands and pushes
3546 (1.2, 1.3), interrupted receive-pack moves no ref (1.4), e2e with a
3547 multiplexed connection (1.4). #257: `MintsCredential` checked in
3548 `Dispatch` (2.2), migration recording the creator for tokens and keys
3549 (2.1), `token revoke` listing and revoking with `--created` (2.1,
3550 2.3), default `--scope read` and release note (2.3, 2.5), API and
3551 Threat-Model pages (2.5). #277: `--ttl` on both add commands (3.3),
3552 enforced at authentication (3.2), last use in `keys list` (3.3),
3553 considered with #257 (3.2, open question 1), migration designed with
3554 0060 (both nullable `ADD COLUMN`, one insert path via `KeyOrigin`).
3555 #276: idle timeout with renewal, absolute cap kept, last use listed
3556 (4.1, 4.2). #278: limit applied, comment corrected (5.1).
3557- **Placeholders.** None; every code step carries the code. Two steps
3558 ask the executor to confirm a name with grep (`nullID`, the
3559 `ssh_test.go` test name) because they were not unique facts to pin.
3560- **Types.** `Revoked{KeyIDs []int64; UserID int64}`, `OnRevoke`,
3561 `announce`, `LiveSSHKeys([]int64) (map[int64]bool, error)` are used
3562 with those shapes in 1.1, 1.3, 2.1, 3.1. `Exec(..., key store.SSHKey,
3563 ..., done, stopping, revoked)` matches in 1.3, 3.2 and `system.go`.
3564 `APITokenUser` returns `(User, APIToken, error)` in 2.1, 2.2 and the
3565 tests. `KeyOrigin{CreatedByToken, ExpiresAt}` is introduced in 2.1
3566 and extended in 3.1. `Ctx.TokenID int64`, `Ctx.Expires *time.Time`
3567 match across 2.2, 2.3, 3.2, 3.3. `SSHKey.CreatedBy` (name) and
3568 `KeyOrigin.CreatedByToken` (id) are distinct on purpose.