git-finalizer 2.0.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.
- git_finalizer/__init__.py +8 -0
- git_finalizer/delivery/__init__.py +3 -0
- git_finalizer/delivery/cli.py +166 -0
- git_finalizer/delivery/content_scan.py +524 -0
- git_finalizer/delivery/engine.py +2364 -0
- git_finalizer/delivery/integration_publish.py +547 -0
- git_finalizer/delivery/parser.py +552 -0
- git_finalizer/delivery/patch_check.py +165 -0
- git_finalizer/delivery/policy.py +311 -0
- git_finalizer/delivery/repo_bootstrap.py +588 -0
- git_finalizer/delivery/repo_state.py +612 -0
- git_finalizer/delivery/retirement_plan.py +740 -0
- git_finalizer/delivery/runtime.py +553 -0
- git_finalizer/delivery/scanners.py +329 -0
- git_finalizer/delivery/snapshot_verify.py +425 -0
- git_finalizer/delivery/source_review.py +374 -0
- git_finalizer/delivery/trailers.py +164 -0
- git_finalizer/delivery/validation.py +1095 -0
- git_finalizer/errors.py +105 -0
- git_finalizer/git_io.py +281 -0
- git_finalizer/json_io.py +55 -0
- git_finalizer/toolchain/__init__.py +3 -0
- git_finalizer/toolchain/tool_skill_sync.py +3044 -0
- git_finalizer/toolchain/tool_temp_dir.py +1057 -0
- git_finalizer/toolchain/workflow_health.py +504 -0
- git_finalizer-2.0.0.dist-info/METADATA +383 -0
- git_finalizer-2.0.0.dist-info/RECORD +30 -0
- git_finalizer-2.0.0.dist-info/WHEEL +4 -0
- git_finalizer-2.0.0.dist-info/entry_points.txt +5 -0
- git_finalizer-2.0.0.dist-info/licenses/LICENSE +202 -0
|
@@ -0,0 +1,374 @@
|
|
|
1
|
+
"""Reviewed-sensitive-source validator for Git Finalizer."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import ast
|
|
6
|
+
from datetime import UTC, datetime, timedelta
|
|
7
|
+
import os
|
|
8
|
+
from pathlib import Path, PurePosixPath
|
|
9
|
+
import re
|
|
10
|
+
import stat
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
from git_finalizer.delivery.content_scan import MAX_SCAN_BYTES, scan
|
|
14
|
+
from git_finalizer.errors import ErrorCode, FinalizerError
|
|
15
|
+
from git_finalizer.git_io import FULL_OID_RE, clean_git_env, read_baseline_blob, run_git
|
|
16
|
+
from git_finalizer.json_io import loads_unique, sha256_bytes
|
|
17
|
+
|
|
18
|
+
MAX_REVIEW_BYTES = 64 * 1024
|
|
19
|
+
MAX_REVIEW_ITEMS = 64
|
|
20
|
+
MAX_VALIDITY = timedelta(days=7)
|
|
21
|
+
_ENV_RE = re.compile(r"(?:^|/)\.env(?:$|[._-])", re.IGNORECASE)
|
|
22
|
+
_MARKER_RE = re.compile(r"(?:^|[/._ -])(?:credentials?|secrets?|tokens?)(?:[/._ -]|$)", re.IGNORECASE)
|
|
23
|
+
_KEY_RE = re.compile(r"(?:^|[/._ -])(?:private|ssh)[._ -]?key(?:[/._ -]|$)", re.IGNORECASE)
|
|
24
|
+
_SSH_NAME_RE = re.compile(r"(?:^|/)(?:id_rsa|id_dsa|id_ecdsa|id_ed25519)(?:\.pub)?$", re.IGNORECASE)
|
|
25
|
+
_KEY_EXT_RE = re.compile(r"\.(?:pem|key|p12|pfx)$", re.IGNORECASE)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class ReviewError(FinalizerError):
|
|
29
|
+
"""Static, non-leaking sensitive-source review rejection."""
|
|
30
|
+
|
|
31
|
+
def __init__(self, review_code: str, static_reason: str) -> None:
|
|
32
|
+
self.review_code = review_code
|
|
33
|
+
self.static_reason = static_reason
|
|
34
|
+
super().__init__(
|
|
35
|
+
ErrorCode.SOURCE_REVIEW_BLOCKED,
|
|
36
|
+
f"reviewed-sensitive-source validation blocked ({review_code}): {static_reason}",
|
|
37
|
+
final_phase="local_validation",
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def sensitive_path_reason(path: str) -> str | None:
|
|
42
|
+
"""Classify sensitive path reason matching exact path markers."""
|
|
43
|
+
lower = path.lower()
|
|
44
|
+
if _ENV_RE.search(lower):
|
|
45
|
+
return ".env 路径"
|
|
46
|
+
if _KEY_RE.search(lower) or _SSH_NAME_RE.search(lower) or _KEY_EXT_RE.search(lower):
|
|
47
|
+
return "private key/SSH key 路径标记"
|
|
48
|
+
if _MARKER_RE.search(lower):
|
|
49
|
+
return "credential/secret/token 路径标记"
|
|
50
|
+
return None
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def is_sensitive_path(path: str) -> bool:
|
|
54
|
+
return sensitive_path_reason(path) is not None
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def _is_disallowed_source_path(path: str) -> bool:
|
|
58
|
+
return sensitive_path_reason(path) != "credential/secret/token 路径标记"
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def read_external_regular_bounded(
|
|
62
|
+
path_str: str,
|
|
63
|
+
*,
|
|
64
|
+
repo: Path,
|
|
65
|
+
common_dir: Path,
|
|
66
|
+
label: str,
|
|
67
|
+
) -> tuple[bytes, Path]:
|
|
68
|
+
"""Open and verify an external non-symlink regular file without stat->read TOCTOU.
|
|
69
|
+
|
|
70
|
+
Accepts owner-writable UPG modes like 0664 (`st_mode & 0o002 == 0`) while blocking world-writable (`o+w`).
|
|
71
|
+
"""
|
|
72
|
+
raw_path = Path(path_str)
|
|
73
|
+
if not raw_path.is_absolute():
|
|
74
|
+
raise ReviewError("REVIEW_PATH_NOT_ABSOLUTE", f"{label} path must be absolute")
|
|
75
|
+
resolved_parent = raw_path.parent.resolve()
|
|
76
|
+
resolved = resolved_parent / raw_path.name
|
|
77
|
+
repo_resolved = repo.resolve()
|
|
78
|
+
common_resolved = common_dir.resolve()
|
|
79
|
+
if resolved == repo_resolved or resolved.is_relative_to(repo_resolved):
|
|
80
|
+
raise ReviewError("REVIEW_IN_REPOSITORY", f"{label} must reside outside the repository")
|
|
81
|
+
if resolved == common_resolved or resolved.is_relative_to(common_resolved):
|
|
82
|
+
raise ReviewError("REVIEW_IN_GIT_DIR", f"{label} must reside outside .git")
|
|
83
|
+
|
|
84
|
+
flags = os.O_RDONLY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0)
|
|
85
|
+
try:
|
|
86
|
+
fd = os.open(raw_path, flags)
|
|
87
|
+
except OSError as exc:
|
|
88
|
+
raise ReviewError("REVIEW_FILE_UNREADABLE", f"{label} cannot be opened safely: {exc.strerror or 'os error'}") from exc
|
|
89
|
+
|
|
90
|
+
try:
|
|
91
|
+
info = os.fstat(fd)
|
|
92
|
+
except OSError as exc:
|
|
93
|
+
os.close(fd)
|
|
94
|
+
raise ReviewError("REVIEW_STAT_FAILED", f"{label} metadata unavailable") from exc
|
|
95
|
+
|
|
96
|
+
if not stat.S_ISREG(info.st_mode):
|
|
97
|
+
os.close(fd)
|
|
98
|
+
raise ReviewError("REVIEW_NOT_REGULAR", f"{label} must be a regular file")
|
|
99
|
+
if hasattr(os, "getuid") and info.st_uid != os.getuid():
|
|
100
|
+
os.close(fd)
|
|
101
|
+
raise ReviewError("REVIEW_OWNER_MISMATCH", f"{label} must be owned by the caller")
|
|
102
|
+
if info.st_mode & 0o002:
|
|
103
|
+
os.close(fd)
|
|
104
|
+
raise ReviewError("REVIEW_WORLD_WRITABLE", f"{label} must not be world-writable")
|
|
105
|
+
if info.st_size > MAX_REVIEW_BYTES:
|
|
106
|
+
os.close(fd)
|
|
107
|
+
raise ReviewError("REVIEW_SIZE_EXCEEDED", f"{label} exceeds 64 KiB limit")
|
|
108
|
+
|
|
109
|
+
with os.fdopen(fd, "rb") as stream:
|
|
110
|
+
data = stream.read(MAX_REVIEW_BYTES + 1)
|
|
111
|
+
if len(data) > MAX_REVIEW_BYTES:
|
|
112
|
+
raise ReviewError("REVIEW_SIZE_EXCEEDED", f"{label} exceeds 64 KiB limit")
|
|
113
|
+
return data, resolved
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def _parse_iso_utc(raw: Any, label: str) -> datetime:
|
|
117
|
+
if not isinstance(raw, str) or not raw:
|
|
118
|
+
raise ReviewError("REVIEW_TIMESTAMP_INVALID", f"{label} timestamp missing or invalid")
|
|
119
|
+
try:
|
|
120
|
+
parsed = datetime.fromisoformat(raw)
|
|
121
|
+
except ValueError as exc:
|
|
122
|
+
raise ReviewError("REVIEW_TIMESTAMP_INVALID", f"{label} timestamp invalid") from exc
|
|
123
|
+
if parsed.tzinfo is None:
|
|
124
|
+
raise ReviewError("REVIEW_TIMESTAMP_NAIVE", f"{label} timestamp must include timezone offset")
|
|
125
|
+
return parsed.astimezone(UTC)
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def _validate_source_syntax(path: str, content: bytes, allowed_extensions: tuple[str, ...]) -> None:
|
|
129
|
+
if _is_disallowed_source_path(path):
|
|
130
|
+
raise ReviewError("REVIEW_PATH_FORBIDDEN", "disallowed secret file pattern")
|
|
131
|
+
suffix = PurePosixPath(path).suffix.lower()
|
|
132
|
+
if suffix not in allowed_extensions:
|
|
133
|
+
raise ReviewError("REVIEW_EXTENSION_UNSUPPORTED", f"unsupported extension for reviewed source: {suffix or '(none)'}")
|
|
134
|
+
if len(content) > 1024 * 1024:
|
|
135
|
+
raise ReviewError("REVIEW_SOURCE_TOO_LARGE", "reviewed source exceeds 1 MiB limit")
|
|
136
|
+
try:
|
|
137
|
+
text = content.decode("utf-8", errors="strict")
|
|
138
|
+
except UnicodeDecodeError as exc:
|
|
139
|
+
raise ReviewError("REVIEW_INVALID_UTF8", "reviewed source must be valid UTF-8") from exc
|
|
140
|
+
if "\x00" in text:
|
|
141
|
+
raise ReviewError("REVIEW_INVALID_NUL", "reviewed source must not contain NUL bytes")
|
|
142
|
+
if suffix == ".py":
|
|
143
|
+
try:
|
|
144
|
+
ast.parse(text)
|
|
145
|
+
except SyntaxError as exc:
|
|
146
|
+
raise ReviewError("REVIEW_INVALID_PYTHON", "reviewed Python source contains syntax errors") from exc
|
|
147
|
+
elif suffix == ".json":
|
|
148
|
+
try:
|
|
149
|
+
loads_unique(text)
|
|
150
|
+
except ValueError as exc:
|
|
151
|
+
raise ReviewError("REVIEW_INVALID_JSON", f"reviewed JSON source invalid: {exc}") from exc
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def _git_output(repo: Path, *arguments: str, env: dict[str, str] | None = None) -> str:
|
|
155
|
+
completed = run_git(repo, *arguments, env=clean_git_env(env))
|
|
156
|
+
if completed.returncode != 0:
|
|
157
|
+
raise ReviewError("REVIEW_GIT_COMMAND_FAILED", f"git {arguments[0]} failed")
|
|
158
|
+
return completed.stdout.decode("utf-8", errors="strict").strip()
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def _commit_root(repo: Path, oid: str, env: dict[str, str] | None = None) -> str:
|
|
162
|
+
roots = _git_output(repo, "rev-list", "--max-parents=0", oid, env=env).splitlines()
|
|
163
|
+
if len(roots) != 1 or FULL_OID_RE.fullmatch(roots[0]) is None:
|
|
164
|
+
raise ReviewError("REVIEW_ROOT_AMBIGUOUS", "repository root commit is missing or ambiguous")
|
|
165
|
+
return roots[0]
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def _head_oid(repo: Path, env: dict[str, str] | None = None) -> str:
|
|
169
|
+
completed = run_git(repo, "rev-parse", "--verify", "HEAD", env=clean_git_env(env))
|
|
170
|
+
if completed.returncode != 0:
|
|
171
|
+
raise ReviewError("REVIEW_UNBORN_REPO", "reviewed-sensitive-source requires an existing HEAD commit")
|
|
172
|
+
return completed.stdout.decode("ascii").strip()
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def validate_review_document(
|
|
176
|
+
*,
|
|
177
|
+
review_file: str,
|
|
178
|
+
repo: Path,
|
|
179
|
+
common_dir: Path,
|
|
180
|
+
repository_id: str | None,
|
|
181
|
+
allocation_id: str | None,
|
|
182
|
+
task_key: str | None,
|
|
183
|
+
authority_key: str | None,
|
|
184
|
+
worktree_path: str | None,
|
|
185
|
+
requested_paths: list[str],
|
|
186
|
+
stage: str = "worktree",
|
|
187
|
+
stage_env: dict[str, str] | None = None,
|
|
188
|
+
allowed_extensions: tuple[str, ...] = (".py", ".css", ".json"),
|
|
189
|
+
candidate_blobs: dict[str, bytes] | None = None,
|
|
190
|
+
commit_ref: str | None = None,
|
|
191
|
+
baseline_ref: str | None = "HEAD",
|
|
192
|
+
) -> list[dict[str, Any]]:
|
|
193
|
+
"""Validate an external reviewed-sensitive-source JSON against linkage, scope, expiry, and source bytes."""
|
|
194
|
+
if not all([repository_id, allocation_id, task_key, authority_key]):
|
|
195
|
+
raise FinalizerError(
|
|
196
|
+
ErrorCode.SOURCE_REVIEW_BLOCKED,
|
|
197
|
+
"source review 要求完整 Controller linkage(--repository-id/--allocation-id/--task-key/--authority-key)",
|
|
198
|
+
final_phase="cli",
|
|
199
|
+
)
|
|
200
|
+
raw_review, resolved_review_file = read_external_regular_bounded(
|
|
201
|
+
review_file, repo=repo, common_dir=common_dir, label="review"
|
|
202
|
+
)
|
|
203
|
+
try:
|
|
204
|
+
doc = loads_unique(raw_review)
|
|
205
|
+
except (UnicodeDecodeError, ValueError) as exc:
|
|
206
|
+
raise ReviewError("REVIEW_JSON_INVALID", f"invalid review JSON: {exc}") from exc
|
|
207
|
+
|
|
208
|
+
if not isinstance(doc, dict) or doc.get("schema_version") != 1 or doc.get("kind") != "reviewed-sensitive-source":
|
|
209
|
+
raise ReviewError("REVIEW_SCHEMA_INVALID", "review schema_version or kind mismatch")
|
|
210
|
+
|
|
211
|
+
repo_meta = doc.get("repository")
|
|
212
|
+
alloc_meta = doc.get("allocation")
|
|
213
|
+
if not isinstance(repo_meta, dict) or not isinstance(alloc_meta, dict):
|
|
214
|
+
raise ReviewError("REVIEW_METADATA_MISSING", "repository or allocation metadata missing")
|
|
215
|
+
|
|
216
|
+
expected_common = str(common_dir.resolve())
|
|
217
|
+
if repo_meta.get("common_dir") != expected_common:
|
|
218
|
+
raise ReviewError("REVIEW_COMMON_DIR_MISMATCH", "repository common_dir mismatch")
|
|
219
|
+
head_oid = _head_oid(repo, env=stage_env)
|
|
220
|
+
expected_root = _commit_root(repo, head_oid, env=stage_env)
|
|
221
|
+
if repo_meta.get("root_commit") != expected_root:
|
|
222
|
+
raise ReviewError("REVIEW_ROOT_COMMIT_MISMATCH", "repository root_commit mismatch")
|
|
223
|
+
|
|
224
|
+
expected_wt = str(Path(worktree_path or repo).resolve())
|
|
225
|
+
if (
|
|
226
|
+
alloc_meta.get("repository_id") != repository_id
|
|
227
|
+
or alloc_meta.get("allocation_id") != allocation_id
|
|
228
|
+
or alloc_meta.get("task_key") != task_key
|
|
229
|
+
or alloc_meta.get("authority_key") != authority_key
|
|
230
|
+
or alloc_meta.get("worktree_path") != expected_wt
|
|
231
|
+
):
|
|
232
|
+
raise ReviewError("REVIEW_ALLOCATION_MISMATCH", "Controller allocation linkage mismatch")
|
|
233
|
+
|
|
234
|
+
reviewed_at = _parse_iso_utc(doc.get("reviewed_at"), "reviewed_at")
|
|
235
|
+
expires_at = _parse_iso_utc(doc.get("expires_at"), "expires_at")
|
|
236
|
+
now = datetime.now(UTC)
|
|
237
|
+
if expires_at <= reviewed_at or (expires_at - reviewed_at) > MAX_VALIDITY:
|
|
238
|
+
raise ReviewError("REVIEW_EXPIRY_WINDOW_INVALID", "review expiry window exceeds 7 days or is inverted")
|
|
239
|
+
if now >= expires_at:
|
|
240
|
+
raise ReviewError("REVIEW_EXPIRED", "review has expired")
|
|
241
|
+
|
|
242
|
+
expected_scope = "\n".join(sorted(requested_paths)) + "\n"
|
|
243
|
+
if doc.get("scope_sha256") != sha256_bytes(expected_scope.encode("utf-8")):
|
|
244
|
+
raise ReviewError("REVIEW_SCOPE_MISMATCH", "scope_sha256 does not match requested paths")
|
|
245
|
+
|
|
246
|
+
reviews = doc.get("reviews")
|
|
247
|
+
if not isinstance(reviews, list) or not reviews or len(reviews) > MAX_REVIEW_ITEMS:
|
|
248
|
+
raise ReviewError("REVIEW_LIST_INVALID", "reviews list empty or oversized")
|
|
249
|
+
|
|
250
|
+
seen_paths: set[str] = set()
|
|
251
|
+
receipts: list[dict[str, Any]] = []
|
|
252
|
+
requested_set = set(requested_paths)
|
|
253
|
+
|
|
254
|
+
for item in reviews:
|
|
255
|
+
if not isinstance(item, dict):
|
|
256
|
+
raise ReviewError("REVIEW_ITEM_INVALID", "review entry must be an object")
|
|
257
|
+
path = item.get("path")
|
|
258
|
+
expected_sha = item.get("sha256")
|
|
259
|
+
purpose = item.get("purpose")
|
|
260
|
+
evidence = item.get("evidence")
|
|
261
|
+
if (
|
|
262
|
+
not isinstance(path, str)
|
|
263
|
+
or not path
|
|
264
|
+
or path in seen_paths
|
|
265
|
+
or (bool(requested_set) and path not in requested_set)
|
|
266
|
+
or _is_disallowed_source_path(path)
|
|
267
|
+
or PurePosixPath(path).is_absolute()
|
|
268
|
+
or str(PurePosixPath(path)) != path
|
|
269
|
+
or ".." in PurePosixPath(path).parts
|
|
270
|
+
or any(c in path for c in "*?[]\\\x00\n\r\t")
|
|
271
|
+
or PurePosixPath(path).suffix.lower() not in allowed_extensions
|
|
272
|
+
or not isinstance(expected_sha, str)
|
|
273
|
+
or not isinstance(purpose, str)
|
|
274
|
+
or not purpose.strip()
|
|
275
|
+
or not isinstance(evidence, dict)
|
|
276
|
+
):
|
|
277
|
+
raise ReviewError("REVIEW_ITEM_FIELDS_INVALID", "invalid path, duplicate path, or missing purpose")
|
|
278
|
+
seen_paths.add(path)
|
|
279
|
+
|
|
280
|
+
ev_path = evidence.get("path")
|
|
281
|
+
ev_sha = evidence.get("sha256")
|
|
282
|
+
if not isinstance(ev_path, str) or not isinstance(ev_sha, str):
|
|
283
|
+
raise ReviewError("REVIEW_EVIDENCE_INVALID", "evidence metadata missing")
|
|
284
|
+
ev_bytes, _ = read_external_regular_bounded(
|
|
285
|
+
ev_path, repo=repo, common_dir=common_dir, label="evidence"
|
|
286
|
+
)
|
|
287
|
+
if sha256_bytes(ev_bytes) != ev_sha:
|
|
288
|
+
raise ReviewError("REVIEW_EVIDENCE_HASH_MISMATCH", "evidence sha256 mismatch")
|
|
289
|
+
|
|
290
|
+
if candidate_blobs and path in candidate_blobs:
|
|
291
|
+
actual_bytes = candidate_blobs[path]
|
|
292
|
+
elif stage == "head" and commit_ref:
|
|
293
|
+
show = run_git(repo, "--literal-pathspecs", "cat-file", "blob", f"{commit_ref}:{path}", env=clean_git_env(stage_env))
|
|
294
|
+
if show.returncode != 0:
|
|
295
|
+
raise ReviewError("REVIEW_HEAD_BLOB_MISSING", "reviewed file missing in created commit")
|
|
296
|
+
actual_bytes = show.stdout
|
|
297
|
+
elif stage == "index":
|
|
298
|
+
show = run_git(repo, "--literal-pathspecs", "cat-file", "blob", f":{path}", env=clean_git_env(stage_env))
|
|
299
|
+
if show.returncode != 0:
|
|
300
|
+
raise ReviewError("REVIEW_INDEX_BLOB_MISSING", "reviewed file missing in index")
|
|
301
|
+
actual_bytes = show.stdout
|
|
302
|
+
else:
|
|
303
|
+
target = repo / path
|
|
304
|
+
if target.is_symlink() or not target.is_file():
|
|
305
|
+
raise ReviewError("REVIEW_TARGET_NOT_REGULAR", "reviewed target is not a regular file")
|
|
306
|
+
actual_bytes = target.read_bytes()
|
|
307
|
+
|
|
308
|
+
_validate_source_syntax(path, actual_bytes, allowed_extensions)
|
|
309
|
+
if sha256_bytes(actual_bytes) != expected_sha:
|
|
310
|
+
raise ReviewError("REVIEW_SOURCE_HASH_MISMATCH", "reviewed file sha256 mismatch")
|
|
311
|
+
|
|
312
|
+
baseline_bytes: bytes | None = None
|
|
313
|
+
if baseline_ref is not None:
|
|
314
|
+
_, baseline_bytes = read_baseline_blob(
|
|
315
|
+
repo, baseline_ref, path, max_bytes=MAX_SCAN_BYTES, env=stage_env
|
|
316
|
+
)
|
|
317
|
+
verdict = scan(actual_bytes, baseline=baseline_bytes)
|
|
318
|
+
content_status = "passed" if verdict == "CLEAR" else "blocked"
|
|
319
|
+
receipts.append(
|
|
320
|
+
{
|
|
321
|
+
"review_id": f"sha256:{sha256_bytes(raw_review)}",
|
|
322
|
+
"path": path,
|
|
323
|
+
"sha256": expected_sha,
|
|
324
|
+
"purpose_sha256": sha256_bytes(purpose.encode("utf-8")),
|
|
325
|
+
"evidence_sha256": ev_sha,
|
|
326
|
+
"repository": repo_meta,
|
|
327
|
+
"allocation": alloc_meta,
|
|
328
|
+
"scope_sha256": doc["scope_sha256"],
|
|
329
|
+
"path_review": "validated",
|
|
330
|
+
"content_scan": content_status,
|
|
331
|
+
}
|
|
332
|
+
)
|
|
333
|
+
if content_status != "passed":
|
|
334
|
+
raise FinalizerError(
|
|
335
|
+
ErrorCode.CONTENT_SCAN_BLOCKED,
|
|
336
|
+
f"reviewed-sensitive-source 内容扫描命中敏感特征 ({verdict}): {path}",
|
|
337
|
+
final_phase="local_validation",
|
|
338
|
+
reviewed_sensitive_sources=receipts,
|
|
339
|
+
)
|
|
340
|
+
|
|
341
|
+
missing_sensitive = [p for p in requested_paths if is_sensitive_path(p) and p not in seen_paths]
|
|
342
|
+
if missing_sensitive:
|
|
343
|
+
raise ReviewError("REVIEW_INCOMPLETE", "not all sensitive paths are covered by review")
|
|
344
|
+
|
|
345
|
+
return receipts
|
|
346
|
+
|
|
347
|
+
|
|
348
|
+
def reviewed_blob_map(
|
|
349
|
+
repo: Path,
|
|
350
|
+
receipts: list[dict[str, Any]],
|
|
351
|
+
*,
|
|
352
|
+
commit_ref: str = "HEAD",
|
|
353
|
+
) -> dict[str, str]:
|
|
354
|
+
"""Resolve `path -> blob_oid` on `commit_ref` for all reviewed paths in `receipts`."""
|
|
355
|
+
mapping: dict[str, str] = {}
|
|
356
|
+
for rec in receipts:
|
|
357
|
+
rel = str(rec["path"])
|
|
358
|
+
res = run_git(repo, "--literal-pathspecs", "ls-tree", "-z", commit_ref, "--", rel)
|
|
359
|
+
if res.returncode != 0 or not res.stdout:
|
|
360
|
+
raise FinalizerError(
|
|
361
|
+
ErrorCode.SOURCE_REVIEW_BLOCKED,
|
|
362
|
+
f"无法解析 reviewed source 对象: {rel}",
|
|
363
|
+
final_phase="local_validation",
|
|
364
|
+
)
|
|
365
|
+
meta, _, _ = res.stdout.rstrip(b"\0").decode("utf-8", errors="strict").partition("\t")
|
|
366
|
+
parts = meta.split()
|
|
367
|
+
if len(parts) != 3 or parts[1] != "blob":
|
|
368
|
+
raise FinalizerError(
|
|
369
|
+
ErrorCode.SOURCE_REVIEW_BLOCKED,
|
|
370
|
+
f"reviewed source 对象类型异常: {rel}",
|
|
371
|
+
final_phase="local_validation",
|
|
372
|
+
)
|
|
373
|
+
mapping[rel] = parts[2]
|
|
374
|
+
return mapping
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
"""AI provenance Git trailers and optional Agent Trace Git Notes (`refs/notes/agent-trace`)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from datetime import UTC, datetime
|
|
6
|
+
import json
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
import re
|
|
9
|
+
import tempfile
|
|
10
|
+
import uuid
|
|
11
|
+
|
|
12
|
+
from git_finalizer import TOOL_NAME, __version__
|
|
13
|
+
from git_finalizer.errors import ErrorCode, FinalizerError
|
|
14
|
+
from git_finalizer.git_io import run_git, validate_oid
|
|
15
|
+
from git_finalizer.json_io import sha256_file
|
|
16
|
+
|
|
17
|
+
AGENT_TRACE_REF = "refs/notes/agent-trace"
|
|
18
|
+
CONTROL_CHARS_RE = re.compile(r"[\x00-\x1f\x7f]")
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def _validate_trailer_value(value: str, flag: str) -> str:
|
|
22
|
+
stripped = value.strip()
|
|
23
|
+
if not stripped or len(stripped) > 512 or CONTROL_CHARS_RE.search(stripped):
|
|
24
|
+
raise FinalizerError(
|
|
25
|
+
ErrorCode.CLI_INVALID_ARGS,
|
|
26
|
+
f"{flag} 值非法(禁止空值、换行或控制字符)",
|
|
27
|
+
final_phase="cli",
|
|
28
|
+
)
|
|
29
|
+
return stripped
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def build_provenance_trailers(
|
|
33
|
+
*,
|
|
34
|
+
trailer_agent: str | None = None,
|
|
35
|
+
trace_ref: str | None = None,
|
|
36
|
+
snapshot_id: str | None = None,
|
|
37
|
+
) -> list[tuple[str, str]]:
|
|
38
|
+
"""Return validated `(key, value)` Git trailer pairs for commit formatting."""
|
|
39
|
+
trailers: list[tuple[str, str]] = []
|
|
40
|
+
if trailer_agent is not None:
|
|
41
|
+
trailers.append(("Assisted-by", _validate_trailer_value(trailer_agent, "--trailer-agent")))
|
|
42
|
+
if snapshot_id is not None:
|
|
43
|
+
validate_oid(snapshot_id, "snapshot ID")
|
|
44
|
+
trailers.append(("Snapshot-Evidence-Id", snapshot_id))
|
|
45
|
+
if trace_ref is not None:
|
|
46
|
+
trailers.append(("Agent-Trace-Ref", _validate_trailer_value(trace_ref, "--trace-ref")))
|
|
47
|
+
return trailers
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def format_commit_message_with_trailers(
|
|
51
|
+
repo: Path,
|
|
52
|
+
message: str,
|
|
53
|
+
trailers: list[tuple[str, str]],
|
|
54
|
+
*,
|
|
55
|
+
env: dict[str, str] | None = None,
|
|
56
|
+
) -> str:
|
|
57
|
+
"""Apply canonical RFC-822 trailers using `git interpret-trailers`."""
|
|
58
|
+
if not trailers:
|
|
59
|
+
return message
|
|
60
|
+
args = ["interpret-trailers", "--if-exists", "addIfDifferent"]
|
|
61
|
+
for key, value in trailers:
|
|
62
|
+
args.extend(["--trailer", f"{key}: {value}"])
|
|
63
|
+
completed = run_git(
|
|
64
|
+
repo,
|
|
65
|
+
*args,
|
|
66
|
+
text=False,
|
|
67
|
+
env=env,
|
|
68
|
+
input_data=(message.rstrip("\n") + "\n").encode("utf-8"),
|
|
69
|
+
)
|
|
70
|
+
if completed.returncode != 0:
|
|
71
|
+
raise FinalizerError(
|
|
72
|
+
ErrorCode.COMMIT_FAILED,
|
|
73
|
+
"无法使用 git interpret-trailers 写入 AI provenance trailers",
|
|
74
|
+
status="failed",
|
|
75
|
+
final_phase="commit",
|
|
76
|
+
)
|
|
77
|
+
return completed.stdout.decode("utf-8", errors="strict")
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def write_agent_trace_note(
|
|
81
|
+
repo: Path,
|
|
82
|
+
commit_sha: str,
|
|
83
|
+
paths: list[str],
|
|
84
|
+
*,
|
|
85
|
+
trailer_agent: str | None = None,
|
|
86
|
+
trace_ref: str | None = None,
|
|
87
|
+
snapshot_id: str | None = None,
|
|
88
|
+
task_key: str | None = None,
|
|
89
|
+
allocation_id: str | None = None,
|
|
90
|
+
env: dict[str, str] | None = None,
|
|
91
|
+
) -> dict[str, object]:
|
|
92
|
+
"""Attach an Agent Trace JSON record as a Git note under `refs/notes/agent-trace`."""
|
|
93
|
+
validate_oid(commit_sha, "commit OID")
|
|
94
|
+
file_records: list[dict[str, object]] = []
|
|
95
|
+
for rel in sorted(dict.fromkeys(paths)):
|
|
96
|
+
target = repo / rel
|
|
97
|
+
entry: dict[str, object] = {"path": rel}
|
|
98
|
+
if target.exists() and not target.is_symlink() and target.is_file():
|
|
99
|
+
entry["sha256"] = sha256_file(target)
|
|
100
|
+
else:
|
|
101
|
+
entry["status"] = "deleted_or_nonregular"
|
|
102
|
+
file_records.append(entry)
|
|
103
|
+
|
|
104
|
+
record: dict[str, object] = {
|
|
105
|
+
"schema": "https://agent-trace.dev/v0/record.schema.json",
|
|
106
|
+
"version": "0.1.0",
|
|
107
|
+
"id": str(uuid.uuid5(uuid.NAMESPACE_URL, f"git-finalizer:{commit_sha}:{','.join(sorted(paths))}")),
|
|
108
|
+
"timestamp": datetime.now(UTC).isoformat(),
|
|
109
|
+
"vcs": {
|
|
110
|
+
"type": "git",
|
|
111
|
+
"revision": commit_sha,
|
|
112
|
+
},
|
|
113
|
+
"tool": {
|
|
114
|
+
"name": TOOL_NAME,
|
|
115
|
+
"version": __version__,
|
|
116
|
+
},
|
|
117
|
+
"files": file_records,
|
|
118
|
+
}
|
|
119
|
+
metadata: dict[str, object] = {}
|
|
120
|
+
if trailer_agent:
|
|
121
|
+
metadata["agent"] = _validate_trailer_value(trailer_agent, "--trailer-agent")
|
|
122
|
+
if trace_ref:
|
|
123
|
+
metadata["trace_ref"] = _validate_trailer_value(trace_ref, "--trace-ref")
|
|
124
|
+
if snapshot_id:
|
|
125
|
+
metadata["snapshot_evidence_id"] = snapshot_id
|
|
126
|
+
if task_key:
|
|
127
|
+
metadata["task_key"] = task_key
|
|
128
|
+
if allocation_id:
|
|
129
|
+
metadata["allocation_id"] = allocation_id
|
|
130
|
+
if metadata:
|
|
131
|
+
record["metadata"] = metadata
|
|
132
|
+
|
|
133
|
+
payload = (json.dumps(record, ensure_ascii=False, sort_keys=True, indent=2) + "\n").encode("utf-8")
|
|
134
|
+
with tempfile.NamedTemporaryFile(prefix="gf-agent-trace-", suffix=".json", delete=True) as tmp:
|
|
135
|
+
tmp.write(payload)
|
|
136
|
+
tmp.flush()
|
|
137
|
+
completed = run_git(
|
|
138
|
+
repo,
|
|
139
|
+
"notes",
|
|
140
|
+
"--ref",
|
|
141
|
+
AGENT_TRACE_REF,
|
|
142
|
+
"add",
|
|
143
|
+
"-f",
|
|
144
|
+
"-F",
|
|
145
|
+
tmp.name,
|
|
146
|
+
commit_sha,
|
|
147
|
+
env=env,
|
|
148
|
+
)
|
|
149
|
+
if completed.returncode != 0:
|
|
150
|
+
raise FinalizerError(
|
|
151
|
+
ErrorCode.COMMIT_FAILED,
|
|
152
|
+
"写入 Agent Trace Git Note 失败",
|
|
153
|
+
status="failed",
|
|
154
|
+
final_phase="commit",
|
|
155
|
+
commit_created=True,
|
|
156
|
+
commit_sha=commit_sha,
|
|
157
|
+
)
|
|
158
|
+
rev = run_git(repo, "notes", "--ref", AGENT_TRACE_REF, "list", commit_sha, env=env)
|
|
159
|
+
note_oid = rev.stdout.decode("ascii", errors="replace").strip() if rev.returncode == 0 else None
|
|
160
|
+
return {
|
|
161
|
+
"ref": AGENT_TRACE_REF,
|
|
162
|
+
"recorded": True,
|
|
163
|
+
"note_oid": note_oid or None,
|
|
164
|
+
}
|