probity-records 0.2.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.
@@ -0,0 +1,197 @@
1
+ """Signed, offline-verifiable records of agent tool calls, shared by the framework integrations."""
2
+
3
+ from .authority import GRANT_ALLOW, QUORUM_ALLOW, Trust
4
+ from .constraints import ConstraintError, narrows
5
+ from .constraints import check as check_constraint
6
+ from .core import (
7
+ APPROVAL_DOMAIN,
8
+ IN_TOTO_PAYLOAD_TYPE,
9
+ Signer,
10
+ admitted_loads,
11
+ args_digest,
12
+ args_sha256,
13
+ canonical,
14
+ canonical_of_received,
15
+ key_id,
16
+ load_public,
17
+ open_envelope,
18
+ pae,
19
+ permit_id,
20
+ sha256_hex,
21
+ sign_approval,
22
+ sign_envelope,
23
+ sign_permit,
24
+ statement,
25
+ verify_approval,
26
+ verify_permit,
27
+ )
28
+ from .exports import (
29
+ EXPORT_SEAL,
30
+ FieldMap,
31
+ compare_seals,
32
+ seal_export,
33
+ verify_export_seal,
34
+ )
35
+ from .exports import census as export_census
36
+ from .governance import (
37
+ EXCEPTION_ALLOW,
38
+ GOVERNANCE_EXCEPTION,
39
+ GOVERNANCE_STEP,
40
+ STEPS,
41
+ check_exception_call,
42
+ exception_body,
43
+ exception_digest,
44
+ exception_evidence,
45
+ route_by_risk,
46
+ step_predicate,
47
+ )
48
+ from .grants import (
49
+ CAPABILITY_GRANT,
50
+ grant_digest,
51
+ grant_evidence,
52
+ issue_grant,
53
+ raw_public,
54
+ verify_call_under_grant,
55
+ verify_chain,
56
+ verify_grant_allow,
57
+ )
58
+ from .journal import (
59
+ CHECKPOINT_TYPE,
60
+ JOURNAL_FILE,
61
+ KEYS_FILE,
62
+ NOT_RUN_RETRY,
63
+ RECONCILED_RETRY,
64
+ RETRY_REASONS,
65
+ Journal,
66
+ verify_journal,
67
+ )
68
+ from .quorum import APPROVAL_QUORUM, QuorumResult, request_hash, sign_vote
69
+ from .quorum import count as count_votes
70
+ from .records import (
71
+ APPROVAL_BINDING_CONTRACT,
72
+ OUTCOMES,
73
+ REPLIES,
74
+ TOOL_CALL_RECORD,
75
+ UNCERTAIN_EFFECT_CONTRACT,
76
+ build_approval_binding,
77
+ build_uncertain_effect,
78
+ embed_approval_binding,
79
+ judge_approval_binding,
80
+ judge_uncertain_effect,
81
+ tool_call_predicate,
82
+ verifier_case,
83
+ )
84
+ from .revocation import (
85
+ REVOCATION_LIST,
86
+ RevocationError,
87
+ RevocationState,
88
+ sign_revocations,
89
+ verify_approval_live,
90
+ )
91
+ from .signing import (
92
+ AwsKmsKey,
93
+ DelegatedKey,
94
+ Delegation,
95
+ GcpKmsKey,
96
+ SigningError,
97
+ SigningKey,
98
+ VaultTransitKey,
99
+ delegate,
100
+ verify_delegation,
101
+ )
102
+ from .walk import grant_permit_claims, grant_walk, mint_grant_permit
103
+
104
+ __all__ = [
105
+ "APPROVAL_BINDING_CONTRACT",
106
+ "APPROVAL_DOMAIN",
107
+ "APPROVAL_QUORUM",
108
+ "CAPABILITY_GRANT",
109
+ "CHECKPOINT_TYPE",
110
+ "EXCEPTION_ALLOW",
111
+ "EXPORT_SEAL",
112
+ "GOVERNANCE_EXCEPTION",
113
+ "GOVERNANCE_STEP",
114
+ "GRANT_ALLOW",
115
+ "IN_TOTO_PAYLOAD_TYPE",
116
+ "JOURNAL_FILE",
117
+ "KEYS_FILE",
118
+ "NOT_RUN_RETRY",
119
+ "OUTCOMES",
120
+ "QUORUM_ALLOW",
121
+ "RECONCILED_RETRY",
122
+ "REPLIES",
123
+ "RETRY_REASONS",
124
+ "REVOCATION_LIST",
125
+ "STEPS",
126
+ "TOOL_CALL_RECORD",
127
+ "UNCERTAIN_EFFECT_CONTRACT",
128
+ "AwsKmsKey",
129
+ "ConstraintError",
130
+ "DelegatedKey",
131
+ "Delegation",
132
+ "FieldMap",
133
+ "GcpKmsKey",
134
+ "Journal",
135
+ "QuorumResult",
136
+ "RevocationError",
137
+ "RevocationState",
138
+ "Signer",
139
+ "SigningError",
140
+ "SigningKey",
141
+ "Trust",
142
+ "VaultTransitKey",
143
+ "admitted_loads",
144
+ "args_digest",
145
+ "args_sha256",
146
+ "build_approval_binding",
147
+ "build_uncertain_effect",
148
+ "canonical",
149
+ "canonical_of_received",
150
+ "check_constraint",
151
+ "check_exception_call",
152
+ "compare_seals",
153
+ "count_votes",
154
+ "delegate",
155
+ "embed_approval_binding",
156
+ "exception_body",
157
+ "exception_digest",
158
+ "exception_evidence",
159
+ "export_census",
160
+ "grant_digest",
161
+ "grant_evidence",
162
+ "grant_permit_claims",
163
+ "grant_walk",
164
+ "issue_grant",
165
+ "judge_approval_binding",
166
+ "judge_uncertain_effect",
167
+ "key_id",
168
+ "load_public",
169
+ "mint_grant_permit",
170
+ "narrows",
171
+ "open_envelope",
172
+ "pae",
173
+ "permit_id",
174
+ "raw_public",
175
+ "request_hash",
176
+ "route_by_risk",
177
+ "seal_export",
178
+ "sha256_hex",
179
+ "sign_approval",
180
+ "sign_envelope",
181
+ "sign_permit",
182
+ "sign_revocations",
183
+ "sign_vote",
184
+ "statement",
185
+ "step_predicate",
186
+ "tool_call_predicate",
187
+ "verifier_case",
188
+ "verify_approval",
189
+ "verify_approval_live",
190
+ "verify_call_under_grant",
191
+ "verify_chain",
192
+ "verify_delegation",
193
+ "verify_export_seal",
194
+ "verify_grant_allow",
195
+ "verify_journal",
196
+ "verify_permit",
197
+ ]
@@ -0,0 +1,68 @@
1
+ """Command line: seal a governance export, verify a seal, compare two seals.
2
+
3
+ python -m probity_records seal-export EXPORT --key KEY.pem --source NAME --kind entities --out SEAL.json
4
+ python -m probity_records verify-export EXPORT SEAL.json --pub PUB.pem
5
+ python -m probity_records compare-seals OLD.json NEW.json
6
+ python -m probity_records identity-vectors [--check FILE]
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import argparse
12
+ import json
13
+ import sys
14
+ from pathlib import Path
15
+
16
+ from .core import Signer
17
+ from .exports import EXPORT_KINDS, compare_seals, seal_export, verify_export_seal
18
+ from .journal import now
19
+
20
+
21
+ def main(argv: list[str] | None = None) -> int:
22
+ parser = argparse.ArgumentParser(prog="python -m probity_records")
23
+ sub = parser.add_subparsers(dest="cmd", required=True)
24
+ seal = sub.add_parser("seal-export")
25
+ seal.add_argument("export", type=Path)
26
+ seal.add_argument("--key", type=Path, required=True)
27
+ seal.add_argument("--source", required=True)
28
+ seal.add_argument("--kind", choices=EXPORT_KINDS, required=True)
29
+ seal.add_argument("--captured-at")
30
+ seal.add_argument("--out", type=Path, required=True)
31
+ ver = sub.add_parser("verify-export")
32
+ ver.add_argument("export", type=Path)
33
+ ver.add_argument("seal", type=Path)
34
+ ver.add_argument("--pub", type=Path, action="append", required=True)
35
+ cmp_ = sub.add_parser("compare-seals")
36
+ cmp_.add_argument("older", type=Path)
37
+ cmp_.add_argument("newer", type=Path)
38
+ idv = sub.add_parser("identity-vectors")
39
+ idv.add_argument("--check", type=Path)
40
+ args = parser.parse_args(argv)
41
+ if args.cmd == "identity-vectors":
42
+ from .identity_vectors import check, vectors
43
+
44
+ if args.check is None:
45
+ print(json.dumps(vectors(), indent=2, sort_keys=True))
46
+ return 0
47
+ bad = check(json.loads(args.check.read_text()))
48
+ print(json.dumps({"differ": bad}))
49
+ return 1 if bad else 0
50
+ if args.cmd == "seal-export":
51
+ envelope = seal_export(Signer.from_pem(args.key.read_bytes()), args.export.read_bytes(), source=args.source,
52
+ kind=args.kind, captured_at=args.captured_at or now())
53
+ args.out.write_text(json.dumps(envelope, indent=2, sort_keys=True) + "\n")
54
+ return 0
55
+ if args.cmd == "verify-export":
56
+ report = verify_export_seal(json.loads(args.seal.read_text()), args.export.read_bytes(),
57
+ [p.read_bytes() for p in args.pub])
58
+ print(json.dumps({k: report[k] for k in ("verdict", "failures")}, sort_keys=True))
59
+ census = report["census"] or {}
60
+ print(f"records {census.get('records')} missing ids {census.get('missingIds')}")
61
+ return 0 if report["verdict"] == "PASS" else 1
62
+ print(json.dumps(compare_seals(json.loads(args.older.read_text()), json.loads(args.newer.read_text())),
63
+ sort_keys=True))
64
+ return 0
65
+
66
+
67
+ if __name__ == "__main__":
68
+ sys.exit(main())
@@ -0,0 +1,118 @@
1
+ """Offline re-check of the authority a tool-call ``authorize`` record rests on.
2
+
3
+ An ``authorize`` record whose ``reason`` is one of the authority reasons below carries an
4
+ ``authority`` object, and the verifier re-runs the matching check from the record alone plus the
5
+ trust the auditor pins (``Trust``): grant issuers, approver keys and quorum policies, revocations.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import base64
11
+ import hashlib
12
+ from collections.abc import Callable, Mapping
13
+ from dataclasses import dataclass, field
14
+ from typing import Any
15
+
16
+ from . import governance, grants, quorum
17
+ from .core import admitted_loads
18
+ from .revocation import RevocationState
19
+
20
+ GRANT_ALLOW = "grant"
21
+ QUORUM_ALLOW = "quorum"
22
+
23
+
24
+ @dataclass(frozen=True)
25
+ class Trust:
26
+ """What an auditor pins before verifying: nothing here is read from the records themselves."""
27
+
28
+ grant_root_key_ids: frozenset[str] = frozenset()
29
+ quorum_policies: Mapping[str, Mapping[str, Any]] = field(default_factory=dict)
30
+ revocations: RevocationState | None = None
31
+ #: issuer URL -> the RFC 7638 thumbprints the auditor pins for that issuer's signing keys
32
+ identity_issuers: Mapping[str, frozenset[str]] = field(default_factory=dict)
33
+ #: "basic" accepts a principals block without an act chain (graded); "strict" refuses it
34
+ identity_profile: str = "basic"
35
+ #: Signing key id -> the custody backend its checkpoint must name ("aws-kms", "vault-transit", ...).
36
+ key_custody: Mapping[str, str] = field(default_factory=dict)
37
+ #: A c2sp.org/tlog-policy (text): when set, a journal verifies only with a checkpoint its quorum
38
+ #: of witnesses (keys the customer holds) cosigned.
39
+ witness_policy: str | None = None
40
+
41
+ def key_revoked(self, kid: str, at: str) -> bool:
42
+ return self.revocations is not None and self.revocations.key_revoked(kid, at)
43
+
44
+ def permit_revoked(self, pid: str, at: str) -> bool:
45
+ return self.revocations is not None and self.revocations.permit_revoked(pid, at)
46
+
47
+ def revoked_grants(self) -> frozenset[str]:
48
+ return self.revocations.revoked_grants() if self.revocations else frozenset()
49
+
50
+
51
+ def _args(evidence: Mapping[str, Any], pred: Mapping[str, Any], problems: list[str], where: str) -> Any:
52
+ raw = base64.b64decode(evidence.get("argsB64", ""))
53
+ if hashlib.sha256(raw).hexdigest() != pred.get("argsSha256"):
54
+ problems.append(f"{where}:authority_args_are_not_the_call_arguments")
55
+ return admitted_loads(raw) if raw else None
56
+
57
+
58
+ def _check_grant(pred: Mapping[str, Any], evidence: Mapping[str, Any], trust: Trust, at: str,
59
+ problems: list[str], where: str) -> None:
60
+ args = _args(evidence, pred, problems, where)
61
+ verdict = grants.verify_grant_allow(list(evidence.get("chain", [])), str(pred.get("tool")), args, at,
62
+ set(trust.grant_root_key_ids), set(trust.revoked_grants()), trust.key_revoked,
63
+ evidence.get("ctx") or {})
64
+ if verdict["decision"] == "needs_approval" and isinstance(evidence.get("quorum"), Mapping):
65
+ leaf = evidence["chain"][-1]["body"]
66
+ carried = leaf["tools"][str(pred.get("tool"))].get("quorum")
67
+ outcome = _quorum_outcome(pred, evidence["quorum"], trust, at, carried)
68
+ if outcome != "ok":
69
+ problems.append(f"{where}:grant_approval_{outcome}")
70
+ elif verdict["decision"] != "allow":
71
+ problems.append(f"{where}:grant_{verdict['decision']}:{verdict['reason']}")
72
+ if verdict["grantDigest"] and verdict["grantDigest"] != pred.get("grantDigest"):
73
+ problems.append(f"{where}:grant_digest_differs_from_record")
74
+
75
+
76
+ def _quorum_outcome(pred: Mapping[str, Any], evidence: Mapping[str, Any], trust: Trust, at: str,
77
+ carried: Mapping[str, Any] | None = None) -> str:
78
+ """A grant that carries its own approval policy is trusted through the verified chain (rooted in
79
+ a pinned issuer); otherwise the policy must be the one the auditor pinned under its id."""
80
+ request = quorum.request_hash(str(pred.get("tool")), str(pred.get("argsSha256")), str(pred.get("permitId")),
81
+ proposer=evidence.get("proposer"), history=evidence.get("historyDigest"))
82
+ pinned = dict(trust.quorum_policies)
83
+ if carried is not None:
84
+ pinned[str(carried.get("policyId"))] = carried
85
+ return quorum.verify_evidence(evidence, pinned, request, at, trust.key_revoked)
86
+
87
+
88
+ def _check_quorum(pred: Mapping[str, Any], evidence: Mapping[str, Any], trust: Trust, at: str,
89
+ problems: list[str], where: str) -> None:
90
+ outcome = _quorum_outcome(pred, evidence, trust, at)
91
+ if outcome != "ok":
92
+ problems.append(f"{where}:{outcome}")
93
+
94
+
95
+ def _check_exception(pred: Mapping[str, Any], evidence: Mapping[str, Any], trust: Trust, at: str,
96
+ problems: list[str], where: str) -> None:
97
+ for problem in governance.verify_exception_evidence(pred, evidence, trust.quorum_policies, at, trust.key_revoked):
98
+ problems.append(f"{where}:{problem}")
99
+
100
+
101
+ CHECKS: dict[str, Callable[..., None]] = {GRANT_ALLOW: _check_grant, QUORUM_ALLOW: _check_quorum,
102
+ governance.EXCEPTION_ALLOW: _check_exception}
103
+
104
+
105
+ def check_authority(pred: Mapping[str, Any], trust: Trust | None, problems: list[str], where: str) -> bool:
106
+ """Run the authority check an allow record names. Returns True when the reason was handled."""
107
+ reason = pred.get("reason")
108
+ if reason not in CHECKS:
109
+ return False
110
+ evidence = pred.get("authority")
111
+ if not isinstance(evidence, Mapping) or evidence.get("kind") != reason:
112
+ problems.append(f"{where}:{reason}_allow_without_authority_evidence")
113
+ return True
114
+ if trust is None:
115
+ problems.append(f"{where}:{reason}_allow_but_no_trust_pinned")
116
+ return True
117
+ CHECKS[reason](pred, evidence, trust, str(pred.get("at")), problems, where)
118
+ return True
@@ -0,0 +1,68 @@
1
+ """CEL (Common Expression Language) conditions for grants, evaluated by Google's cel-cpp runtime.
2
+
3
+ A CEL condition is a boolean expression over a fixed set of variables. It holds only when the
4
+ expression evaluates to exactly ``true``; an error, a non-boolean result or a compile failure is
5
+ ``false``, so a malformed or surprising condition refuses rather than admits.
6
+
7
+ JSON values bind to CEL by one rule every verifier shares (the TypeScript verifier runs the same
8
+ rule over the same vectors): a number whose value is an integer in the signed 64-bit range binds as
9
+ ``int``, any other number as ``double``; strings, booleans, null, arrays and objects bind as
10
+ ``string``, ``bool``, ``null``, ``list`` and ``map``. RFC 8785 serialises ``1.0`` and ``1`` to the
11
+ same bytes, so a verifier that reads the canonical bytes cannot tell them apart, and neither may we.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from functools import lru_cache
17
+ from typing import Any
18
+
19
+ from cel_expr_python import cel
20
+
21
+ #: The variables a condition may name: ``value`` (one argument, for an argument constraint),
22
+ #: ``args`` (every argument of the call), ``tool`` (the tool name) and ``ctx`` (the call context the
23
+ #: permit names: workflow, run, call, agent).
24
+ VARIABLES = ("value", "args", "tool", "ctx")
25
+ INT64 = 2**63
26
+
27
+
28
+ def to_cel(value: Any) -> Any:
29
+ """The CEL binding of a JSON value, by the shared rule in the module docstring."""
30
+ if isinstance(value, bool) or value is None or isinstance(value, str):
31
+ return value
32
+ if isinstance(value, int):
33
+ return value if -INT64 <= value < INT64 else float(value)
34
+ if isinstance(value, float):
35
+ return int(value) if value.is_integer() and -INT64 <= value < INT64 else value
36
+ if isinstance(value, list):
37
+ return [to_cel(v) for v in value]
38
+ if isinstance(value, dict):
39
+ return {str(k): to_cel(v) for k, v in value.items()}
40
+ raise TypeError(f"not a JSON value: {type(value).__name__}")
41
+
42
+
43
+ @lru_cache(maxsize=1)
44
+ def _env() -> Any:
45
+ return cel.NewEnv(variables={name: cel.Type.DYN for name in VARIABLES})
46
+
47
+
48
+ @lru_cache(maxsize=4096)
49
+ def compile_expr(expr: str) -> Any:
50
+ """The compiled program; ValueError when ``expr`` does not compile or does not name only the
51
+ shared variables."""
52
+ if not isinstance(expr, str) or not expr.strip():
53
+ raise ValueError("cel_expression_empty")
54
+ try:
55
+ return _env().compile(expr)
56
+ except Exception as exc:
57
+ raise ValueError(f"cel_compile_failed:{exc}") from exc
58
+
59
+
60
+ def holds(expr: str, bindings: dict[str, Any]) -> bool:
61
+ """True only when ``expr`` evaluates to exactly ``true`` under ``bindings``."""
62
+ try:
63
+ program = compile_expr(expr)
64
+ data = {name: to_cel(bindings.get(name)) for name in VARIABLES}
65
+ result = program.eval(data=data).value()
66
+ except Exception: # noqa: BLE001 - any evaluation error refuses
67
+ return False
68
+ return result is True