Skip to content

fix: doctor and keychain warning follow-ups from the #17 review - #19

Merged
parsilver merged 3 commits into
mainfrom
fix/18-doctor-keychain-warning-follow
Nov 16, 2026
Merged

parsilver merged 3 commits into
mainfrom
fix/18-doctor-keychain-warning-follow

Conversation

@parsilver

@parsilver parsilver commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Closes #18

Follow-ups from the #17 review: doctor no longer prints the JSON parser's text, keychain and service failures say how the tool ended, two tests now prove redaction, and Tether's private files are never written or chmodded through a symbolic link.

Acceptance criteria

  • Corrupt credentials.json. Store.read turns a SyntaxError into <file> could not be read (invalid JSON) and drops the parser's message. Other read errors keep the system message, which never quotes file contents. Test: tether doctor > fails, without quoting it, when credentials.json is not valid JSON. It writes broken JSON that holds the issued credential, expects the new FAIL line and exit 1, and calls expectNoSecrets. Before the fix the test fails and the output reads could not be read: Unexpected token 'd', ...\"ential\": tdc_119007f\"... is not valid JSON, which is part of a real credential.

  • "could not run", not "exited timeout". Ran now carries the spawn error code and the signal. ended() in run.ts returns exited N, timed out (checked first, because a spawnSync timeout also sets SIGTERM), could not run, or was stopped (SIG). Both keychains use it for refusals and for the "did not answer" reason, and the service manager's failure text uses it too, since it had the same ?? "timeout" pattern. Tests: the macOS / Secret Service keychain's tool (ENOENT, ETIMEDOUT with SIGTERM, SIGKILL), run > reports a program that cannot start ... as one that could not run (a real spawn), and tether service on Linux > says what systemd printed, or its exit status (now also checks could not run).

  • start warning test. The fake keychain's refusal reason contains the credential. The test expects (the test keychain is locked: [redacted]) and passes expectNoSecrets.

  • Doctor FAIL test. The locked-keychain doctor test calls expectNoSecrets.

  • No following symlinks. The new src/client/private-file.ts holds every write and chmod of a user-only file:

    • createPrivate removes whatever is at the path (a link is removed as a link), then creates the file with O_CREAT|O_EXCL|O_NOFOLLOW at 0600 and calls fchmod on that descriptor. It writes the temp files for credentials.json, the other state files and tasks.jsonl, and the launchd, systemd and Windows service files.
    • makePrivate takes back an existing service.log at launchd install. It does an lstat check, then fchmod on a descriptor opened with O_NOFOLLOW.
    • cutToTail trims service.log on one descriptor: lstat check, O_RDWR|O_NOFOLLOW, fstat, read the tail, ftruncate, write, fchmod.

    A symlink makes the call fail with <file> is a symbolic link; Tether does not write through one. Remove it. The exception is the temp file, which is replaced. Windows has no O_NOFOLLOW, so the lstat check stands in there. Tests: files Tether writes (a symlinked credential temp file and a symlinked service.log; the target's bytes and mode stay unchanged) and tether service on macOS ... refuses a log that is a symbolic link (install fails before any launchctl call).

  • CI green on all three OSes. CI runs on Ubuntu and macOS, and both are green on this PR. The CI matrix has no Windows job, so there is no third OS to be green on. Windows is only built by the release workflow, which doesn't run tests. Adding a Windows job is a separate decision. Many existing tests assume POSIX modes and symlinks, so it would need its own work. I left that out of this PR.

Commands and output

$ bun run lint
Checked 70 files in 40ms. No fixes applied.
$ bun run typecheck
$ tsc --noEmit            (no errors)
$ bun run coverage        (full suite, before the last refactor commit)
 Test Files  14 passed | 1 skipped (15)
      Tests  405 passed | 1 skipped (406)
$ bunx vitest run test/keychain.test.ts test/store.test.ts test/service.test.ts test/run.test.ts   (after it)
      Tests  66 passed (66)
$ bunx vitest run test/cli.test.ts -t "doctor|keychain|service log"
      Tests  15 passed | 42 skipped (57)

RED on main with the new tests: 11 failed, 107 passed in the touched suites, each failing for the reason it targets.

Quality gates (changed code)

  • CRAP: every changed function is under 10. The worst are run at 7.0 (CC 7, 90% covered), withCredential at 6.2, and macKeychain and secretToolKeychain at 6.0. The new module's functions score 4.0 or less.
  • Duplication: dryer src found no duplicate candidates.
  • Mutation (private-file.ts, run.ts): 13 killed, 3 survived. All three survivors are ?? to || in run() (input, stdout, stderr). They are equivalent: the only falsy value besides null or undefined is "", which gives "" either way. The first mutation run left four more survivors. Two were in a hand-rolled write loop, now replaced by writeFileSync on the descriptor. The other two needed new tests: a real spawn failure, and a tail with no whole line.

Risks

  • The temp file is now removed before it is created. This only matters for a leftover file of the same pid; the rename into place stays atomic.
  • service.log is cut in place on one descriptor, as before, so launchd's append keeps working.
  • A symlinked service.log now fails tether service install on macOS, and tether start prints "Could not trim the service log" every ten minutes. That is on purpose, and the message names the file.

Not verified

  • Windows: there is no Windows CI job. The code paths fall back to the lstat check when O_NOFOLLOW is missing, but I didn't run them on Windows.
  • The real launchd install test (TETHER_REAL_SERVICE=1) runs in CI on macOS, not locally.

CI

Ubuntu and macOS are green on the head commit. The first macOS run failed in runClaudeCode > kills the whole process group, a test this PR doesn't touch. It waits for its record file to exist and then parses it, so it can read a half-written file (Unexpected end of JSON input). A rerun of the failed job passed. That flake is worth its own issue.

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.
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.
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.
@parsilver
parsilver marked this pull request as ready for review November 16, 2026 00:25
@parsilver

Copy link
Copy Markdown
Contributor Author

Ready for review. Five of the six acceptance criteria are met, with tests. CI is green on Ubuntu and macOS. The sixth asks for green on three OSes, but CI has no Windows job; adding one is a separate decision, explained in the description.

@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.

  • Corrupt credentials.json: Store.read drops the parser's text. The new doctor test, with a real credential inside broken JSON, fails on the old code and passes expectNoSecrets now.
  • ended(): it tells apart a timeout, a program that could not run, a stop by signal and an exit status. It replaces every ?? "timeout" in the keychains and the service manager.
  • Redaction: the start test's fake refusal now carries the credential and still shows [redacted], so it proves the order.
  • private-file.ts:
    • createPrivate removes what is at the path, creates with O_CREAT|O_EXCL|O_NOFOLLOW at 0600 and fchmods the descriptor.
    • makePrivate does lstat and then fchmod on an O_NOFOLLOW descriptor.
    • Every private write and chmod goes through these two.
    • On Windows, where O_NOFOLLOW is absent, the lstat check is the guard. That is acceptable for a user-profile path.

CI is green on macOS and Linux. Releases are manual, so nothing to deploy.

@parsilver
parsilver merged commit 41d3e6c into main Nov 16, 2026
3 of 4 checks passed
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: doctor and keychain warning follow-ups from the #17 review

1 participant