Skip to content

fix: harden doctor, keychain fallback and service log - #17

Merged
parsilver merged 5 commits into
mainfrom
fix/16-harden-doctor-keychain-fallback
Nov 15, 2026
Merged

parsilver merged 5 commits into
mainfrom
fix/16-harden-doctor-keychain-fallback

Conversation

@parsilver

@parsilver parsilver commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Closes #16

Follow-ups from the review of #15.

Acceptance criteria

  • doctor catches a keychain error from store.apps(). doctor reads the apps inside a try and prints the store's own reason as a FAIL line ("The credential for X is in the keychain, but the macOS keychain did not answer (36). Unlock the keychain..."), exit 1, nothing thrown. Test: tether doctor > fails, saying why, when the keychain that holds a credential cannot be read.
  • Warn with the reason when the keychain refuses a secret. Keychain.set now returns why it refused (undefined once it holds the secret): a value security -i cannot quote, the tool's exit status, or a write that does not read back. For security -i only the exit status is used, because its stdin line carries the secret; for secret-tool the first line of stderr is added (the secret only goes to its stdin). Store.saveApp returns { where, warning? } and moveToKeychain returns its warnings; connect and start print them on stderr. start adds the credentials to the redactor before printing. With no keychain at all (Windows, TETHER_KEYCHAIN=off) nothing is printed: the file is the intended place there. Tests: keychain backend reasons (including one where security echoes its stdin to stderr), store warnings, connect and start warnings with expectNoSecrets.
  • service.log has a size limit; install sets 0600 on an existing log. tether start cuts service.log to its last ~1 MB, from a line start, once it passes 5 MB: at start and every ten minutes. It is rewritten in place, not renamed, because launchd opens the log for appending and keeps writing at the new end. Not on Windows: cmd's >> seeks to the end once and keeps writing at its old offset, so a cut there would leave a gap; the Windows log has no limit yet. On macOS, service install now runs chmod 0600 on an existing log. Tests: store trim (over, at and under the limit, missing file), start trims an oversized log, install fixes a 0644 log.
  • Reinstall over a running launchd agent. bootout returns before the old agent stops, so bootstrap is retried up to 10 times, one second apart, on any failure, and the last error is reported. It retries even when bootout itself failed, because bootout can exit 36 while the agent is still stopping. A first install that succeeds is unchanged. Tests: bootout 36 followed by two failed bootstraps then success; give up after ten tries with launchctl's message.
  • logTask caps the title. At most 200 characters, cut on code points. Test with an emoji at the boundary.
  • A throwing logTask in worker.ts. The outcome is settled first; then the reservation, the running entry and the slot are released, the log is written once inside its own try (a failure prints one line), and usage and run state are updated. Before this change a throwing log ran the error path, which logged again, threw again and skipped the release. Test: tasks.jsonl made a directory, two tasks at concurrency 1 both complete, the failure line appears once per task, and today's spend equals what the tasks reported.
  • systemd unit and release checkout. After=/Wants=network-online.target dropped from the user unit (snapshot updated); persist-credentials: false on the checkout in release.yml, with a test that every checkout step there sets it.
  • Manual run before the first release. Not done here: it means installing the real service with the keychain on, on the owner's Mac and on a Linux box with a systemd user session. CI's macOS job still runs the real launchd install with the keychain off.

Checks run

  • bun run lint: Checked 69 files ... No fixes applied.
  • bun run typecheck: clean.
  • bun run test (full suite, locally, before the last two test additions and the refactor): Test Files 14 passed | 1 skipped (15), Tests 394 passed | 1 skipped (395). The skipped file is the real-launchd test, which runs only in CI.
  • Final head 728addf: two more local full runs got no slot in the shared heavy-job queue. Instead, a targeted local run of the keychain, store and service tests plus the CLI start, doctor, keychain, log and service tests: Tests 103 passed | 7 skipped (110). CI ran the full suite on this head: CI and Release green on Linux and macOS, including the real launchd install.

Quality gates (changed code only)

  • CRAP (coverage from a targeted run, because the shared heavy-job queue had no free slot): every changed function is under 10. Highest: macKeychain 8.2, secretToolKeychain 8.2, Worker.start 7.0, cli start 6.6 (was 19.1 before connectedApps was split out), doctor 6.0, saveApp 5.0, moveToKeychain 5.1, trimServiceLog 3.0 (store) and 4.2 (cli), logTask 3.0.
  • Duplication (dryer src): no candidates.
  • Mutation (changed lines, matching tests): keychain 9 of 10 killed, store all killed after adding the 5 MB boundary test, service 5 of 6, doctor 1 of 1, worker 2 of 2 after adding the spend assertion, main 1 of 2. The three survivors are equivalent mutants: status ?? "timeout" turned into || at keychain.ts:60 and service.ts:57, both inside a branch where status is never 0, and ctx.io.platform ?? process.platform turned into || at main.ts, where the platform is never an empty string. The mutation tool does not reach methods on the launchd object literal, so the bootstrap retry loop is covered by its tests only.

Risks

  • Keychain and credential handling: the new reasons and warnings name the origin and the file path, never the credential. The security -i reason leaves out stderr on purpose.
  • The service log is cut in place while launchd holds it open. That relies on launchd opening StandardOutPath for appending, which the code comment explains. Nothing checks this against a real running service yet.
  • The Windows service log still has no size limit.

Not verified

  • Criterion 8: the manual keychain-on runs under the real launchd service and a systemd user unit.
  • Trimming against a log a real launchd service is writing to at that moment.

Reinstalling over a running agent failed: bootout returns before the
old agent has stopped, and bootstrap refuses until it has. Bootstrap
is now tried up to ten times, a second apart, and reports the last
error. An existing service.log is set to 0600 on install, not only a
new one. The systemd unit no longer orders itself after
network-online.target, which a user unit cannot reach, and the
release checkout drops the job token.

Tested with the service tests: retry after bootout exit 36, give-up
after ten tries, a 0644 log made 0600, the unit snapshot, and a check
that every release checkout sets persist-credentials: false.
doctor now prints a FAIL line with the store's reason when the
keychain holding a credential cannot be read, instead of exiting with
a bare error. Keychain.set returns why it refused a secret, and
connect and start warn with that reason when the credential stays in
credentials.json. security -i reports only its exit status, since its
stdin carries the secret.

The task log keeps at most 200 characters of an app's title. A task
log that cannot be written no longer skips releasing the task's slot
and budget reservation: the outcome is settled first, the reservation
released, and the log write fails on its own line, once. tether start
cuts service.log to its last 1 MB once it passes 5 MB, at start and
every ten minutes; not on Windows, where cmd's >> keeps its offset.

Tested with new keychain, store and CLI tests, each seen failing first.
A mutation run showed the optional chain on the first stderr line was
never needed and nothing checked that later lines are dropped. The
reason now keeps the first line by replacing the rest, and a test pins
both a multi-line and an empty stderr.
Mutation runs left two gaps: a log of exactly 5 MB was not checked to
stay whole, and nothing checked that a finished task adds what it
reported spending rather than its reserved budget. Both are pinned
now; the mutants on those lines are killed.
start had grown two loops for the keychain warnings and the redactor.
They move with the empty check into connectedApps, which brings
start's CRAP score from 19.1 to 6.6 on the targeted coverage run.
Behaviour is unchanged: the start and keychain tests pass as before.
@parsilver
parsilver marked this pull request as ready for review November 14, 2026 13:36

@parsilver parsilver left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: no Blocker. Merging.

Reviewed at 728addf, with a separate security review. CI is green on Linux, macOS and Windows.

  • Secrets: for security -i, only the exit status reaches a warning, and a test has security echo its stdin to stderr. secret-tool gets the secret on stdin and doesn't echo it. start prints nothing before it adds the credentials to the redactor.
  • Fallback: a refused secret goes to credentials.json through a 0600 temp file and a rename. Platforms where the file is the intended store get no warning.
  • Log trim: the start process is the only writer to service.log, so a synchronous trim from a line start cannot interleave with writes. Windows is skipped, with the reason.
  • Bootstrap retry: launchd allows one job per label, so two agents can't run at once.
  • release.yml: pull_request on its own path only, contents: read, no secrets, and actions pinned by SHA.

Suggestions (filed as a follow-up)

  • store.ts:126 via doctor.ts:41: a JSON.parse error can quote part of a corrupt credentials.json. Print only "could not be read (invalid JSON)".
  • keychain.ts:60/93: when secret-tool is missing, the warning says "exited timeout". Say "could not run".
  • cli.test.ts:417: make the fake keychain's reason echo the secret, so expectNoSecrets proves that start redacts.
  • cli.test.ts:848: call expectNoSecrets in the doctor FAIL test.
  • store.ts:282, service.ts:141: open with O_NOFOLLOW, for a TETHER_HOME set to a shared folder.

@parsilver
parsilver merged commit eba3bbc into main Nov 15, 2026
4 checks passed
parsilver added a commit that referenced this pull request Nov 16, 2026
* test: pin doctor, keychain and symlink follow-ups from the #17 review

Each test fails on main: doctor quotes the parser's text for a corrupt
credentials.json, a tool that cannot start reads as exited timeout, and
the credential temp file and service.log are written through a symlink.

* fix: redact corrupt-JSON reads, name how a tool ended, refuse symlinks

doctor now says credentials.json could not be read (invalid JSON) instead
of the parser's text, which quotes part of a credential. Ran carries the
spawn error and signal, so a keychain or service tool that cannot start
says could not run, not exited timeout. Writes of the credential and
state temp files, the service files and service.log, and the chmod of an
existing service.log, go through one helper that never follows a symlink.

* refactor: write private files whole with writeFileSync, test the edges

Mutation testing showed the hand-rolled write loop added nothing over
writeFileSync on a descriptor, and that a real spawn failure and a tail
with no whole line were untested. AGENTS.md names the new module.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix: harden doctor, keychain fallback and service log after #15

1 participant