cli: day-1 bootstrap helpers — config check, agent cert, node pair, plaintext crypt

[mbertschler]

Summary

Bootstrap-day helpers from #162 — the friction-densest stretch of the reference-setup walk (F1–F4, F34). Four of the five scoped items land here; listener-less agent mode (F35) is deferred to a small follow-up PR so this one stays reviewable.

Changes

• squirrel config check (F4, F8, F34, F21) — parses and resolves the whole config (env vars included), stats every volume path and node byte-path, validates offload_requires against target capabilities, and prints the affirmative N volumes, M destinations, K nodes — all resolvable. Strictly read-only (a question per ux-principle 2): it never opens the store or creates a path. Missing/empty volume paths, missing node byte-paths, and structurally-unsatisfiable offload targets are surfaced; problems exit non-zero, advisory warnings do not.
• squirrel agent cert (F1) — generates an ECDSA self-signed cert+key at the configured [agent.tls] paths and prints the sha256: pin ready to paste into peers' [nodes.X.tls]. Refuses to clobber an existing cert without --force (regenerating changes the fingerprint and breaks every peer that pinned it). The agent now also logs its own fingerprint on the startup line.
• squirrel node pair <peer> (F3) — see decision below.
• Plaintext crypt passwords (F2) — see breaking-change note below.

⚠️ Decision to confirm: node pair shape

The issue left "exact shape to be designed in the PR". I implemented the simplest defensible shape: squirrel node pair <peer> emits the matching config halves for both sides of the relationship. It generates the two bearer tokens a bidirectional pair needs and places each in the two slots that must agree ([nodes.X].auth.bearer on one side ≡ [agent.auth.peers.X].bearer on the other), so the four-binding token matrix is correct by construction — killing the F3 error class. This node's endpoint/fingerprint are filled where known; peer-side facts it cannot know (peer endpoint/path/fingerprint, and where the peer mounts this node) are clearly-marked <...> placeholders, fillable via --peer-endpoint / --peer-path / --peer-fingerprint / --local-endpoint. It prints only — it never edits either config, so the operator reviews and pastes.

Alternatives not taken (heavier): writing directly into config files, or a stateful interactive handshake between two running agents. Please confirm this print-both-halves shape before it sets precedent.

⚠️ Breaking change + migration: crypt secrets

Crypt password/password2 are now plaintext by default (a literal or { env = "VAR" }); squirrel obscures them into rclone's on-disk form at load time, retiring the manual rclone obscure step. A config that already holds obscured values will double-obscure and fail to decrypt. Migration, documented in docs/.../encrypted.md and the README:

• Recommended: put the plaintext in the env var / literal and drop nothing else — squirrel handles the rest.
• Keep existing obscured values: add obscured = true to the crypt block (a marker key) to render them verbatim.

The obscure helper matches rclone's format (AES-CTR under rclone's public key, base64url) but derives the IV deterministically from the plaintext, so the rendered rclone.conf stays byte-stable and the "unexpected rewrite is a signal" invariant in WriteRcloneConfig holds. Determinism costs nothing: obscure is obfuscation, not encryption (the key is public). Cross-checked against real rclone reveal in a (rclone-gated) test. This reconciles with the parallel #153 obscure work — expect a merge reconciliation if both land.

Testing

• go vet ./..., go test ./..., golangci-lint run (v2.12.2) — all clean.
• New tests: obscure round-trip/determinism/rclone-reveal cross-check; plaintext-vs-obscured crypt resolution; cert generation + fingerprint identity with the peer-sync verifier; config check affirmative/empty/missing/offload-unsatisfiable/read-only; agent cert generate/refuse-overwrite/force/no-tls; node pair both-halves cross-match + placeholders + fingerprint embedding.

Scope

Addresses #162 (F1–F4, F34). Listener-less agent mode (F35) follows in a separate PR referencing #162, so this PR intentionally does not close the issue.

🤖 Generated with Claude Code

https://claude.ai/code/session_014Skm2Qm6wWUB7dD4CpPTz7

---

Generated by Claude Code

[Copilot]

Pull request overview

Adds “day-1 bootstrap” CLI helpers and config ergonomics to reduce setup friction around config validation, agent TLS pinning, node pairing, and crypt secret handling.

Changes:

• Add squirrel config check for read-only, full config resolution + path/policy validation with an affirmative summary.
• Add squirrel agent cert and log the agent TLS fingerprint at startup for easy peer pinning.
• Add squirrel node pair <peer> to emit both sides of a bidirectional peer relationship (tokens/endpoints/fingerprints) and switch crypt password/password2 to plaintext-by-default with an obscured = true migration marker.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
sync/rclone_test.go	Updates test config fixture to include crypt.obscured = true.
README.md	Documents plaintext-by-default crypt secrets and the obscured migration marker.
docs/src/content/docs/reference/configuration.md	Updates reference docs for crypt secrets + obscured flag.
docs/src/content/docs/layouts/encrypted.md	Updates encrypted layout docs and adds migration note for already-obscured configs.
config/obscure.go	Implements rclone-compatible “obscure” encoding with deterministic IV derivation.
config/obscure_test.go	Adds round-trip/determinism tests and an optional cross-check against rclone reveal.
config/destinations.go	Resolves crypt secrets (plaintext→obscured) and supports crypt.obscured passthrough.
config/crypt_plaintext_test.go	Tests plaintext→obscured behavior and obscured = true migration behavior.
config/config.go	Updates Crypt struct docs to reflect plaintext-by-default + obscured behavior.
config/config_test.go	Updates config tests/fixtures to include obscured = true where needed.
cmd/squirrel/root.go	Registers new top-level config and node command groups.
cmd/squirrel/node.go	Adds squirrel node parent command.
cmd/squirrel/node_pair.go	Implements squirrel node pair <peer> which prints both config halves with tokens/placeholders.
cmd/squirrel/node_pair_test.go	Tests node pairing output shape, token cross-match, and fingerprint embedding.
cmd/squirrel/config.go	Adds squirrel config parent command.
cmd/squirrel/config_check.go	Implements squirrel config check validation/statting + summarized outcome.
cmd/squirrel/config_check_test.go	Tests config check success/warn/fail paths and “read-only” invariant.
cmd/squirrel/agent.go	Adds agent cert subcommand and logs cert fingerprint on startup when TLS is enabled.
cmd/squirrel/agent_cert.go	Implements squirrel agent cert to generate cert/key and print pasteable pin snippet.
cmd/squirrel/agent_cert_test.go	Tests cert generation, refusal to overwrite, --force, and missing TLS config behavior.
agent/cert.go	Adds self-signed cert generation + fingerprinting helpers used by CLI and server logging.
agent/cert_test.go	Tests cert/key validity, fingerprint correctness/shape, uniqueness, and file fingerprinting.
agent/agent.go	Adds Server.CertFingerprint() accessor used for startup logging.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.