flux-spec 0.5.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.
flux_spec/__init__.py ADDED
@@ -0,0 +1,19 @@
1
+ """flux_spec — the FLUX reference validator, RFC-04 enforcement gate, and
2
+ RFC-09 evidence bundler, as an installable package.
3
+
4
+ from flux_spec.validate import Bundle
5
+ from flux_spec.enforce import decide, run_vectors
6
+ from flux_spec.bundle import pack, verify
7
+
8
+ `scripts/validate.py`, `scripts/enforce.py` and `scripts/bundle.py` at the
9
+ repo root remain the documented CLI entry points — they are thin shims onto
10
+ this package, so command-line behaviour is unchanged.
11
+ """
12
+
13
+ __version__ = "0.5.0"
14
+
15
+ # The FLUX schema version this package's vendored/packaged data matches
16
+ # (schema/flux-schema-<SCHEMA_VERSION>.json, i.e. the current "latest").
17
+ SCHEMA_VERSION = "0.5.0"
18
+
19
+ __all__ = ["__version__", "SCHEMA_VERSION"]
flux_spec/_paths.py ADDED
@@ -0,0 +1,46 @@
1
+ """Resource path resolution for flux_spec.
2
+
3
+ Two ways to run this package, one set of bytes:
4
+
5
+ * **Source checkout** — `flux_spec/` sits at the repo root next to `schema/`,
6
+ `vendor/fluid/` and `tests/`. Those are canonical: a contributor edits them
7
+ directly, and CI validates them in place.
8
+ * **Installed distribution** (`pip install flux-spec` or `pip install .`) —
9
+ there is no `schema/` next to the installed package, only the committed
10
+ copies under `flux_spec/data/` (kept in sync with the canonical files by
11
+ `scripts/sync-package-data.py`, gated in CI by a `git diff --exit-code`).
12
+ Those are read back via `importlib.resources` rather than a hardcoded
13
+ site-packages path.
14
+
15
+ Detection is a single filesystem check: does `schema/` exist next to this
16
+ package's parent directory?
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import importlib.resources
22
+ from pathlib import Path
23
+
24
+ _PACKAGE_DIR = Path(__file__).resolve().parent
25
+ REPO = _PACKAGE_DIR.parent
26
+ _SOURCE_CHECKOUT = (REPO / "schema").is_dir()
27
+
28
+
29
+ def _packaged(*parts: str) -> Path:
30
+ return Path(importlib.resources.files("flux_spec").joinpath("data", *parts))
31
+
32
+
33
+ def schema_dir() -> Path:
34
+ return (REPO / "schema") if _SOURCE_CHECKOUT else _packaged("schema")
35
+
36
+
37
+ def vendor_fluid_dir() -> Path:
38
+ return (REPO / "vendor" / "fluid") if _SOURCE_CHECKOUT else _packaged("vendor", "fluid")
39
+
40
+
41
+ def enforcement_vectors_path() -> Path:
42
+ return (
43
+ (REPO / "tests" / "enforcement-vectors.json")
44
+ if _SOURCE_CHECKOUT
45
+ else _packaged("vectors", "enforcement-vectors.json")
46
+ )
flux_spec/bundle.py ADDED
@@ -0,0 +1,406 @@
1
+ #!/usr/bin/env python3
2
+ """FLUX evidence bundles (RFC-09).
3
+
4
+ Turns a validated bundle directory into a portable, verifiable artifact:
5
+
6
+ python3 scripts/bundle.py pack examples/telco-payment-recovery -o dist/
7
+ python3 scripts/bundle.py verify dist/telco-payment-recovery.flux.tgz
8
+
9
+ `pack` validates the bundle offline, writes `flux-manifest.json` (per-file
10
+ sha256, an RFC 6962 Merkle root, and an attestation of what the toolchain
11
+ could prove), emits a **deterministic** gzip archive, and writes an in-toto
12
+ Statement v1 for supply-chain tooling.
13
+
14
+ Determinism follows the reproducible-builds.org recipe: entries sorted by
15
+ name, mtime zeroed in both the tar entries and the gzip header, ownership
16
+ normalised to 0/0 with empty names, fixed mode, GNU format (PAX extended
17
+ headers can smuggle atime/ctime). Same inputs, same bytes — so two parties
18
+ can compare bundles by digest alone.
19
+
20
+ `verify` re-derives every digest and the Merkle root, re-validates the
21
+ documents, and checks the attestation against reality. It needs nothing from
22
+ the author: no engine, no network, no trust in the packer.
23
+
24
+ Signing is deliberately transport-agnostic and detached: sign the manifest
25
+ bytes with whatever your organisation already uses —
26
+
27
+ ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n flux flux-manifest.json
28
+ cosign sign-blob --key cosign.key flux-manifest.json
29
+ openssl dgst -sha256 -sign key.pem -out flux-manifest.sig flux-manifest.json
30
+
31
+ — and ship the signature alongside. Because the manifest commits to the
32
+ Merkle root, a signature over the manifest covers every byte of the bundle.
33
+
34
+ Profiles: an offline bundler may attest `core` (validator green) or
35
+ `enterprise` (validator green plus a Playback scorecard). It never attests
36
+ `runtime` — Level 3 requires a live engine, so claiming it from a packer
37
+ would be a lie.
38
+ """
39
+
40
+ from __future__ import annotations
41
+
42
+ import argparse
43
+ import gzip
44
+ import hashlib
45
+ import io
46
+ import json
47
+ import shutil
48
+ import sys
49
+ import tarfile
50
+ import tempfile
51
+ from pathlib import Path
52
+
53
+ from .validate import Bundle, load_yaml_docs
54
+ from ._paths import REPO, schema_dir
55
+
56
+ from jsonschema import Draft202012Validator, FormatChecker
57
+ from jsonschema.exceptions import ValidationError
58
+
59
+
60
+ class _Rejected(Exception):
61
+ """Internal: stop verifying, the problem list already says why."""
62
+
63
+ SCHEMA_PATH = schema_dir() / "flux-schema-latest.json"
64
+ MANIFEST_SCHEMA_PATH = schema_dir() / "flux-manifest-0.5.0.json"
65
+ MANIFEST_NAME = "flux-manifest.json"
66
+ STATEMENT_SUFFIX = ".attestation.json"
67
+ PREDICATE_TYPE = "https://agenticstiger.github.io/flux/attestation/v1"
68
+ GENERATOR = "flux bundle 0.5.0"
69
+
70
+
71
+ def sha256_file(path: Path) -> str:
72
+ return hashlib.sha256(path.read_bytes()).hexdigest()
73
+
74
+
75
+ def merkle_root(files: dict[str, str]) -> str:
76
+ """Root over sorted (path, digest) pairs.
77
+
78
+ Domain separation follows RFC 6962 (Certificate Transparency): leaves are
79
+ hashed with a 0x00 prefix and interior nodes with 0x01, so an interior
80
+ hash can never be replayed as a leaf (the Merkle second-preimage attack).
81
+ An odd node is promoted unchanged.
82
+
83
+ One deliberate divergence from RFC 6962: the leaf commits to
84
+ `path\\0digest`, not to the file bytes alone. A manifest must bind *which*
85
+ file has which digest — without the path in the leaf, swapping the
86
+ contents of two manifested files would leave the root unchanged.
87
+
88
+ Paths are sorted by Unicode code point (Python's default), which is
89
+ locale-independent — unlike shell `sort`, a known reproducibility trap.
90
+ """
91
+ LEAF, NODE = b"\x00", b"\x01"
92
+ level = [
93
+ hashlib.sha256(LEAF + path.encode() + b"\x00" + bytes.fromhex(digest.split(":", 1)[1])).digest()
94
+ for path, digest in sorted(files.items())
95
+ ]
96
+ if not level:
97
+ return "sha256:" + hashlib.sha256(LEAF).hexdigest()
98
+ while len(level) > 1:
99
+ level = [
100
+ hashlib.sha256(NODE + level[i] + level[i + 1]).digest() if i + 1 < len(level) else level[i]
101
+ for i in range(0, len(level), 2)
102
+ ]
103
+ return "sha256:" + level[0].hex()
104
+
105
+
106
+ def intoto_statement(archive: Path, manifest: dict) -> dict:
107
+ """The attestation as an in-toto Statement v1 (in-toto.io/Statement/v1).
108
+
109
+ The manifest is the bundle's *internal* integrity structure; this is the
110
+ *interop* artifact. Shaping it as an in-toto Statement means existing
111
+ supply-chain tooling — cosign, in-toto-verify, anything that speaks DSSE —
112
+ can carry, sign and verify FLUX evidence without knowing what FLUX is:
113
+
114
+ cosign attest-blob --predicate flux-attestation.json \\
115
+ --type https://agenticstiger.github.io/flux/attestation/v1 <archive>
116
+
117
+ Note in-toto digests are bare hex keyed by algorithm, not the `sha256:`
118
+ prefixed form used inside the FLUX manifest.
119
+ """
120
+ return {
121
+ "_type": "https://in-toto.io/Statement/v1",
122
+ "subject": [{"name": archive.name, "digest": {"sha256": sha256_file(archive)}}],
123
+ "predicateType": PREDICATE_TYPE,
124
+ "predicate": {
125
+ "schemaId": manifest["schemaId"],
126
+ "fluxVersions": manifest["fluxVersions"],
127
+ "merkleRoot": manifest["merkleRoot"],
128
+ "fileCount": len(manifest["files"]),
129
+ **manifest["attestation"],
130
+ },
131
+ }
132
+
133
+
134
+ def bundle_files(directory: Path, skip_signatures: bool = True) -> dict[str, str]:
135
+ """Digest every file in the bundle.
136
+
137
+ The manifest is always excluded — it cannot contain its own digest.
138
+ Detached signatures are excluded while *packing* (they belong beside the
139
+ archive, not inside it), but never while *verifying*: an unmanifested
140
+ file must be reported no matter what it is called, or `evil.sig` becomes
141
+ a place to smuggle content past the digest check.
142
+ """
143
+ out = {}
144
+ for path in sorted(p for p in directory.rglob("*") if p.is_file()):
145
+ rel = path.relative_to(directory).as_posix()
146
+ if rel == MANIFEST_NAME or (skip_signatures and rel.endswith(".sig")):
147
+ continue
148
+ out[rel] = "sha256:" + sha256_file(path)
149
+ return out
150
+
151
+
152
+ def collect_attestation(directory: Path, validator) -> tuple[dict, list[str]]:
153
+ """Validate the bundle and describe what can honestly be attested."""
154
+ b = Bundle(directory, validator)
155
+ errors = b.run()
156
+ if errors:
157
+ return {}, errors
158
+
159
+ scorecards, seam, versions = [], [], set()
160
+ for doc_id, doc in b.flux_docs.items():
161
+ versions.add(doc.get("fluxVersion"))
162
+ spec = doc.get("spec", {})
163
+ if doc.get("kind") == "Playback" and isinstance(spec.get("scorecard"), dict):
164
+ sc = spec["scorecard"]
165
+ scorecards.append({"playbackId": doc_id, "grade": sc["grade"], "credibility": sc["credibility"]})
166
+ if doc.get("kind") == "Simulation":
167
+ for emit in spec.get("emits", []):
168
+ entry = {
169
+ "simulationId": doc_id,
170
+ "productRef": emit["productRef"],
171
+ "exposeId": emit["exposeId"],
172
+ "fluidVersion": emit["fluidVersion"],
173
+ }
174
+ digest = (emit.get("provenance") or {}).get("contractDigest")
175
+ if digest:
176
+ entry["contractDigest"] = digest
177
+ seam.append(entry)
178
+
179
+ attestation = {
180
+ "profile": "enterprise" if scorecards else "core",
181
+ "validator": {"status": "green", "documents": len(b.flux_docs)},
182
+ }
183
+ if scorecards:
184
+ attestation["scorecards"] = sorted(scorecards, key=lambda s: s["playbackId"])
185
+ if seam:
186
+ attestation["seam"] = seam
187
+ return {"attestation": attestation, "fluxVersions": sorted(v for v in versions if v)}, []
188
+
189
+
190
+ def build_manifest(directory: Path, validator) -> tuple[dict, list[str]]:
191
+ extra, errors = collect_attestation(directory, validator)
192
+ if errors:
193
+ return {}, errors
194
+ files = bundle_files(directory)
195
+ schema_id = json.loads(SCHEMA_PATH.read_text())["$id"]
196
+ manifest = {
197
+ "manifestVersion": 1,
198
+ "generator": GENERATOR,
199
+ "schemaId": schema_id,
200
+ "fluxVersions": extra["fluxVersions"],
201
+ "files": files,
202
+ "merkleRoot": merkle_root(files),
203
+ "attestation": extra["attestation"],
204
+ }
205
+ return manifest, []
206
+
207
+
208
+ def _deterministic_info(name: str, size: int) -> tarfile.TarInfo:
209
+ info = tarfile.TarInfo(name)
210
+ info.size = size
211
+ info.mtime = 0 # zeroed: same inputs -> same bytes
212
+ info.mode = 0o644
213
+ info.uid = info.gid = 0
214
+ info.uname = info.gname = ""
215
+ return info
216
+
217
+
218
+ def pack(directory: Path, out_dir: Path, validator) -> int:
219
+ directory = directory.resolve() # `pack .` must not become a nameless archive
220
+ if not directory.name:
221
+ print(f"[FAIL] {directory}: cannot determine a bundle name")
222
+ return 1
223
+ manifest, errors = build_manifest(directory, validator)
224
+ if errors:
225
+ print(f"[FAIL] {directory}: bundle does not validate — refusing to pack")
226
+ for e in errors[:10]:
227
+ print(f" {e}")
228
+ return 1
229
+ Draft202012Validator(json.loads(MANIFEST_SCHEMA_PATH.read_text())).validate(manifest)
230
+
231
+ (directory / MANIFEST_NAME).write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n")
232
+ out_dir.mkdir(parents=True, exist_ok=True)
233
+ archive = out_dir / f"{directory.name}.flux.tgz"
234
+
235
+ payload = dict(manifest["files"])
236
+ payload[MANIFEST_NAME] = "sha256:" + sha256_file(directory / MANIFEST_NAME)
237
+ raw = io.BytesIO()
238
+ # GNU format, not PAX: reproducible-builds.org warns PAX extended headers
239
+ # can carry atime/ctime (and PIDs under POSIXLY_CORRECT).
240
+ with tarfile.open(fileobj=raw, mode="w", format=tarfile.GNU_FORMAT) as tar:
241
+ for rel in sorted(payload):
242
+ data = (directory / rel).read_bytes()
243
+ tar.addfile(_deterministic_info(f"{directory.name}/{rel}", len(data)), io.BytesIO(data))
244
+ # gzip separately with mtime=0 — the gzip header carries its own timestamp,
245
+ # which would otherwise make every repack a different file.
246
+ with open(archive, "wb") as fh:
247
+ with gzip.GzipFile(filename="", mode="wb", compresslevel=9, fileobj=fh, mtime=0) as gz:
248
+ gz.write(raw.getvalue())
249
+
250
+ statement = intoto_statement(archive, manifest)
251
+ statement_path = out_dir / f"{directory.name}{STATEMENT_SUFFIX}"
252
+ statement_path.write_text(json.dumps(statement, indent=2, sort_keys=True) + "\n")
253
+
254
+ print(f"[ok] packed {archive}")
255
+ print(f" profile={manifest['attestation']['profile']} "
256
+ f"documents={manifest['attestation']['validator']['documents']} "
257
+ f"files={len(manifest['files'])}")
258
+ print(f" merkleRoot={manifest['merkleRoot']}")
259
+ print(f" archive sha256:{sha256_file(archive)}")
260
+ print(f" in-toto statement: {statement_path}")
261
+ print(f" sign it: ssh-keygen -Y sign -f <key> -n flux {directory / MANIFEST_NAME}")
262
+ print(f" or: cosign attest-blob --predicate {statement_path} --type {PREDICATE_TYPE} {archive}")
263
+ return 0
264
+
265
+
266
+ MAX_BUNDLE_BYTES = 256 * 1024 * 1024 # declared, uncompressed, across all members
267
+ MAX_MEMBERS = 10_000
268
+ COPY_CHUNK = 1 << 20
269
+
270
+
271
+ def _extract_safely(tar: tarfile.TarFile, root: Path, problems: list[str]) -> Path | None:
272
+ """Materialise a verified-safe subset of the archive under `root`.
273
+
274
+ Everything hostile is rejected *before* anything is written: attacker-declared
275
+ sizes are budgeted first (gzip compresses zeros ~1000:1, so a 500 KB archive
276
+ can otherwise claim gigabytes), only regular files are extracted, and every
277
+ member must live under one shared top-level directory — a member outside it
278
+ would be extracted but never digested, which is exactly how undeclared
279
+ content sneaks past a manifest.
280
+ """
281
+ members = tar.getmembers()
282
+ if len(members) > MAX_MEMBERS:
283
+ problems.append(f"archive declares {len(members)} members, above the {MAX_MEMBERS} cap")
284
+ return None
285
+ declared = sum(m.size for m in members if m.isfile())
286
+ if declared > MAX_BUNDLE_BYTES:
287
+ problems.append(f"archive declares {declared} uncompressed bytes, above the {MAX_BUNDLE_BYTES} cap")
288
+ return None
289
+
290
+ tops = set()
291
+ for m in members:
292
+ name = Path(m.name)
293
+ if name.is_absolute() or ".." in name.parts or not name.parts:
294
+ problems.append(f"unsafe archive path: {m.name}")
295
+ return None
296
+ tops.add(name.parts[0])
297
+ if len(tops) != 1:
298
+ problems.append(f"expected exactly one bundle directory, found {sorted(tops) or 'none'}")
299
+ return None
300
+
301
+ for m in members:
302
+ if m.isdir():
303
+ continue
304
+ if not m.isfile():
305
+ problems.append(f"unsupported archive entry ({'symlink' if m.issym() or m.islnk() else 'special'}): {m.name}")
306
+ return None
307
+ if len(Path(m.name).parts) < 2:
308
+ problems.append(f"entry outside the bundle directory: {m.name}")
309
+ return None
310
+ target = root / m.name
311
+ if target.exists():
312
+ problems.append(f"duplicate archive entry: {m.name}")
313
+ return None
314
+ target.parent.mkdir(parents=True, exist_ok=True)
315
+ source = tar.extractfile(m)
316
+ if source is None:
317
+ problems.append(f"unreadable archive entry: {m.name}")
318
+ return None
319
+ with open(target, "wb") as fh:
320
+ shutil.copyfileobj(source, fh, COPY_CHUNK)
321
+ return root / tops.pop()
322
+
323
+
324
+ def verify(archive: Path, validator) -> int:
325
+ """Verify an archive offline. Always reports; never raises."""
326
+ problems: list[str] = []
327
+ manifest = {}
328
+ try:
329
+ with tempfile.TemporaryDirectory() as tmp:
330
+ root = Path(tmp)
331
+ with tarfile.open(archive, "r:gz") as tar:
332
+ directory = _extract_safely(tar, root, problems)
333
+ if directory is None:
334
+ raise _Rejected()
335
+
336
+ manifest_path = directory / MANIFEST_NAME
337
+ if not manifest_path.exists():
338
+ problems.append(f"no {MANIFEST_NAME}")
339
+ raise _Rejected()
340
+ manifest = json.loads(manifest_path.read_text())
341
+ Draft202012Validator(json.loads(MANIFEST_SCHEMA_PATH.read_text())).validate(manifest)
342
+
343
+ actual = bundle_files(directory, skip_signatures=False)
344
+ for rel, digest in manifest["files"].items():
345
+ if rel not in actual:
346
+ problems.append(f"missing file: {rel}")
347
+ elif actual[rel] != digest:
348
+ problems.append(f"digest mismatch: {rel}")
349
+ for rel in actual:
350
+ if rel not in manifest["files"]:
351
+ problems.append(f"unmanifested file: {rel}")
352
+ if merkle_root(manifest["files"]) != manifest["merkleRoot"]:
353
+ problems.append("merkleRoot does not match the manifest file list")
354
+
355
+ # Everything the manifest asserts is re-derived, never trusted.
356
+ expected_schema_id = json.loads(SCHEMA_PATH.read_text())["$id"]
357
+ if manifest["schemaId"] != expected_schema_id:
358
+ problems.append(f"schemaId {manifest['schemaId']} is not this toolchain's schema ({expected_schema_id})")
359
+ rebuilt, errors = collect_attestation(directory, validator)
360
+ if errors:
361
+ problems.append(f"bundle no longer validates ({len(errors)} errors, first: {errors[0]})")
362
+ else:
363
+ if rebuilt["attestation"] != manifest["attestation"]:
364
+ problems.append("attestation does not match a fresh validation of the bundle")
365
+ if rebuilt["fluxVersions"] != manifest["fluxVersions"]:
366
+ problems.append(f"fluxVersions {manifest['fluxVersions']} does not match the documents ({rebuilt['fluxVersions']})")
367
+ except _Rejected:
368
+ pass
369
+ except tarfile.ReadError as exc:
370
+ problems.append(f"not a readable gzip archive: {exc}")
371
+ except json.JSONDecodeError as exc:
372
+ problems.append(f"{MANIFEST_NAME} is not valid JSON: {exc}")
373
+ except ValidationError as exc:
374
+ problems.append(f"{MANIFEST_NAME} violates the manifest schema: {exc.message}")
375
+ except OSError as exc:
376
+ problems.append(f"cannot read archive: {exc}")
377
+
378
+ if problems:
379
+ print(f"[FAIL] {archive}")
380
+ for p in problems[:10]:
381
+ print(f" {p}")
382
+ return 1
383
+ print(f"[ok] {archive} — {len(manifest['files'])} files, merkle root verified, "
384
+ f"attestation reproduced (profile={manifest['attestation']['profile']})")
385
+ print(f" verify the signature separately, e.g. ssh-keygen -Y verify ... < {MANIFEST_NAME}")
386
+ return 0
387
+
388
+
389
+ def main(argv=None) -> int:
390
+ ap = argparse.ArgumentParser(description="FLUX evidence bundles (RFC-09)")
391
+ sub = ap.add_subparsers(dest="cmd", required=True)
392
+ p = sub.add_parser("pack", help="validate, manifest and archive a bundle")
393
+ p.add_argument("directory", type=Path)
394
+ p.add_argument("-o", "--out", type=Path, default=REPO / "dist")
395
+ v = sub.add_parser("verify", help="verify an archive offline")
396
+ v.add_argument("archive", type=Path)
397
+ args = ap.parse_args(argv)
398
+
399
+ validator = Draft202012Validator(json.loads(SCHEMA_PATH.read_text()), format_checker=FormatChecker())
400
+ if args.cmd == "pack":
401
+ return pack(args.directory, args.out, validator)
402
+ return verify(args.archive, validator)
403
+
404
+
405
+ if __name__ == "__main__":
406
+ raise SystemExit(main())
@@ -0,0 +1,121 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://agenticstiger.github.io/flux/schema/flux-enforcement-0.5.0.json",
4
+ "title": "FLUX Enforcement Decision Contract",
5
+ "description": "RFC-04: the normative runtime contract every conformant policy gate implements. Input: an agentPolicy (from any FLUX document), a request, and optionally the skill binding the call is made through. Output: a decision. Checks run in a fixed, normative order \u2014 INVALID_POLICY, INVALID_REQUEST, MODEL_NOT_ALLOWED, USE_CASE_DENIED, USE_CASE_NOT_ALLOWED, PURPOSE_REQUIRED, TOKEN_BUDGET_EXCEEDED \u2014 and the first failure wins, so identical inputs yield identical decisions on every implementation. NUMBERS: integers follow JSON semantics, not a host language's types \u2014 200000.0 is the integer 200000, and booleans are never integers. Values above 2^53-1 (9007199254740991) are rejected, because they cannot cross a JSON boundary or be canonicalised per RFC 8785 without silent precision loss. STRINGS: model and useCase identifiers are NFC-normalised and surrounding whitespace stripped before comparison; matching is case-sensitive. POLICIES: a gate MUST reject an off-spec policy with INVALID_POLICY rather than enforce a degraded reading of it \u2014 a missing or non-integer tokenBudget is never an unlimited budget. SKILLS: when a call is made through a skill, the effective budget is min(skill.tokenBudget, policy.tokenBudget) \u2014 a skill narrows and can never widen. The decision reports it as effectiveBudget, and policyDigest always digests the DOCUMENT's policy so an auditor can join a decision back to the document that authorised it. DIGESTS: policyDigest is sha256 over the RFC 8785 (JCS) canonicalisation of the policy, so gates in different languages agree byte-for-byte. Conformance is demonstrated by passing the published test vectors (tests/enforcement-vectors.json), which pin allow, reasonCode and policyDigest.",
6
+ "$defs": {
7
+ "request": {
8
+ "type": "object",
9
+ "required": [
10
+ "model",
11
+ "useCase",
12
+ "tokens"
13
+ ],
14
+ "additionalProperties": false,
15
+ "properties": {
16
+ "model": {
17
+ "type": "string",
18
+ "minLength": 1,
19
+ "description": "Model identifier the caller wants to invoke."
20
+ },
21
+ "useCase": {
22
+ "type": "string",
23
+ "minLength": 1,
24
+ "description": "Declared use case of the call."
25
+ },
26
+ "purpose": {
27
+ "type": "string",
28
+ "minLength": 1,
29
+ "description": "Free-text purpose statement. Required by policies with purposeLimitation (the default)."
30
+ },
31
+ "tokens": {
32
+ "type": "integer",
33
+ "minimum": 0,
34
+ "description": "Requested token budget for the call. An integer in the JSON sense (200000.0 is 200000; true is not 1)."
35
+ }
36
+ }
37
+ },
38
+ "decision": {
39
+ "type": "object",
40
+ "required": [
41
+ "allow",
42
+ "reasonCode",
43
+ "reason",
44
+ "policyDigest",
45
+ "request"
46
+ ],
47
+ "additionalProperties": false,
48
+ "properties": {
49
+ "allow": {
50
+ "type": "boolean"
51
+ },
52
+ "reasonCode": {
53
+ "type": "string",
54
+ "enum": [
55
+ "ALLOWED",
56
+ "INVALID_POLICY",
57
+ "INVALID_REQUEST",
58
+ "MODEL_NOT_ALLOWED",
59
+ "USE_CASE_DENIED",
60
+ "USE_CASE_NOT_ALLOWED",
61
+ "PURPOSE_REQUIRED",
62
+ "TOKEN_BUDGET_EXCEEDED"
63
+ ],
64
+ "description": "Machine-readable outcome. Deny codes follow the normative check order; the first failing check wins."
65
+ },
66
+ "reason": {
67
+ "type": "string",
68
+ "minLength": 1,
69
+ "description": "Human-readable explanation."
70
+ },
71
+ "policyDigest": {
72
+ "type": "string",
73
+ "pattern": "^sha256:[a-f0-9]{64}$",
74
+ "description": "sha256 over the RFC 8785 (JCS) canonicalisation of the DOCUMENT's agentPolicy \u2014 the audit anchor binding decision to policy. Never a synthesised or skill-narrowed policy."
75
+ },
76
+ "request": {
77
+ "type": "object",
78
+ "description": "Echo of the evaluated request. Deliberately unconstrained: on the INVALID_REQUEST path the request is malformed by definition, and the decision must still be able to carry it. The decision plus this echo is the audit record."
79
+ },
80
+ "effectiveBudget": {
81
+ "type": "integer",
82
+ "minimum": 0,
83
+ "description": "The token budget actually applied \u2014 min(skill, policy) when a skill narrows it. Present whenever the policy was well-formed."
84
+ },
85
+ "skillRef": {
86
+ "type": "string",
87
+ "minLength": 1,
88
+ "description": "Name of the skill binding the call was made through, when there was one. With effectiveBudget this makes the narrowing auditable without mutating the policy."
89
+ }
90
+ },
91
+ "allOf": [
92
+ {
93
+ "if": {
94
+ "properties": {
95
+ "reasonCode": {
96
+ "const": "ALLOWED"
97
+ }
98
+ },
99
+ "required": [
100
+ "reasonCode"
101
+ ]
102
+ },
103
+ "then": {
104
+ "properties": {
105
+ "allow": {
106
+ "const": true
107
+ }
108
+ }
109
+ },
110
+ "else": {
111
+ "properties": {
112
+ "allow": {
113
+ "const": false
114
+ }
115
+ }
116
+ }
117
+ }
118
+ ]
119
+ }
120
+ }
121
+ }