Add secrets_sync.py to Sync Secret Files With 1Password Through op - #4165

Summary

Adds scripts/secrets_sync.py, an attended hub tool. It syncs secret files between a home directory and 1Password through the op CLI. It ships with unit tests in tests/test_secrets_sync.py and a section in scripts/README.md.

• A bucket is a named set of secret files owned by one project or host. Each bucket is one vault named exactly Secrets <bucket>, where the name matches ^[a-z0-9-]+$.
• Each file is one Document item, titled with its POSIX path relative to the home directory. Its mode rides as a mode:<octal> tag.
• No local state and no tracked per-item state. The live comparison is the truth. Consumers keep reading flat files.
• Subcommands: status, push, pull, archive, selftest. The README section states each one's behavior and every guard.

The tool is stdlib-only. It follows scripts/handoff.py's shape: a Parser whose usage errors exit 1, Refusal (1) and Execution (2), and a catch-all that maps an unexpected error to 2, printing its type only. Every op call goes through one runner, run_op, which caps stderr, and --dry-run sits on that same path. SIGINT and SIGTERM take one path, which stops the child, signs out a session the run created, and removes temporary files. The run then ends by re-raising the signal.

tests/test_cli_usage.py gains op among its recorded stubs, so no entry point's run reaches a real op. It also gains status as the BEFORE_FLAG argument for the new script. cspell.json gains the words the new files use.

selftest on op 2.42.0

The maintainer ran selftest against a real op 2.42.0 on Linux, at head c25adbd, on constructed data only.

On Windows 11 the maintainer confirmed that op signin and op whoami work with sign-in assisted by the 1Password desktop app. That ran op itself, not this tool. The tool's own run on Windows is still unexercised. That is the path where op signin prints no session assignment and op whoami then accepts, which a unit test covers through the fake.

Not exercised: --account with several accounts, the PowerShell export form, and the tool's own run on Windows.

Verification

• python3 tests/test_secrets_sync.py passes locally on Linux (Python 3.13). The two interrupt cases run the script under its interpreter with an executable stub op on PATH. One signals mid-call and asserts death by the signal, the child stopped, the created session signed out, and no temporary file left.
• uv run --no-project --with-requirements tests/requirements.txt python tests/test_cli_usage.py and ... tests/test_backlog_metrics.py pass. tests/test_tooling_encoding.py passes.
• ruff check, ruff format, and mypy are clean over the changed files. The prose gate is clean over the diff.
• Each guard was checked by deleting it and confirming a test fails. Every deletion was caught, except a few redundant guards a later round removed.
• No real op ran anywhere. The host has none installed, so everything above is against the fake or the stub. The attended commands below are the live proof, and they need the maintainer.

Attended verification for the maintainer

Run these from a hub checkout. Each uses constructed names, so substitute your own bucket and file.

python3 scripts/secrets_sync.py selftest
python3 scripts/secrets_sync.py push --bucket alpha ~/.secrets/alpha_api_token
python3 scripts/secrets_sync.py status --bucket alpha
mkdir -m 700 /tmp/restore-proof && python3 scripts/secrets_sync.py pull --bucket alpha --home /tmp/restore-proof

Local review passes

Each recorded local-strict-review pass ran at the frontier tier and read the full diff against develop.

• Pass 1 raised 20 findings. The fixes make the signal handler pass over a second signal and have selftest read field names before any parse. They refuse two named paths that differ only in case and a Windows junction as a link. A pull re-reads each target before writing. Missing guard tests were added. The README and test_cli_usage.py findings were the edits held until another pull request released those files.
• Pass 2 raised 15 findings. The fixes refuse Windows-forbidden title characters, the CONIN$/CONOUT$ device names, and a path miscased against the directory. They report an unreadable local path by name and accept a sign-in the desktop app holds. They share one comparison between status and pull. README claims were corrected and guard tests added. Two guards the read-back already covers were removed as over-hardening.
• Pass 3 raised 9 findings after the first push's edit budget was spent. All are fixed in a120d78: a named stale path is refused, a linked title shows as link in status, and the unreachable signout and unread flag are gone. The README's re-check claim and the restore-root docstring were corrected, and the untested guards gained tests.
• Pass 4 raised 11 findings, fixed in cb2e0cf. selftest warns when the vault it made cannot be listed, and prints its results before removing scratch files. Messages name the operation a missing item followed. Tests now cover the second signal, a junction as the restore root, an absent archive vault, a vault create that lists nothing, a missing op, and the stderr cap.
• Pass 5 raised 2 findings, fixed in 2c2b547. A pull skips a local file newer than the remote copy unless --overwrite-newer, mirroring push. A dry-run archive and a dry-run update now have tests.
• Pass 6 raised 3 findings, fixed in d345569. Empty --home, --bucket, and --mode values are usage errors, an unreadable entry under ~/.secrets leaves the unheld list rather than ending status, and archive's prompt is tested.
• Pass 7 raised 4 findings, fixed in 488b837. An empty --account is a usage error, a path under an unlistable directory is refused by name, every op call prints a progress line, and pull, archive, and selftest each prove they need a terminal.
• Pass 8 raised 3 findings, fixed in 3e2da95. A mode-only push is judged for staleness, a push refuses an existing item's malformed tag unless --mode names the replacement, and a test proves the temporary file is 0600 before the secret lands in it.
• Pass 9 raised 2 findings, fixed in a0c2dd8. --mode applies only to files named on the command line, and each plan line shows a mode the write changes as was->now.
• Pass 10 raised 2 findings. The listed() consolidation is fixed in df78664. The staleness finding went to the maintainer, whose decision is below.
• Pass 11 raised 3 findings. Two are fixed in c25adbd: digest prefixes come from an HMAC keyed per run, so an eight-character prefix reveals nothing about a short secret, and a reserved name with a space before its dot or a superscript digit is refused. The third went to the maintainer, whose decision is below.
• Pass 12 raised 2 findings, fixed in d45ddf7.
• Pass 13 raised 3 findings. Two are fixed in 8fd4359: the docstring no longer credits selftest with measuring sign-in, and a new file's group is stated as the platform's choice. The third waits on the design seat, below.
• Pass 14 raised the 2 findings below after this push's edit budget was spent.

Maintainer decisions, applied in d45ddf7

• Staleness judges content only. A file whose content matches and whose mode differs is a tag update, planned and confirmed like any other change, with no time check. ctime is deliberately not used, since a rename or chmod moves it and would hide a stale copy.
• pull keeps the temporary file and os.replace. A replaced file's group is set on the temporary file before the rename, and a group it cannot keep is a refusal. A new file takes the account's default group. The README states that ACLs and extended attributes are not carried.
• Account bootstrap: with no account configured and a terminal on stdin, the tool runs op account add on the terminal, then re-reads the account list and continues into the session. Without a terminal it refuses as before. The tool prints no account address itself.

The pass-12 findings are fixed in d45ddf7: the case-collision test reads the right refusal on a case-insensitive file system, and the README's link rule says "below the home directory". The README now names host-setup/linux/install-tools.sh --install op as where op comes from, and the docstrings say which behaviors 2.42.0 measured.

Open, waiting on the design seat

• scripts/secrets_sync.py cmd_pull: a retag moves the remote updated_at forward without changing content. So a host holding a newer, unpushed copy of that file reads it as older on its next pull, and --yes overwrites it. A later push from that host also skips the file as stale. The recommendation is to record each pushed file's content time as a second tag, mtime:<iso>, and judge staleness against that rather than updated_at. Class: introduced.

Open findings from pass 14 (introduced)

• scripts/secrets_sync.py push_plans: a push lists only its own bucket, so pushing a title another bucket holds creates a second owner. The duplicate is refused only when both buckets are pulled together. Class: introduced.
• scripts/secrets_sync.py write_secret: os.replace makes the running user the owner of a replaced file that another uid owned. The README names the group as carried, and ACLs and extended attributes as not carried, but it does not mention the owner. Class: introduced.

Declined

• Consolidating Parser/Refusal/Execution/report_stderr/rows/run/reraise with scripts/handoff.py and catalog/snippets/hub_fetch_run.py. The snippet is carried standalone and cannot import a sibling. handoff.py's helpers are bound to gh. A shared module would edit another tool and its tests, which is a separate change. Class: design.

Notes

• The pull request runs no real op. The host has none, and every behavior above is against the in-memory fake or the executable stub.
• pull sets the mode on the open temporary file's descriptor before os.replace, rather than on the path afterwards. The file then never appears under another mode, and no chmod follows a path.

🤖 Generated with Claude Code