@mokuyoaxis/agent-guard 0.2.2
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.
- package/CONTRIBUTING.md +101 -0
- package/LICENSE +21 -0
- package/README.md +558 -0
- package/README.zh-CN.md +488 -0
- package/adapters/INTEGRATION.md +94 -0
- package/adapters/claude/README.md +141 -0
- package/adapters/claude/compatibility.json +17 -0
- package/adapters/claude/harness/README.md +59 -0
- package/adapters/claude/harness/mock_anthropic_api.mjs +47 -0
- package/adapters/claude/harness/run_scenario.sh +79 -0
- package/adapters/claude/harness/run_scenario_no_python3.sh +49 -0
- package/adapters/claude/hook_bridge.sh +33 -0
- package/adapters/claude/pre_tool_use.py +264 -0
- package/adapters/claude/settings.example.json +16 -0
- package/adapters/codex/harness/README.md +53 -0
- package/adapters/codex/harness/acceptance.py +226 -0
- package/adapters/dsh/README.md +62 -0
- package/adapters/dsh/cordis.patch.yml +30 -0
- package/adapters/dsh/lib/index.js +500 -0
- package/adapters/kimi-code/README.md +169 -0
- package/adapters/kimi-code/compatibility.json +17 -0
- package/adapters/kimi-code/config.example.toml +26 -0
- package/adapters/kimi-code/hook_bridge.sh +32 -0
- package/adapters/kimi-code/pre_tool_use.py +72 -0
- package/core/__init__.py +47 -0
- package/core/audit.py +86 -0
- package/core/classifier.py +1175 -0
- package/core/dialects.py +898 -0
- package/core/policy.py +817 -0
- package/core/recovery.py +700 -0
- package/core/redaction.py +1096 -0
- package/core/safe_view.py +212 -0
- package/docs/architecture.md +223 -0
- package/docs/compatibility.md +142 -0
- package/docs/development-note-unguarded-deletion.md +187 -0
- package/docs/friction.md +266 -0
- package/docs/harness-capabilities.md +72 -0
- package/docs/host-drift.md +142 -0
- package/docs/publishing-from-ephemeral-environments.md +104 -0
- package/docs/release-notes-0.2.0-rc1.md +46 -0
- package/docs/release-notes-0.2.0.md +72 -0
- package/docs/release-notes-0.2.1.md +78 -0
- package/docs/release-notes-0.2.2.md +120 -0
- package/docs/secret-guard-analysis.md +416 -0
- package/docs/secret-guard-architecture.md +93 -0
- package/docs/secret-guard-design.md +649 -0
- package/docs/test-report-claude-code-harness.md +462 -0
- package/docs/test-report-codex-gpt-5.6-sol.md +335 -0
- package/docs/test-report-codex-gpt-6-astra-high.md +129 -0
- package/docs/test-report-dsh-0.1.5-rc.1.md +84 -0
- package/docs/test-report-dsh-v0.1.1.md +126 -0
- package/docs/test-report-kimi-code-block.md +198 -0
- package/docs/test-report-zcode-glm-flash.md +241 -0
- package/docs/threat-model.md +44 -0
- package/doctor.py +756 -0
- package/live_sentinel.py +339 -0
- package/package.json +69 -0
- package/skills/delete-guard/SKILL.md +109 -0
- package/skills/delete-guard/agents/openai.yaml +4 -0
- package/skills/delete-guard/references/policy.md +161 -0
- package/skills/delete-guard/scripts/_bootstrap.py +8 -0
- package/skills/delete-guard/scripts/check.py +370 -0
- package/skills/delete-guard/scripts/gc.py +103 -0
- package/skills/delete-guard/scripts/restore.py +98 -0
- package/skills/delete-guard/scripts/safe_delete.py +256 -0
- package/skills/delete-guard/scripts/status.py +130 -0
- package/skills/exfil-guard/SKILL.md +143 -0
- package/skills/exfil-guard/agents/openai.yaml +4 -0
- package/skills/exfil-guard/references/channels.md +58 -0
- package/skills/exfil-guard/references/rules.md +194 -0
- package/skills/exfil-guard/scripts/_bootstrap.py +8 -0
- package/skills/exfil-guard/scripts/check_span.py +250 -0
- package/skills/exfil-guard/scripts/sanitize.py +155 -0
- package/skills/exfil-guard/scripts/view.py +44 -0
- package/skills/recovery-audit/SKILL.md +283 -0
- package/skills/recovery-audit/agents/openai.yaml +4 -0
- package/skills/recovery-audit/references/evidence-records.md +85 -0
package/core/recovery.py
ADDED
|
@@ -0,0 +1,700 @@
|
|
|
1
|
+
"""Recoverability pillar: the Compensation Engine.
|
|
2
|
+
|
|
3
|
+
Two compensation strategies, chosen by the caller (policy decides which):
|
|
4
|
+
|
|
5
|
+
relocate - move targets into the quarantine tree, preserving their
|
|
6
|
+
workspace-relative structure under one transaction id
|
|
7
|
+
snapshot_git - capture tracked modifications as a stash commit WITHOUT
|
|
8
|
+
changing the working tree (git stash create + store), so a
|
|
9
|
+
subsequent reset --hard / restore stays reversible
|
|
10
|
+
|
|
11
|
+
Everything lands in an append-only manifest (JSONL). Restore is itself
|
|
12
|
+
non-destructive: it refuses to overwrite anything that now exists at the
|
|
13
|
+
origin path unless the human passes force explicitly.
|
|
14
|
+
|
|
15
|
+
The quarantine directory must be Git-ignored before it is created. An existing
|
|
16
|
+
repository `.gitignore` rule is accepted; otherwise the engine adds a local
|
|
17
|
+
`.git/info/exclude` rule without modifying the user's tracked files.
|
|
18
|
+
"""
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import json
|
|
22
|
+
import os
|
|
23
|
+
import shutil
|
|
24
|
+
import subprocess
|
|
25
|
+
import time
|
|
26
|
+
import errno
|
|
27
|
+
import re
|
|
28
|
+
from typing import Any, Dict, List, Optional, Tuple
|
|
29
|
+
|
|
30
|
+
from . import MANIFEST_NAME, TRASH_DIRNAME
|
|
31
|
+
from .audit import new_txid, utc_now_iso
|
|
32
|
+
from .classifier import PathSpec, _physical, _physical_keep_final
|
|
33
|
+
|
|
34
|
+
# Soft retention policy (docs/references: GC). Thresholds only MARK entries
|
|
35
|
+
# GC_ELIGIBLE; actual purging is an explicit maintenance action - a system
|
|
36
|
+
# that promises recoverability must never silently destroy its own evidence.
|
|
37
|
+
SOFT_RETENTION_DAYS = 30
|
|
38
|
+
SOFT_SIZE_LIMIT_BYTES = 5 * 1024 * 1024 * 1024 # 5 GiB
|
|
39
|
+
|
|
40
|
+
_STORAGE_ERRNOS = {
|
|
41
|
+
getattr(errno, "ENOSPC", None),
|
|
42
|
+
getattr(errno, "EDQUOT", None),
|
|
43
|
+
} - {None}
|
|
44
|
+
|
|
45
|
+
# A transaction directory is one direct child of the quarantine, never a
|
|
46
|
+
# caller-supplied path. Accept simple historical identifiers too, but no
|
|
47
|
+
# separators or dots that could turn an ID into a path traversal.
|
|
48
|
+
_GC_TXID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]*\Z")
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class StorageUnavailable(OSError):
|
|
52
|
+
"""Quarantine cannot accept new relocations (disk full / quota)."""
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
class RecoveryEngine:
|
|
56
|
+
def __init__(self, workspace: str, trash_root: Optional[str] = None):
|
|
57
|
+
self.workspace = os.path.normpath(os.path.abspath(workspace))
|
|
58
|
+
self.trash_root = os.path.normpath(os.path.abspath(
|
|
59
|
+
trash_root or os.path.join(self.workspace, TRASH_DIRNAME)))
|
|
60
|
+
|
|
61
|
+
# ------------------------------------------------------------- layout
|
|
62
|
+
|
|
63
|
+
@staticmethod
|
|
64
|
+
def _contained_dest(dest: str, tx_dir: str) -> str:
|
|
65
|
+
"""Return dest, refusing anything that escapes trash_root/<txid>/.
|
|
66
|
+
|
|
67
|
+
Relocation must be RECOVERABLE: a destination outside the
|
|
68
|
+
transaction directory is evidence that the origin/trash spelling
|
|
69
|
+
pair diverged (the macOS /var link bug) or that a symlink moved
|
|
70
|
+
under us. Never silently write there - raise OSError, which the
|
|
71
|
+
caller turns into a controlled failure plus a manifest record.
|
|
72
|
+
"""
|
|
73
|
+
root = _physical(os.path.normpath(os.path.abspath(tx_dir)))
|
|
74
|
+
candidate = _physical(os.path.normpath(os.path.abspath(dest)))
|
|
75
|
+
if candidate == root:
|
|
76
|
+
raise OSError(
|
|
77
|
+
f"refusing to relocate onto the transaction directory: {dest}")
|
|
78
|
+
if os.path.commonpath([candidate, root]) != root:
|
|
79
|
+
raise OSError(
|
|
80
|
+
f"destination escapes quarantine transaction directory "
|
|
81
|
+
f"{root}: {dest}")
|
|
82
|
+
return candidate
|
|
83
|
+
|
|
84
|
+
@property
|
|
85
|
+
def manifest_path(self) -> str:
|
|
86
|
+
return os.path.join(self.trash_root, MANIFEST_NAME)
|
|
87
|
+
|
|
88
|
+
def ensure_layout(self) -> None:
|
|
89
|
+
# Establish the ignore rule first. If protected Git metadata prevents
|
|
90
|
+
# this, fail without leaving a new untracked quarantine directory.
|
|
91
|
+
self._exclude_from_git()
|
|
92
|
+
os.makedirs(self.trash_root, exist_ok=True)
|
|
93
|
+
|
|
94
|
+
def _trash_is_git_ignored(self) -> bool:
|
|
95
|
+
"""Whether Git already excludes the quarantine path.
|
|
96
|
+
|
|
97
|
+
Codex and other harness sandboxes commonly protect `.git` from writes.
|
|
98
|
+
A repository-level `.gitignore` is sufficient in that environment, so
|
|
99
|
+
do not require a redundant `.git/info/exclude` mutation.
|
|
100
|
+
"""
|
|
101
|
+
try:
|
|
102
|
+
rel = os.path.relpath(_physical(self.trash_root),
|
|
103
|
+
_physical(self.workspace))
|
|
104
|
+
if rel == os.pardir or rel.startswith(os.pardir + os.sep):
|
|
105
|
+
return True # external quarantine cannot pollute this repo
|
|
106
|
+
git_rel = rel.replace(os.sep, "/").rstrip("/") + "/"
|
|
107
|
+
proc = subprocess.run(
|
|
108
|
+
["git", "-C", self.workspace, "check-ignore", "-q",
|
|
109
|
+
"--no-index", "--", git_rel],
|
|
110
|
+
capture_output=True, timeout=10)
|
|
111
|
+
return proc.returncode == 0
|
|
112
|
+
except (OSError, subprocess.TimeoutExpired, ValueError):
|
|
113
|
+
return False
|
|
114
|
+
|
|
115
|
+
def _exclude_from_git(self) -> None:
|
|
116
|
+
"""Hide the quarantine from git status via .git/info/exclude."""
|
|
117
|
+
git_marker = os.path.join(self.workspace, ".git")
|
|
118
|
+
if not os.path.exists(git_marker): # dir or worktree pointer file
|
|
119
|
+
return
|
|
120
|
+
if self._trash_is_git_ignored():
|
|
121
|
+
return
|
|
122
|
+
resolved = subprocess.run(
|
|
123
|
+
["git", "-C", self.workspace, "rev-parse", "--git-path",
|
|
124
|
+
"info/exclude"], capture_output=True, text=True, timeout=10)
|
|
125
|
+
if resolved.returncode != 0 or not resolved.stdout.strip():
|
|
126
|
+
raise OSError((resolved.stderr or
|
|
127
|
+
"cannot resolve Git exclude path").strip())
|
|
128
|
+
exclude = resolved.stdout.strip()
|
|
129
|
+
if not os.path.isabs(exclude):
|
|
130
|
+
exclude = os.path.join(self.workspace, exclude)
|
|
131
|
+
info = os.path.dirname(exclude)
|
|
132
|
+
os.makedirs(info, exist_ok=True)
|
|
133
|
+
try:
|
|
134
|
+
with open(exclude, "r", encoding="utf-8") as fh:
|
|
135
|
+
existing = fh.read()
|
|
136
|
+
except OSError:
|
|
137
|
+
existing = ""
|
|
138
|
+
# Both sides physical: an external AGENT_GUARD_TRASH given in a
|
|
139
|
+
# non-physical spelling (symlinked ancestor) would otherwise yield
|
|
140
|
+
# a `..`-laden pattern that excludes the wrong path from git status.
|
|
141
|
+
rel = os.path.relpath(
|
|
142
|
+
_physical(self.trash_root),
|
|
143
|
+
_physical(self.workspace)).replace(os.sep, "/")
|
|
144
|
+
pattern = f"/{rel.strip('/')}/"
|
|
145
|
+
for line in existing.splitlines():
|
|
146
|
+
if line.strip() in (TRASH_DIRNAME, pattern):
|
|
147
|
+
return
|
|
148
|
+
with open(exclude, "a", encoding="utf-8") as fh:
|
|
149
|
+
if existing and not existing.endswith("\n"):
|
|
150
|
+
fh.write("\n")
|
|
151
|
+
fh.write(f"# added by agent-guard (quarantine is not project data)\n")
|
|
152
|
+
fh.write(f"{pattern}\n")
|
|
153
|
+
|
|
154
|
+
# ------------------------------------------------------------ manifest
|
|
155
|
+
|
|
156
|
+
def _manifest_append(self, records: List[Dict[str, Any]]) -> None:
|
|
157
|
+
self.ensure_layout()
|
|
158
|
+
with open(self.manifest_path, "a", encoding="utf-8") as fh:
|
|
159
|
+
for record in records:
|
|
160
|
+
record.setdefault("ts", utc_now_iso())
|
|
161
|
+
fh.write(json.dumps(record, ensure_ascii=False,
|
|
162
|
+
sort_keys=True) + "\n")
|
|
163
|
+
fh.flush()
|
|
164
|
+
os.fsync(fh.fileno())
|
|
165
|
+
|
|
166
|
+
def read_manifest(self) -> List[Dict[str, Any]]:
|
|
167
|
+
path = self.manifest_path
|
|
168
|
+
if not os.path.exists(path):
|
|
169
|
+
return []
|
|
170
|
+
out: List[Dict[str, Any]] = []
|
|
171
|
+
with open(path, "r", encoding="utf-8") as fh:
|
|
172
|
+
for raw in fh:
|
|
173
|
+
raw = raw.strip()
|
|
174
|
+
if not raw:
|
|
175
|
+
continue
|
|
176
|
+
try:
|
|
177
|
+
out.append(json.loads(raw))
|
|
178
|
+
except json.JSONDecodeError:
|
|
179
|
+
continue
|
|
180
|
+
return out
|
|
181
|
+
|
|
182
|
+
# -------------------------------------------------------------- move
|
|
183
|
+
|
|
184
|
+
@staticmethod
|
|
185
|
+
def _move(src: str, dest: str) -> None:
|
|
186
|
+
"""Move file/symlink/dir preserving symlink semantics.
|
|
187
|
+
|
|
188
|
+
Same-filesystem moves are plain renames. Cross-device fallbacks keep
|
|
189
|
+
symlinks as symlinks (never materialize what they point at).
|
|
190
|
+
"""
|
|
191
|
+
try:
|
|
192
|
+
os.rename(src, dest)
|
|
193
|
+
return
|
|
194
|
+
except OSError as exc:
|
|
195
|
+
if exc.errno in _STORAGE_ERRNOS:
|
|
196
|
+
raise StorageUnavailable(
|
|
197
|
+
f"quarantine storage unavailable: {exc}") from exc
|
|
198
|
+
if exc.errno != errno.EXDEV:
|
|
199
|
+
raise
|
|
200
|
+
try:
|
|
201
|
+
if os.path.islink(src):
|
|
202
|
+
link_target = os.readlink(src)
|
|
203
|
+
os.symlink(link_target, dest)
|
|
204
|
+
os.unlink(src)
|
|
205
|
+
elif os.path.isdir(src):
|
|
206
|
+
shutil.copytree(src, dest, symlinks=True)
|
|
207
|
+
shutil.rmtree(src)
|
|
208
|
+
else:
|
|
209
|
+
shutil.copy2(src, dest)
|
|
210
|
+
os.unlink(src)
|
|
211
|
+
except OSError as exc:
|
|
212
|
+
if exc.errno in _STORAGE_ERRNOS:
|
|
213
|
+
raise StorageUnavailable(
|
|
214
|
+
f"quarantine storage unavailable: {exc}") from exc
|
|
215
|
+
raise
|
|
216
|
+
|
|
217
|
+
# ----------------------------------------------------------- relocate
|
|
218
|
+
|
|
219
|
+
def relocate(self, specs: List[PathSpec], txid: Optional[str] = None,
|
|
220
|
+
meta: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
|
221
|
+
"""Move every concrete target into trash/<txid>/<workspace-relative>.
|
|
222
|
+
|
|
223
|
+
Layout arithmetic uses PHYSICAL spellings on BOTH sides: the
|
|
224
|
+
workspace root is realpath-resolved (F8) while ``spec.resolved`` is
|
|
225
|
+
deliberately LEXICAL, so a lexically-spelled target under a
|
|
226
|
+
symlinked ancestor (macOS /var -> /private/var) used to produce a
|
|
227
|
+
multi-segment ``..`` relpath and a destination OUTSIDE the
|
|
228
|
+
transaction directory. ``origin_path`` stays lexical: restore and
|
|
229
|
+
every message must speak the caller's spelling.
|
|
230
|
+
"""
|
|
231
|
+
txid = txid or new_txid()
|
|
232
|
+
# Write-ahead journal: no source mutation may happen until the
|
|
233
|
+
# transaction exists durably. Each target intent is durable before its
|
|
234
|
+
# move, so an interrupted completion write remains discoverable.
|
|
235
|
+
self._manifest_append([{
|
|
236
|
+
"type": "tx-start", "txid": txid, "strategy": "relocate",
|
|
237
|
+
"meta": meta or {},
|
|
238
|
+
}])
|
|
239
|
+
moved: List[Dict[str, Any]] = []
|
|
240
|
+
skipped: List[Dict[str, Any]] = []
|
|
241
|
+
storage_failure = False
|
|
242
|
+
for spec in specs:
|
|
243
|
+
src = spec.resolved
|
|
244
|
+
entry_base = {"raw": spec.raw}
|
|
245
|
+
if spec.wildcard or spec.indeterminable or not src:
|
|
246
|
+
skipped.append({**entry_base, "reason": "not concretely resolved"})
|
|
247
|
+
continue
|
|
248
|
+
if not os.path.lexists(src):
|
|
249
|
+
skipped.append({**entry_base, "reason": "already absent"})
|
|
250
|
+
continue
|
|
251
|
+
tx_dir = os.path.join(self.trash_root, txid)
|
|
252
|
+
# Parent chain physical, final component verbatim: a target
|
|
253
|
+
# that is itself a symlink keeps its own location (F9).
|
|
254
|
+
rel = os.path.relpath(_physical_keep_final(src),
|
|
255
|
+
_physical(self.workspace))
|
|
256
|
+
dest = os.path.join(tx_dir, rel)
|
|
257
|
+
try:
|
|
258
|
+
# Defence in depth (F9): a symlink race or an exotic
|
|
259
|
+
# spelling must never let a target land outside its own
|
|
260
|
+
# transaction directory. Fail closed, with evidence.
|
|
261
|
+
dest = self._contained_dest(dest, tx_dir)
|
|
262
|
+
except OSError as exc:
|
|
263
|
+
skipped.append({**entry_base,
|
|
264
|
+
"reason": f"uncontained destination: {exc}"})
|
|
265
|
+
self._manifest_append([{
|
|
266
|
+
"type": "relocate-failed", "txid": txid,
|
|
267
|
+
"origin_path": src, "trash_path": dest,
|
|
268
|
+
"reason": str(exc),
|
|
269
|
+
}])
|
|
270
|
+
continue
|
|
271
|
+
intent = {"type": "relocate-intent", "txid": txid,
|
|
272
|
+
"origin_path": src, "trash_path": dest,
|
|
273
|
+
"raw": spec.raw}
|
|
274
|
+
self._manifest_append([intent])
|
|
275
|
+
try:
|
|
276
|
+
os.makedirs(os.path.dirname(dest), exist_ok=True)
|
|
277
|
+
self._move(src, dest)
|
|
278
|
+
except StorageUnavailable:
|
|
279
|
+
# Hard principle: capacity limits never downgrade to
|
|
280
|
+
# permanent deletion. Abort; the failed target stays at its
|
|
281
|
+
# origin untouched; callers map this to BLOCK.
|
|
282
|
+
storage_failure = True
|
|
283
|
+
self._manifest_append([{
|
|
284
|
+
"type": "relocate-failed", "txid": txid,
|
|
285
|
+
"origin_path": src, "trash_path": dest,
|
|
286
|
+
"reason": "storage unavailable",
|
|
287
|
+
}])
|
|
288
|
+
break
|
|
289
|
+
except OSError as exc:
|
|
290
|
+
self._manifest_append([{
|
|
291
|
+
"type": "relocate-failed", "txid": txid,
|
|
292
|
+
"origin_path": src, "trash_path": dest,
|
|
293
|
+
"reason": str(exc),
|
|
294
|
+
}])
|
|
295
|
+
raise
|
|
296
|
+
item = {"type": "relocate", "txid": txid,
|
|
297
|
+
"origin_path": src, "trash_path": dest}
|
|
298
|
+
self._manifest_append([item])
|
|
299
|
+
moved.append({"origin": src, "trash": dest})
|
|
300
|
+
return {"txid": txid, "moved": moved, "skipped": skipped,
|
|
301
|
+
"storage_failure": storage_failure}
|
|
302
|
+
|
|
303
|
+
# ------------------------------------------------------ git snapshot
|
|
304
|
+
|
|
305
|
+
def snapshot_git(self, cwd: Optional[str] = None,
|
|
306
|
+
txid: Optional[str] = None,
|
|
307
|
+
meta: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
|
308
|
+
"""Stash-create tracked modifications without touching the tree.
|
|
309
|
+
|
|
310
|
+
Returns sha=None when there is nothing to snapshot (clean tree) -
|
|
311
|
+
that is success, not failure.
|
|
312
|
+
"""
|
|
313
|
+
cwd = cwd or self.workspace
|
|
314
|
+
txid = txid or new_txid()
|
|
315
|
+
create = subprocess.run(["git", "-C", cwd, "stash", "create"],
|
|
316
|
+
capture_output=True, text=True, timeout=30)
|
|
317
|
+
if create.returncode != 0:
|
|
318
|
+
return {"ok": False, "clean": False, "txid": txid,
|
|
319
|
+
"sha": None, "stored": False,
|
|
320
|
+
"error": (create.stderr or
|
|
321
|
+
"git stash create failed").strip()}
|
|
322
|
+
sha = create.stdout.strip()
|
|
323
|
+
if not sha:
|
|
324
|
+
self._manifest_append([{
|
|
325
|
+
"type": "snapshot", "txid": txid, "sha": None,
|
|
326
|
+
"note": "working tree clean; nothing to snapshot",
|
|
327
|
+
"meta": meta or {},
|
|
328
|
+
}])
|
|
329
|
+
return {"ok": True, "clean": True, "txid": txid,
|
|
330
|
+
"sha": None, "stored": False, "error": ""}
|
|
331
|
+
store = subprocess.run(
|
|
332
|
+
["git", "-C", cwd, "stash", "store", "-m", f"agent-guard:{txid}", sha],
|
|
333
|
+
capture_output=True, text=True, timeout=30)
|
|
334
|
+
stored = store.returncode == 0
|
|
335
|
+
error = "" if stored else (
|
|
336
|
+
store.stderr or "git stash store failed").strip()
|
|
337
|
+
self._manifest_append([{
|
|
338
|
+
"type": "snapshot", "txid": txid, "sha": sha,
|
|
339
|
+
"stored": stored, "error": error, "meta": meta or {},
|
|
340
|
+
}])
|
|
341
|
+
return {"ok": stored, "clean": False, "txid": txid, "sha": sha,
|
|
342
|
+
"stored": stored, "error": error}
|
|
343
|
+
|
|
344
|
+
# --------------------------------------------------- git clean enum
|
|
345
|
+
|
|
346
|
+
@staticmethod
|
|
347
|
+
def _decode_git_quoted_path(value: str) -> str:
|
|
348
|
+
"""Decode Git's double-quoted C-style path representation."""
|
|
349
|
+
if len(value) < 2 or not (value.startswith('"') and
|
|
350
|
+
value.endswith('"')):
|
|
351
|
+
return value
|
|
352
|
+
data = value[1:-1]
|
|
353
|
+
result = bytearray()
|
|
354
|
+
escapes = {
|
|
355
|
+
"a": 7, "b": 8, "t": 9, "n": 10, "v": 11,
|
|
356
|
+
"f": 12, "r": 13, "\\": 92, '"': 34,
|
|
357
|
+
}
|
|
358
|
+
i = 0
|
|
359
|
+
while i < len(data):
|
|
360
|
+
ch = data[i]
|
|
361
|
+
if ch != "\\":
|
|
362
|
+
result.extend(os.fsencode(ch))
|
|
363
|
+
i += 1
|
|
364
|
+
continue
|
|
365
|
+
i += 1
|
|
366
|
+
if i >= len(data):
|
|
367
|
+
raise ValueError("trailing backslash in Git-quoted path")
|
|
368
|
+
esc = data[i]
|
|
369
|
+
if esc in "01234567":
|
|
370
|
+
digits = esc
|
|
371
|
+
i += 1
|
|
372
|
+
while i < len(data) and len(digits) < 3 and data[i] in "01234567":
|
|
373
|
+
digits += data[i]
|
|
374
|
+
i += 1
|
|
375
|
+
result.append(int(digits, 8))
|
|
376
|
+
continue
|
|
377
|
+
if esc not in escapes:
|
|
378
|
+
raise ValueError(f"unknown Git path escape: \\{esc}")
|
|
379
|
+
result.append(escapes[esc])
|
|
380
|
+
i += 1
|
|
381
|
+
return os.fsdecode(bytes(result))
|
|
382
|
+
|
|
383
|
+
def enumerate_git_clean(self, cwd: Optional[str],
|
|
384
|
+
clean_flags: List[str],
|
|
385
|
+
targets: Optional[List[str]] = None,
|
|
386
|
+
) -> Tuple[List[str], str]:
|
|
387
|
+
"""Dry-run `git clean` mirroring the caller's scope flags.
|
|
388
|
+
|
|
389
|
+
Returns (untracked_paths, stderr). Nested repositories are reported
|
|
390
|
+
by git as 'Would skip' and are intentionally left alone.
|
|
391
|
+
"""
|
|
392
|
+
cwd = cwd or self.workspace
|
|
393
|
+
mirror = ["-n"]
|
|
394
|
+
allowed = {"-d", "-x", "-X", "--directory", "--ignored"}
|
|
395
|
+
for flag in clean_flags:
|
|
396
|
+
if flag in allowed:
|
|
397
|
+
mirror.append(flag)
|
|
398
|
+
if targets:
|
|
399
|
+
mirror.extend(["--", *targets])
|
|
400
|
+
env = dict(os.environ)
|
|
401
|
+
env["LC_ALL"] = "C"
|
|
402
|
+
proc = subprocess.run(["git", "-C", cwd, "clean"] + mirror,
|
|
403
|
+
capture_output=True, text=True, timeout=60,
|
|
404
|
+
env=env)
|
|
405
|
+
if proc.returncode != 0:
|
|
406
|
+
detail = (proc.stderr or proc.stdout or
|
|
407
|
+
"git clean dry-run failed").strip()
|
|
408
|
+
return [], detail
|
|
409
|
+
paths: List[str] = []
|
|
410
|
+
unparsed: List[str] = []
|
|
411
|
+
for line in proc.stdout.splitlines():
|
|
412
|
+
line = line.strip()
|
|
413
|
+
if not line:
|
|
414
|
+
continue
|
|
415
|
+
if line.startswith("Would skip repository "):
|
|
416
|
+
continue
|
|
417
|
+
if not line.startswith("Would remove "):
|
|
418
|
+
unparsed.append(line)
|
|
419
|
+
continue
|
|
420
|
+
target = line[len("Would remove "):].strip()
|
|
421
|
+
try:
|
|
422
|
+
paths.append(self._decode_git_quoted_path(target))
|
|
423
|
+
except ValueError as exc:
|
|
424
|
+
return [], f"cannot decode git clean path {target!r}: {exc}"
|
|
425
|
+
if unparsed:
|
|
426
|
+
return [], "unrecognized git clean dry-run output: " + \
|
|
427
|
+
"; ".join(unparsed[:3])
|
|
428
|
+
return paths, proc.stderr.strip()
|
|
429
|
+
|
|
430
|
+
# ------------------------------------------------------------- restore
|
|
431
|
+
|
|
432
|
+
def transactions(self) -> Dict[str, Dict[str, Any]]:
|
|
433
|
+
"""Group manifest entries by transaction id (insertion order)."""
|
|
434
|
+
out: Dict[str, Dict[str, Any]] = {}
|
|
435
|
+
for record in self.read_manifest():
|
|
436
|
+
txid = record.get("txid")
|
|
437
|
+
if not txid:
|
|
438
|
+
continue
|
|
439
|
+
slot = out.setdefault(txid, {"txid": txid, "items": []})
|
|
440
|
+
if record.get("type") == "tx-start":
|
|
441
|
+
slot["meta"] = record.get("meta", {})
|
|
442
|
+
slot["ts"] = record.get("ts")
|
|
443
|
+
elif record.get("type") in ("relocate", "snapshot"):
|
|
444
|
+
slot["items"].append(record)
|
|
445
|
+
elif record.get("type") == "relocate-intent":
|
|
446
|
+
slot.setdefault("_intents", []).append(record)
|
|
447
|
+
elif record.get("type") == "relocate-failed":
|
|
448
|
+
slot.setdefault("failures", []).append(record)
|
|
449
|
+
elif record.get("type") == "restore":
|
|
450
|
+
slot["last_restore"] = record
|
|
451
|
+
elif record.get("type") == "purged":
|
|
452
|
+
slot["purged"] = True
|
|
453
|
+
|
|
454
|
+
# If a move succeeded but its completion record could not be written,
|
|
455
|
+
# the durable intent plus filesystem state is sufficient to recover.
|
|
456
|
+
for slot in out.values():
|
|
457
|
+
completed = {
|
|
458
|
+
(item.get("origin_path"), item.get("trash_path"))
|
|
459
|
+
for item in slot["items"] if item.get("type") == "relocate"
|
|
460
|
+
}
|
|
461
|
+
for intent in slot.pop("_intents", []):
|
|
462
|
+
key = (intent.get("origin_path"), intent.get("trash_path"))
|
|
463
|
+
if key in completed:
|
|
464
|
+
continue
|
|
465
|
+
origin, trash = key
|
|
466
|
+
if trash and os.path.lexists(trash):
|
|
467
|
+
slot["items"].append({
|
|
468
|
+
**intent, "type": "relocate",
|
|
469
|
+
"recovered_from_intent": True,
|
|
470
|
+
})
|
|
471
|
+
live_items = 0
|
|
472
|
+
for item in slot["items"]:
|
|
473
|
+
if item.get("type") == "relocate" and \
|
|
474
|
+
os.path.lexists(item.get("trash_path", "")):
|
|
475
|
+
live_items += 1
|
|
476
|
+
elif item.get("type") == "snapshot" and item.get("sha"):
|
|
477
|
+
# Stored stashes are deliberately retained after apply.
|
|
478
|
+
live_items += 1
|
|
479
|
+
slot["restorable_items"] = live_items
|
|
480
|
+
restored = slot.get("last_restore", {})
|
|
481
|
+
if slot.get("purged"):
|
|
482
|
+
slot["state"] = "PURGED"
|
|
483
|
+
elif restored.get("restored") and not restored.get("errors") and \
|
|
484
|
+
not restored.get("conflicts"):
|
|
485
|
+
slot["state"] = "RESTORED"
|
|
486
|
+
elif live_items:
|
|
487
|
+
slot["state"] = "RESTORABLE"
|
|
488
|
+
elif slot.get("failures"):
|
|
489
|
+
slot["state"] = "FAILED"
|
|
490
|
+
else:
|
|
491
|
+
slot["state"] = "EMPTY"
|
|
492
|
+
return out
|
|
493
|
+
|
|
494
|
+
def restore(self, txid: str, force: bool = False,
|
|
495
|
+
cwd: Optional[str] = None) -> Dict[str, Any]:
|
|
496
|
+
"""Undo one transaction. Refuses to overwrite unless force is set.
|
|
497
|
+
|
|
498
|
+
Relocate items move back to their origin paths; snapshot items apply
|
|
499
|
+
the stored stash (apply, never drop - the evidence stays until a
|
|
500
|
+
human prunes it).
|
|
501
|
+
"""
|
|
502
|
+
tx = self.transactions().get(txid)
|
|
503
|
+
if not tx:
|
|
504
|
+
return {"ok": False, "error": f"unknown transaction: {txid}"}
|
|
505
|
+
restored: List[str] = []
|
|
506
|
+
conflicts: List[str] = []
|
|
507
|
+
errors: List[str] = []
|
|
508
|
+
for item in tx["items"]:
|
|
509
|
+
if item.get("type") == "relocate":
|
|
510
|
+
origin = item["origin_path"]
|
|
511
|
+
trash = item["trash_path"]
|
|
512
|
+
if not os.path.lexists(trash):
|
|
513
|
+
errors.append(f"quarantine copy vanished: {trash}")
|
|
514
|
+
continue
|
|
515
|
+
if os.path.lexists(origin):
|
|
516
|
+
if not force:
|
|
517
|
+
conflicts.append(origin)
|
|
518
|
+
continue
|
|
519
|
+
if os.path.isdir(origin) and not os.path.islink(origin):
|
|
520
|
+
shutil.rmtree(origin)
|
|
521
|
+
else:
|
|
522
|
+
os.unlink(origin)
|
|
523
|
+
parent = os.path.dirname(origin)
|
|
524
|
+
if parent:
|
|
525
|
+
os.makedirs(parent, exist_ok=True)
|
|
526
|
+
try:
|
|
527
|
+
self._move(trash, origin)
|
|
528
|
+
restored.append(origin)
|
|
529
|
+
except OSError as exc:
|
|
530
|
+
errors.append(f"{origin}: {exc}")
|
|
531
|
+
elif item.get("type") == "snapshot":
|
|
532
|
+
sha = item.get("sha")
|
|
533
|
+
if not sha:
|
|
534
|
+
continue
|
|
535
|
+
apply = subprocess.run(
|
|
536
|
+
["git", "-C", cwd or self.workspace, "stash", "apply", sha],
|
|
537
|
+
capture_output=True, text=True, timeout=60)
|
|
538
|
+
if apply.returncode == 0:
|
|
539
|
+
restored.append(f"stash:{sha}")
|
|
540
|
+
else:
|
|
541
|
+
errors.append(
|
|
542
|
+
f"stash apply {sha}: {(apply.stderr or '').strip()}")
|
|
543
|
+
|
|
544
|
+
self._manifest_append([{
|
|
545
|
+
"type": "restore", "txid": txid, "force": force,
|
|
546
|
+
"restored": restored, "conflicts": conflicts, "errors": errors,
|
|
547
|
+
}])
|
|
548
|
+
# drop empty quarantine directories for tidy listings
|
|
549
|
+
txdir = os.path.join(self.trash_root, txid)
|
|
550
|
+
try:
|
|
551
|
+
if os.path.isdir(txdir) and not os.listdir(txdir):
|
|
552
|
+
os.rmdir(txdir)
|
|
553
|
+
except OSError:
|
|
554
|
+
pass
|
|
555
|
+
return {"ok": not errors and not conflicts,
|
|
556
|
+
"restored": restored, "conflicts": conflicts, "errors": errors}
|
|
557
|
+
|
|
558
|
+
# ------------------------------------------------------------- status
|
|
559
|
+
|
|
560
|
+
def usage(self) -> Dict[str, Any]:
|
|
561
|
+
"""Size/count summary of the quarantine tree."""
|
|
562
|
+
files = 0
|
|
563
|
+
total = 0
|
|
564
|
+
for root, _dirs, names in os.walk(self.trash_root):
|
|
565
|
+
for name in names:
|
|
566
|
+
path = os.path.join(root, name)
|
|
567
|
+
if os.path.islink(path):
|
|
568
|
+
files += 1
|
|
569
|
+
continue
|
|
570
|
+
try:
|
|
571
|
+
total += os.lstat(path).st_size
|
|
572
|
+
files += 1
|
|
573
|
+
except OSError:
|
|
574
|
+
pass
|
|
575
|
+
transactions = self.transactions()
|
|
576
|
+
return {
|
|
577
|
+
"files": files,
|
|
578
|
+
"bytes": total,
|
|
579
|
+
"transactions": len(transactions),
|
|
580
|
+
"restorable_transactions": sum(
|
|
581
|
+
1 for tx in transactions.values()
|
|
582
|
+
if tx.get("state") == "RESTORABLE"),
|
|
583
|
+
"restorable_items": sum(
|
|
584
|
+
tx.get("restorable_items", 0)
|
|
585
|
+
for tx in transactions.values()),
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
# ------------------------------------------------------ GC lifecycle
|
|
589
|
+
|
|
590
|
+
@staticmethod
|
|
591
|
+
def _parse_ts(value: Optional[str]) -> Optional[float]:
|
|
592
|
+
if not value:
|
|
593
|
+
return None
|
|
594
|
+
try:
|
|
595
|
+
return time.mktime(time.strptime(
|
|
596
|
+
value, "%Y-%m-%dT%H:%M:%SZ")) - time.timezone
|
|
597
|
+
except (ValueError, TypeError):
|
|
598
|
+
return None
|
|
599
|
+
|
|
600
|
+
def tx_inventory(self) -> List[Dict[str, Any]]:
|
|
601
|
+
"""Per-transaction age/size facts for retention decisions."""
|
|
602
|
+
inventory: List[Dict[str, Any]] = []
|
|
603
|
+
for txid, tx in self.transactions().items():
|
|
604
|
+
tx_dir = os.path.join(self.trash_root, txid)
|
|
605
|
+
total = 0
|
|
606
|
+
for root, _dirs, names in os.walk(tx_dir):
|
|
607
|
+
for name in names:
|
|
608
|
+
p = os.path.join(root, name)
|
|
609
|
+
if not os.path.islink(p):
|
|
610
|
+
try:
|
|
611
|
+
total += os.lstat(p).st_size
|
|
612
|
+
except OSError:
|
|
613
|
+
pass
|
|
614
|
+
created = self._parse_ts(tx.get("ts"))
|
|
615
|
+
inventory.append({
|
|
616
|
+
"txid": txid, "ts": tx.get("ts"), "created_epoch": created,
|
|
617
|
+
"bytes": total, "items": len(tx["items"]),
|
|
618
|
+
})
|
|
619
|
+
inventory.sort(key=lambda e: e.get("created_epoch") or 0)
|
|
620
|
+
return inventory
|
|
621
|
+
|
|
622
|
+
def gc_plan(self, now: Optional[float] = None,
|
|
623
|
+
retention_days: int = SOFT_RETENTION_DAYS,
|
|
624
|
+
size_limit_bytes: int = SOFT_SIZE_LIMIT_BYTES,
|
|
625
|
+
) -> Dict[str, Any]:
|
|
626
|
+
"""Mark GC_ELIGIBLE entries. Never deletes anything by itself.
|
|
627
|
+
|
|
628
|
+
Eligibility: older than the soft retention window, or - when the
|
|
629
|
+
quarantine exceeds the soft size cap - oldest-first until back
|
|
630
|
+
under the cap. The audit log is never eligible.
|
|
631
|
+
"""
|
|
632
|
+
now = now if now is not None else time.time()
|
|
633
|
+
cutoff = now - retention_days * 86400
|
|
634
|
+
inventory = self.tx_inventory()
|
|
635
|
+
total = sum(e["bytes"] for e in inventory)
|
|
636
|
+
eligible: List[Dict[str, Any]] = []
|
|
637
|
+
for entry in inventory:
|
|
638
|
+
created = entry.get("created_epoch")
|
|
639
|
+
if created is not None and created < cutoff:
|
|
640
|
+
eligible.append({**entry, "reason": "age"})
|
|
641
|
+
remaining = total - sum(e["bytes"] for e in eligible)
|
|
642
|
+
if remaining > size_limit_bytes:
|
|
643
|
+
for entry in inventory:
|
|
644
|
+
if any(e["txid"] == entry["txid"] for e in eligible):
|
|
645
|
+
continue
|
|
646
|
+
if remaining <= size_limit_bytes:
|
|
647
|
+
break
|
|
648
|
+
if entry["bytes"] <= 0 and entry["items"] == 0:
|
|
649
|
+
continue
|
|
650
|
+
eligible.append({**entry, "reason": "capacity"})
|
|
651
|
+
remaining -= entry["bytes"]
|
|
652
|
+
return {
|
|
653
|
+
"retention_days": retention_days,
|
|
654
|
+
"size_limit_bytes": size_limit_bytes,
|
|
655
|
+
"total_bytes": total,
|
|
656
|
+
"eligible": eligible,
|
|
657
|
+
"remaining_bytes_after_gc": max(remaining, 0),
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
def validate_gc_targets(self, txids: List[str]) -> List[Tuple[str, str]]:
|
|
661
|
+
"""Resolve only manifest-owned direct children of the quarantine."""
|
|
662
|
+
# Validate the whole batch before touching anything: an unsafe ID
|
|
663
|
+
# after a valid one must not cause a partial purge. A directory that
|
|
664
|
+
# is not backed by a manifest transaction is not ours to delete.
|
|
665
|
+
known = self.transactions()
|
|
666
|
+
trash_physical = os.path.realpath(self.trash_root)
|
|
667
|
+
targets: List[Tuple[str, str]] = []
|
|
668
|
+
for txid in txids:
|
|
669
|
+
if not isinstance(txid, str) or not _GC_TXID_RE.fullmatch(txid):
|
|
670
|
+
raise ValueError(f"invalid quarantine transaction id: {txid!r}")
|
|
671
|
+
tx_dir = os.path.join(self.trash_root, txid)
|
|
672
|
+
if os.path.islink(tx_dir):
|
|
673
|
+
raise ValueError(f"refusing symlinked transaction: {txid}")
|
|
674
|
+
if os.path.isdir(tx_dir):
|
|
675
|
+
if txid not in known or known[txid].get("purged"):
|
|
676
|
+
raise ValueError(f"unmanaged quarantine directory: {txid}")
|
|
677
|
+
if os.path.dirname(os.path.realpath(tx_dir)) != trash_physical:
|
|
678
|
+
raise ValueError(f"transaction escapes quarantine: {txid}")
|
|
679
|
+
targets.append((txid, tx_dir))
|
|
680
|
+
|
|
681
|
+
return targets
|
|
682
|
+
|
|
683
|
+
def gc_execute(self, txids: List[str]) -> Dict[str, Any]:
|
|
684
|
+
"""Purge validated transactions; write tombstones after removal.
|
|
685
|
+
|
|
686
|
+
Audit records are NEVER removed - the QUARANTINED -> RESTORABLE ->
|
|
687
|
+
GC_ELIGIBLE -> PURGED lifecycle stays fully reconstructible.
|
|
688
|
+
"""
|
|
689
|
+
targets = self.validate_gc_targets(txids)
|
|
690
|
+
purged: List[str] = []
|
|
691
|
+
missing: List[str] = []
|
|
692
|
+
for txid, tx_dir in targets:
|
|
693
|
+
if not os.path.isdir(tx_dir):
|
|
694
|
+
missing.append(txid)
|
|
695
|
+
continue
|
|
696
|
+
# Never report PURGED after a failed or partial filesystem remove.
|
|
697
|
+
shutil.rmtree(tx_dir)
|
|
698
|
+
self._manifest_append([{"type": "purged", "txid": txid}])
|
|
699
|
+
purged.append(txid)
|
|
700
|
+
return {"purged": purged, "missing": missing}
|