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 +19 -0
- flux_spec/_paths.py +46 -0
- flux_spec/bundle.py +406 -0
- flux_spec/data/schema/flux-enforcement-0.5.0.json +121 -0
- flux_spec/data/schema/flux-manifest-0.5.0.json +153 -0
- flux_spec/data/schema/flux-schema-0.2.0.json +465 -0
- flux_spec/data/schema/flux-schema-0.3.0.json +876 -0
- flux_spec/data/schema/flux-schema-0.4.0.json +1601 -0
- flux_spec/data/schema/flux-schema-0.4.1.json +1668 -0
- flux_spec/data/schema/flux-schema-0.5.0.json +1669 -0
- flux_spec/data/schema/flux-schema-latest.json +1669 -0
- flux_spec/data/schema/flux-ui-hints-0.4.0.json +795 -0
- flux_spec/data/schema/flux-ui-hints-0.4.1.json +852 -0
- flux_spec/data/schema/flux-ui-hints-0.5.0.json +852 -0
- flux_spec/data/vectors/enforcement-vectors.json +935 -0
- flux_spec/data/vendor/fluid/fluid-schema-0.7.3.json +5234 -0
- flux_spec/data/vendor/fluid/fluid-schema-0.7.4.json +5437 -0
- flux_spec/data/vendor/fluid/fluid-schema-0.7.5.json +5630 -0
- flux_spec/enforce.py +315 -0
- flux_spec/validate.py +535 -0
- flux_spec-0.5.0.dist-info/METADATA +202 -0
- flux_spec-0.5.0.dist-info/RECORD +26 -0
- flux_spec-0.5.0.dist-info/WHEEL +5 -0
- flux_spec-0.5.0.dist-info/licenses/LICENSE +202 -0
- flux_spec-0.5.0.dist-info/licenses/NOTICE +2 -0
- flux_spec-0.5.0.dist-info/top_level.txt +1 -0
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
|
+
}
|