From ed17b1e70db4a660839e6909b91596122356dba5 Mon Sep 17 00:00:00 2001 From: Daniel JB Clark Date: Mon, 26 Oct 2026 01:52:57 -0400 Subject: [PATCH 1/3] secrets-collect --yes low findings: dated sentinel with age (race vs leftover), exit 3 when the clear failed, SKILL printf only after a failed or missing clear, production lock-path test Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 3 + skills/sudo-secretspec/SKILL.md | 31 ++-- .../scripts/secrets-collect.py | 69 +++++++-- .../sudo_postinstall/test_secrets_collect.py | 138 +++++++++++++++++- 4 files changed, 215 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index eb94cc4d2..6f200f530 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 right after the read under a per-user lock so parallel runs cannot store one copy twice, reports partial stores, and never prints value characters. Piped answers without `--yes` and `--yes` without `--clipboard` are refused. + The sentinel carries the date and says how long ago the copy was consumed, so + a leftover from an earlier run reads differently from a parallel-run race. + A run that stored but could not clear the clipboard exits 3 instead of 0. ### Fixed diff --git a/skills/sudo-secretspec/SKILL.md b/skills/sudo-secretspec/SKILL.md index aaee9ad43..75870640d 100644 --- a/skills/sudo-secretspec/SKILL.md +++ b/skills/sudo-secretspec/SKILL.md @@ -189,11 +189,14 @@ run, on a pty or not: two harnesses share it) is held from before `pbpaste` until after the clear. A second run waits about 10 s for it, then exits 1 ("another secrets-collect run holds the clipboard lock"); one that gets in after the clear reads the sentinel, - which names the run that consumed the copy (`... cleared by the run for NAME at - HH:MM:SS ...`), and exits 1. **A parallel loser is not harmless:** the winner may + which names the run that consumed the copy and when (`... cleared by the run for + NAME at 2026-10-26T01:40:59-0400 ...`) and says how long ago ("N s ago"), and + exits 1. **Within 60 s that is a lock race and the loser is not harmless:** the winner may have taken a copy meant for the loser's name, so **both names must be re-collected, one at a time**, each after a fresh copy. Re-running only the loser leaves the winner holding the wrong value (its length would still pass). + **Older than 60 s it says "a leftover from an earlier run, not a race"**: no other run + is involved, only copy the value again; do not re-collect the named run. 3. **The spec MUST carry the expected length** (`NAME=desc:32`), else exit 2. A regex does not count: the spec cannot carry both, and a regex can match stale prose (`.+`); if you need a pattern, pin the length in it and use it @@ -213,8 +216,12 @@ than retrying, and **overwrites the clipboard itself right after the read** SIGTERM and SIGHUP are blocked while the overwrite runs, so one that arrives then is delivered after it. A SIGKILL or power loss between the read and the clear cannot be caught, and neither can a `pbcopy` that fails). The -next run sees a fresh copy or the sentinel, never the previous secret. A failed -overwrite prints `WARNING: ... NOT cleared`. The rejection text gives a count +next run sees a fresh copy or the sentinel, never the previous secret. **A failed +overwrite prints `WARNING: ... NOT cleared` and the run exits 3 instead of 0** (still +stored and notified, `--dry-run` included; its last line says "...the clipboard was NOT +cleared: overwrite it yourself, exit 3"): treat 3 as "done, but the secret may still be on the +pasteboard", never as a clean success. A run that fails otherwise keeps its code (1, 2, 130). +The rejection text gives a count and character classes, never the characters. A clipboard that was stale **before the first run** and has the same shape and length cannot be detected: have the operator copy, say so in chat, then run. SIGTERM/SIGHUP mid-store gets @@ -230,14 +237,16 @@ since a regex does not waive it. For those, and only those, use `--literal` with ```bash python3 $S --secret 'NAME=desc:32' --clipboard --yes -printf 'cleared' | ~/ops/site-private/bin/clip # regardless of the exit status: `;`, never `&&` +# ONLY if it exited 3, its output says `NOT cleared`, or it gave no report at all (killed or +# timed out: exit 124/137, or no output); after a run that cleared, do NOT run this line: +printf 'cleared' | ~/ops/site-private/bin/clip sudo-secretspec run -- sh -c 'echo ${#NAME}' ``` -The script clears the clipboard itself; the second line is the belt for the -runs where it died before the read (or printed the WARNING). Run it whether or -not the first line succeeded, so a secret never stays on the pasteboard (clipboard -managers, Universal Clipboard). +The script clears the clipboard itself, so the `printf` line is only for the runs where +the value can still be on the pasteboard (a failed clear, or a run that died before it reported). +After a run that cleared it would overwrite the sentinel, which names the run that consumed the +copy, and the next run could no longer tell whose copy it was. Verified 2026-10-26 (stub `sudo-secretspec`/`pbpaste`/`pbcopy`; no live vault). @@ -488,7 +497,9 @@ listener cannot reach private data through it. an expiry you write down. A fine-grained token is `github_pat_` plus 82 characters (93 in all). 2. **Declare:** `sudo-secretspec add NAME --description "..." --optional --reason "..."` (`--optional` so `check` stays green on hosts that never set it). -3. **Store:** the clipboard route above; then overwrite the clipboard. +3. **Store:** the clipboard route above. With `secrets-collect.py` the script clears the clipboard + itself; overwrite it by hand only on exit 3, `NOT cleared` in the output, or no report at all + (the rule under "An agent with no terminal"); otherwise you would erase the sentinel's consumer name. 4. **Prove its reach without printing it.** Run a throwaway script under `run` that prints only the length, the prefix and HTTP statuses, then delete the script: ```bash diff --git a/skills/sudo-secretspec/scripts/secrets-collect.py b/skills/sudo-secretspec/scripts/secrets-collect.py index 46c44fe43..bdf7d474d 100755 --- a/skills/sudo-secretspec/scripts/secrets-collect.py +++ b/skills/sudo-secretspec/scripts/secrets-collect.py @@ -50,12 +50,16 @@ arrives then is delivered after the clear), and (d) holds an exclusive per-user lock (~/Library/Caches/secrets-collect.lock, not under TMPDIR) from before pbpaste until after that overwrite. A second run waits about 10 s, then exits 1; one that gets in after the - clear reads the sentinel and fails, naming the run that consumed the copy: that run may have - taken a copy meant for the loser's name, so BOTH names must be re-collected. A SIGKILL or - power loss between the read and the clear, or a failing pbcopy (a WARNING is printed), leaves - the value on the pasteboard. A clipboard that was stale before the FIRST run and happens to - have the same shape and length is not detectable; --dry-run reads and clears too, so it - consumes the operator's copy. + clear reads the sentinel (it carries the date, time and zone) and fails, naming the run that + consumed the copy and how long ago. Within STALE_AFTER (60 s) that is a lock race: the run + may have taken a copy meant for the loser's name, so BOTH names must be re-collected. Older + than that it is a leftover from an earlier run, no other run is involved: copy the value + again. A SIGKILL or power loss between the read and the clear leaves the value on the + pasteboard. A failing pbcopy prints a WARNING and the run (still storing and notifying, also + under --dry-run) exits 3 instead of 0, its last line saying the clipboard was NOT cleared; + a run that fails otherwise keeps its own code (1, 2, 130). A clipboard that was stale + before the FIRST run and happens to have the same shape and length is not detectable; + --dry-run reads and clears too, so it consumes the operator's copy. --clipboard with a non-tty stdin and no --yes is refused: piped answers are not the operator. 8. A clipboard value identical to one already collected in the same run is refused (the clipboard did not change between secrets), so a pty cannot read one value into N names. @@ -64,6 +68,7 @@ import argparse import contextlib +import datetime import fcntl import getpass import os @@ -80,26 +85,49 @@ CLEARED_PREFIX = "secrets-collect: clipboard cleared" # every sentinel this script ever wrote CLEARED_WORD = "cleared" LOCK_WAIT = 10.0 # seconds a second run waits for the clipboard lock before giving up -_CONSUMER = re.compile(r"cleared by the run for (\S+) at (\d\d:\d\d:\d\d)") +STALE_AFTER = 60.0 # seconds: a sentinel older than this is a leftover, not a lock-race loser's read +_CONSUMER = re.compile(r"cleared by the run for (\S+) at " + r"(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d[+-]\d{4}|\d\d:\d\d:\d\d)") # 2nd: old form +_clear_failed = False # set by clear_clipboard when pbcopy failed; main() resets it and exits 3 def is_sentinel(value: str) -> bool: return value == CLEARED_WORD or value.startswith(CLEARED_PREFIX) +def _sentinel_age(at: str) -> float | None: + """Seconds since the sentinel's stamp, or None when it has no date (the old HH:MM:SS form), + cannot be parsed or lies in the future.""" + try: + age = time.time() - datetime.datetime.strptime(at, "%Y-%m-%dT%H:%M:%S%z").timestamp() + except ValueError: + return None + return age if age >= 0 else None + + def sentinel_error(value: str, name: str) -> str: """Why a sentinel was read. A run that lost the lock race read the winner's sentinel, and the - winner may have taken a copy meant for THIS name, so say who consumed it.""" + winner may have taken a copy meant for THIS name, so say who consumed it. A sentinel older + than STALE_AFTER is not a race (the loser reads it within about LOCK_WAIT of the clear): it + is left over from an earlier run, so no other run is involved.""" m = _CONSUMER.search(value) if not m: return ("the clipboard holds a cleared-clipboard sentinel: no fresh copy was made since " "the last clear") who, at = m.groups() + age = _sentinel_age(at) + ago = "" + if age is not None: + ago = f" ({int(age)} s ago)" if age < 60 else f" ({int(age // 60)} min ago)" + if age is not None and age > STALE_AFTER: + return (f"the clipboard holds a cleared-clipboard sentinel left by the run for {who} at " + f"{at}{ago}: a leftover from an earlier run, not a race, and no other run is " + f"involved; copy the value again (no re-collection of {who} is needed)") if who == name: return (f"the clipboard holds a cleared-clipboard sentinel: an earlier run for {name} " - f"consumed the copy at {at}; copy the value again") + f"consumed the copy at {at}{ago}; copy the value again") return (f"the clipboard holds a cleared-clipboard sentinel: the run for {who} consumed this " - f"copy at {at}; if the copy was for {name}, {who} now holds that value: " + f"copy at {at}{ago}; if the copy was for {name}, {who} now holds that value: " f"re-collect {who} too") @@ -160,6 +188,8 @@ def _ignore_cancel_signals() -> None: def _not_cleared(e: BaseException) -> None: + global _clear_failed + _clear_failed = True print(f" WARNING: the clipboard was NOT cleared ({type(e).__name__}); " "overwrite it yourself", file=sys.stderr) @@ -167,8 +197,8 @@ def _not_cleared(e: BaseException) -> None: def clear_clipboard(name: str) -> None: """Overwrite the pasteboard with a sentinel naming the run that consumed the copy, so a later run cannot read this secret again and a loser of a lock race can say whom to re-collect.""" - mark = (f"{CLEARED_PREFIX} by the run for {name} at {time.strftime('%H:%M:%S')}, " - "copy the value again") + mark = (f"{CLEARED_PREFIX} by the run for {name} at " + f"{time.strftime('%Y-%m-%dT%H:%M:%S%z')}, copy the value again") try: subprocess.run(["pbcopy"], input=mark, text=True, check=True, capture_output=True, env=_pb_env(), timeout=15) @@ -377,6 +407,8 @@ def notify(role: str, names: list[tuple[str, int]], reason: str) -> None: def main() -> int: + global _clear_failed + _clear_failed = False # in-process callers (tests) run main more than once ap = argparse.ArgumentParser(description="Collect and store secret values (see the module docstring).") ap.add_argument("--secret", action="append", required=True, metavar="NAME=DESC[:LEN]", help="repeatable; LEN is an expected character count (warns on mismatch; " @@ -398,9 +430,20 @@ def main() -> int: "Enter wait (tty or not): ONE secret per run, LEN required, the clipboard is " "cleared after the read, and a lock stops two runs at once. Needed for any " "--clipboard run with a non-tty stdin. Without --clipboard it needs a " - "terminal (hidden prompt)") + "terminal (hidden prompt). Exit 3 = done, but the clipboard could not be " + "cleared: overwrite it yourself") a = ap.parse_args() + rc = _run(a) + if rc == 0 and _clear_failed: + what = "dry run, nothing stored" if a.dry_run else "stored" + print(f"{what}, but the clipboard was NOT cleared: overwrite it yourself, exit 3", + flush=True) + return 3 + return rc + + +def _run(a: argparse.Namespace) -> int: tty = sys.stdin.isatty() if a.yes and not a.clipboard and not tty: print("refusing: --yes without --clipboard needs a terminal; a value piped on stdin " diff --git a/tests/sudo_postinstall/test_secrets_collect.py b/tests/sudo_postinstall/test_secrets_collect.py index 7406141c6..67d31a8dc 100644 --- a/tests/sudo_postinstall/test_secrets_collect.py +++ b/tests/sudo_postinstall/test_secrets_collect.py @@ -2,6 +2,7 @@ Every subprocess has a hard timeout: a mutant that loops must fail, not hang CI. """ +import calendar import importlib.util import os import pty @@ -11,6 +12,7 @@ import subprocess import sys import time +import types from pathlib import Path import pytest @@ -20,7 +22,7 @@ LEN = len(VALUE) OLD_MARK = "secrets-collect: clipboard cleared, copy the value again" # round 1/2 sentinel CLEARED = re.compile(r"secrets-collect: clipboard cleared by the run for (\w+) at " - r"\d\d:\d\d:\d\d, copy the value again") + r"\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d[+-]\d{4}, copy the value again") TIMEOUT = 10 @@ -141,8 +143,10 @@ def test_second_run_without_a_fresh_copy_stores_nothing(env): assert calls(log) == "" assert "sentinel" in out(r) # it names the run that consumed the copy, since that run may have taken B's value - assert re.search(r"the run for A consumed this copy at \d\d:\d\d:\d\d", out(r)) + assert re.search(r"the run for A consumed this copy at " + r"\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d[+-]\d{4} \(\d+ s ago\)", out(r)) assert "re-collect A too" in out(r) + assert "leftover" not in out(r) assert "nothing was copied" not in out(r) @@ -157,7 +161,9 @@ def test_second_run_for_the_same_name_says_so(env): @pytest.mark.parametrize("stale", [ "cleared", OLD_MARK, - "secrets-collect: clipboard cleared by the run for Z at 01:02:03, copy the value again"]) + "secrets-collect: clipboard cleared by the run for Z at 01:02:03, copy the value again", + "secrets-collect: clipboard cleared by the run for Z at 2020-01-02T03:04:05+0000, " + "copy the value again"]) def test_sentinels_refused_even_when_length_and_literal_fit(env, stale): _, log, clip, _ = env clip.write_text(stale) @@ -236,6 +242,118 @@ def test_pbcopy_failure_is_loud(env): assert clip.read_text() == VALUE +# --- the sentinel carries a date: a race and a leftover read differently ------------------------- + +def _stamp(epoch): + return time.strftime("%Y-%m-%dT%H:%M:%S%z", time.localtime(epoch)) + + +def _mark(who, stamp): + return f"secrets-collect: clipboard cleared by the run for {who} at {stamp}, copy the value again" + + +@pytest.mark.parametrize("who", ["A", "Z"]) +def test_an_old_sentinel_is_a_leftover_not_a_race(env, who): + _, log, clip, _ = env + mark = _mark(who, _stamp(time.time() - 600)) + clip.write_text(mark) + r = run(env, yes_args(f"A=a:{len(mark)}", "--literal")) + o = out(r) + assert r.returncode == 1 and calls(log) == "" + assert "10 min ago" in o + assert "a leftover from an earlier run, not a race" in o and "no other run is involved" in o + assert "re-collect Z too" not in o and "re-collect A too" not in o + assert "Traceback" not in o + + +def test_sentinel_error_threshold_and_fallbacks(monkeypatch): + m = _load_module() + base = calendar.timegm((2026, 10, 26, 12, 0, 0)) + + def err(stamp, delta, name="A"): + monkeypatch.setattr(m, "time", types.SimpleNamespace(time=lambda: base + delta)) + return m.sentinel_error(_mark("Z", stamp), name) + + dated = "2026-10-26T12:00:00+0000" + e = err(dated, 59) + assert "(59 s ago)" in e and "re-collect Z too" in e and "leftover" not in e + e = err(dated, 60) # exactly STALE_AFTER is still a race + assert "(1 min ago)" in e and "re-collect Z too" in e and "leftover" not in e + e = err(dated, 61) + assert "(1 min ago)" in e and "a leftover from an earlier run, not a race" in e + assert "re-collect Z too" not in e + e = err(dated, 7200) + assert "(120 min ago)" in e and "leftover" in e + e = err(dated, 7200, name="Z") # the same name: leftover too, never "an earlier run for Z" + assert "leftover" in e and "an earlier run for Z" not in e + e = err(dated, 30, name="Z") + assert "an earlier run for Z consumed the copy at" in e and "(30 s ago)" in e + # not usable as an age: the old wording, no crash + for stamp, delta in [(dated, -30), ("2026-13-45T99:99:99+0000", 100), ("01:02:03", 100000)]: + e = err(stamp, delta) + assert "re-collect Z too" in e and "ago" not in e and "leftover" not in e, stamp + + +# --- a failed clear is loud: exit 3 -------------------------------------------------------- + +def _break_pbcopy(bindir): + (bindir / "pbcopy").write_text("#!/bin/sh\nexit 1\n") + + +def test_failed_clear_after_a_store_exits_3_and_says_so(env): + _, log, clip, bindir = env + _break_pbcopy(bindir) + r = run(env, yes_args()) + assert r.returncode == 3, out(r) + assert VALUE in calls(log) # stored all the same + assert "NOT cleared" in r.stderr + assert r.stdout.splitlines()[-1] == ("stored, but the clipboard was NOT cleared: " + "overwrite it yourself, exit 3") + assert clip.read_text() == VALUE + + +def test_failed_clear_on_a_dry_run_exits_3_with_nothing_stored(env): + _, log, clip, bindir = env + _break_pbcopy(bindir) + r = run(env, yes_args(f"A=a:{LEN}", "--dry-run")) + assert r.returncode == 3, out(r) + assert calls(log) == "" + assert r.stdout.splitlines()[-1] == ("dry run, nothing stored, but the clipboard was NOT " + "cleared: overwrite it yourself, exit 3") + + +@pytest.mark.parametrize("spec, extra_env", [(f"A=a:{LEN + 1}", None), (f"A=a:{LEN}", {"FAIL_NAME": "A"})]) +def test_failed_clear_does_not_change_another_failures_code(env, spec, extra_env): + _, log, _, bindir = env + _break_pbcopy(bindir) + r = run(env, yes_args(spec), extra_env=extra_env) # a rejected value / a failed store + assert r.returncode == 1, out(r) + assert "NOT cleared" in r.stderr and "exit 3" not in out(r) + + +def test_a_working_clear_exits_0_and_the_failed_flag_does_not_leak_between_calls( + env, monkeypatch, capsys): + e, log, clip, bindir = env + m = _load_module() + for k in ("PATH", "TMPDIR", "SECRETS_COLLECT_LOCK_DIR"): + monkeypatch.setenv(k, e[k]) + monkeypatch.setattr(sys, "argv", ["secrets-collect", *yes_args()]) + # main() installs SIGTERM/SIGHUP handlers on the pytest process: put them back afterwards + old = {sig: signal.getsignal(sig) for sig in (signal.SIGTERM, signal.SIGHUP)} + try: + good = (bindir / "pbcopy").read_text() + _break_pbcopy(bindir) + assert m.main() == 3 + (bindir / "pbcopy").write_text(good) + clip.write_text(VALUE) + assert m.main() == 0 # a fresh call starts clean + assert cleared_by(clip.read_text()) == "A" + finally: + for sig, h in old.items(): + signal.signal(sig, h) + capsys.readouterr() + + # --- findings 2/12a/3: piped answers are not the operator ------------------------------------ def test_clipboard_with_piped_stdin_and_no_yes_is_refused(env): @@ -372,6 +490,20 @@ def test_unopenable_lock_file_is_reported_as_the_lock(env, tmp_path): assert clip.read_text() == VALUE and calls(log) == "" +def test_default_lock_path_is_under_the_users_home_not_tmpdir(tmp_path, monkeypatch): + m = _load_module() + other = tmp_path / "other_tmpdir" + other.mkdir() + monkeypatch.delenv("SECRETS_COLLECT_LOCK_DIR", raising=False) + monkeypatch.setenv("TMPDIR", str(other)) + monkeypatch.setattr(m, "pwd", types.SimpleNamespace( + getpwuid=lambda uid: types.SimpleNamespace(pw_dir=str(tmp_path)))) + caches = tmp_path / "Library" / "Caches" + assert m.lock_path() == str(caches / "secrets-collect.lock") + assert stat.S_IMODE(caches.stat().st_mode) == 0o700 + assert list(other.iterdir()) == [] # nothing went under TMPDIR + + # --- findings 3, 4: partial stores --------------------------------------------------------- TWO = ["--secret", "A=a", "--secret", "B=b"] From 80d2c9c56dad0a10262b057203ea5d5f00cf1d26 Mon Sep 17 00:00:00 2001 From: Daniel JB Clark Date: Mon, 26 Oct 2026 02:15:10 -0400 Subject: [PATCH 2/3] secrets-collect --yes: another name's sentinel is always conditional, whatever its age (adversary round 5 B1); tz-offset age test; SKILL printf rule covers exit 2 and unreadable clipboard Co-Authored-By: Claude --- CHANGELOG.md | 4 +- skills/sudo-secretspec/SKILL.md | 28 +++++---- .../scripts/secrets-collect.py | 44 +++++++------- .../sudo_postinstall/test_secrets_collect.py | 60 +++++++++++++------ 4 files changed, 82 insertions(+), 54 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6f200f530..a6b114cd4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,8 +16,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 right after the read under a per-user lock so parallel runs cannot store one copy twice, reports partial stores, and never prints value characters. Piped answers without `--yes` and `--yes` without `--clipboard` are refused. - The sentinel carries the date and says how long ago the copy was consumed, so - a leftover from an earlier run reads differently from a parallel-run race. + The sentinel carries the date, time and zone, and the error adds its age, so an + agent can compare the stamp with when the value was copied: copied before it, re-collect both names. A run that stored but could not clear the clipboard exits 3 instead of 0. ### Fixed diff --git a/skills/sudo-secretspec/SKILL.md b/skills/sudo-secretspec/SKILL.md index 75870640d..5a7255203 100644 --- a/skills/sudo-secretspec/SKILL.md +++ b/skills/sudo-secretspec/SKILL.md @@ -189,14 +189,15 @@ run, on a pty or not: two harnesses share it) is held from before `pbpaste` until after the clear. A second run waits about 10 s for it, then exits 1 ("another secrets-collect run holds the clipboard lock"); one that gets in after the clear reads the sentinel, - which names the run that consumed the copy and when (`... cleared by the run for - NAME at 2026-10-26T01:40:59-0400 ...`) and says how long ago ("N s ago"), and - exits 1. **Within 60 s that is a lock race and the loser is not harmless:** the winner may - have taken a copy meant for the loser's name, so **both names must be - re-collected, one at a time**, each after a fresh copy. Re-running only the - loser leaves the winner holding the wrong value (its length would still pass). - **Older than 60 s it says "a leftover from an earlier run, not a race"**: no other run - is involved, only copy the value again; do not re-collect the named run. + which names the run that consumed the copy and carries its date, time, zone and age + (`... cleared by the run for NAME at 2026-10-26T01:40:59-0400 ...`, "N s ago"/"N min ago"), + and exits 1. **The age never proves the loser is harmless: the message is always + conditional.** Compare the stamp with when the operator said the value for the loser's name was + copied. **Copied before the stamp:** the named run may have taken that copy, so **both names + must be re-collected, one at a time**, each after a fresh copy (re-running only the loser + leaves the named run holding the wrong value, and its length would still pass). **Nothing + copied since:** only copy the value again. Never read an old sentinel as "no other run is + involved". 3. **The spec MUST carry the expected length** (`NAME=desc:32`), else exit 2. A regex does not count: the spec cannot carry both, and a regex can match stale prose (`.+`); if you need a pattern, pin the length in it and use it @@ -237,14 +238,16 @@ since a regex does not waive it. For those, and only those, use `--literal` with ```bash python3 $S --secret 'NAME=desc:32' --clipboard --yes -# ONLY if it exited 3, its output says `NOT cleared`, or it gave no report at all (killed or -# timed out: exit 124/137, or no output); after a run that cleared, do NOT run this line: +# ONLY if it exited 3, its stdout or stderr says `NOT cleared`, or it exited 2, or said +# `could not read the clipboard`, and you are not re-running it at once, or it gave no report at +# all (killed or timed out: exit 124/137, or no output); after a run that cleared, do NOT run this line: printf 'cleared' | ~/ops/site-private/bin/clip sudo-secretspec run -- sh -c 'echo ${#NAME}' ``` The script clears the clipboard itself, so the `printf` line is only for the runs where -the value can still be on the pasteboard (a failed clear, or a run that died before it reported). +the value can still be on the pasteboard (a failed clear, or a run that died before it reported) or +where nothing was consumed (exit 2, an unreadable clipboard: clearing erases no consumer name). After a run that cleared it would overwrite the sentinel, which names the run that consumed the copy, and the next run could no longer tell whose copy it was. @@ -498,7 +501,8 @@ listener cannot reach private data through it. 2. **Declare:** `sudo-secretspec add NAME --description "..." --optional --reason "..."` (`--optional` so `check` stays green on hosts that never set it). 3. **Store:** the clipboard route above. With `secrets-collect.py` the script clears the clipboard - itself; overwrite it by hand only on exit 3, `NOT cleared` in the output, or no report at all + itself; overwrite it by hand only on exit 3, `NOT cleared` in stdout or stderr, exit 2, `could not + read the clipboard` (when you are not re-running it at once), or no report at all (the rule under "An agent with no terminal"); otherwise you would erase the sentinel's consumer name. 4. **Prove its reach without printing it.** Run a throwaway script under `run` that prints only the length, the prefix and HTTP statuses, then delete the script: diff --git a/skills/sudo-secretspec/scripts/secrets-collect.py b/skills/sudo-secretspec/scripts/secrets-collect.py index bdf7d474d..121a8a6b7 100755 --- a/skills/sudo-secretspec/scripts/secrets-collect.py +++ b/skills/sudo-secretspec/scripts/secrets-collect.py @@ -50,11 +50,12 @@ arrives then is delivered after the clear), and (d) holds an exclusive per-user lock (~/Library/Caches/secrets-collect.lock, not under TMPDIR) from before pbpaste until after that overwrite. A second run waits about 10 s, then exits 1; one that gets in after the - clear reads the sentinel (it carries the date, time and zone) and fails, naming the run that - consumed the copy and how long ago. Within STALE_AFTER (60 s) that is a lock race: the run - may have taken a copy meant for the loser's name, so BOTH names must be re-collected. Older - than that it is a leftover from an earlier run, no other run is involved: copy the value - again. A SIGKILL or power loss between the read and the clear leaves the value on the + clear reads the sentinel (it carries the date, time and zone; the error adds the age) and + fails, naming the run that consumed the copy. The age never proves that run is unrelated: + compare the stamp with when the operator said the value was copied. Copied before the stamp: + that run may have taken it, so BOTH names must be re-collected, one at a time; nothing copied + since: copy the value again. A same-name sentinel only needs a new copy. A SIGKILL or power + loss between the read and the clear leaves the value on the pasteboard. A failing pbcopy prints a WARNING and the run (still storing and notifying, also under --dry-run) exits 3 instead of 0, its last line saying the clipboard was NOT cleared; a run that fails otherwise keeps its own code (1, 2, 130). A clipboard that was stale @@ -85,7 +86,7 @@ CLEARED_PREFIX = "secrets-collect: clipboard cleared" # every sentinel this script ever wrote CLEARED_WORD = "cleared" LOCK_WAIT = 10.0 # seconds a second run waits for the clipboard lock before giving up -STALE_AFTER = 60.0 # seconds: a sentinel older than this is a leftover, not a lock-race loser's read +AGE_IN_MINUTES_FROM = 60 # seconds: the age is shown as "N s ago" below this, "N min ago" from it _CONSUMER = re.compile(r"cleared by the run for (\S+) at " r"(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d[+-]\d{4}|\d\d:\d\d:\d\d)") # 2nd: old form _clear_failed = False # set by clear_clipboard when pbcopy failed; main() resets it and exits 3 @@ -106,10 +107,9 @@ def _sentinel_age(at: str) -> float | None: def sentinel_error(value: str, name: str) -> str: - """Why a sentinel was read. A run that lost the lock race read the winner's sentinel, and the - winner may have taken a copy meant for THIS name, so say who consumed it. A sentinel older - than STALE_AFTER is not a race (the loser reads it within about LOCK_WAIT of the clear): it - is left over from an earlier run, so no other run is involved.""" + """Why a sentinel was read. Another name's sentinel is ALWAYS conditional, whatever its age: + the run that consumed the copy may have taken a copy meant for THIS name, and the age cannot + say whether the operator copied for this name before that run read the clipboard.""" m = _CONSUMER.search(value) if not m: return ("the clipboard holds a cleared-clipboard sentinel: no fresh copy was made since " @@ -118,17 +118,14 @@ def sentinel_error(value: str, name: str) -> str: age = _sentinel_age(at) ago = "" if age is not None: - ago = f" ({int(age)} s ago)" if age < 60 else f" ({int(age // 60)} min ago)" - if age is not None and age > STALE_AFTER: - return (f"the clipboard holds a cleared-clipboard sentinel left by the run for {who} at " - f"{at}{ago}: a leftover from an earlier run, not a race, and no other run is " - f"involved; copy the value again (no re-collection of {who} is needed)") + ago = (f" ({int(age)} s ago)" if age < AGE_IN_MINUTES_FROM + else f" ({int(age // 60)} min ago)") if who == name: return (f"the clipboard holds a cleared-clipboard sentinel: an earlier run for {name} " f"consumed the copy at {at}{ago}; copy the value again") - return (f"the clipboard holds a cleared-clipboard sentinel: the run for {who} consumed this " - f"copy at {at}{ago}; if the copy was for {name}, {who} now holds that value: " - f"re-collect {who} too") + return (f"the clipboard holds a cleared-clipboard sentinel: the run for {who} consumed a copy " + f"at {at}{ago}; if the operator copied the value for {name} before {at}, {who} now " + f"holds it: re-collect {who} too; if nothing was copied since, only copy again") class StoreError(Exception): @@ -428,10 +425,13 @@ def main() -> int: ap.add_argument("--yes", action="store_true", help="skip the final 'Store these?' prompt. With --clipboard it also skips the " "Enter wait (tty or not): ONE secret per run, LEN required, the clipboard is " - "cleared after the read, and a lock stops two runs at once. Needed for any " - "--clipboard run with a non-tty stdin. Without --clipboard it needs a " - "terminal (hidden prompt). Exit 3 = done, but the clipboard could not be " - "cleared: overwrite it yourself") + "cleared after the read, and a lock stops two runs at once. A run that " + "finds another name's sentinel prints its date, time, zone and age: compare " + "the stamp with when the value for your name was copied (before it: " + "re-collect both names one at a time; nothing copied since: copy again). " + "Needed for any --clipboard run with a non-tty stdin. Without --clipboard " + "it needs a terminal (hidden prompt). Exit 3 = done, but the clipboard " + "could not be cleared: overwrite it yourself") a = ap.parse_args() rc = _run(a) diff --git a/tests/sudo_postinstall/test_secrets_collect.py b/tests/sudo_postinstall/test_secrets_collect.py index 67d31a8dc..b85b928bf 100644 --- a/tests/sudo_postinstall/test_secrets_collect.py +++ b/tests/sudo_postinstall/test_secrets_collect.py @@ -143,11 +143,11 @@ def test_second_run_without_a_fresh_copy_stores_nothing(env): assert calls(log) == "" assert "sentinel" in out(r) # it names the run that consumed the copy, since that run may have taken B's value - assert re.search(r"the run for A consumed this copy at " + assert re.search(r"the run for A consumed a copy at " r"\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d[+-]\d{4} \(\d+ s ago\)", out(r)) assert "re-collect A too" in out(r) + assert "if nothing was copied since, only copy again" in out(r) assert "leftover" not in out(r) - assert "nothing was copied" not in out(r) def test_second_run_for_the_same_name_says_so(env): @@ -253,20 +253,32 @@ def _mark(who, stamp): @pytest.mark.parametrize("who", ["A", "Z"]) -def test_an_old_sentinel_is_a_leftover_not_a_race(env, who): +def test_an_old_sentinel_for_another_name_is_still_conditional(env, who): _, log, clip, _ = env mark = _mark(who, _stamp(time.time() - 600)) clip.write_text(mark) - r = run(env, yes_args(f"A=a:{len(mark)}", "--literal")) + r = run(env, yes_args(f"B=b:{len(mark)}", "--literal")) o = out(r) assert r.returncode == 1 and calls(log) == "" assert "10 min ago" in o - assert "a leftover from an earlier run, not a race" in o and "no other run is involved" in o - assert "re-collect Z too" not in o and "re-collect A too" not in o + assert f"re-collect {who} too" in o and "if nothing was copied since, only copy again" in o + for verdict in ("no re-collection", "leftover", "not a race", "no other run"): + assert verdict not in o assert "Traceback" not in o -def test_sentinel_error_threshold_and_fallbacks(monkeypatch): +@pytest.mark.parametrize("tz", ["UTC", "America/New_York"]) +def test_sentinel_error_age_and_fallbacks(monkeypatch, tz): + monkeypatch.setenv("TZ", tz) + time.tzset() + try: + _check_sentinel_error_age_and_fallbacks(monkeypatch) + finally: + monkeypatch.undo() + time.tzset() + + +def _check_sentinel_error_age_and_fallbacks(monkeypatch): m = _load_module() base = calendar.timegm((2026, 10, 26, 12, 0, 0)) @@ -274,24 +286,36 @@ def err(stamp, delta, name="A"): monkeypatch.setattr(m, "time", types.SimpleNamespace(time=lambda: base + delta)) return m.sentinel_error(_mark("Z", stamp), name) + def conditional(e): + return ("re-collect Z too" in e and "if nothing was copied since, only copy again" in e + and "if the operator copied the value for A before" in e + and not any(v in e for v in ("no re-collection", "leftover", "not a race", + "no other run"))) + dated = "2026-10-26T12:00:00+0000" e = err(dated, 59) - assert "(59 s ago)" in e and "re-collect Z too" in e and "leftover" not in e - e = err(dated, 60) # exactly STALE_AFTER is still a race - assert "(1 min ago)" in e and "re-collect Z too" in e and "leftover" not in e + assert "(59 s ago)" in e and conditional(e) + e = err(dated, 60) # the unit switches at 60 s, nothing else does + assert "(1 min ago)" in e and conditional(e) e = err(dated, 61) - assert "(1 min ago)" in e and "a leftover from an earlier run, not a race" in e - assert "re-collect Z too" not in e + assert "(1 min ago)" in e and conditional(e) e = err(dated, 7200) - assert "(120 min ago)" in e and "leftover" in e - e = err(dated, 7200, name="Z") # the same name: leftover too, never "an earlier run for Z" - assert "leftover" in e and "an earlier run for Z" not in e + assert "(120 min ago)" in e and conditional(e) + # a stamp with a non-zero offset is the same instant as 12:00 UTC; a parse that ignores + # the zone (reads it as local time) is off by hours at TZ=UTC or New_York alike + e = err("2026-10-26T08:00:00-0400", 30) + assert "(30 s ago)" in e and conditional(e) + e = err("2026-10-26T17:30:00+0530", 90) # 12:00 UTC + assert "(1 min ago)" in e and conditional(e) + e = err(dated, 7200, name="Z") # the same name: only a new copy, never "re-collect" + assert "an earlier run for Z consumed the copy at" in e and "(120 min ago)" in e + assert "re-collect" not in e e = err(dated, 30, name="Z") assert "an earlier run for Z consumed the copy at" in e and "(30 s ago)" in e - # not usable as an age: the old wording, no crash + # not usable as an age: the conditional text without an age, no crash for stamp, delta in [(dated, -30), ("2026-13-45T99:99:99+0000", 100), ("01:02:03", 100000)]: e = err(stamp, delta) - assert "re-collect Z too" in e and "ago" not in e and "leftover" not in e, stamp + assert conditional(e) and "ago" not in e, stamp # --- a failed clear is loud: exit 3 -------------------------------------------------------- @@ -423,7 +447,7 @@ def test_parallel_runs_store_the_copy_at_most_once(env, tmp_path, own_tmpdirs): winner = names[[rc for _, rc in res].index(0)] loser_out = res[1 - names.index(winner)][0] assert cleared_by(clip.read_text()) == winner - assert f"the run for {winner} consumed this copy" in "".join(loser_out) + assert f"the run for {winner} consumed a copy" in "".join(loser_out) assert f"re-collect {winner} too" in "".join(loser_out) From 79c09395ae2ad2198873568bb5c221b270eba962 Mon Sep 17 00:00:00 2001 From: Daniel JB Clark Date: Mon, 26 Oct 2026 02:23:27 -0400 Subject: [PATCH 3/3] secrets-collect --yes: wording from adversary round 6 (L1' printf rule, L3 stamp vs copy, N1-N3) Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 4 +-- skills/sudo-secretspec/SKILL.md | 34 +++++++++++-------- .../scripts/secrets-collect.py | 12 +++---- .../sudo_postinstall/test_secrets_collect.py | 2 +- 4 files changed, 29 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a6b114cd4..2be82049a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,8 +16,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 right after the read under a per-user lock so parallel runs cannot store one copy twice, reports partial stores, and never prints value characters. Piped answers without `--yes` and `--yes` without `--clipboard` are refused. - The sentinel carries the date, time and zone, and the error adds its age, so an - agent can compare the stamp with when the value was copied: copied before it, re-collect both names. + The sentinel carries the date, time and zone, and the error adds its age; + if the value was copied before the stamp, re-collect both names. A run that stored but could not clear the clipboard exits 3 instead of 0. ### Fixed diff --git a/skills/sudo-secretspec/SKILL.md b/skills/sudo-secretspec/SKILL.md index 5a7255203..3c3d7ec8f 100644 --- a/skills/sudo-secretspec/SKILL.md +++ b/skills/sudo-secretspec/SKILL.md @@ -192,12 +192,15 @@ run, on a pty or not: which names the run that consumed the copy and carries its date, time, zone and age (`... cleared by the run for NAME at 2026-10-26T01:40:59-0400 ...`, "N s ago"/"N min ago"), and exits 1. **The age never proves the loser is harmless: the message is always - conditional.** Compare the stamp with when the operator said the value for the loser's name was - copied. **Copied before the stamp:** the named run may have taken that copy, so **both names - must be re-collected, one at a time**, each after a fresh copy (re-running only the loser - leaves the named run holding the wrong value, and its length would still pass). **Nothing - copied since:** only copy the value again. Never read an old sentinel as "no other run is - involved". + conditional.** A copy made after the stamp would have replaced the sentinel, so while the + sentinel is on the clipboard every copy the operator made was before it. **If the operator told + you they copied the value for the loser's name** (whenever they said so: their message + arrives after the copy, often after the stamp, so never compare the stamp with the message), + the named run may have taken that copy, so **both names must be re-collected, one at a time**, + each after a fresh copy (re-running only the loser leaves the named run holding the wrong + value, and its length would still pass). **Only if the operator confirms they had not copied + yet:** copy the value again. **Unsure: re-collect both.** Never read an old sentinel as "no + other run is involved". 3. **The spec MUST carry the expected length** (`NAME=desc:32`), else exit 2. A regex does not count: the spec cannot carry both, and a regex can match stale prose (`.+`); if you need a pattern, pin the length in it and use it @@ -238,16 +241,19 @@ since a regex does not waive it. For those, and only those, use `--literal` with ```bash python3 $S --secret 'NAME=desc:32' --clipboard --yes -# ONLY if it exited 3, its stdout or stderr says `NOT cleared`, or it exited 2, or said -# `could not read the clipboard`, and you are not re-running it at once, or it gave no report at -# all (killed or timed out: exit 124/137, or no output); after a run that cleared, do NOT run this line: +# ONLY if it exited 3, its stdout or stderr says `NOT cleared`, or it gave no report at all +# (killed or timed out: exit 124/137, or no output). After a run that cleared, do NOT run this line. +# A run that never read the clipboard (exit 2, `bad --secret`/`bad secret name`/`bad regex`, +# `could not open the lock file`, `could not read the clipboard`): fix the call and re-run it, +# that run reads, clears and reports any sentinel; run this line only if you give up on the name. printf 'cleared' | ~/ops/site-private/bin/clip sudo-secretspec run -- sh -c 'echo ${#NAME}' ``` The script clears the clipboard itself, so the `printf` line is only for the runs where -the value can still be on the pasteboard (a failed clear, or a run that died before it reported) or -where nothing was consumed (exit 2, an unreadable clipboard: clearing erases no consumer name). +the value can still be on the pasteboard (a failed clear, or a run that died before it reported), +or for giving up on a name after a run that never read the clipboard. Do not run it before +re-running: such a run never looked at the clipboard, which may hold another run's sentinel. After a run that cleared it would overwrite the sentinel, which names the run that consumed the copy, and the next run could no longer tell whose copy it was. @@ -501,9 +507,9 @@ listener cannot reach private data through it. 2. **Declare:** `sudo-secretspec add NAME --description "..." --optional --reason "..."` (`--optional` so `check` stays green on hosts that never set it). 3. **Store:** the clipboard route above. With `secrets-collect.py` the script clears the clipboard - itself; overwrite it by hand only on exit 3, `NOT cleared` in stdout or stderr, exit 2, `could not - read the clipboard` (when you are not re-running it at once), or no report at all - (the rule under "An agent with no terminal"); otherwise you would erase the sentinel's consumer name. + itself; overwrite it by hand only on exit 3, `NOT cleared` in stdout or stderr, or no report at all, + or to give up on the name after a run that never read the clipboard (the rule under "An agent + with no terminal"); otherwise you would erase the sentinel's consumer name. 4. **Prove its reach without printing it.** Run a throwaway script under `run` that prints only the length, the prefix and HTTP statuses, then delete the script: ```bash diff --git a/skills/sudo-secretspec/scripts/secrets-collect.py b/skills/sudo-secretspec/scripts/secrets-collect.py index 121a8a6b7..88a1bc2b9 100755 --- a/skills/sudo-secretspec/scripts/secrets-collect.py +++ b/skills/sudo-secretspec/scripts/secrets-collect.py @@ -52,9 +52,9 @@ that overwrite. A second run waits about 10 s, then exits 1; one that gets in after the clear reads the sentinel (it carries the date, time and zone; the error adds the age) and fails, naming the run that consumed the copy. The age never proves that run is unrelated: - compare the stamp with when the operator said the value was copied. Copied before the stamp: - that run may have taken it, so BOTH names must be re-collected, one at a time; nothing copied - since: copy the value again. A same-name sentinel only needs a new copy. A SIGKILL or power + a copy made after the stamp would have replaced it, so if the operator copied the value for + this name at all, that run may have taken it and BOTH names must be re-collected, one at a + time; only if the operator had not copied yet: copy the value again; unsure: both. A same-name sentinel only needs a new copy. A SIGKILL or power loss between the read and the clear leaves the value on the pasteboard. A failing pbcopy prints a WARNING and the run (still storing and notifying, also under --dry-run) exits 3 instead of 0, its last line saying the clipboard was NOT cleared; @@ -429,9 +429,9 @@ def main() -> int: "finds another name's sentinel prints its date, time, zone and age: compare " "the stamp with when the value for your name was copied (before it: " "re-collect both names one at a time; nothing copied since: copy again). " - "Needed for any --clipboard run with a non-tty stdin. Without --clipboard " - "it needs a terminal (hidden prompt). Exit 3 = done, but the clipboard " - "could not be cleared: overwrite it yourself") + "Exit 3 = done, but the clipboard could not be cleared: overwrite it " + "yourself. Needed for any --clipboard run with a non-tty stdin. Without " + "--clipboard it needs a terminal (hidden prompt)") a = ap.parse_args() rc = _run(a) diff --git a/tests/sudo_postinstall/test_secrets_collect.py b/tests/sudo_postinstall/test_secrets_collect.py index b85b928bf..08dee54fe 100644 --- a/tests/sudo_postinstall/test_secrets_collect.py +++ b/tests/sudo_postinstall/test_secrets_collect.py @@ -242,7 +242,7 @@ def test_pbcopy_failure_is_loud(env): assert clip.read_text() == VALUE -# --- the sentinel carries a date: a race and a leftover read differently ------------------------- +# --- the sentinel carries a date and an age: the other-name text stays conditional at every age ------------------------- def _stamp(epoch): return time.strftime("%Y-%m-%dT%H:%M:%S%z", time.localtime(epoch))