notbefore 0.2.0__py3-none-any.whl

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/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/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/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/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/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"
+}

notbefore/verifier/bls_drand.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""
+bls_drand.py — full BLS verification of drand quicknet rounds (scheme bls-unchained-g1-rfc9380).
+
+Checks  e(σ, g₂) == e(H(m), pk)  on BLS12-381 with
+  σ  = round signature, 48-byte compressed G1 point
+  pk = the League of Entropy quicknet GROUP public key, 96-byte compressed G2 point (pinned)
+  m  = SHA-256(round as uint64 big-endian)          (unchained: no previous signature in the message)
+  H  = hash-to-curve into G1 per RFC 9380, DST "BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_NUL_"
+
+A valid σ is the unique signature a ≥threshold set of operators could produce for that round; it
+cannot be precomputed, forged, or swapped for another round. This removes the HTTP relay, DNS and TLS
+from the trust base — only the pinned group key and the ≥t-honest-operators assumption remain.
+
+Requires `pip install py_ecc` (pure Python; ~1-2 s per verification). Absent it, callers should WARN.
+"""
+import hashlib, json, os
+
+PIN_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "keys", "drand-quicknet.json")
+DST = b"BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_NUL_"
+
+def available():
+    try:
+        import py_ecc  # noqa
+        return True
+    except ImportError:
+        return False
+
+def pinned():
+    return json.load(open(PIN_FILE))
+
+def message(round_no: int) -> bytes:
+    return hashlib.sha256(int(round_no).to_bytes(8, "big")).digest()
+
+def verify_round(pk_hex: str, round_no: int, sig_hex: str) -> bool:
+    from py_ecc.bls.hash_to_curve import hash_to_G1
+    from py_ecc.bls.point_compression import decompress_G1, decompress_G2
+    from py_ecc.optimized_bls12_381 import pairing, G2, is_on_curve, b, b2, curve_order, multiply, Z1, Z2
+    sig_b, pk_b = bytes.fromhex(sig_hex), bytes.fromhex(pk_hex)
+    if len(sig_b) != 48 or len(pk_b) != 96:
+        return False
+    try:
+        sig = decompress_G1(int.from_bytes(sig_b, "big"))
+        pk  = decompress_G2((int.from_bytes(pk_b[:48], "big"), int.from_bytes(pk_b[48:], "big")))
+    except Exception:
+        return False
+    # subgroup + curve checks (decompress checks curve; be explicit about the prime-order subgroup)
+    if not is_on_curve(sig, b) or not is_on_curve(pk, b2):
+        return False
+    if multiply(sig, curve_order) != Z1 or multiply(pk, curve_order) != Z2:
+        return False
+    hm = hash_to_G1(message(round_no), DST, hashlib.sha256)
+    return pairing(G2, sig) == pairing(pk, hm)
+
+def verify_pinned(round_no: int, sig_hex: str, chain_hash: str) -> tuple:
+    p = pinned()
+    if chain_hash != p["chain_hash"]:
+        return False, "chain hash does not match the pinned quicknet chain"
+    ok = verify_round(p["public_key"], round_no, sig_hex)
+    return ok, ("BLS signature verifies under the pinned League of Entropy quicknet group key" if ok
+                else "BLS signature does NOT verify under the pinned group key")
+
+if __name__ == "__main__":
+    import sys, urllib.request, time
+    CH = "52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971"
+    def get(u):
+        with urllib.request.urlopen(u, timeout=15) as r: return json.load(r)
+    print("=== 1. cross-check the group public key across independent operators ===")
+    keys = {}
+    for base in ("https://api.drand.sh", "https://api2.drand.sh", "https://api3.drand.sh", "https://drand.cloudflare.com"):
+        try: i = get(f"{base}/{CH}/info"); keys[base] = (i["public_key"], i["hash"], i["schemeID"], i["genesis_time"], i["period"])
+        except Exception as e: keys[base] = ("ERR", str(e)[:40])
+    vals = {v for v in keys.values() if v[0] != "ERR"}
+    for k, v in keys.items(): print("  %-30s %s" % (k, v[0][:24] + "..." if v[0] != "ERR" else v))
+    print("  agreement across operators:", len(vals) == 1, "| scheme:", next(iter(vals))[2])
+    pk = next(iter(vals))[0]
+    print("\n=== 2. verify REAL rounds (the three we have mixed, plus latest) ===")
+    for rnd in (32122604, 32123484, 32123921, None):
+        d = get(f"https://api.drand.sh/{CH}/public/{'latest' if rnd is None else rnd}")
+        t0 = time.time(); ok = verify_round(pk, d["round"], d["signature"]); dt = time.time() - t0
+        print("  round %d: %s (%.2fs)" % (d["round"], "VALID" if ok else "INVALID", dt))
+    print("\n=== 3. NEGATIVES — every one of these must be INVALID ===")
+    d = get(f"https://api.drand.sh/{CH}/public/32123921")
+    print("  same σ, round+1 (relay relabels the round):", "INVALID" if not verify_round(pk, d["round"] + 1, d["signature"]) else "VALID  <-- BUG")
+    sb = bytearray(bytes.fromhex(d["signature"])); sb[-1] ^= 0x01
+    print("  σ with one bit flipped:                     ", "INVALID" if not verify_round(pk, d["round"], sb.hex()) else "VALID  <-- BUG")
+    other = get("https://api.drand.sh/8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce/info")["public_key"]
+    print("  real σ against the DEFAULT network's key:   ", "INVALID" if not verify_round(other if len(other) == 192 else pk, d["round"], d["signature"]) or len(other) != 192 else "VALID  <-- BUG")

notbefore/verifier/ci/KNOWN_NONCOMPLIANT.json

@@ -0,0 +1,7 @@
+{
+  "note": "Pulses that are EXPECTED to fail the current verifier because of a published erratum. CI counts them separately; any other failure still fails the build, and a listed pulse that unexpectedly PASSES is flagged so this list cannot silently hide anything. Pulses are immutable; the list only grows.",
+  "pulses": {
+    "18": {"erratum": "ERR-007", "expected_failure": "witness: k3 reports a healthy clock", "reason": "witness epoch guard misfired (kernel TAI offset unset on k3; refid PHC); clock healthy on live evidence"},
+    "19": {"erratum": "ERR-007", "expected_failure": "witness: k3 reports a healthy clock", "reason": "same as 18"}
+  }
+}