trooth 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- trooth/__init__.py +14 -0
- trooth/integrations/__init__.py +16 -0
- trooth/integrations/langchain.py +33 -0
- trooth/integrations/llama_index.py +34 -0
- trooth/integrations/openai_agents.py +44 -0
- trooth-0.1.0.dist-info/METADATA +88 -0
- trooth-0.1.0.dist-info/RECORD +20 -0
- trooth-0.1.0.dist-info/WHEEL +5 -0
- trooth-0.1.0.dist-info/entry_points.txt +2 -0
- trooth-0.1.0.dist-info/licenses/LICENSE +70 -0
- trooth-0.1.0.dist-info/top_level.txt +2 -0
- trooth_semanto_verify/__init__.py +94 -0
- trooth_semanto_verify/__main__.py +8 -0
- trooth_semanto_verify/canonical.py +88 -0
- trooth_semanto_verify/cli.py +246 -0
- trooth_semanto_verify/client.py +127 -0
- trooth_semanto_verify/httpsig.py +217 -0
- trooth_semanto_verify/jws.py +255 -0
- trooth_semanto_verify/merkle.py +110 -0
- trooth_semanto_verify/verify.py +541 -0
|
@@ -0,0 +1,541 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
# Copyright (c) 2026 Trooth, LLC
|
|
3
|
+
#
|
|
4
|
+
# The top-level Semanto checks: a whole file offline, a per-page proof, a
|
|
5
|
+
# signed response, tree heads, log inclusion and consistency, checkpoints,
|
|
6
|
+
# offers, revocation lists, and the state of a version at an instant. Every
|
|
7
|
+
# function returns plain dicts: {"ok", "reason", "checks": [{"name", "ok",
|
|
8
|
+
# "detail"}]} so a CLI prints exactly what was checked, in plain words. Nothing
|
|
9
|
+
# here produces a number or a verdict about a company.
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import base64
|
|
14
|
+
import hashlib
|
|
15
|
+
import re
|
|
16
|
+
import time
|
|
17
|
+
from datetime import datetime, timezone
|
|
18
|
+
from typing import Any, Callable, Dict, List, Optional, Union
|
|
19
|
+
|
|
20
|
+
from .canonical import canonical_bytes, canonicalize
|
|
21
|
+
from .httpsig import (
|
|
22
|
+
SEMANTO_RESPONSE_COMPONENTS,
|
|
23
|
+
SEMANTO_RESPONSE_MUST_COVER_WHEN_PRESENT,
|
|
24
|
+
SEMANTO_RESPONSE_TAG,
|
|
25
|
+
WEB_BOT_AUTH_REQUIRED,
|
|
26
|
+
WEB_BOT_AUTH_TAG,
|
|
27
|
+
header_get,
|
|
28
|
+
parse_signature_input,
|
|
29
|
+
verify_content_digest,
|
|
30
|
+
verify_message,
|
|
31
|
+
)
|
|
32
|
+
from .jws import JWS_TYPES, b64url_decode, ed25519_verify, has_roles, parse_time, role_keys, role_resolver, strict_role_resolver, verify_jws
|
|
33
|
+
from .merkle import digest, digest_bytes, is_digest, leaf_hash, root_from_leaf_hashes, verify_consistency as _verify_consistency, verify_inclusion
|
|
34
|
+
|
|
35
|
+
SCHEMA_URL = "https://trooth.co/schemas/semanto/v1.json"
|
|
36
|
+
TROOTH_LOG_SIGNER_NAME = "trooth.co"
|
|
37
|
+
TROOTH_LOG_ORIGIN = "trooth.co/semanto/log/v1"
|
|
38
|
+
_B32 = "abcdefghijklmnopqrstuvwxyz234567"
|
|
39
|
+
_ISO = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$")
|
|
40
|
+
|
|
41
|
+
Now = Union[datetime, str, int, float, None]
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def _at(now: Now) -> datetime:
|
|
45
|
+
if now is None:
|
|
46
|
+
return datetime.now(timezone.utc)
|
|
47
|
+
if isinstance(now, datetime):
|
|
48
|
+
return now if now.tzinfo else now.replace(tzinfo=timezone.utc)
|
|
49
|
+
if isinstance(now, (int, float)):
|
|
50
|
+
return datetime.fromtimestamp(now, tz=timezone.utc)
|
|
51
|
+
return parse_time(now)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _epoch(now: Now) -> int:
|
|
55
|
+
return int(_at(now).timestamp())
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
# ------------------------------------------------------------------ ids and hashing
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def semanto_id(prefix: str, d: str) -> str:
|
|
62
|
+
if not is_digest(d):
|
|
63
|
+
raise ValueError("semanto_id needs a digest")
|
|
64
|
+
bits = "".join(f"{int(ch, 16):04b}" for ch in d[7:])
|
|
65
|
+
out = "".join(_B32[int(bits[i : i + 5], 2)] for i in range(0, len(bits) - 4, 5))[:26]
|
|
66
|
+
return f"{prefix}_{out}"
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def pages_root(manifest: List[dict]) -> str:
|
|
70
|
+
leaves = [leaf_hash(digest_bytes(p["hash"])) for p in manifest]
|
|
71
|
+
return "sha256:" + root_from_leaf_hashes(leaves).hex()
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def facts_root(facts: List[dict]) -> str:
|
|
75
|
+
ordered = sorted(facts, key=lambda f: f["id"])
|
|
76
|
+
leaves = [leaf_hash(canonical_bytes(f)) for f in ordered]
|
|
77
|
+
return "sha256:" + root_from_leaf_hashes(leaves).hex()
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def tier_hash(value: Any) -> str:
|
|
81
|
+
return digest(canonical_bytes(value))
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def root_hash(header: dict) -> str:
|
|
85
|
+
return digest(canonical_bytes(header))
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def version_id(root: str) -> str:
|
|
89
|
+
return semanto_id("smv", root)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def fact_id(fact: dict) -> str:
|
|
93
|
+
rest = {k: v for k, v in fact.items() if k != "id"}
|
|
94
|
+
return semanto_id("smf", digest(canonical_bytes(rest)))
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
# ------------------------------------------------------------------ states
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def state_of(version: dict, now: Now = None, revocations: Optional[dict] = None, latest: Optional[int] = None) -> str:
|
|
101
|
+
"""The state at `now` in the ledger's words: current, superseded, behind, expired, withdrawn or unsigned."""
|
|
102
|
+
header = version.get("header", version)
|
|
103
|
+
at = _at(now)
|
|
104
|
+
root = version.get("root_hash") or header.get("root_hash")
|
|
105
|
+
smv = version_id(root) if root and is_digest(root) else None
|
|
106
|
+
entries: list = []
|
|
107
|
+
if revocations:
|
|
108
|
+
entries = revocations.get("revocations") or revocations.get("entries") or (revocations.get("payload") or {}).get("revocations") or []
|
|
109
|
+
for e in entries:
|
|
110
|
+
if e.get("kind") != "version":
|
|
111
|
+
continue
|
|
112
|
+
if (smv and e.get("ref") == smv) or (root and e.get("ref") == root):
|
|
113
|
+
if not e.get("revoked_at") or at >= parse_time(e["revoked_at"]):
|
|
114
|
+
return "withdrawn"
|
|
115
|
+
state = header.get("state")
|
|
116
|
+
if state == "withdrawn":
|
|
117
|
+
return "withdrawn"
|
|
118
|
+
if state in ("read", "confirmed"):
|
|
119
|
+
return "unsigned"
|
|
120
|
+
if state == "signed" and "header" in version and not version.get("signature"):
|
|
121
|
+
return "unsigned"
|
|
122
|
+
if header.get("not_after") and at >= parse_time(header["not_after"]):
|
|
123
|
+
return "expired"
|
|
124
|
+
if header.get("not_before") and at < parse_time(header["not_before"]):
|
|
125
|
+
return "behind"
|
|
126
|
+
if isinstance(latest, int) and isinstance(header.get("version"), int) and latest > header["version"]:
|
|
127
|
+
return "superseded"
|
|
128
|
+
return "current" if state == "signed" else "unsigned"
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
# ------------------------------------------------------------------ check list
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
class _Checks:
|
|
135
|
+
def __init__(self) -> None:
|
|
136
|
+
self.list: List[dict] = []
|
|
137
|
+
self.notes: List[str] = []
|
|
138
|
+
self.reason: Optional[str] = None
|
|
139
|
+
|
|
140
|
+
def note(self, text: str) -> None:
|
|
141
|
+
self.notes.append(text)
|
|
142
|
+
|
|
143
|
+
def add(self, name: str, ok: bool, detail: str, reason: Optional[str] = None) -> bool:
|
|
144
|
+
self.list.append({"name": name, "ok": ok, "detail": detail})
|
|
145
|
+
if not ok and self.reason is None:
|
|
146
|
+
self.reason = reason or name
|
|
147
|
+
return ok
|
|
148
|
+
|
|
149
|
+
def result(self, **extra: Any) -> dict:
|
|
150
|
+
ok = all(c["ok"] for c in self.list)
|
|
151
|
+
out = {"ok": ok, "reason": None if ok else self.reason, "checks": self.list, "notes": self.notes}
|
|
152
|
+
out.update(extra)
|
|
153
|
+
return out
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def _validate(file: dict, out: List[dict]) -> bool:
|
|
157
|
+
def push(path: str, message: str) -> None:
|
|
158
|
+
out.append({"path": path, "message": message})
|
|
159
|
+
|
|
160
|
+
h = file.get("header")
|
|
161
|
+
if not isinstance(h, dict):
|
|
162
|
+
push("header", "missing")
|
|
163
|
+
return False
|
|
164
|
+
if h.get("schema") != SCHEMA_URL:
|
|
165
|
+
push("header.schema", "unknown schema")
|
|
166
|
+
if h.get("contract") != 1:
|
|
167
|
+
push("header.contract", "expected 1")
|
|
168
|
+
if not isinstance(h.get("org"), str) or not h["org"]:
|
|
169
|
+
push("header.org", "required")
|
|
170
|
+
if not isinstance(h.get("domains"), list) or not h["domains"]:
|
|
171
|
+
push("header.domains", "at least one domain")
|
|
172
|
+
if not isinstance(h.get("version"), int) or h["version"] < 1:
|
|
173
|
+
push("header.version", "positive integer")
|
|
174
|
+
if not isinstance(h.get("built_at"), str) or not _ISO.match(h["built_at"]):
|
|
175
|
+
push("header.built_at", "ISO 8601 UTC")
|
|
176
|
+
if h.get("state") not in ("read", "confirmed", "signed", "withdrawn"):
|
|
177
|
+
push("header.state", "unknown state")
|
|
178
|
+
if not is_digest(h.get("pages_root")):
|
|
179
|
+
push("header.pages_root", "digest")
|
|
180
|
+
if not is_digest(h.get("facts_root")):
|
|
181
|
+
push("header.facts_root", "digest")
|
|
182
|
+
if not isinstance(h.get("tiers"), list):
|
|
183
|
+
push("header.tiers", "array")
|
|
184
|
+
if not isinstance(h.get("pages_manifest"), list):
|
|
185
|
+
push("header.pages_manifest", "array")
|
|
186
|
+
else:
|
|
187
|
+
for i, p in enumerate(h["pages_manifest"]):
|
|
188
|
+
if not is_digest(p.get("hash")):
|
|
189
|
+
push(f"header.pages_manifest[{i}].hash", "digest")
|
|
190
|
+
if not isinstance(p.get("url"), str) or not p["url"].startswith("https://"):
|
|
191
|
+
push(f"header.pages_manifest[{i}].url", "https url")
|
|
192
|
+
if not isinstance(file.get("facts"), list):
|
|
193
|
+
push("facts", "array")
|
|
194
|
+
else:
|
|
195
|
+
for i, f in enumerate(file["facts"]):
|
|
196
|
+
if f.get("provenance") not in ("witnessed", "public_record", "attested", "declared"):
|
|
197
|
+
push(f"facts[{i}].provenance", "unknown provenance")
|
|
198
|
+
if not isinstance(f.get("evidence"), dict) or not isinstance(f["evidence"].get("url"), str):
|
|
199
|
+
push(f"facts[{i}].evidence.url", "required")
|
|
200
|
+
if not isinstance(file.get("controls"), dict) or not isinstance(file["controls"].get("when_unknown"), str):
|
|
201
|
+
push("controls.when_unknown", "required")
|
|
202
|
+
if not is_digest(file.get("root_hash")):
|
|
203
|
+
push("root_hash", "digest")
|
|
204
|
+
return not out
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
PageBytes = Union[Dict[str, Union[bytes, str]], Callable[[dict], Optional[bytes]], None]
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
def _as_bytes(b: Union[bytes, bytearray, str]) -> bytes:
|
|
211
|
+
return b.encode("utf-8") if isinstance(b, str) else bytes(b)
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
def verify_semanto(file: dict, page_bytes_by_url: PageBytes = None, keys: Any = None, now: Now = None, revocations: Optional[dict] = None, latest: Optional[int] = None) -> dict:
|
|
215
|
+
"""Verify a whole Semanto file offline. See docs/spec/semanto-file.md.
|
|
216
|
+
|
|
217
|
+
keys: {"company": <JWK Set>, "trooth": <JWK Set>}. The company signature resolves only against the company's set,
|
|
218
|
+
the witness statement only against Trooth's. A plain JWK Set is the company's, and then no witness checks out.
|
|
219
|
+
"""
|
|
220
|
+
c = _Checks()
|
|
221
|
+
at = _at(now)
|
|
222
|
+
company_key = strict_role_resolver(keys, "company")
|
|
223
|
+
trooth_key = strict_role_resolver(keys, "trooth")
|
|
224
|
+
issues: List[dict] = []
|
|
225
|
+
if not isinstance(file, dict) or not isinstance(file.get("header"), dict):
|
|
226
|
+
c.add("structure", False, "The file has no header.", "malformed")
|
|
227
|
+
return c.result(issues=issues)
|
|
228
|
+
ok = _validate(file, issues)
|
|
229
|
+
c.add("structure", ok, "The file has every required field." if ok else "; ".join(f"{i['path']}: {i['message']}" for i in issues), "malformed")
|
|
230
|
+
if not ok:
|
|
231
|
+
return c.result(issues=issues)
|
|
232
|
+
h = file["header"]
|
|
233
|
+
|
|
234
|
+
root = root_hash(h)
|
|
235
|
+
c.add("root_hash", root == file["root_hash"], f"root_hash is the digest of the canonical header: {root}" if root == file["root_hash"] else f"root_hash {file['root_hash']} is not the digest of the header, which is {root}", "root_hash_mismatch")
|
|
236
|
+
pr = pages_root(h["pages_manifest"])
|
|
237
|
+
c.add("pages_root", pr == h["pages_root"], f"pages_root matches the {len(h['pages_manifest'])} page hashes in the manifest." if pr == h["pages_root"] else f"pages_root does not match the manifest (computed {pr}).", "pages_root_mismatch")
|
|
238
|
+
fr = facts_root(file["facts"])
|
|
239
|
+
c.add("facts_root", fr == h["facts_root"], f"facts_root matches the {len(file['facts'])} facts." if fr == h["facts_root"] else f"facts_root does not match the facts (computed {fr}).", "facts_root_mismatch")
|
|
240
|
+
|
|
241
|
+
tiers = {"facts": file.get("facts"), "controls": file.get("controls"), "question_map": file.get("question_map"), "documents": file.get("documents"), "products": file.get("products"), "pages": h["pages_manifest"]}
|
|
242
|
+
for t in h.get("tiers") or []:
|
|
243
|
+
name = t.get("name")
|
|
244
|
+
if name == "header":
|
|
245
|
+
continue
|
|
246
|
+
if name not in tiers or tiers[name] is None:
|
|
247
|
+
c.add(f"tier.{name}", False, f"The header lists a {name} tier that is not in the file.", "tier_missing")
|
|
248
|
+
continue
|
|
249
|
+
th = tier_hash(tiers[name])
|
|
250
|
+
c.add(f"tier.{name}", th == t.get("hash"), f"The {name} tier matches its hash." if th == t.get("hash") else f"The {name} tier does not match its hash in the header.", "tier_hash_mismatch")
|
|
251
|
+
|
|
252
|
+
bad = [f["id"] for f in file["facts"] if fact_id(f) != f.get("id")]
|
|
253
|
+
c.add("fact_ids", not bad, "Every fact id is the digest of its fact." if not bad else "These fact ids do not match their facts: " + ", ".join(bad), "fact_id_mismatch")
|
|
254
|
+
|
|
255
|
+
checked, wrong = 0, []
|
|
256
|
+
for p in h["pages_manifest"]:
|
|
257
|
+
if callable(page_bytes_by_url):
|
|
258
|
+
b = page_bytes_by_url(p)
|
|
259
|
+
elif page_bytes_by_url:
|
|
260
|
+
b = page_bytes_by_url.get(p["url"], page_bytes_by_url.get(p.get("id")))
|
|
261
|
+
else:
|
|
262
|
+
b = None
|
|
263
|
+
if b is None:
|
|
264
|
+
continue
|
|
265
|
+
checked += 1
|
|
266
|
+
if digest(_as_bytes(b)) != p["hash"]:
|
|
267
|
+
wrong.append(p["url"])
|
|
268
|
+
if checked:
|
|
269
|
+
c.add("page_bytes", not wrong, f"{checked} of {len(h['pages_manifest'])} pages were given and every one matches its hash." if not wrong else "These pages do not match their hash: " + ", ".join(wrong), "page_hash_mismatch")
|
|
270
|
+
else:
|
|
271
|
+
c.list.append({"name": "page_bytes", "ok": True, "detail": "No page bytes were given, so page bytes were not checked."})
|
|
272
|
+
|
|
273
|
+
sig = file.get("signature")
|
|
274
|
+
if sig:
|
|
275
|
+
v = verify_jws(sig.get("jws"), company_key, expect_typ=JWS_TYPES["semantoVersion"], payload=h, at=at)
|
|
276
|
+
c.add("company_signature", v["ok"], f"The header is signed by the company's key {v['header']['kid']} (typ semanto-version)." if v["ok"] else f"The company's signature did not check out: {v['reason']}.", None if v["ok"] else v["reason"])
|
|
277
|
+
for n in v.get("notes", []) if v["ok"] else []:
|
|
278
|
+
c.note(f"Company signature: {n}.")
|
|
279
|
+
else:
|
|
280
|
+
c.add("company_signature", h.get("state") != "signed", "The file says it is signed but carries no signature." if h.get("state") == "signed" else "The file is not signed yet; that matches its state.", "unsigned")
|
|
281
|
+
|
|
282
|
+
w = file.get("witness")
|
|
283
|
+
if w:
|
|
284
|
+
payload = {"root_hash": file["root_hash"], "witnessed_at": w.get("at")}
|
|
285
|
+
v = verify_jws(w.get("jws"), trooth_key, expect_typ=JWS_TYPES["witness"], payload=payload, at=at)
|
|
286
|
+
c.add("witness", v["ok"], f"Trooth witnessed root_hash at {w.get('at')} with Trooth's key {v['header']['kid']}." if v["ok"] else f"The witness statement did not check out against Trooth's keys: {v['reason']}.", None if v["ok"] else f"witness_{v['reason']}")
|
|
287
|
+
for n in v.get("notes", []) if v["ok"] else []:
|
|
288
|
+
c.note(f"Witness statement: {n}.")
|
|
289
|
+
else:
|
|
290
|
+
c.list.append({"name": "witness", "ok": True, "detail": "No witness statement in the file."})
|
|
291
|
+
|
|
292
|
+
state = state_of(file, at, revocations, latest)
|
|
293
|
+
c.add("state", state == "current" or h.get("state") != "signed", f"State at {at.isoformat()}: {state}.", state)
|
|
294
|
+
return c.result(issues=issues, state=state, version_id=version_id(file["root_hash"]) if is_digest(file.get("root_hash")) else None)
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
def verify_page_proof(proof: dict, page_bytes: Union[bytes, str], keys: Any = None, now: Now = None, header: Optional[dict] = None, allow_unwitnessed: bool = False, allow_unlogged: bool = False, allow_unsigned: bool = False) -> dict:
|
|
298
|
+
"""Verify a semanto.proof document (what /pages/{id}/proof returns) against the page's bytes, strictly.
|
|
299
|
+
|
|
300
|
+
The version header (fetched beside the proof) and the company signature are required. The witness
|
|
301
|
+
statement and the log entry are required unless allow_unwitnessed or allow_unlogged; a missing one is
|
|
302
|
+
a check that reads "absent", never a silent skip. keys: {"company", "trooth"} kept apart by role.
|
|
303
|
+
"""
|
|
304
|
+
c = _Checks()
|
|
305
|
+
at = _at(now)
|
|
306
|
+
company_key = strict_role_resolver(keys, "company")
|
|
307
|
+
b = _as_bytes(page_bytes)
|
|
308
|
+
h = header if header is not None else (proof.get("header") if isinstance(proof, dict) else None)
|
|
309
|
+
inc = proof.get("inclusion") if isinstance(proof, dict) else None
|
|
310
|
+
if not isinstance(proof, dict) or proof.get("object") != "semanto.proof" or not is_digest(proof.get("page_hash")) or not is_digest(proof.get("pages_root")) or not is_digest(proof.get("root_hash")) or not isinstance(inc, dict):
|
|
311
|
+
c.add("structure", False, "The proof is not a semanto.proof with full digests and an inclusion block.", "malformed")
|
|
312
|
+
return c.result()
|
|
313
|
+
|
|
314
|
+
d = digest(b)
|
|
315
|
+
c.add("page_hash", d == proof["page_hash"], f"The page bytes hash to {d}, the hash in the manifest." if d == proof["page_hash"] else f"The page bytes hash to {d}; the proof says {proof['page_hash']}. The page is not the one that was signed.", "page_hash_mismatch")
|
|
316
|
+
|
|
317
|
+
index, size = inc.get("index"), inc.get("size")
|
|
318
|
+
try:
|
|
319
|
+
in_pages = verify_inclusion(leaf_hash(digest_bytes(proof["page_hash"])), index, size, [digest_bytes(x) for x in inc.get("path") or []], digest_bytes(proof["pages_root"]))
|
|
320
|
+
except (ValueError, TypeError):
|
|
321
|
+
in_pages = False
|
|
322
|
+
c.add("pages_root", in_pages, f"Page {index + 1} of {size} is in pages_root {proof['pages_root']}." if in_pages else "The inclusion proof does not lead to pages_root.", "pages_root_mismatch")
|
|
323
|
+
|
|
324
|
+
if h is not None:
|
|
325
|
+
manifest = h.get("pages_manifest") or []
|
|
326
|
+
entry = manifest[index] if isinstance(index, int) and 0 <= index < len(manifest) else None
|
|
327
|
+
root = root_hash(h)
|
|
328
|
+
bound = h.get("pages_root") == proof["pages_root"] and root == proof["root_hash"] and entry is not None and entry.get("id") == proof.get("page_id") and entry.get("hash") == proof["page_hash"] and h.get("version") == proof.get("version")
|
|
329
|
+
if bound:
|
|
330
|
+
detail, reason = f"The version header hashes to root_hash {root} and lists this page at index {index}.", None
|
|
331
|
+
elif root != proof["root_hash"]:
|
|
332
|
+
detail, reason = f"The header hashes to {root}, not the proof's root_hash {proof['root_hash']}.", "root_hash_mismatch"
|
|
333
|
+
else:
|
|
334
|
+
detail, reason = "The header does not list this page at that index with this hash.", "manifest_mismatch"
|
|
335
|
+
c.add("header", bound, detail, reason)
|
|
336
|
+
if not proof.get("signature"):
|
|
337
|
+
# A Semanto Basic page is witnessed by Trooth and not signed by the company: allow_unsigned accepts it knowingly.
|
|
338
|
+
c.add("company_signature", allow_unsigned, "Absent: the proof carries no company signature (allowed by the caller: a record witnessed by Trooth and not signed by the company)." if allow_unsigned else "The proof carries no company signature.", "signature_absent")
|
|
339
|
+
else:
|
|
340
|
+
sig = verify_jws(proof.get("signature"), company_key, expect_typ=JWS_TYPES["semantoVersion"], payload=h, at=at)
|
|
341
|
+
c.add("company_signature", sig["ok"], f"The header is signed by the company's key {sig['header']['kid']} (typ semanto-version)." if sig["ok"] else f"The company's signature did not check out: {sig['reason']}.", None if sig["ok"] else sig["reason"])
|
|
342
|
+
for n in sig.get("notes", []) if sig["ok"] else []:
|
|
343
|
+
c.note(f"Company signature: {n}.")
|
|
344
|
+
else:
|
|
345
|
+
c.add("header", False, "No version header was given, so the proof is not tied to a signed version. Fetch the version beside the proof.", "header_absent")
|
|
346
|
+
c.add("company_signature", False, "The company signature cannot be checked without the version header.", "header_absent")
|
|
347
|
+
|
|
348
|
+
trooth_keys = keys if has_roles(keys) else {"trooth": []}
|
|
349
|
+
if proof.get("witness") and proof.get("witnessed_at"):
|
|
350
|
+
payload = {"root_hash": proof["root_hash"], "witnessed_at": proof.get("witnessed_at")}
|
|
351
|
+
w = verify_jws(proof["witness"], strict_role_resolver(keys, "trooth"), expect_typ=JWS_TYPES["witness"], payload=payload, at=at)
|
|
352
|
+
c.add("witness", w["ok"], f"Trooth witnessed this root_hash at {proof.get('witnessed_at')} with Trooth's key {w['header']['kid']}." if w["ok"] else f"The witness statement did not check out against Trooth's keys: {w['reason']}.", None if w["ok"] else f"witness_{w['reason']}")
|
|
353
|
+
for n in w.get("notes", []) if w["ok"] else []:
|
|
354
|
+
c.note(f"Witness statement: {n}.")
|
|
355
|
+
else:
|
|
356
|
+
c.add("witness", allow_unwitnessed, "Absent: the proof carries no witness statement (allowed by the caller)." if allow_unwitnessed else "Absent: the proof carries no witness statement.", "witness_absent")
|
|
357
|
+
|
|
358
|
+
l = proof.get("ledger")
|
|
359
|
+
if l:
|
|
360
|
+
try:
|
|
361
|
+
leaf_h: Optional[bytes] = digest_bytes(l.get("leaf_hash"))
|
|
362
|
+
except ValueError:
|
|
363
|
+
leaf_h = None
|
|
364
|
+
leaf = l.get("leaf")
|
|
365
|
+
if leaf is not None:
|
|
366
|
+
recomputed = leaf_hash(canonical_bytes(leaf)).hex()
|
|
367
|
+
same_hash = recomputed == str(l.get("leaf_hash"))[7:]
|
|
368
|
+
names = leaf.get("hash") == proof["root_hash"] and leaf.get("kind") == "semanto_version"
|
|
369
|
+
c.add("log_leaf", same_hash and names, ("The log leaf is the canonical leaf record and names this root_hash." if names else "The log leaf names a different root_hash.") if same_hash else "The leaf record does not hash to leaf_hash.", "log_leaf_mismatch")
|
|
370
|
+
else:
|
|
371
|
+
c.list.append({"name": "log_leaf", "ok": True, "detail": "The proof carries only the leaf hash, so the leaf record was not recomputed."})
|
|
372
|
+
try:
|
|
373
|
+
in_log = leaf_h is not None and verify_inclusion(leaf_h, l["index"], l["tree_size"], [digest_bytes(x) for x in (l.get("inclusion_path") or l.get("path") or [])], digest_bytes(l["root_hash"]))
|
|
374
|
+
except (ValueError, KeyError, TypeError):
|
|
375
|
+
in_log = False
|
|
376
|
+
c.add("log_inclusion", in_log, f"Leaf {l.get('index')} is in the log of size {l.get('tree_size')} with root {l.get('root_hash')}." if in_log else "The log inclusion proof does not lead to the tree head.", "log_inclusion_failed")
|
|
377
|
+
th = verify_tree_head({"jws": l.get("tree_head_jws") or (l.get("tree_head") or {}).get("jws"), "payload": (l.get("tree_head") or {}).get("payload")}, trooth_keys, at)
|
|
378
|
+
same = th["ok"] and th.get("tree_size") == l.get("tree_size") and th.get("root_hash") == l.get("root_hash")
|
|
379
|
+
c.add("tree_head", same, (f"The tree head of size {th.get('tree_size')} is signed by Trooth (key {th.get('kid')})." if same else "The signed tree head names a different tree.") if th["ok"] else f"The tree head signature did not check out against Trooth's keys: {th['reason']}.", "tree_head_mismatch" if th["ok"] else f"tree_head_{th['reason']}")
|
|
380
|
+
else:
|
|
381
|
+
c.add("log", allow_unlogged, "Absent: the proof carries no log entry (allowed by the caller)." if allow_unlogged else "Absent: the proof carries no log entry.", "log_absent")
|
|
382
|
+
|
|
383
|
+
vid = proof.get("version_id") or (version_id(proof["root_hash"]) if is_digest(proof.get("root_hash")) else None)
|
|
384
|
+
return c.result(version_id=vid)
|
|
385
|
+
|
|
386
|
+
|
|
387
|
+
def verify_response(status: int, headers: Dict[str, Any], body: Union[bytes, str], keys: Any = None, now: Now = None, tag: str = SEMANTO_RESPONSE_TAG, required: Optional[List[str]] = None, max_age_seconds: Optional[int] = None) -> dict:
|
|
388
|
+
"""Verify a signed HTTP response: RFC 9421 with tag trooth-semanto and RFC 9530 Content-Digest.
|
|
389
|
+
|
|
390
|
+
The covered list is read from Signature-Input: the fixed components must be covered, and
|
|
391
|
+
Trooth-Signed-Page-Hash, Trooth-Signed-By, Trooth-Semanto-State and Location must be covered
|
|
392
|
+
whenever present. Trooth-Page-Hash is always the digest of the body. Trooth-Signed-By: witness
|
|
393
|
+
resolves against Trooth's keys; anything else against the company's.
|
|
394
|
+
"""
|
|
395
|
+
c = _Checks()
|
|
396
|
+
b = _as_bytes(body)
|
|
397
|
+
role = "trooth" if (header_get(headers, "trooth-signed-by") or "").strip().lower() == "witness" else "company"
|
|
398
|
+
who = "Trooth" if role == "trooth" else "company"
|
|
399
|
+
now_sec = int(time.time()) if now is None else _epoch(now)
|
|
400
|
+
dg = verify_content_digest(header_get(headers, "content-digest"), b)
|
|
401
|
+
c.add("content_digest", dg, "Content-Digest matches the body." if dg else "Content-Digest does not match the body, or is missing.", "content_digest_mismatch")
|
|
402
|
+
v = verify_message({"kind": "response", "status": status, "headers": headers}, role_resolver(keys, role), required=required or SEMANTO_RESPONSE_COMPONENTS, tag=tag, now=now_sec, max_age_seconds=max_age_seconds)
|
|
403
|
+
c.add("signature", v["ok"], f"The response is signed by the {who} key {v['keyid']} with tag {v['params'].get('tag')}, covering {', '.join(v['components'])}." if v["ok"] else f"The response signature did not check out against the {who} keys: {v['reason']}.", None if v["ok"] else v["reason"])
|
|
404
|
+
if v["ok"]:
|
|
405
|
+
for n in v.get("notes", []):
|
|
406
|
+
c.note(f"Response signature: {n}.")
|
|
407
|
+
covered = [x.lower() for x in v["components"]]
|
|
408
|
+
uncovered = [n for n in SEMANTO_RESPONSE_MUST_COVER_WHEN_PRESENT if header_get(headers, n) is not None and n not in covered]
|
|
409
|
+
c.add("covered_headers", not uncovered, "Every Trooth header the response carries is covered by the signature." if not uncovered else "These headers are present but not covered by the signature: " + ", ".join(uncovered) + ".", "header_not_covered")
|
|
410
|
+
for n in ("content-signal", "link"):
|
|
411
|
+
if header_get(headers, n) is not None and n not in covered:
|
|
412
|
+
c.note(f"{n} is present but not covered by the signature; do not rely on it.")
|
|
413
|
+
page_hash = header_get(headers, "trooth-page-hash")
|
|
414
|
+
d = digest(b)
|
|
415
|
+
c.add("page_hash", page_hash == d, f"Trooth-Page-Hash is the digest of the body: {d}" if page_hash == d else (f"Trooth-Page-Hash {page_hash} is not the digest of the body ({d})." if page_hash else "The response carries no Trooth-Page-Hash."), "page_hash_mismatch")
|
|
416
|
+
return c.result(keyid=v.get("keyid") if v["ok"] else None, params=v.get("params") if v["ok"] else None, signed_by=role, version=header_get(headers, "trooth-semanto-version"), page_hash=page_hash, signed_page_hash=header_get(headers, "trooth-signed-page-hash"))
|
|
417
|
+
|
|
418
|
+
|
|
419
|
+
def verify_web_bot_auth_request(method: str, url: str, headers: Dict[str, Any], keys: Any = None, now: Now = None, max_age_seconds: Optional[int] = None) -> dict:
|
|
420
|
+
"""Verify a Web Bot Auth signed request against the agent's keys; one web-bot-auth label only."""
|
|
421
|
+
now_sec = int(time.time()) if now is None else _epoch(now)
|
|
422
|
+
inputs = parse_signature_input(header_get(headers, "signature-input") or "")
|
|
423
|
+
labels = [l for l, e in inputs.items() if e["params"].get("tag") == WEB_BOT_AUTH_TAG]
|
|
424
|
+
if len(labels) > 1:
|
|
425
|
+
return {"ok": False, "reason": "more_than_one_label"}
|
|
426
|
+
v = verify_message({"kind": "request", "method": method, "url": url, "headers": headers}, role_resolver(keys, "agent"), required=WEB_BOT_AUTH_REQUIRED, tag=WEB_BOT_AUTH_TAG, now=now_sec, max_age_seconds=max_age_seconds, label=labels[0] if labels else None)
|
|
427
|
+
if not v["ok"]:
|
|
428
|
+
return v
|
|
429
|
+
agent = (header_get(headers, "signature-agent") or "").strip().strip('"')
|
|
430
|
+
return {**v, "agent": agent}
|
|
431
|
+
|
|
432
|
+
|
|
433
|
+
def verify_tree_head(tree_head: Union[dict, str], keys: Any = None, now: Now = None) -> dict:
|
|
434
|
+
"""A compact JWS (typ signed-tree-head) over { tree_size, root_hash, signed_at }, against Trooth's keys; a string, {"jws"} or {"payload", "jws"}."""
|
|
435
|
+
if not isinstance(tree_head, (str, dict)):
|
|
436
|
+
return {"ok": False, "reason": "malformed"}
|
|
437
|
+
jws = tree_head if isinstance(tree_head, str) else (tree_head.get("jws") or tree_head.get("tree_head_jws"))
|
|
438
|
+
given = None if isinstance(tree_head, str) else tree_head.get("payload")
|
|
439
|
+
v = verify_jws(jws, role_resolver(keys, "trooth"), expect_typ=JWS_TYPES["treeHead"], payload=given, at=_at(now))
|
|
440
|
+
if not v["ok"]:
|
|
441
|
+
return v
|
|
442
|
+
p = v["payload"]
|
|
443
|
+
if not isinstance(p, dict) or not isinstance(p.get("tree_size"), int) or not is_digest(p.get("root_hash")):
|
|
444
|
+
return {"ok": False, "reason": "malformed"}
|
|
445
|
+
if isinstance(tree_head, dict) and tree_head.get("root_hash") is not None:
|
|
446
|
+
if tree_head["root_hash"] != p["root_hash"] or (tree_head.get("tree_size") is not None and tree_head["tree_size"] != p["tree_size"]):
|
|
447
|
+
return {"ok": False, "reason": "payload_mismatch"}
|
|
448
|
+
return {"ok": True, "kid": v["header"]["kid"], "payload": p, "tree_size": p["tree_size"], "root_hash": p["root_hash"], "signed_at": p.get("signed_at"), "notes": v.get("notes", [])}
|
|
449
|
+
|
|
450
|
+
|
|
451
|
+
def verify_inclusion_in_log(proof: dict, root_hash_override: Optional[str] = None) -> bool:
|
|
452
|
+
leaf_h = digest_bytes(proof["leaf_hash"]) if proof.get("leaf_hash") else leaf_hash(canonical_bytes(proof["leaf"]))
|
|
453
|
+
root = digest_bytes(root_hash_override or proof["root_hash"])
|
|
454
|
+
return verify_inclusion(leaf_h, proof["index"], proof["tree_size"], [digest_bytes(x) for x in (proof.get("path") or proof.get("inclusion_path") or [])], root)
|
|
455
|
+
|
|
456
|
+
|
|
457
|
+
def verify_consistency(proof: dict) -> bool:
|
|
458
|
+
return _verify_consistency(proof["from"], proof["to"], digest_bytes(proof["old_root"]), digest_bytes(proof["new_root"]), [digest_bytes(x) for x in proof.get("path") or []])
|
|
459
|
+
|
|
460
|
+
|
|
461
|
+
def verify_checkpoint(text: str, keys: Any = None, expected_origin: Optional[str] = TROOTH_LOG_ORIGIN, expected_name: Optional[str] = TROOTH_LOG_SIGNER_NAME) -> dict:
|
|
462
|
+
"""A signed note (golang.org/x/mod/sumdb/note): origin, size, base64 root, blank line, then lines "\u2014 name base64(keyhash4||sig)".
|
|
463
|
+
|
|
464
|
+
keyhash4 is the first 4 bytes of SHA-256(name || "\n" || 0x01 || pubkey). Only Trooth's keys are tried,
|
|
465
|
+
only a line named "trooth.co" counts, and the origin must be "trooth.co/semanto/log/v1" unless another is named.
|
|
466
|
+
"""
|
|
467
|
+
if not isinstance(text, str):
|
|
468
|
+
return {"ok": False, "reason": "malformed"}
|
|
469
|
+
split = text.find("\n\n")
|
|
470
|
+
if split < 0:
|
|
471
|
+
return {"ok": False, "reason": "malformed"}
|
|
472
|
+
body, sig_block = text[: split + 1], text[split + 2 :]
|
|
473
|
+
lines = body.split("\n")
|
|
474
|
+
if len(lines) < 3:
|
|
475
|
+
return {"ok": False, "reason": "malformed"}
|
|
476
|
+
origin = lines[0]
|
|
477
|
+
if expected_origin and origin != expected_origin:
|
|
478
|
+
return {"ok": False, "reason": "wrong_origin"}
|
|
479
|
+
if not re.fullmatch(r"\d+", lines[1]):
|
|
480
|
+
return {"ok": False, "reason": "malformed"}
|
|
481
|
+
try:
|
|
482
|
+
size = int(lines[1])
|
|
483
|
+
root = base64.b64decode(lines[2], validate=True)
|
|
484
|
+
except (ValueError, TypeError):
|
|
485
|
+
return {"ok": False, "reason": "malformed"}
|
|
486
|
+
candidates = role_keys(keys, "trooth")
|
|
487
|
+
saw_line = False
|
|
488
|
+
saw_name = False
|
|
489
|
+
for line in sig_block.split("\n"):
|
|
490
|
+
m = re.match(r"^\u2014 (\S+) (\S+)$", line)
|
|
491
|
+
if not m:
|
|
492
|
+
continue
|
|
493
|
+
saw_line = True
|
|
494
|
+
name = m.group(1)
|
|
495
|
+
if expected_name and name != expected_name:
|
|
496
|
+
continue
|
|
497
|
+
saw_name = True
|
|
498
|
+
try:
|
|
499
|
+
blob = base64.b64decode(m.group(2))
|
|
500
|
+
except (ValueError, TypeError):
|
|
501
|
+
continue
|
|
502
|
+
key_hash, sig = blob[:4], blob[4:]
|
|
503
|
+
for jwk in candidates:
|
|
504
|
+
pub = b64url_decode(jwk["x"])
|
|
505
|
+
expect = hashlib.sha256(name.encode("utf-8") + b"\n\x01" + pub).digest()[:4]
|
|
506
|
+
if key_hash != expect:
|
|
507
|
+
continue
|
|
508
|
+
if ed25519_verify(jwk, sig, body.encode("utf-8")):
|
|
509
|
+
return {"ok": True, "origin": origin, "name": name, "tree_size": size, "root_hash": "sha256:" + root.hex(), "kid": jwk.get("kid")}
|
|
510
|
+
return {"ok": False, "reason": "bad_signature"}
|
|
511
|
+
return {"ok": False, "reason": "malformed" if not saw_line else ("wrong_signer" if not saw_name else "unknown_key")}
|
|
512
|
+
|
|
513
|
+
|
|
514
|
+
def verify_offer(jws: str, keys: Any = None, now: Now = None) -> dict:
|
|
515
|
+
"""A signed offer (typ signed-offer), against the company's keys."""
|
|
516
|
+
v = verify_jws(jws, role_resolver(keys, "company"), expect_typ=JWS_TYPES["offer"], at=_at(now))
|
|
517
|
+
if not v["ok"]:
|
|
518
|
+
return v
|
|
519
|
+
return {**v, "offer_id": semanto_id("smo", digest(canonical_bytes(v["payload"])))}
|
|
520
|
+
|
|
521
|
+
|
|
522
|
+
def verify_revocation_list(jws: str, keys: Any = None, now: Now = None) -> dict:
|
|
523
|
+
"""A signed revocation list (typ revocation-list), against Trooth's keys."""
|
|
524
|
+
v = verify_jws(jws, role_resolver(keys, "trooth"), expect_typ=JWS_TYPES["revocation"], at=_at(now))
|
|
525
|
+
if not v["ok"]:
|
|
526
|
+
return v
|
|
527
|
+
if not isinstance(v["payload"], dict) or not isinstance(v["payload"].get("revocations"), list):
|
|
528
|
+
return {"ok": False, "reason": "malformed"}
|
|
529
|
+
return v
|
|
530
|
+
|
|
531
|
+
|
|
532
|
+
def parse_link(value: Optional[str]) -> List[dict]:
|
|
533
|
+
out: List[dict] = []
|
|
534
|
+
if not value:
|
|
535
|
+
return out
|
|
536
|
+
for m in re.finditer(r'<([^>]*)>((?:\s*;\s*[A-Za-z0-9-]+=(?:"[^"]*"|[^;,]*))*)', value):
|
|
537
|
+
params = {}
|
|
538
|
+
for pm in re.finditer(r';\s*([A-Za-z0-9-]+)=("([^"]*)"|[^;,]*)', m.group(2)):
|
|
539
|
+
params[pm.group(1).lower()] = pm.group(3) if pm.group(3) is not None else pm.group(2).strip()
|
|
540
|
+
out.append({"url": m.group(1), "params": params})
|
|
541
|
+
return out
|