avm-ac2 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.
- avm_ac2/__init__.py +67 -0
- avm_ac2/cli.py +185 -0
- avm_ac2/consent.py +513 -0
- avm_ac2/txn_consent.py +216 -0
- avm_ac2-0.1.0.dist-info/METADATA +306 -0
- avm_ac2-0.1.0.dist-info/RECORD +11 -0
- avm_ac2-0.1.0.dist-info/WHEEL +5 -0
- avm_ac2-0.1.0.dist-info/entry_points.txt +2 -0
- avm_ac2-0.1.0.dist-info/licenses/LICENSE +190 -0
- avm_ac2-0.1.0.dist-info/licenses/NOTICE +26 -0
- avm_ac2-0.1.0.dist-info/top_level.txt +1 -0
avm_ac2/__init__.py
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
"""avm-ac2 -- AC2 consent, bound to an avm-mesh settlement.
|
|
2
|
+
|
|
3
|
+
The seam in one sentence: **avm-mesh proves what settled, AC2 proves who
|
|
4
|
+
approved, and this package makes the second checkable against the first.**
|
|
5
|
+
|
|
6
|
+
Neither protocol is changed. ``avm-mesh`` gains no new wire format, and AC2 gains
|
|
7
|
+
no new message type: the consent travels inside the sealed receipt's existing
|
|
8
|
+
``content`` dict, which is hashed before the consensus attestation is inserted,
|
|
9
|
+
so the block is covered by ``content_hash`` and cannot be edited, swapped or
|
|
10
|
+
stripped without breaking LEVEL 1.
|
|
11
|
+
|
|
12
|
+
Read :mod:`avm_ac2.consent` for what each level proves and -- more importantly --
|
|
13
|
+
what it deliberately does not.
|
|
14
|
+
"""
|
|
15
|
+
from .consent import (
|
|
16
|
+
AC2_CONSENT_KEY,
|
|
17
|
+
AC2_CONSENT_VERSION,
|
|
18
|
+
LEVELS,
|
|
19
|
+
LEVEL_CONSENSUS,
|
|
20
|
+
LEVEL_CONSENT,
|
|
21
|
+
LEVEL_NONE,
|
|
22
|
+
LEVEL_SENDER,
|
|
23
|
+
ConsentAttestation,
|
|
24
|
+
build_consent,
|
|
25
|
+
canonical_bytes,
|
|
26
|
+
consent_digest,
|
|
27
|
+
consent_level,
|
|
28
|
+
consent_payload,
|
|
29
|
+
sender_from_bundle,
|
|
30
|
+
verify_consent,
|
|
31
|
+
)
|
|
32
|
+
|
|
33
|
+
# Transaction-bound consent: the fallback that needs no arbitrary-payload
|
|
34
|
+
# approval from the wallet. Same guarantees where it applies, different preimage.
|
|
35
|
+
from .txn_consent import (
|
|
36
|
+
TXN_CONSENT_KEY,
|
|
37
|
+
TXN_CONSENT_VERSION,
|
|
38
|
+
build_txn_consent,
|
|
39
|
+
preimage_digest,
|
|
40
|
+
signing_preimage,
|
|
41
|
+
verify_txn_consent,
|
|
42
|
+
)
|
|
43
|
+
|
|
44
|
+
__all__ = [
|
|
45
|
+
"AC2_CONSENT_KEY",
|
|
46
|
+
"AC2_CONSENT_VERSION",
|
|
47
|
+
"LEVELS",
|
|
48
|
+
"LEVEL_NONE",
|
|
49
|
+
"LEVEL_CONSENT",
|
|
50
|
+
"LEVEL_SENDER",
|
|
51
|
+
"LEVEL_CONSENSUS",
|
|
52
|
+
"ConsentAttestation",
|
|
53
|
+
"build_consent",
|
|
54
|
+
"canonical_bytes",
|
|
55
|
+
"consent_digest",
|
|
56
|
+
"consent_level",
|
|
57
|
+
"consent_payload",
|
|
58
|
+
"sender_from_bundle",
|
|
59
|
+
"verify_consent",
|
|
60
|
+
"TXN_CONSENT_KEY",
|
|
61
|
+
"TXN_CONSENT_VERSION",
|
|
62
|
+
"build_txn_consent",
|
|
63
|
+
"preimage_digest",
|
|
64
|
+
"signing_preimage",
|
|
65
|
+
"verify_txn_consent",
|
|
66
|
+
]
|
|
67
|
+
__version__ = "0.1.0"
|
avm_ac2/cli.py
ADDED
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
"""``avm-ac2`` -- check the AC2 consent inside a sealed settlement receipt.
|
|
2
|
+
|
|
3
|
+
Three read-only subcommands:
|
|
4
|
+
|
|
5
|
+
avm-ac2 payload <settlement.json> bytes to be signed
|
|
6
|
+
avm-ac2 verify <sealed.json> --evidence <dir> [...] full report
|
|
7
|
+
avm-ac2 level <sealed.json> --evidence <dir> [...] one line
|
|
8
|
+
|
|
9
|
+
``verify`` and ``level`` re-derive the sender from the bundle's authenticated
|
|
10
|
+
``SignedTxnInBlock`` rather than accepting it from the receipt, because a value a
|
|
11
|
+
receipt asserts about itself is not evidence for itself.
|
|
12
|
+
"""
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import argparse
|
|
16
|
+
import base64
|
|
17
|
+
import json
|
|
18
|
+
import pathlib
|
|
19
|
+
import sys
|
|
20
|
+
|
|
21
|
+
from avm_mesh import MeshError
|
|
22
|
+
from avm_mesh.receipt import create_receipt, verify_receipt
|
|
23
|
+
|
|
24
|
+
from .consent import consent_level, consent_payload
|
|
25
|
+
from .txn_consent import TXN_CONSENT_KEY, verify_txn_consent
|
|
26
|
+
|
|
27
|
+
LEVEL_ORDER = ["none", "consent_present", "sender_bound", "consensus_bound"]
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _read_json(path: str) -> dict:
|
|
31
|
+
"""Read a JSON document, transparently handling gzip.
|
|
32
|
+
|
|
33
|
+
Proofpacks are routinely stored gzipped (``*.json.gz``), and a plain
|
|
34
|
+
``read_text`` on one dies with a UnicodeDecodeError on the gzip magic byte
|
|
35
|
+
``0x8b`` — which reads like a corrupt fixture rather than an unhandled
|
|
36
|
+
format. Sniff the magic number instead of trusting the extension, because a
|
|
37
|
+
capture can be named either way.
|
|
38
|
+
"""
|
|
39
|
+
raw = pathlib.Path(path).read_bytes()
|
|
40
|
+
if raw[:2] == b"\x1f\x8b":
|
|
41
|
+
import gzip
|
|
42
|
+
|
|
43
|
+
raw = gzip.decompress(raw)
|
|
44
|
+
data = json.loads(raw.decode("utf-8"))
|
|
45
|
+
if not isinstance(data, dict):
|
|
46
|
+
raise MeshError(f"{path} does not contain a JSON object")
|
|
47
|
+
return data
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _resolve_from(directory: str):
|
|
51
|
+
"""Resolve a proofpack from a directory, refusing to leave it.
|
|
52
|
+
|
|
53
|
+
One path component, and the resolved path must stay inside the directory: the
|
|
54
|
+
uri comes from the receipt, which is the untrusted input here.
|
|
55
|
+
"""
|
|
56
|
+
root = pathlib.Path(directory).resolve()
|
|
57
|
+
|
|
58
|
+
def resolve(uri: str) -> dict:
|
|
59
|
+
name = str(uri).rsplit("/", 1)[-1]
|
|
60
|
+
if not name or name.startswith(".") or "/" in name or "\\" in name:
|
|
61
|
+
raise MeshError(f"refusing to resolve a path-like uri: {uri!r}")
|
|
62
|
+
candidate = (root / name).resolve()
|
|
63
|
+
if candidate != root and root not in candidate.parents:
|
|
64
|
+
raise MeshError(f"resolved path escapes the evidence directory: {uri!r}")
|
|
65
|
+
if not candidate.is_file():
|
|
66
|
+
raise MeshError(f"no evidence file for {uri!r} in {root}")
|
|
67
|
+
return _read_json(str(candidate))
|
|
68
|
+
|
|
69
|
+
return resolve
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _cmd_payload(args: argparse.Namespace) -> int:
|
|
73
|
+
sys.stdout.write(consent_payload(_read_json(args.settlement)).decode("utf-8"))
|
|
74
|
+
sys.stdout.write("\n")
|
|
75
|
+
return 0
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def _cmd_verify(args: argparse.Namespace) -> int:
|
|
79
|
+
envelope = _read_json(args.receipt)
|
|
80
|
+
|
|
81
|
+
report = None
|
|
82
|
+
bundle = None
|
|
83
|
+
if args.evidence:
|
|
84
|
+
from avm_proofpack.verify import TrustedVoters
|
|
85
|
+
|
|
86
|
+
content = json.loads(base64.b64decode(envelope["canonical_bytes_b64"]).decode())
|
|
87
|
+
attestation = content.get("consensus_attestation") or {}
|
|
88
|
+
uri = attestation.get("evidence_uri")
|
|
89
|
+
if not uri:
|
|
90
|
+
raise MeshError("sealed receipt carries no consensus attestation to resolve")
|
|
91
|
+
|
|
92
|
+
voter = None
|
|
93
|
+
if args.voters_commitment and args.ln_proven_weight is not None:
|
|
94
|
+
voter = TrustedVoters(base64.b64decode(args.voters_commitment.encode()),
|
|
95
|
+
int(args.ln_proven_weight))
|
|
96
|
+
bundle = _resolve_from(args.evidence)(uri)
|
|
97
|
+
# Public path: build a receipt over the resolved bundle, then verify it.
|
|
98
|
+
# The report (chain, txid, round, tier) comes out of the verification,
|
|
99
|
+
# never off the receipt's own claims.
|
|
100
|
+
receipt = create_receipt(bundle, uri, trusted_voters=voter)
|
|
101
|
+
report = verify_receipt(
|
|
102
|
+
receipt,
|
|
103
|
+
lambda _u: bundle,
|
|
104
|
+
trusted_voters=voter,
|
|
105
|
+
expected_genesis_hash_b64=args.genesis,
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
# Two consent flavours exist and they verify against different preimages. The
|
|
109
|
+
# CLI must dispatch on which block is present rather than assuming the
|
|
110
|
+
# canonical one: reporting 'none' for a valid transaction-bound consent
|
|
111
|
+
# would be a false negative on a correctly signed receipt.
|
|
112
|
+
import base64 as _b64
|
|
113
|
+
import json as _json
|
|
114
|
+
_content = _json.loads(_b64.b64decode(envelope["canonical_bytes_b64"]))
|
|
115
|
+
if TXN_CONSENT_KEY in _content:
|
|
116
|
+
if bundle is None or report is None:
|
|
117
|
+
raise MeshError(
|
|
118
|
+
"a transaction-bound consent needs --evidence and a resolvable "
|
|
119
|
+
"proofpack to rebuild the signed preimage"
|
|
120
|
+
)
|
|
121
|
+
out = verify_txn_consent(envelope, bundle, report.genesis_id,
|
|
122
|
+
require=args.require)
|
|
123
|
+
out["flavour"] = "transaction_bound"
|
|
124
|
+
else:
|
|
125
|
+
out = consent_level(envelope, report, bundle=bundle, require=args.require)
|
|
126
|
+
out["flavour"] = "canonical_payload"
|
|
127
|
+
|
|
128
|
+
if args.json:
|
|
129
|
+
print(json.dumps({**out, "settlement_tier": getattr(report, "trust_root", None)},
|
|
130
|
+
indent=2, sort_keys=True))
|
|
131
|
+
else:
|
|
132
|
+
print(f"consent level: {out['level']} ({out.get('flavour', '-')})")
|
|
133
|
+
if report is not None:
|
|
134
|
+
print(f"settlement: {report.genesis_id} {report.txid[:16]}... "
|
|
135
|
+
f"round {report.round} ({report.trust_root})")
|
|
136
|
+
print(f"controller: {out.get('did') or '-'}")
|
|
137
|
+
print(f"why: {out['reason']}")
|
|
138
|
+
|
|
139
|
+
if args.min_level and LEVEL_ORDER.index(out["level"]) < LEVEL_ORDER.index(args.min_level):
|
|
140
|
+
print(f"below required level {args.min_level}: {out['level']}", file=sys.stderr)
|
|
141
|
+
return 2
|
|
142
|
+
return 0
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
146
|
+
parser = argparse.ArgumentParser(
|
|
147
|
+
prog="avm-ac2",
|
|
148
|
+
description="Check AC2 consent inside a sealed avm-mesh settlement receipt.")
|
|
149
|
+
sub = parser.add_subparsers(dest="cmd", required=True)
|
|
150
|
+
|
|
151
|
+
pay = sub.add_parser("payload", help="print the exact bytes a controller signs")
|
|
152
|
+
pay.add_argument("settlement", help="JSON file describing the settlement")
|
|
153
|
+
pay.set_defaults(func=_cmd_payload)
|
|
154
|
+
|
|
155
|
+
for name, help_text in (("verify", "verify consent and print a report"),
|
|
156
|
+
("level", "same check, report only the level")):
|
|
157
|
+
v = sub.add_parser(name, help=help_text)
|
|
158
|
+
v.add_argument("receipt", help="sealed receipt JSON")
|
|
159
|
+
v.add_argument("--evidence", default=None,
|
|
160
|
+
help="directory holding the proofpack the attestation names")
|
|
161
|
+
v.add_argument("--genesis", default=None,
|
|
162
|
+
help="pinned genesis hash, base64 (checked against the header)")
|
|
163
|
+
v.add_argument("--voters-commitment", default=None,
|
|
164
|
+
help="trusted voters commitment, base64")
|
|
165
|
+
v.add_argument("--ln-proven-weight", type=int, default=None)
|
|
166
|
+
v.add_argument("--require", action="store_true",
|
|
167
|
+
help="fail if the receipt carries no consent block")
|
|
168
|
+
v.add_argument("--min-level", default=None, choices=LEVEL_ORDER,
|
|
169
|
+
help="exit non-zero unless at least this level was reached")
|
|
170
|
+
v.add_argument("--json", action="store_true", help="machine-readable output")
|
|
171
|
+
v.set_defaults(func=_cmd_verify)
|
|
172
|
+
return parser
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def main(argv: list[str] | None = None) -> int:
|
|
176
|
+
args = build_parser().parse_args(argv)
|
|
177
|
+
try:
|
|
178
|
+
return args.func(args)
|
|
179
|
+
except (MeshError, FileNotFoundError) as exc:
|
|
180
|
+
print(f"error: {exc}", file=sys.stderr)
|
|
181
|
+
return 2
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
if __name__ == "__main__":
|
|
185
|
+
raise SystemExit(main())
|