notbefore 0.2.0__tar.gz

notbefore-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+chain/pending/*.secret
+chain/pending/*.revealed
+cycle.log
+cycle.out
+tsa-certs/
+__pycache__/
+*.pyc
+
+# vendored inside the CLI package (the repo-root tsa-certs/ cache stays ignored)
+!cli/notbefore/verifier/tsa-certs/
+cli/dist/
+cli/.venv/
+cli/*.egg-info/
+.pytest_cache/

notbefore-0.2.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Bill Dailey (docdailey)
+
+Applies to the software in this repository: verify.py, pulse.py, tsa.py, drand_anchor.py,
+bls_drand.py, watcher.py, beacon-cycle.py, make_pulse.py, ci/, merkle/*.py, systemd/.
+The published log data and documents are licensed separately — see LICENSE-DATA.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

notbefore-0.2.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: notbefore
+Version: 0.2.0
+Summary: NotBefore: verify an hourly commit-then-reveal seed from the public qrng-beacon-log and derive labeled seeds, shuffles and splits from it — with a pinned, vendored verifier.
+Project-URL: Homepage, https://github.com/docdailey/qrng-beacon-log
+Project-URL: Specification, https://github.com/docdailey/qrng-beacon-log/blob/main/NOTBEFORE.md
+Project-URL: Log, https://github.com/docdailey/qrng-beacon-log/tree/main/chain
+Author: docdailey
+License: MIT
+License-File: LICENSE
+Keywords: beacon,commit-reveal,drand,randomness,reproducibility,transparency-log
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Requires-Dist: py-ecc>=7
+Provides-Extra: anchors
+Requires-Dist: opentimestamps-client>=0.7; extra == 'anchors'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# notbefore
+
+Consumer CLI for the public **qrng-beacon-log** — an hourly, commit-then-reveal, host-attested randomness log
+anchored to drand quicknet, RFC 3161 timestamps, Rekor and OpenTimestamps. Spec: `NOTBEFORE.md` (draft 0.2) in
+<https://github.com/docdailey/qrng-beacon-log>.
+
+**What it proves:** the 32-byte attested value \(V\) of hour \(N\) was **fixed before** drand round \(R\) and
+**not selected after** \(R\) existed. **What it does not prove:** that the bits are quantum, secret, certified, or
+unique. This is not a certification of anything; see `CLAIMS.md` in the log repository.
+
+```bash
+pip install notbefore            # needs git and openssl on PATH; add [anchors] for OpenTimestamps proofs
+notbefore verify 41              # commit 40 + reveal 41: signatures (pinned keys), drand BLS offline, RFC 3161, Rekor anchors
+notbefore value 41               # V, only if verify passes
+notbefore seed 41 --purpose clinic-qi-roster-2026-09-12       # S = SHA256("notbefore/derive/v1" || V || purpose)
+notbefore shuffle 41 --purpose split:iris-csv:v3 rows.txt      # deterministic shuffle of the lines of rows.txt
+notbefore split 41 --purpose split:iris-csv:v3 --frac 0.8 rows.txt
+```
+
+`seed`, `shuffle` and `split` write a **transcript** JSON (`notbefore-<seq>-<purpose>.json`) — the engineering
+artifact that lets anyone reproduce the result from the public log.
+
+**Trust model.** The verifier, the signing keys, the drand group key, the Rekor log key, the freetsa CA and the
+expected host configuration are **vendored inside this package**, pinned at a named commit of the log repository
+(`notbefore --version` prints it). The CLI executes only those files; the log is read as data. Updating the
+verifier means updating the package — deliberately.
+
+Eligible pairs start at 0020/0021 (0026/0027 preferred, execution enforced). `verify 19` fails by design (ERR-007).
+Pulses 0001–0041 carry retroactive anchors (2026-09-12 12:47 UTC); from 0042 anchors are contemporaneous.
+
+MIT. Data in the log: CC BY 4.0.

notbefore-0.2.0/README.md

@@ -0,0 +1,31 @@
+# notbefore
+
+Consumer CLI for the public **qrng-beacon-log** — an hourly, commit-then-reveal, host-attested randomness log
+anchored to drand quicknet, RFC 3161 timestamps, Rekor and OpenTimestamps. Spec: `NOTBEFORE.md` (draft 0.2) in
+<https://github.com/docdailey/qrng-beacon-log>.
+
+**What it proves:** the 32-byte attested value \(V\) of hour \(N\) was **fixed before** drand round \(R\) and
+**not selected after** \(R\) existed. **What it does not prove:** that the bits are quantum, secret, certified, or
+unique. This is not a certification of anything; see `CLAIMS.md` in the log repository.
+
+```bash
+pip install notbefore            # needs git and openssl on PATH; add [anchors] for OpenTimestamps proofs
+notbefore verify 41              # commit 40 + reveal 41: signatures (pinned keys), drand BLS offline, RFC 3161, Rekor anchors
+notbefore value 41               # V, only if verify passes
+notbefore seed 41 --purpose clinic-qi-roster-2026-09-12       # S = SHA256("notbefore/derive/v1" || V || purpose)
+notbefore shuffle 41 --purpose split:iris-csv:v3 rows.txt      # deterministic shuffle of the lines of rows.txt
+notbefore split 41 --purpose split:iris-csv:v3 --frac 0.8 rows.txt
+```
+
+`seed`, `shuffle` and `split` write a **transcript** JSON (`notbefore-<seq>-<purpose>.json`) — the engineering
+artifact that lets anyone reproduce the result from the public log.
+
+**Trust model.** The verifier, the signing keys, the drand group key, the Rekor log key, the freetsa CA and the
+expected host configuration are **vendored inside this package**, pinned at a named commit of the log repository
+(`notbefore --version` prints it). The CLI executes only those files; the log is read as data. Updating the
+verifier means updating the package — deliberately.
+
+Eligible pairs start at 0020/0021 (0026/0027 preferred, execution enforced). `verify 19` fails by design (ERR-007).
+Pulses 0001–0041 carry retroactive anchors (2026-09-12 12:47 UTC); from 0042 anchors are contemporaneous.
+
+MIT. Data in the log: CC BY 4.0.

notbefore-0.2.0/notbefore/__init__.py

@@ -0,0 +1,12 @@
+"""NotBefore — the consumer side of the qrng-beacon-log: verify one hourly commit-then-reveal pair with a
+pinned, vendored verifier, and derive labeled seeds / shuffles / splits from its attested value.
+
+Spec: NOTBEFORE.md in https://github.com/docdailey/qrng-beacon-log (draft 0.2). Not a certification of anything.
+"""
+__version__ = "0.2.0"
+SPEC = "notbefore/spec/0.2"
+D_DERIVE = b"notbefore/derive/v1"
+D_SHUFFLE = b"notbefore/shuffle/v1"
+DEFAULT_REPO = "https://github.com/docdailey/qrng-beacon-log.git"
+FIRST_ELIGIBLE_REVEAL = 21          # 0020/0021; 18/19 are KNOWN-NONCOMPLIANT (ERR-007)
+ANCHOR_GRACE_S = 1500               # a pulse older than this with no anchor is non-compliant

notbefore-0.2.0/notbefore/check.py

@@ -0,0 +1,115 @@
+"""Verify one NotBefore pair (commit N-1, reveal N) with the VENDORED verifier and keys (NOTBEFORE.md §5–6).
+The log supplies data only. Exit-code discipline: a CheckResult with ok=False must never yield V or S."""
+import os, sys, json, subprocess, time, base64
+from . import FIRST_ELIGIBLE_REVEAL, ANCHOR_GRACE_S
+from .log import LogSource
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+VENDOR = os.path.join(HERE, "verifier")
+KEYS = os.path.join(VENDOR, "keys")
+sys.path.insert(0, os.path.join(VENDOR, "ci"))
+
+def vendored_meta():
+    try: return json.load(open(os.path.join(VENDOR, "VENDORED.json")))
+    except Exception: return {}
+
+def known_noncompliant():
+    try: return {int(k): v for k, v in json.load(open(os.path.join(VENDOR, "ci", "KNOWN_NONCOMPLIANT.json"))).get("pulses", {}).items()}
+    except Exception: return {}
+
+class CheckResult:
+    def __init__(self, seq):
+        self.seq = seq; self.ok = True; self.lines = []; self.verbose = []
+        self.commit_seq = self.pulse_hash_reveal = self.pulse_hash_commit = self.attested_value = self.drand_round = None
+        self.bls_offline = False; self.tsa_pass = 0; self.anchors = "not checked"
+        self.log_git_sha = self.log_ref = None; self.verifier_git_sha = vendored_meta().get("git_sha")
+    def say(self, ok, msg, level=None):
+        tag = level or ("PASS" if ok else "FAIL")
+        if tag == "FAIL": self.ok = False
+        self.lines.append(f"[{tag}] {msg}")
+    def summary(self):
+        return {"ok": self.ok, "bls_offline": self.bls_offline, "tsa_tokens_verified": self.tsa_pass, "anchors": self.anchors,
+                "lines": self.lines}
+
+def _run(args, cwd=None):
+    r = subprocess.run([sys.executable, *args], cwd=cwd, capture_output=True, text=True); return r.returncode, r.stdout + r.stderr
+
+def check_pair(seq: int, src: LogSource, refetch=True, anchors=True, verbose=False) -> CheckResult:
+    R = CheckResult(seq); R.log_git_sha, R.log_ref = src.log_git_sha, (src.ref or "working tree")
+    knc = known_noncompliant()
+    # ---- eligibility (§6) before anything is executed
+    if seq < FIRST_ELIGIBLE_REVEAL: R.say(False, f"seq {seq} is below the first eligible reveal ({FIRST_ELIGIBLE_REVEAL}); pulses 1–17 are legacy (ERR-005), 18–19 KNOWN-NONCOMPLIANT (ERR-007)")
+    for s in (seq, seq - 1):
+        if s in knc: R.say(False, f"seq {s} is KNOWN-NONCOMPLIANT ({knc[s].get('erratum')}): {knc[s].get('reason')}")
+    if not R.ok: return R
+    rev = src.pulse(seq); com = src.pulse(seq - 1)
+    if rev is None: R.say(False, f"pulse {seq:04d} is not in the log at {R.log_ref}"); return R
+    if com is None: R.say(False, f"predecessor pulse {seq-1:04d} is not in the log"); return R
+    rc_, cc_ = rev["core"], com["core"]
+    R.pulse_hash_reveal, R.pulse_hash_commit = rev["pulse_hash"], com["pulse_hash"]
+    R.say(rc_.get("v") == "0.5", f"reveal {seq:04d} is protocol v0.5 (got {rc_.get('v') or rc_.get('version') or 'legacy'})")
+    R.say(rc_.get("type") == "reveal", f"pulse {seq:04d} is a reveal (type {rc_.get('type')})")
+    R.say(cc_.get("type") == "commit", f"pulse {seq-1:04d} is a commit (type {cc_.get('type')})")
+    R.say((rc_.get("derived") or {}).get("commit_seq") == seq - 1, f"reveal names commit_seq {seq-1} (derived.commit_seq = {(rc_.get('derived') or {}).get('commit_seq')})")
+    if not R.ok: return R
+    R.commit_seq = seq - 1; R.attested_value = rc_["derived"]["attested_value"]; R.drand_round = rc_["drand"]["round"]
+    # ---- materialize the pair (+ the commit's predecessor for its chain link) and run the vendored verifier
+    p_rev, p_com = src.materialize(seq), src.materialize(seq - 1)
+    p_pp = src.materialize(seq - 2) if src.has_pulse(seq - 2) else None
+    vpy = os.path.join(VENDOR, "verify.py"); extra = ["--refetch"] if refetch else []
+    rc, out = _run([vpy, p_com, "--pin", KEYS] + (["--prev", p_pp] if p_pp else []) + extra); R.verbose.append(out)
+    R.say(rc == 0 and "ALL CHECKS PASSED" in out, f"commit {seq-1:04d}: vendored verify.py (pinned keys{', chained to %04d' % (seq-2) if p_pp else ''}{', drand refetched' if refetch else ''})")
+    _bls_c = "[full BLS, offline]" in out and "BLS verification skipped" not in out
+    rc, out = _run([vpy, p_rev, "--pin", KEYS, "--prev", p_com] + extra); R.verbose.append(out)
+    R.say(rc == 0 and "ALL CHECKS PASSED" in out, f"reveal {seq:04d}: vendored verify.py (pinned keys, chained to {seq-1:04d}, C = SHA256(D_commit||E), V recomputed, timing contract{', drand refetched' if refetch else ''})")
+    R.bls_offline = _bls_c and "[full BLS, offline]" in out and "BLS verification skipped" not in out
+    R.say(R.bls_offline, "drand round BLS-verified offline under the pinned quicknet group key (py_ecc)")
+    if f"Attested value {R.attested_value}" not in out: R.say(False, "verifier's attested value differs from the pulse's derived.attested_value")
+    # ---- RFC 3161 on the commit
+    rc, out = _run([os.path.join(VENDOR, "tsa.py"), "verify", p_com]); R.verbose.append(out)
+    R.tsa_pass = out.count("[PASS] RFC3161")
+    R.say(R.tsa_pass >= 2 and "[FAIL]" not in out, f"commit {seq-1:04d}: {R.tsa_pass} RFC 3161 token(s) verify (need ≥ 2: freetsa + DigiCert)")
+    # ---- publication anchors (SHOULD; missing anchors fail once the pulse is older than the grace period)
+    if anchors:
+        R.anchors = _check_anchors(R, src, (seq - 1, seq), rc_, refetch)
+    else: R.anchors = "skipped (--no-anchors)"
+    return R
+
+def _check_anchors(R, src, seqs, rev_core, refetch):
+    if not src.anchors_available():
+        R.say(True, "publication anchors: no anchors branch reachable from this log source — not checked", "WARN"); return "unavailable"
+    try:
+        import anchor_lib as L
+    except Exception as e:
+        R.say(True, f"publication anchors: vendored anchor_lib unavailable ({e})", "WARN"); return "unavailable"
+    anchor_pub = L.load_pub(open(os.path.join(KEYS, "anchor.pub"), "rb").read()); rekor_pub = L.load_pub(open(os.path.join(KEYS, "rekor.pub"), "rb").read())
+    age = time.time() - float((rev_core.get("derived") or {}).get("round_release_unix_s") or time.time())
+    status = []
+    for s in seqs:
+        rec, stmt = src.anchor(s)
+        if rec is None:
+            if age > ANCHOR_GRACE_S: R.say(False, f"pulse {s:04d}: no publication anchor {age/60:.0f} min after its round (grace {ANCHOR_GRACE_S//60} min)")
+            else: R.say(True, f"pulse {s:04d}: anchor pending ({age:.0f} s since its round)", "WARN")
+            status.append("missing"); continue
+        pf = os.path.join(src.tmp, "chain", f"pulse-{s:04d}.json")
+        want, _ = L.statement_for(pf); entry = rec["rekor"]["entry"]
+        ok = stmt == want and rec["statement_sha256"] == L.sha256(want)
+        h, k = L.entry_hash_and_key(entry)
+        ok &= h == L.sha256(want) and k is not None and L.key_id(L.load_pub(k)) == L.key_id(anchor_pub)
+        ok &= L.verify_sig(anchor_pub, base64.b64decode(rec["signature_b64"]), want)
+        ok &= entry.get("logID") == L.REKOR_LOG_ID and L.verify_set(entry, rekor_pub)
+        inc, why = L.verify_inclusion(entry, rekor_pub); ok &= inc
+        live = ""
+        if refetch and ok:
+            try:
+                e2 = L.rekor_get(rec["rekor"]["uuid"]); ok &= e2["body"] == entry["body"] and e2["integratedTime"] == entry["integratedTime"]; live = ", re-fetched live"
+            except Exception as ex: R.say(True, f"pulse {s:04d}: Rekor refetch failed ({ex}); offline proof stands", "WARN")
+        when = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(entry["integratedTime"]))
+        R.say(ok, f"pulse {s:04d}: Rekor anchor logIndex {entry['logIndex']} @ {when} — statement, signature, SET, inclusion proof + checkpoint verified offline against pinned keys{live}; OTS {rec.get('ots', {}).get('status')}")
+        status.append("ok" if ok else "FAIL")
+    if all(x == "ok" for x in status):
+        rel = float((rev_core.get("derived") or {}).get("round_release_unix_s") or 0); rec_c, _ = src.anchor(seqs[0])
+        it = rec_c["rekor"]["entry"]["integratedTime"]
+        if it < rel: R.say(True, f"commit {seqs[0]:04d}: Rekor time precedes the drand release by {rel-it:.0f} s (third independent clock on the commit)")
+        else: R.say(True, f"commit {seqs[0]:04d}: Rekor time is {it-rel:.0f} s AFTER the drand release — a retroactive anchor (pulses ≤ 0041 were anchored 2026-09-12 12:47 UTC); the RFC 3161 tokens are the commit-time proof", "WARN")
+    return "/".join(status)

notbefore-0.2.0/notbefore/cli.py

@@ -0,0 +1,112 @@
+"""notbefore — CLI (NOTBEFORE.md §8).
+
+  notbefore verify  <seq>
+  notbefore value   <seq>
+  notbefore seed    <seq> --purpose <P>
+  notbefore shuffle <seq> --purpose <P> <file>
+  notbefore split   <seq> --purpose <P> --frac 0.8 <file>
+
+`value`/`seed`/`shuffle`/`split` print nothing usable unless `verify` would pass; exit 1 otherwise.
+The verifier and every key are vendored in this package; the log is read as data. Requires `git` and `openssl` on PATH.
+"""
+import sys, os, json, argparse, hashlib
+from . import __version__, SPEC, DEFAULT_REPO
+from .log import LogSource, LogError
+from .check import check_pair, vendored_meta
+from . import derive as D
+
+def _err(msg): sys.stderr.write("notbefore: " + msg + "\n")
+
+def build_parser():
+    ap = argparse.ArgumentParser(prog="notbefore", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--version", action="version", version=f"notbefore {__version__} ({SPEC}; verifier vendored from {vendored_meta().get('git_sha','?')[:12]})")
+    g = ap.add_argument_group("log source")
+    g.add_argument("--repo", default=DEFAULT_REPO, help="git URL of the log (default: the public qrng-beacon-log)")
+    g.add_argument("--log-dir", help="use this local checkout/directory instead of a cached clone")
+    g.add_argument("--log-ref", help="git ref/sha of the log to read (default origin/main; with --log-dir default: working tree)")
+    g.add_argument("--cache", help="cache directory for the clone (default ~/.cache/notbefore/qrng-beacon-log)")
+    g.add_argument("--offline", action="store_true", help="no network: no fetch, no drand/Rekor refetch (BLS + proofs still verify offline)")
+    g.add_argument("--no-anchors", action="store_true", help="skip the Rekor/OpenTimestamps anchor check")
+    ap.add_argument("-v", "--verbose", action="store_true", help="print the vendored verifier's full output")
+    ap.add_argument("--json", action="store_true", help="machine-readable result on stdout")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    def common(p, purpose=False, file=False):
+        p.add_argument("seq", type=int, help="reveal seq N (its commit is N-1)")
+        for flags, kw in ((("-v", "--verbose"), {}), (("--json",), {}), (("--offline",), {}), (("--no-anchors",), {})):
+            p.add_argument(*flags, action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS, **kw)
+        if purpose:
+            p.add_argument("--purpose", required=True, help="non-secret label, ^[A-Za-z0-9._:/=@+-]+$, ≤ 256 bytes")
+            p.add_argument("--transcript", help="write the transcript JSON here (default: ./notbefore-<seq>-<purpose>.json); '-' for stdout, 'none' to skip")
+        if file: p.add_argument("file", help="input file, one record per line (UTF-8)")
+    common(sub.add_parser("verify", help="verify the pair (commit N-1, reveal N); exit 0/1"))
+    common(sub.add_parser("value", help="print the attested value V (hex) if the pair verifies"))
+    common(sub.add_parser("seed", help="print the derived seed S = SHA256(D_derive || V || purpose)"), purpose=True)
+    common(sub.add_parser("shuffle", help="deterministically shuffle the lines of FILE with S"), purpose=True, file=True)
+    sp = sub.add_parser("split", help="shuffle, then split FILE into A (first floor(frac·k)) and B"); common(sp, purpose=True, file=True)
+    sp.add_argument("--frac", type=float, required=True); sp.add_argument("--out-a"); sp.add_argument("--out-b")
+    return ap
+
+def _open_source(a):
+    return LogSource(repo=a.repo, log_dir=a.log_dir, cache=a.cache, ref=a.log_ref, offline=a.offline)
+
+def _print_check(R, a):
+    if a.json: return
+    for l in R.lines: sys.stderr.write(l + "\n")
+    if a.verbose:
+        for v in R.verbose: sys.stderr.write("\n--- verifier output ---\n" + v)
+    sys.stderr.write(("VERIFIED" if R.ok else "NOT VERIFIED") + f" — NotBefore {R.seq} (commit {R.commit_seq}), log {str(R.log_git_sha)[:12]}\n")
+
+def _read_records(path):
+    raw = open(path, "rb").read()
+    text = raw.decode("utf-8")
+    recs = text.split("\n")
+    if recs and recs[-1] == "": recs.pop()
+    return [r.rstrip("\r") for r in recs], hashlib.sha256(raw).hexdigest()
+
+def _write_transcript(a, t, slug):
+    dest = a.transcript
+    if dest == "none": return None
+    if dest == "-": print(json.dumps(t, indent=1, sort_keys=True)); return "-"
+    dest = dest or f"notbefore-{a.seq}-{slug}.json"
+    json.dump(t, open(dest, "w"), indent=1, sort_keys=True); _err(f"transcript written: {dest}"); return dest
+
+def main(argv=None):
+    a = build_parser().parse_args(argv)
+    try:
+        src = _open_source(a)
+    except LogError as e:
+        _err(str(e)); return 1
+    try:
+        R = check_pair(a.seq, src, refetch=not a.offline, anchors=not a.no_anchors, verbose=a.verbose)
+        _print_check(R, a)
+        if a.cmd == "verify":
+            if a.json: print(json.dumps(R.summary() | {"seq": R.seq, "commit_seq": R.commit_seq, "attested_value": R.attested_value if R.ok else None, "log_git_sha": R.log_git_sha}, indent=1))
+            return 0 if R.ok else 1
+        if not R.ok:
+            _err("pair did not verify; refusing to emit a value"); return 1
+        if a.cmd == "value":
+            print(json.dumps({"seq": R.seq, "attested_value": R.attested_value}) if a.json else R.attested_value); return 0
+        try: P = D.normalize_purpose(a.purpose).decode()
+        except D.PurposeError as e: _err(f"bad purpose: {e}"); return 2
+        S = D.seed(R.attested_value, P); slug = P.replace("/", "_").replace(":", "_")
+        if a.cmd == "seed":
+            t = D.transcript(R, P, S); _write_transcript(a, t, slug)
+            print(json.dumps({"seq": R.seq, "purpose": P, "derived_seed": S.hex()}) if a.json else S.hex()); return 0
+        recs, in_sha = _read_records(a.file)
+        if a.cmd == "shuffle":
+            out = D.shuffle(recs, S); body = "\n".join(out) + ("\n" if out else "")
+            t = D.transcript(R, P, S, {"operation": "shuffle", "input_file": os.path.basename(a.file), "input_sha256": in_sha, "record_count": len(recs), "output_sha256": D.sha256_hex(body.encode())})
+            _write_transcript(a, t, slug); sys.stdout.write(body); return 0
+        if a.cmd == "split":
+            try: A_, B_ = D.split(recs, S, a.frac)
+            except ValueError as e: _err(str(e)); return 2
+            oa, ob = a.out_a or a.file + ".A", a.out_b or a.file + ".B"
+            ba, bb = "\n".join(A_) + ("\n" if A_ else ""), "\n".join(B_) + ("\n" if B_ else "")
+            open(oa, "w").write(ba); open(ob, "w").write(bb)
+            t = D.transcript(R, P, S, {"operation": "split", "frac": a.frac, "input_file": os.path.basename(a.file), "input_sha256": in_sha, "record_count": len(recs),
+                                       "A": {"file": os.path.basename(oa), "count": len(A_), "sha256": D.sha256_hex(ba.encode())}, "B": {"file": os.path.basename(ob), "count": len(B_), "sha256": D.sha256_hex(bb.encode())}})
+            _write_transcript(a, t, slug); _err(f"A: {len(A_)} -> {oa}   B: {len(B_)} -> {ob}"); return 0
+    finally:
+        src.close()
+
+if __name__ == "__main__": sys.exit(main())

notbefore-0.2.0/notbefore/derive.py

@@ -0,0 +1,51 @@
+"""The derive layer (NOTBEFORE.md §7): labeled seed, shuffle, split, transcript. Pure functions; no I/O."""
+import hashlib, re, unicodedata, json, time
+from . import D_DERIVE, D_SHUFFLE, SPEC, __version__
+
+PURPOSE_RE = re.compile(r"^[A-Za-z0-9._:/=@+-]+$")
+
+class PurposeError(ValueError): pass
+
+def normalize_purpose(purpose: str) -> bytes:
+    """UTF-8 NFC, 1–256 bytes, CLI-safe charset, no newline. Returns the exact bytes that enter the hash."""
+    if not isinstance(purpose, str) or purpose == "": raise PurposeError("purpose must be a non-empty string")
+    if "\n" in purpose or "\r" in purpose: raise PurposeError("purpose must not contain a newline")
+    p = unicodedata.normalize("NFC", purpose).encode("utf-8")
+    if len(p) > 256: raise PurposeError("purpose must be at most 256 bytes of UTF-8")
+    if not PURPOSE_RE.match(p.decode("utf-8")): raise PurposeError("purpose must match ^[A-Za-z0-9._:/=@+-]+$ (no spaces; use - or _)")
+    return p
+
+def seed(attested_value_hex: str, purpose: str) -> bytes:
+    """S = SHA256( 'notbefore/derive/v1' || V || purpose ). V is the 32 raw bytes of the attested value."""
+    V = bytes.fromhex(attested_value_hex)
+    if len(V) != 32: raise ValueError("attested_value must be 32 bytes")
+    return hashlib.sha256(D_DERIVE + V + normalize_purpose(purpose)).digest()
+
+def rank(key: bytes, i: int, record: str) -> bytes:
+    return hashlib.sha256(D_SHUFFLE + key + i.to_bytes(8, "big") + record.encode("utf-8")).digest()
+
+def shuffle(records, key: bytes):
+    """Stable sort by rank ascending; tie-break on the hex of the record bytes. Input order is part of the transcript."""
+    if len(key) != 32: raise ValueError("key must be the 32-byte derived seed")
+    ranked = [(rank(key, i, x), x.encode("utf-8").hex(), x) for i, x in enumerate(records)]
+    ranked.sort(key=lambda t: (t[0], t[1]))
+    return [t[2] for t in ranked]
+
+def split(records, key: bytes, frac: float):
+    if not (0.0 < frac < 1.0): raise ValueError("frac must be in (0, 1)")
+    s = shuffle(records, key); k = int(frac * len(s))          # floor(f * k); do not re-draw
+    return s[:k], s[k:]
+
+def sha256_hex(b: bytes) -> str: return hashlib.sha256(b).hexdigest()
+
+def transcript(check, purpose: str, derived: bytes, extra=None):
+    """The engineering artifact (§7.5). `check` is a CheckResult from notbefore.check."""
+    t = {"spec": SPEC, "derive_domain": D_DERIVE.decode(), "seq": check.seq, "commit_seq": check.commit_seq,
+         "pulse_hash_reveal": check.pulse_hash_reveal, "pulse_hash_commit": check.pulse_hash_commit,
+         "attested_value": check.attested_value, "drand_round": check.drand_round,
+         "purpose": normalize_purpose(purpose).decode("utf-8"), "derived_seed": derived.hex(),
+         "verifier_git_sha": check.verifier_git_sha, "log_git_sha": check.log_git_sha, "log_ref": check.log_ref,
+         "cli_version": __version__, "verified_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+         "checks": check.summary()}
+    if extra: t.update(extra)
+    return t

notbefore-0.2.0/notbefore/log.py

@@ -0,0 +1,90 @@
+"""Read the public log as DATA. Nothing from the log is ever executed: the verifier and keys are vendored in this package."""
+import os, subprocess, tempfile, json, shutil
+from . import DEFAULT_REPO
+
+SIDE = ("", ".tsa.json", ".freetsa.tsr", ".digicert.tsr")
+
+class LogError(Exception): pass
+
+def _git(*a, cwd=None, check=True):
+    r = subprocess.run(["git", *a], cwd=cwd, capture_output=True, text=True)
+    if check and r.returncode: raise LogError(f"git {' '.join(a)}: {(r.stderr or r.stdout).strip()[:300]}")
+    return r
+
+class LogSource:
+    """Either a remote clone kept in a cache directory (default) or a local directory (--log-dir)."""
+    def __init__(self, repo=DEFAULT_REPO, log_dir=None, cache=None, ref=None, offline=False):
+        self.repo, self.offline = repo, offline
+        self.tmp = tempfile.mkdtemp(prefix="notbefore-")
+        if log_dir:
+            self.dir = os.path.abspath(log_dir); self.mode = "dir"
+            self.is_git = _git("rev-parse", "--is-inside-work-tree", cwd=self.dir, check=False).returncode == 0
+            self.ref = ref                      # None -> working tree
+        else:
+            self.dir = cache or os.path.join(os.environ.get("XDG_CACHE_HOME") or os.path.expanduser("~/.cache"), "notbefore", "qrng-beacon-log")
+            self.mode = "cache"; self.is_git = True
+            if not os.path.isdir(os.path.join(self.dir, ".git")):
+                if offline: raise LogError(f"no cached clone at {self.dir} and --offline given")
+                os.makedirs(os.path.dirname(self.dir), exist_ok=True); _git("clone", "--quiet", repo, self.dir)
+            elif not offline:
+                _git("fetch", "--quiet", "--prune", "origin", cwd=self.dir)
+            self.ref = ref or "origin/main"
+        self.log_git_sha = self._sha()
+
+    def _sha(self):
+        if not self.is_git: return "unknown (not a git checkout)"
+        return _git("rev-parse", self.ref or "HEAD", cwd=self.dir).stdout.strip()
+
+    def close(self): shutil.rmtree(self.tmp, ignore_errors=True)
+
+    # ---- files
+    def _read(self, relpath):
+        """Bytes of a file at the pinned ref (or the working tree for a plain --log-dir). None if absent."""
+        if self.mode == "dir" and self.ref is None:
+            p = os.path.join(self.dir, relpath); return open(p, "rb").read() if os.path.exists(p) else None
+        r = _git("show", f"{self.ref}:{relpath}", cwd=self.dir, check=False)
+        return r.stdout.encode("utf-8", "surrogateescape") if r.returncode == 0 else None
+
+    def _read_bytes(self, relpath):
+        # binary-safe variant for .tsr (git show via text mode would mangle bytes)
+        if self.mode == "dir" and self.ref is None:
+            p = os.path.join(self.dir, relpath); return open(p, "rb").read() if os.path.exists(p) else None
+        r = subprocess.run(["git", "show", f"{self.ref}:{relpath}"], cwd=self.dir, capture_output=True)
+        return r.stdout if r.returncode == 0 else None
+
+    def has_pulse(self, seq): return self._read_bytes(f"chain/pulse-{seq:04d}.json") is not None
+
+    def materialize(self, seq):
+        """Write chain/pulse-NNNN.json and its TSA sidecars into the temp dir; return the pulse path (or None)."""
+        out = os.path.join(self.tmp, "chain"); os.makedirs(out, exist_ok=True)
+        base = f"chain/pulse-{seq:04d}.json"; main = None
+        for s in SIDE:
+            b = self._read_bytes(base + s)
+            if b is None:
+                if s == "": return None
+                continue
+            p = os.path.join(out, os.path.basename(base + s)); open(p, "wb").write(b)
+            if s == "": main = p
+        return main
+
+    def pulse(self, seq):
+        b = self._read_bytes(f"chain/pulse-{seq:04d}.json"); return json.loads(b) if b else None
+
+    # ---- anchors branch
+    def anchors_available(self):
+        if not self.is_git: return os.path.isdir(os.path.join(self.dir, "anchors"))
+        return _git("rev-parse", "--verify", "--quiet", "origin/anchors", cwd=self.dir, check=False).returncode == 0 \
+            or os.path.isdir(os.path.join(self.dir, "anchors"))
+
+    def anchor(self, seq):
+        """(record dict, statement bytes) for a pulse from origin/anchors (or an anchors/ worktree), or (None, None)."""
+        rec = stmt = None
+        if self.is_git:
+            r = subprocess.run(["git", "show", f"origin/anchors:pulse-{seq:04d}.anchor.json"], cwd=self.dir, capture_output=True)
+            s = subprocess.run(["git", "show", f"origin/anchors:pulse-{seq:04d}.stmt.json"], cwd=self.dir, capture_output=True)
+            if r.returncode == 0 and s.returncode == 0: rec, stmt = json.loads(r.stdout), s.stdout
+        if rec is None:
+            d = os.path.join(self.dir, "anchors")
+            rp, sp = os.path.join(d, f"pulse-{seq:04d}.anchor.json"), os.path.join(d, f"pulse-{seq:04d}.stmt.json")
+            if os.path.exists(rp) and os.path.exists(sp): rec, stmt = json.load(open(rp)), open(sp, "rb").read()
+        return rec, stmt

notbefore-0.2.0/notbefore/verifier/VENDORED.json

@@ -0,0 +1,31 @@
+{
+ "files": {
+  "bls_drand.py": "b909dd175b1f1c2dff0e78b77d83f2446afca73222a9946e35c2233732228ed9",
+  "ci/KNOWN_NONCOMPLIANT.json": "403268695cbbb93f5e4f757cdb3568056b40fbb31a14d0a0a1cb8b4ec953abd6",
+  "ci/anchor_lib.py": "7b65da28c3ff750808df2bc6e76ee7c8cb7273308cead542da0766c42f2edc71",
+  "drand_anchor.py": "8c1d16bd8376218697626e5614644713f52f83b31aeb836cd7dd302b500eac85",
+  "hosts/EXPECTED.json": "4fa57dfff93b7227db41fbd5c9001c1687e9ffb9f5e568b84ac8029be92c6e35",
+  "hosts/attest_host.py": "036cc9ca5e978fe9b3fb749a0ab7627fe1b18991ccfb05bbdeb3d1d4eec99a6a",
+  "hosts/attest_lib.py": "02ffc2a881d15daba1c1e1dda512d7f5efcf2adb9917a3748a7521954eea506f",
+  "hosts/entropy_host.py": "d2eaa923b7ac817f63b04a171abc667b0d56229c90b3e832ac787940710cd254",
+  "hosts/gnss_probe.py": "e5ccf3e8e400b69be669113f6fb1ce2439225e6635054150b64fcd65f0d12cdb",
+  "hosts/stamp_probe.py": "785763bd7d75cf792732387a7c439a78545ebe8414309ce738d3417c2d16fe48",
+  "keys/KEYS.json": "9de75424793bcb2b00b42efc271465fa1a6656194507b1dd3ffdb7e28eef9b3f",
+  "keys/anchor.pub": "5afc8aef90f65ae47aae97790aca4181c92b4cb37d23c7ab936c3a2b07de7b24",
+  "keys/drand-quicknet.json": "11ff6ba94bac65555551f3e097f4a498d5859cbf8a269127d569dedeaa1b8bf7",
+  "keys/entropy_signer.pub": "bbd318423b18b0a107382edf4f6f7be4f4a6186be6a0f73b17051e9f6f9713ab",
+  "keys/rekor.pub": "dce5ef715502ec9f3cdfd11f8cc384b31a6141023d3e7595e9908a81cb6241bd",
+  "keys/time_attester.f9t.RETIRED.pub": "fd6077eb26b8603c8ef8f445edfa3d5d13fa8d5298dcd7f3df20bafb9bd0565d",
+  "keys/time_attester.pub": "20b72663dddc2ce0ff73f9af4a4ad70761fe0af8c009a9bce520724d9c4ef424",
+  "keys/time_witness.pub": "2af608da26b0140ba3b2327357ebfd2a72167e983895aed1113a8ce19acc8267",
+  "schema.py": "d9f4bb521bb40020230ab14506c03b192467c7a6ddc07f5877d0cd56d178f8f1",
+  "tsa-certs/freetsa-ca.pem": "2151b61137ffa86bf664691ba67e7da0b19f98c758e3d228d5d8ebf27e044438",
+  "tsa-certs/freetsa-tsa.crt": "8bfb0305bb64e2571ca507552ef3245cb1c2fee8728e0ff8689225081ea13467",
+  "tsa.py": "dccdd56c6e087ee86e30c6d9130c2c9aef10eac10e6c24c2c39f492f44ed565a",
+  "verify.py": "898a3b343225b8ad5f42065c3f8d1690476edde5659bae2acc00d81c70200605"
+ },
+ "git_sha": "19fed1b1d291db54469fec682960ee544598da61",
+ "log_repo": "https://github.com/docdailey/qrng-beacon-log",
+ "note": "Verifier, keys and expected-config pinned at this commit. The CLI executes ONLY these files; the log is read as data.",
+ "vendored_utc": "2026-09-12T13:26:52Z"
+}