@mokuyoaxis/agent-guard 0.2.6 → 0.2.8
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/README.md +45 -20
- package/README.zh-CN.md +39 -19
- package/adapters/INTEGRATION.md +6 -0
- package/adapters/mcp/__init__.py +1 -0
- package/adapters/mcp/doctor.py +325 -0
- package/adapters/mcp/operations.py +174 -0
- package/adapters/mcp/requirements.txt +3 -0
- package/adapters/mcp/server.py +126 -0
- package/core/admission.py +388 -0
- package/core/audit.py +1 -1
- package/core/classifier.py +2 -1
- package/core/cleanup.py +297 -0
- package/core/delete_config.py +153 -0
- package/core/policy.py +35 -7
- package/core/recovery.py +10 -0
- package/docs/README.md +35 -14
- package/docs/design/architecture.md +42 -16
- package/docs/design/compatibility.md +246 -7
- package/docs/design/threat-model.md +53 -1
- package/docs/guides/cleanup-plan.md +227 -0
- package/docs/guides/deletion-limits.md +150 -0
- package/docs/guides/getting-started.md +26 -12
- package/docs/guides/harness-capabilities.md +29 -4
- package/docs/guides/mcp.md +420 -0
- package/docs/history/friction.md +99 -1
- package/docs/releases/release-notes-0.2.7.md +217 -0
- package/docs/releases/release-notes-0.2.8.md +172 -0
- package/docs/releases/unreleased.md +182 -5
- package/docs/reports/test-report-dsh-paired-lab.md +1 -1
- package/docs/reports/test-report-kimi-code-block.md +1 -1
- package/doctor.py +25 -1
- package/live_sentinel.py +1 -1
- package/package.json +3 -1
- package/skills/delete-guard/SKILL.md +69 -1
- package/skills/delete-guard/references/policy.md +66 -3
- package/skills/delete-guard/scripts/check.py +39 -9
- package/skills/delete-guard/scripts/cleanup.py +164 -0
- package/skills/delete-guard/scripts/safe_delete.py +22 -4
- package/skills/delete-guard/scripts/status.py +77 -1
package/core/cleanup.py
ADDED
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
"""Metadata-only cleanup proposals; deletion remains owned by safe_delete.
|
|
2
|
+
|
|
3
|
+
The plan is a local review aid, not permission to bypass policy. It does not
|
|
4
|
+
read candidate contents, follow directory links, or create guard metadata.
|
|
5
|
+
"""
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import hashlib
|
|
9
|
+
import json
|
|
10
|
+
import os
|
|
11
|
+
import stat
|
|
12
|
+
import subprocess
|
|
13
|
+
from dataclasses import dataclass, field
|
|
14
|
+
from typing import Any, Dict, Iterable, List, Optional, Tuple
|
|
15
|
+
|
|
16
|
+
from . import TRASH_DIRNAME, classifier, policy
|
|
17
|
+
from .delete_config import CONFIG_DIRECTORY, fingerprint, load_config
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
CATEGORIES = ("regenerable", "discarded", "uncertain", "protected")
|
|
21
|
+
PROTECTED_NAMES = frozenset({".git", ".internal", TRASH_DIRNAME, CONFIG_DIRECTORY})
|
|
22
|
+
DEFAULT_MAX_ENTRIES = 10_000
|
|
23
|
+
DEFAULT_MAX_DEPTH = 32
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _digest(value: Any) -> str:
|
|
27
|
+
encoded = json.dumps(value, sort_keys=True, ensure_ascii=True,
|
|
28
|
+
separators=(",", ":")).encode("ascii")
|
|
29
|
+
return hashlib.sha256(encoded).hexdigest()
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _under(path: str, parent: str) -> bool:
|
|
33
|
+
return parent == "." or path == parent or path.startswith(parent + "/")
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _declared_paths(values: Iterable[str], root: str, *, must_exist: bool) -> List[str]:
|
|
37
|
+
result = set()
|
|
38
|
+
for value in values:
|
|
39
|
+
absolute = os.path.normpath(os.path.join(root, os.fspath(value)))
|
|
40
|
+
if not classifier.inside_path(absolute, root):
|
|
41
|
+
raise ValueError("declared cleanup paths must be inside the workspace")
|
|
42
|
+
if must_exist and absolute == root:
|
|
43
|
+
raise ValueError("the workspace root cannot be declared discarded")
|
|
44
|
+
if must_exist and not os.path.lexists(absolute):
|
|
45
|
+
raise ValueError("discard target does not exist: " + os.fspath(value))
|
|
46
|
+
result.add(os.path.relpath(absolute, root).replace(os.sep, "/"))
|
|
47
|
+
return sorted(result)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
@dataclass
|
|
51
|
+
class _Node:
|
|
52
|
+
path: str
|
|
53
|
+
kind: str = "unknown"
|
|
54
|
+
signature: Optional[List[int]] = None
|
|
55
|
+
protected: Optional[str] = None
|
|
56
|
+
complete: bool = True
|
|
57
|
+
children: List["_Node"] = field(default_factory=list)
|
|
58
|
+
files: Dict[Tuple[int, int], int] = field(default_factory=dict)
|
|
59
|
+
fingerprint: str = ""
|
|
60
|
+
has_protected: bool = False
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _git_facts(root: str, paths: List[str]):
|
|
64
|
+
"""Batch queries; an unavailable Git supplies no regenerability proof."""
|
|
65
|
+
env = dict(os.environ, GIT_OPTIONAL_LOCKS="0")
|
|
66
|
+
try:
|
|
67
|
+
tracked = subprocess.run(
|
|
68
|
+
["git", "-C", root, "ls-files", "--cached", "-z"],
|
|
69
|
+
capture_output=True, timeout=10, env=env)
|
|
70
|
+
if tracked.returncode:
|
|
71
|
+
return set(), set(), "GIT_UNAVAILABLE"
|
|
72
|
+
ignored = subprocess.run(
|
|
73
|
+
["git", "-C", root, "check-ignore", "--stdin", "-z"],
|
|
74
|
+
input=b"".join(os.fsencode(p) + b"\0" for p in paths),
|
|
75
|
+
capture_output=True, timeout=10, env=env)
|
|
76
|
+
if ignored.returncode not in (0, 1):
|
|
77
|
+
return set(), set(), "GIT_IGNORE_UNAVAILABLE"
|
|
78
|
+
except (OSError, subprocess.TimeoutExpired):
|
|
79
|
+
return set(), set(), "GIT_UNAVAILABLE"
|
|
80
|
+
return ({os.fsdecode(p).replace(os.sep, "/") for p in tracked.stdout.split(b"\0") if p},
|
|
81
|
+
{os.fsdecode(p).replace(os.sep, "/") for p in ignored.stdout.split(b"\0") if p},
|
|
82
|
+
None)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def plan_cleanup(
|
|
86
|
+
workspace: str, *, discard: Iterable[str] = (), protect: Iterable[str] = (),
|
|
87
|
+
max_entries: int = DEFAULT_MAX_ENTRIES, max_depth: int = DEFAULT_MAX_DEPTH,
|
|
88
|
+
) -> Dict[str, Any]:
|
|
89
|
+
"""Propose disjoint targets under a bounded workspace scan.
|
|
90
|
+
|
|
91
|
+
Protected subtrees are represented without traversal or size estimates.
|
|
92
|
+
Ordinary unknown subtrees collapse to one review row; generated or
|
|
93
|
+
explicitly discarded children remain visible. Sizes deduplicate hardlinks
|
|
94
|
+
and exclude directory metadata; they do not predict released disk blocks.
|
|
95
|
+
"""
|
|
96
|
+
if type(max_entries) is not int or max_entries < 1:
|
|
97
|
+
raise ValueError("max_entries must be a positive integer")
|
|
98
|
+
if type(max_depth) is not int or not 1 <= max_depth <= 128:
|
|
99
|
+
raise ValueError("max_depth must be between 1 and 128")
|
|
100
|
+
root = os.path.realpath(os.path.abspath(os.fspath(workspace)))
|
|
101
|
+
if not os.path.isdir(root) or classifier.protected_ancestor_root(root):
|
|
102
|
+
raise ValueError("provide an existing workspace below a filesystem root")
|
|
103
|
+
delete_config = load_config(root)
|
|
104
|
+
discard = _declared_paths(discard, root, must_exist=True)
|
|
105
|
+
protect = list(protect) + delete_config.protected_paths
|
|
106
|
+
protect = sorted(set(_declared_paths(protect, root, must_exist=False)) | PROTECTED_NAMES)
|
|
107
|
+
# A declared path may cross a directory alias. Protect both spellings:
|
|
108
|
+
# deleting a physical ancestor must not cover the declared evidence.
|
|
109
|
+
physical_protection = []
|
|
110
|
+
for path in protect:
|
|
111
|
+
physical = os.path.realpath(os.path.join(root, path))
|
|
112
|
+
if classifier.inside_path(physical, root):
|
|
113
|
+
physical_protection.append(os.path.relpath(physical, root).replace(os.sep, "/"))
|
|
114
|
+
protect = sorted(set(protect + physical_protection))
|
|
115
|
+
trash = os.path.abspath(os.environ.get("AGENT_GUARD_TRASH", os.path.join(root, TRASH_DIRNAME)))
|
|
116
|
+
if classifier.inside_path(trash, root):
|
|
117
|
+
protect = sorted(set(protect + [os.path.relpath(trash, root).replace(os.sep, "/")]))
|
|
118
|
+
ctx = policy.PolicyContext(workspace=root, trash_root=trash, base_dir=root,
|
|
119
|
+
mode=policy.load_mode(trash)["mode"])
|
|
120
|
+
errors = []
|
|
121
|
+
nodes: List[_Node] = []
|
|
122
|
+
examined = 0
|
|
123
|
+
|
|
124
|
+
def problem(node: _Node, code: str) -> None:
|
|
125
|
+
node.complete = False
|
|
126
|
+
record = {"path": node.path, "code": code}
|
|
127
|
+
if record not in errors:
|
|
128
|
+
errors.append(record)
|
|
129
|
+
|
|
130
|
+
def visit(relative: str, depth: int) -> _Node:
|
|
131
|
+
nonlocal examined
|
|
132
|
+
node = _Node(relative)
|
|
133
|
+
nodes.append(node)
|
|
134
|
+
absolute = os.path.join(root, relative)
|
|
135
|
+
if (set(relative.split("/")) & PROTECTED_NAMES
|
|
136
|
+
or any(_under(relative, p) for p in protect)):
|
|
137
|
+
node.protected = "protected project or recovery subtree; not traversed"
|
|
138
|
+
physical = os.path.realpath(absolute)
|
|
139
|
+
if physical != absolute and classifier.inside_path(physical, root):
|
|
140
|
+
physical_relative = os.path.relpath(physical, root).replace(os.sep, "/")
|
|
141
|
+
if not any(_under(physical_relative, p) for p in protect):
|
|
142
|
+
# A nested protected alias was not known before traversal.
|
|
143
|
+
# Require an upfront declaration before selecting ancestors.
|
|
144
|
+
problem(node, "PROTECTED_ALIAS_REQUIRES_EXPLICIT_PROTECT")
|
|
145
|
+
else:
|
|
146
|
+
try:
|
|
147
|
+
info = os.lstat(absolute)
|
|
148
|
+
node.signature = [info.st_dev, info.st_ino, info.st_mode,
|
|
149
|
+
info.st_size, info.st_mtime_ns, info.st_ctime_ns]
|
|
150
|
+
spec = (classifier.classify_paths(["./" + relative], root, root, trash)[0]
|
|
151
|
+
if relative != "." else None)
|
|
152
|
+
physical = os.path.relpath(os.path.realpath(absolute), root).replace(os.sep, "/")
|
|
153
|
+
if ((spec and spec.protected) or set(physical.split("/")) & PROTECTED_NAMES
|
|
154
|
+
or any(_under(physical, p) for p in protect)
|
|
155
|
+
or (stat.S_ISLNK(info.st_mode)
|
|
156
|
+
and any(_under(p, relative) for p in protect))):
|
|
157
|
+
node.protected = "protected boundary or link destination; not traversed"
|
|
158
|
+
elif stat.S_ISDIR(info.st_mode):
|
|
159
|
+
node.kind = "directory"
|
|
160
|
+
if depth >= max_depth:
|
|
161
|
+
problem(node, "DEPTH_LIMIT_REACHED")
|
|
162
|
+
else:
|
|
163
|
+
names = []
|
|
164
|
+
with os.scandir(absolute) as entries:
|
|
165
|
+
for entry in entries:
|
|
166
|
+
if examined + len(names) >= max_entries:
|
|
167
|
+
problem(node, "ENTRY_LIMIT_REACHED")
|
|
168
|
+
break
|
|
169
|
+
names.append(entry.name)
|
|
170
|
+
for name in sorted(names):
|
|
171
|
+
if examined >= max_entries:
|
|
172
|
+
problem(node, "ENTRY_LIMIT_REACHED")
|
|
173
|
+
break
|
|
174
|
+
examined += 1
|
|
175
|
+
child = visit(name if relative == "." else relative + "/" + name,
|
|
176
|
+
depth + 1)
|
|
177
|
+
node.children.append(child)
|
|
178
|
+
node.files.update(child.files)
|
|
179
|
+
node.complete &= child.complete
|
|
180
|
+
after = os.lstat(absolute)
|
|
181
|
+
if [after.st_dev, after.st_ino, after.st_mode, after.st_size,
|
|
182
|
+
after.st_mtime_ns, after.st_ctime_ns] != node.signature:
|
|
183
|
+
problem(node, "SOURCE_CHANGED_DURING_SCAN")
|
|
184
|
+
elif stat.S_ISREG(info.st_mode) or stat.S_ISLNK(info.st_mode):
|
|
185
|
+
node.kind = "symlink" if stat.S_ISLNK(info.st_mode) else "file"
|
|
186
|
+
node.files[(info.st_dev, info.st_ino)] = info.st_size
|
|
187
|
+
else:
|
|
188
|
+
node.protected = "special filesystem entry; manual review required"
|
|
189
|
+
except OSError as exc:
|
|
190
|
+
problem(node, "OS_ERROR_" + str(exc.errno))
|
|
191
|
+
node.has_protected = (bool(node.protected)
|
|
192
|
+
or any(c.has_protected for c in node.children)
|
|
193
|
+
or (node.kind == "directory"
|
|
194
|
+
and any(_under(p, node.path) for p in protect)))
|
|
195
|
+
node.fingerprint = _digest([node.path, node.signature if not node.protected else None,
|
|
196
|
+
node.protected, node.complete,
|
|
197
|
+
[c.fingerprint for c in node.children]])
|
|
198
|
+
return node
|
|
199
|
+
|
|
200
|
+
# The workspace root is a boundary, but its children are scanned.
|
|
201
|
+
tree = visit(".", 0)
|
|
202
|
+
tracked, ignored, git_warning = _git_facts(
|
|
203
|
+
root, [n.path for n in nodes if n.path != "." and not n.protected])
|
|
204
|
+
tracked_ancestors = set(tracked)
|
|
205
|
+
for path in tracked:
|
|
206
|
+
parts = path.split("/")
|
|
207
|
+
tracked_ancestors.update("/".join(parts[:i]) for i in range(1, len(parts)))
|
|
208
|
+
|
|
209
|
+
def row(node: _Node, category: str, reason: str) -> Dict[str, Any]:
|
|
210
|
+
result = {
|
|
211
|
+
"path": node.path, "kind": node.kind, "category": category,
|
|
212
|
+
"size_bytes": None if node.protected else sum(node.files.values()),
|
|
213
|
+
"size_complete": node.complete and not node.has_protected,
|
|
214
|
+
"reason": reason, "selectable": False, "effect": "review",
|
|
215
|
+
"policy_code": None, "fingerprint": node.fingerprint,
|
|
216
|
+
}
|
|
217
|
+
if category == "protected":
|
|
218
|
+
result["effect"] = "keep"
|
|
219
|
+
elif category in ("regenerable", "discarded"):
|
|
220
|
+
# Concrete, relative spelling also used by the execution CLI.
|
|
221
|
+
spelling = "./" + node.path
|
|
222
|
+
specs = classifier.classify_paths([spelling], root, root, trash)
|
|
223
|
+
verdict = policy.decide_path_batch(specs, ctx, recursive=True)
|
|
224
|
+
result["policy_code"] = verdict.code
|
|
225
|
+
literal = (not specs[0].wildcard and not specs[0].indeterminable
|
|
226
|
+
and specs[0].resolved == os.path.join(root, node.path))
|
|
227
|
+
if literal and not verdict.blocked:
|
|
228
|
+
result["selectable"] = True
|
|
229
|
+
result["effect"] = ("delete" if verdict.code == policy.CODE_ALLOW_REGENERABLE
|
|
230
|
+
else "quarantine")
|
|
231
|
+
else:
|
|
232
|
+
result["effect"] = "blocked"
|
|
233
|
+
result["reason"] += "; existing path API or policy refuses execution"
|
|
234
|
+
return result
|
|
235
|
+
|
|
236
|
+
def flatten(node: _Node) -> List[Dict[str, Any]]:
|
|
237
|
+
if node.protected:
|
|
238
|
+
return [row(node, "protected", node.protected)]
|
|
239
|
+
if not node.complete and node.path != ".":
|
|
240
|
+
return [row(node, "uncertain", "incomplete scan; not executable")]
|
|
241
|
+
if node.path != "." and node.complete and not node.has_protected:
|
|
242
|
+
if any(_under(node.path, p) for p in discard):
|
|
243
|
+
return [row(node, "discarded", "explicitly declared discarded by caller")]
|
|
244
|
+
if (node.path in ignored and node.path not in tracked_ancestors
|
|
245
|
+
and policy._matches_artifact(node.path.replace("/", os.sep),
|
|
246
|
+
ctx.config.artifact_patterns)):
|
|
247
|
+
return [row(node, "regenerable", "Git-ignored and matches an artifact pattern")]
|
|
248
|
+
children = [entry for child in node.children for entry in flatten(child)]
|
|
249
|
+
if (node.path == "."
|
|
250
|
+
or any(entry["category"] != "uncertain" for entry in children)):
|
|
251
|
+
return children
|
|
252
|
+
return [row(node, "uncertain", "tracked content or no explicit discard/regeneration evidence")]
|
|
253
|
+
|
|
254
|
+
entries = sorted(flatten(tree), key=lambda entry: entry["path"])
|
|
255
|
+
summary = {}
|
|
256
|
+
by_path = {n.path: n for n in nodes}
|
|
257
|
+
for category in CATEGORIES:
|
|
258
|
+
subset = [e for e in entries if e["category"] == category]
|
|
259
|
+
unique_files = {}
|
|
260
|
+
for entry in subset:
|
|
261
|
+
unique_files.update(by_path[entry["path"]].files)
|
|
262
|
+
summary[category] = {"count": len(subset), "size_bytes": sum(unique_files.values())}
|
|
263
|
+
result = {
|
|
264
|
+
"schema_version": 1, "tool": "cleanup", "workspace": root,
|
|
265
|
+
"trash_root": trash, "mode": ctx.mode, "complete": not errors,
|
|
266
|
+
"examined": examined, "options": {"discard": discard, "protect": protect,
|
|
267
|
+
"max_entries": max_entries, "max_depth": max_depth},
|
|
268
|
+
"summary": summary, "entries": entries, "errors": errors,
|
|
269
|
+
"protected_names": sorted(PROTECTED_NAMES),
|
|
270
|
+
"warnings": [git_warning] if git_warning else [],
|
|
271
|
+
"size_notice": "Logical bytes, hardlinks counted once per category; protected subtrees omitted. Quarantine retains storage; bytes are not a freed-space estimate.",
|
|
272
|
+
}
|
|
273
|
+
result["plan_id"] = _digest({"plan": result, "tree": tree.fingerprint,
|
|
274
|
+
"config": vars(ctx.config),
|
|
275
|
+
"deletion_config": fingerprint(delete_config)})
|
|
276
|
+
return result
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
def select_entries(plan: Dict[str, Any], paths: Iterable[str], plan_id: str) -> List[Dict[str, Any]]:
|
|
280
|
+
"""Validate the exact reviewed selection before requesting confirmation."""
|
|
281
|
+
if plan_id != plan["plan_id"]:
|
|
282
|
+
raise ValueError("plan changed; review a fresh plan before executing")
|
|
283
|
+
if not plan["complete"]:
|
|
284
|
+
raise ValueError("incomplete scan; resolve scan limits/errors before executing")
|
|
285
|
+
selected = _declared_paths(paths, plan["workspace"], must_exist=True)
|
|
286
|
+
if not selected:
|
|
287
|
+
raise ValueError("--execute requires at least one explicit --select path")
|
|
288
|
+
rows = {entry["path"]: entry for entry in plan["entries"]}
|
|
289
|
+
result = []
|
|
290
|
+
for path in selected:
|
|
291
|
+
entry = rows.get(path)
|
|
292
|
+
if entry is None or not entry["selectable"]:
|
|
293
|
+
raise ValueError("target is not a selectable plan entry: " + path)
|
|
294
|
+
if any(_under(path, other["path"]) for other in result):
|
|
295
|
+
raise ValueError("overlapping selections are not allowed")
|
|
296
|
+
result.append(entry)
|
|
297
|
+
return result
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
"""Local deletion limits and protected paths; advisory against same-UID edits.
|
|
2
|
+
|
|
3
|
+
The optional JSON file is read only. Missing configuration uses documented
|
|
4
|
+
defaults; malformed configuration never silently disables protection.
|
|
5
|
+
"""
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from dataclasses import asdict, dataclass, field
|
|
9
|
+
import hashlib
|
|
10
|
+
import json
|
|
11
|
+
import os
|
|
12
|
+
import stat
|
|
13
|
+
from typing import List, Optional
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
CONFIG_DIRECTORY = ".agent-guard"
|
|
17
|
+
CONFIG_NAME = "delete-policy.json"
|
|
18
|
+
MAX_CONFIG_BYTES = 1024 * 1024
|
|
19
|
+
MAX_INTEGER = (1 << 63) - 1
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class DeleteConfigError(ValueError):
|
|
23
|
+
"""The local deletion configuration cannot be used safely."""
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass
|
|
27
|
+
class DeleteConfig:
|
|
28
|
+
quarantine_max_bytes: int = 5 * 1024 ** 3
|
|
29
|
+
quarantine_max_entries: int = 100_000
|
|
30
|
+
session_max_bytes: int = 1024 ** 3
|
|
31
|
+
session_max_entries: int = 10_000
|
|
32
|
+
rate_window_seconds: int = 60
|
|
33
|
+
rate_max_operations: int = 60
|
|
34
|
+
repeat_max_operations: int = 5
|
|
35
|
+
batch_max_bytes: int = 256 * 1024 ** 2
|
|
36
|
+
batch_max_entries: int = 1_000
|
|
37
|
+
protected_paths: List[str] = field(default_factory=list)
|
|
38
|
+
|
|
39
|
+
def fingerprint(self) -> str:
|
|
40
|
+
return fingerprint(self)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _inside(path: str, root: str) -> bool:
|
|
44
|
+
try:
|
|
45
|
+
path, root = os.path.normcase(path), os.path.normcase(root)
|
|
46
|
+
return os.path.commonpath([path, root]) == root
|
|
47
|
+
except ValueError:
|
|
48
|
+
return False
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def _declaration(value: str, workspace: str) -> str:
|
|
52
|
+
if not isinstance(value, str) or not value or "\0" in value:
|
|
53
|
+
raise DeleteConfigError("protected_paths must contain nonempty literal paths")
|
|
54
|
+
root = os.path.abspath(workspace)
|
|
55
|
+
path = os.path.normpath(os.path.join(root, value))
|
|
56
|
+
if not _inside(path, root):
|
|
57
|
+
raise DeleteConfigError("protected_paths must stay inside the workspace")
|
|
58
|
+
# Resolve directory aliases, retaining a final link's own location: a
|
|
59
|
+
# declaration can protect an outward-pointing link without authorizing
|
|
60
|
+
# configuration of an arbitrary external directory.
|
|
61
|
+
parent, leaf = os.path.split(path)
|
|
62
|
+
location = os.path.join(os.path.realpath(parent), leaf)
|
|
63
|
+
if path != root and not _inside(location, os.path.realpath(root)):
|
|
64
|
+
raise DeleteConfigError("protected_paths cannot cross an external directory link")
|
|
65
|
+
return os.path.relpath(path, root)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _unique_object(pairs):
|
|
69
|
+
result = {}
|
|
70
|
+
for name, value in pairs:
|
|
71
|
+
if name in result:
|
|
72
|
+
raise DeleteConfigError("duplicate deletion configuration field")
|
|
73
|
+
result[name] = value
|
|
74
|
+
return result
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def load_config(workspace: str) -> DeleteConfig:
|
|
78
|
+
"""Read the optional workspace policy, rejecting malformed known fields."""
|
|
79
|
+
path = os.path.join(os.path.abspath(workspace), CONFIG_DIRECTORY, CONFIG_NAME)
|
|
80
|
+
try:
|
|
81
|
+
# A FIFO must not block even briefly before we can classify it. Check
|
|
82
|
+
# the opened descriptor, rather than stat-then-open with a race.
|
|
83
|
+
descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0))
|
|
84
|
+
try:
|
|
85
|
+
if not stat.S_ISREG(os.fstat(descriptor).st_mode):
|
|
86
|
+
raise DeleteConfigError("deletion configuration must be a regular file")
|
|
87
|
+
with os.fdopen(descriptor, "rb", closefd=False) as handle:
|
|
88
|
+
raw = handle.read(MAX_CONFIG_BYTES + 1)
|
|
89
|
+
finally:
|
|
90
|
+
os.close(descriptor)
|
|
91
|
+
except FileNotFoundError as exc:
|
|
92
|
+
if os.path.lexists(path):
|
|
93
|
+
raise DeleteConfigError("deletion configuration is an unreadable link") from exc
|
|
94
|
+
return DeleteConfig()
|
|
95
|
+
except OSError as exc:
|
|
96
|
+
raise DeleteConfigError("cannot read deletion configuration") from exc
|
|
97
|
+
if len(raw) > MAX_CONFIG_BYTES:
|
|
98
|
+
raise DeleteConfigError("deletion configuration exceeds the size limit")
|
|
99
|
+
try:
|
|
100
|
+
data = json.loads(raw.decode("utf-8"), object_pairs_hook=_unique_object)
|
|
101
|
+
except (UnicodeError, json.JSONDecodeError, RecursionError) as exc:
|
|
102
|
+
raise DeleteConfigError("deletion configuration must be a valid UTF-8 JSON object") from exc
|
|
103
|
+
if not isinstance(data, dict):
|
|
104
|
+
raise DeleteConfigError("deletion configuration must be an object")
|
|
105
|
+
known = DeleteConfig.__dataclass_fields__
|
|
106
|
+
if set(data) - set(known):
|
|
107
|
+
raise DeleteConfigError("unknown deletion configuration field")
|
|
108
|
+
values = dict(data)
|
|
109
|
+
for name, value in values.items():
|
|
110
|
+
if name == "protected_paths":
|
|
111
|
+
if not isinstance(value, list):
|
|
112
|
+
raise DeleteConfigError("protected_paths must be a list of literal paths")
|
|
113
|
+
values[name] = sorted(set(_declaration(item, workspace) for item in value))
|
|
114
|
+
else:
|
|
115
|
+
minimum = 0 if name.endswith("_bytes") else 1
|
|
116
|
+
if type(value) is not int or not minimum <= value <= MAX_INTEGER:
|
|
117
|
+
raise DeleteConfigError("deletion limits require bounded integers; only byte limits may be zero")
|
|
118
|
+
return DeleteConfig(**values)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def fingerprint(config: DeleteConfig) -> str:
|
|
122
|
+
"""Digest effective limits and paths without exposing their contents."""
|
|
123
|
+
raw = json.dumps(asdict(config), ensure_ascii=True, sort_keys=True,
|
|
124
|
+
separators=(",", ":")).encode("ascii")
|
|
125
|
+
return hashlib.sha256(raw).hexdigest()
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def protected_reason(paths: List[str], workspace: str,
|
|
129
|
+
config: Optional[DeleteConfig] = None) -> Optional[str]:
|
|
130
|
+
"""Return a static reason when deleting any target overlaps protection.
|
|
131
|
+
|
|
132
|
+
Both the named location and physical destination are protected, including
|
|
133
|
+
deletion of an ancestor that would remove a protected descendant.
|
|
134
|
+
"""
|
|
135
|
+
config = config if config is not None else load_config(workspace)
|
|
136
|
+
root = os.path.abspath(workspace)
|
|
137
|
+
protected = [os.path.join(root, CONFIG_DIRECTORY)]
|
|
138
|
+
protected.extend(os.path.join(root, value) for value in config.protected_paths)
|
|
139
|
+
boundaries = set()
|
|
140
|
+
for path in protected:
|
|
141
|
+
absolute = os.path.normpath(path)
|
|
142
|
+
parent, leaf = os.path.split(absolute)
|
|
143
|
+
boundaries.update((absolute, os.path.realpath(absolute),
|
|
144
|
+
os.path.join(os.path.realpath(parent), leaf)))
|
|
145
|
+
for value in paths:
|
|
146
|
+
absolute = os.path.normpath(os.path.join(root, value))
|
|
147
|
+
parent, leaf = os.path.split(absolute)
|
|
148
|
+
variants = (absolute, os.path.realpath(absolute),
|
|
149
|
+
os.path.join(os.path.realpath(parent), leaf))
|
|
150
|
+
if any(_inside(target, boundary) or _inside(boundary, target)
|
|
151
|
+
for target in variants for boundary in boundaries):
|
|
152
|
+
return "target overlaps deletion configuration or a configured protected path"
|
|
153
|
+
return None
|
package/core/policy.py
CHANGED
|
@@ -59,6 +59,7 @@ from typing import Any, Dict, List, Optional
|
|
|
59
59
|
|
|
60
60
|
from . import STATE_NAME, TRASH_DIRNAME
|
|
61
61
|
from . import redaction
|
|
62
|
+
from . import delete_config
|
|
62
63
|
from .redaction import get_channel
|
|
63
64
|
from .classifier import (
|
|
64
65
|
KIND_FS_DELETE,
|
|
@@ -105,6 +106,13 @@ CODE_BLOCK_FORCE_PUSH = "BLOCK_FORCE_PUSH"
|
|
|
105
106
|
CODE_BLOCK_DIALECT_UNKNOWN = "BLOCK_DIALECT_UNKNOWN" # config
|
|
106
107
|
CODE_BLOCK_DIALECT_INVALID = "BLOCK_DIALECT_INVALID" # config
|
|
107
108
|
CODE_BLOCK_RELOCATE_FAILED_STORAGE = "RELOCATE_FAILED_STORAGE"
|
|
109
|
+
CODE_BLOCK_DELETE_CONFIG_INVALID = "BLOCK_DELETE_CONFIG_INVALID"
|
|
110
|
+
CODE_BLOCK_DELETE_PROTECTED = "BLOCK_DELETE_PROTECTED"
|
|
111
|
+
CODE_BLOCK_DELETE_LIMIT = "BLOCK_DELETE_LIMIT"
|
|
112
|
+
CODE_BLOCK_DELETE_RATE = "BLOCK_DELETE_RATE"
|
|
113
|
+
CODE_BLOCK_DELETE_REPEAT = "BLOCK_DELETE_REPEAT"
|
|
114
|
+
CODE_BLOCK_DELETE_BATCH_CONFIRM = "BLOCK_DELETE_BATCH_CONFIRM"
|
|
115
|
+
CODE_BLOCK_DELETE_STATE_INVALID = "BLOCK_DELETE_STATE_INVALID"
|
|
108
116
|
# exfil-guard (span decisions). Rule ids (`secret/*`, `path/*`) are payload,
|
|
109
117
|
# never verdict codes; these codes name the *disposition*, not the pattern.
|
|
110
118
|
CODE_SANITIZE_SECRET_REDACT = "SANITIZE_SECRET_REDACT"
|
|
@@ -122,6 +130,13 @@ CODE_BLOCK_GIT_RESET_COLLISION = "BLOCK_GIT_RESET_COLLISION"
|
|
|
122
130
|
|
|
123
131
|
# Human-facing one-liners: why the guard cannot just do it (or did do it).
|
|
124
132
|
EXPLANATIONS: Dict[str, str] = {
|
|
133
|
+
CODE_BLOCK_DELETE_CONFIG_INVALID: "Deletion configuration is invalid or unreadable; repair it before deleting.",
|
|
134
|
+
CODE_BLOCK_DELETE_PROTECTED: "Target overlaps deletion configuration or a configured protected path; deletion is refused.",
|
|
135
|
+
CODE_BLOCK_DELETE_LIMIT: "Deletion would exceed the quarantine capacity or session budget; targets were not admitted.",
|
|
136
|
+
CODE_BLOCK_DELETE_RATE: "This session reached its deletion rate limit; wait for the configured window before retrying.",
|
|
137
|
+
CODE_BLOCK_DELETE_REPEAT: "Repeated deletion of the same target reached the configured limit; inspect the loop before retrying.",
|
|
138
|
+
CODE_BLOCK_DELETE_BATCH_CONFIRM: "This batch requires a reviewed Cleanup Copilot plan and explicit confirmation.",
|
|
139
|
+
CODE_BLOCK_DELETE_STATE_INVALID: "Deletion budget state is invalid or unavailable; no new deletion was admitted.",
|
|
125
140
|
CODE_ALLOW_NOOP: "No recovery action is needed for the recognized operations. "
|
|
126
141
|
"Unrecognized command effects have not been checked.",
|
|
127
142
|
CODE_ALLOW_REGENERABLE: "All targets are git-ignored and match known "
|
|
@@ -509,6 +524,26 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
|
|
|
509
524
|
[f"protected: {s.protected} ({s.raw})"
|
|
510
525
|
for s in protected_other[:5]])
|
|
511
526
|
|
|
527
|
+
# Preserve the existing outer-boundary reason, including parents of the
|
|
528
|
+
# workspace. Explicit external quarantine housekeeping remains allowed.
|
|
529
|
+
protected_outside = [s for s in specs if s.protected == "outside-workspace"]
|
|
530
|
+
if protected_outside and not all(s.inside_trash for s in specs):
|
|
531
|
+
return Verdict(DECISION_BLOCK, CODE_BLOCK_OUT_OF_WORKSPACE,
|
|
532
|
+
[f"outside workspace boundary: {s.raw}"
|
|
533
|
+
for s in protected_outside[:5]])
|
|
534
|
+
|
|
535
|
+
try:
|
|
536
|
+
deletion_config = delete_config.load_config(ctx.workspace)
|
|
537
|
+
protection = delete_config.protected_reason(
|
|
538
|
+
[s.resolved for s in specs if s.resolved], ctx.workspace,
|
|
539
|
+
deletion_config)
|
|
540
|
+
except delete_config.DeleteConfigError as exc:
|
|
541
|
+
return Verdict(DECISION_BLOCK, CODE_BLOCK_DELETE_CONFIG_INVALID,
|
|
542
|
+
[str(exc)])
|
|
543
|
+
if protection:
|
|
544
|
+
return Verdict(DECISION_BLOCK, CODE_BLOCK_DELETE_PROTECTED,
|
|
545
|
+
[protection])
|
|
546
|
+
|
|
512
547
|
if specs and all(s.inside_trash for s in specs):
|
|
513
548
|
if any(s.wildcard for s in specs):
|
|
514
549
|
return Verdict(DECISION_BLOCK, CODE_BLOCK_WILDCARD,
|
|
@@ -516,13 +551,6 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
|
|
|
516
551
|
"enumerate explicitly with safe_delete"])
|
|
517
552
|
return Verdict(DECISION_ALLOW, CODE_ALLOW_TRASH_GC)
|
|
518
553
|
|
|
519
|
-
protected_outside = [s for s in specs
|
|
520
|
-
if s.protected == "outside-workspace"]
|
|
521
|
-
if protected_outside:
|
|
522
|
-
return Verdict(DECISION_BLOCK, CODE_BLOCK_OUT_OF_WORKSPACE,
|
|
523
|
-
[f"outside workspace boundary: {s.raw}"
|
|
524
|
-
for s in protected_outside[:5]])
|
|
525
|
-
|
|
526
554
|
wild = [s for s in specs if s.wildcard]
|
|
527
555
|
if wild:
|
|
528
556
|
return Verdict(DECISION_BLOCK, CODE_BLOCK_WILDCARD,
|
package/core/recovery.py
CHANGED
|
@@ -31,6 +31,7 @@ from typing import Any, Dict, List, Optional, Tuple
|
|
|
31
31
|
from . import MANIFEST_NAME, TRASH_DIRNAME
|
|
32
32
|
from .audit import new_txid, utc_now_iso
|
|
33
33
|
from .classifier import PathSpec, _physical, _physical_keep_final, inside_path
|
|
34
|
+
from . import admission
|
|
34
35
|
|
|
35
36
|
# Soft retention policy (docs/references: GC). Thresholds only MARK entries
|
|
36
37
|
# GC_ELIGIBLE; actual purging is an explicit maintenance action - a system
|
|
@@ -220,6 +221,15 @@ class RecoveryEngine:
|
|
|
220
221
|
|
|
221
222
|
def relocate(self, specs: List[PathSpec], txid: Optional[str] = None,
|
|
222
223
|
meta: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
|
224
|
+
"""Admit one relocation batch before starting its recovery journal."""
|
|
225
|
+
self.ensure_layout()
|
|
226
|
+
paths = [spec.resolved for spec in specs
|
|
227
|
+
if spec.resolved and not spec.wildcard and not spec.indeterminable]
|
|
228
|
+
with admission.admit(self.workspace, self.trash_root, paths):
|
|
229
|
+
return self._relocate_admitted(specs, txid=txid, meta=meta)
|
|
230
|
+
|
|
231
|
+
def _relocate_admitted(self, specs: List[PathSpec], txid: Optional[str] = None,
|
|
232
|
+
meta: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
|
223
233
|
"""Move every concrete target into trash/<txid>/<workspace-relative>.
|
|
224
234
|
|
|
225
235
|
Layout arithmetic uses PHYSICAL spellings on BOTH sides: the
|
package/docs/README.md
CHANGED
|
@@ -1,28 +1,41 @@
|
|
|
1
1
|
# Documentation / 文档导航
|
|
2
2
|
|
|
3
3
|
Start with [getting started](guides/getting-started.md) for installation and
|
|
4
|
-
setup. The three main
|
|
5
|
-
|
|
6
|
-
[behaviour experiments](lab/guard-lab.md). Use the
|
|
4
|
+
setup. The three main capabilities are **Exfil-guard**, **Delete-guard** and
|
|
5
|
+
**Guard-lab**. Use the
|
|
7
6
|
[harness capability matrix](guides/harness-capabilities.md) for observed coverage
|
|
8
7
|
and the [architecture](design/architecture.md) for the shared Core.
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
[
|
|
13
|
-
|
|
14
|
-
|
|
9
|
+
| Main capability / 主要功能 | Included functions and guides / 下属功能与指南 |
|
|
10
|
+
|---|---|
|
|
11
|
+
| **Exfil-guard** | [Text checks and redaction](../skills/exfil-guard/SKILL.md) · [Safe config view](../skills/exfil-guard/SKILL.md#safe-config-view) |
|
|
12
|
+
| **Delete-guard** | [Recoverable deletion](../skills/delete-guard/SKILL.md) · [Cleanup Copilot](guides/cleanup-plan.md) · [Deletion limits](guides/deletion-limits.md) · [Recovery and GC](guides/recovery-feedback.md) · [MCP tools](guides/mcp.md) · [MCP doctor (0.2.8)](guides/mcp.md#diagnose-a-local-service-028) |
|
|
13
|
+
| **Guard-lab** | [Controlled experiments and evidence](lab/guard-lab.md) · [Four zero-model controls](lab/blue-team-calibration.md) · [Defensive research](research/README.md) |
|
|
14
|
+
|
|
15
|
+
Cleanup Copilot, deletion admission and the current MCP tools/doctor are
|
|
16
|
+
Delete-guard functions. [Recovery-audit](../skills/recovery-audit/SKILL.md)
|
|
17
|
+
is an auxiliary incident-recovery workflow.
|
|
18
|
+
|
|
19
|
+
Version [0.2.8](releases/release-notes-0.2.8.md) adds MCP diagnosis and
|
|
20
|
+
recovery validation to the [0.2.7](releases/release-notes-0.2.7.md) baseline
|
|
21
|
+
of Cleanup plans, deletion admission and optional local MCP tools.
|
|
22
|
+
Before installing 0.2.8,
|
|
23
|
+
check the exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.8)
|
|
24
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.8)
|
|
25
|
+
for availability. A checkout or manifest does not establish publication or
|
|
26
|
+
the current npm `latest` channel.
|
|
15
27
|
The opt-in `rc` line remains [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md), and `hotfix` is the
|
|
16
28
|
opt-in [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
|
|
17
29
|
quarantine protection backport. The [getting-started guide](guides/getting-started.md)
|
|
18
30
|
explains exact-version and local-package installation.
|
|
19
31
|
|
|
20
|
-
[0.2.6](releases/release-notes-0.2.6.md) covers Kimi Stop feedback,
|
|
32
|
+
The earlier published [0.2.6](releases/release-notes-0.2.6.md) covers Kimi Stop feedback,
|
|
21
33
|
its doctor checks, Kimi 2.3.0 root-Bash compatibility, DSH Lab preflight
|
|
22
34
|
diagnostics and alpha.4 default deletion compatibility. Existing 0.2.5 installations
|
|
23
|
-
need an upgrade to acquire
|
|
35
|
+
need an upgrade to acquire those additions; see its [version notes](releases/release-notes-0.2.6.md).
|
|
24
36
|
|
|
25
|
-
|
|
37
|
+
先看入门指南,再按 Exfil-guard、Delete-guard、Guard-lab 三大功能选择入口。
|
|
38
|
+
Cleanup、删除限制与当前 MCP 工具/doctor 归入 Delete-guard。测试报告按所测版本与配置保留;发布记录、
|
|
26
39
|
历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
|
|
27
40
|
|
|
28
41
|
| Category / 分类 | Contents / 内容 |
|
|
@@ -44,6 +57,10 @@ ALLOW_NOOP 覆盖边界及准确 GC 用法;纳入 0.2.5。
|
|
|
44
57
|
|---|---|
|
|
45
58
|
| [Getting started](guides/getting-started.md) | 安装路径、Agent 接入提示词与最短验证流程 |
|
|
46
59
|
| [Status and cleanup feedback](guides/recovery-feedback.md) | Python/插件状态、ALLOW_NOOP、保留空间与手动 GC |
|
|
60
|
+
| [Cleanup Copilot](guides/cleanup-plan.md) | Delete-guard,0.2.7:零写入计划、四类候选、大小与显式确认执行 |
|
|
61
|
+
| [Deletion limits](guides/deletion-limits.md) | Delete-guard,0.2.7:隔离容量、会话预算、频率、保护路径与批量确认 |
|
|
62
|
+
| [Local MCP tools](guides/mcp.md) | Delete-guard,0.2.7:本地 stdio 安全删除、普通恢复、事务/状态和 GC 预览;不替代 hook |
|
|
63
|
+
| [MCP diagnosis](guides/mcp.md#diagnose-a-local-service-028) | Delete-guard,0.2.8:选定本地服务的依赖、握手、工作区绑定与只读调用检查 |
|
|
47
64
|
| [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
|
|
48
65
|
| [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
|
|
49
66
|
| [Trash locations](guides/trash-index.md) | 0.2.4 的只读位置查询、Agent/前端共享 JSON 契约 |
|
|
@@ -51,7 +68,9 @@ ALLOW_NOOP 覆盖边界及准确 GC 用法;纳入 0.2.5。
|
|
|
51
68
|
| [Publishing from ephemeral environments](guides/publishing-from-ephemeral-environments.md) | 临时环境中的 GitHub 发布操作参考 |
|
|
52
69
|
|
|
53
70
|
Adapter setup remains in [adapters/](../adapters/INTEGRATION.md). Skill contracts
|
|
54
|
-
|
|
71
|
+
are documented separately for [Exfil-guard](../skills/exfil-guard/SKILL.md) and
|
|
72
|
+
[Delete-guard](../skills/delete-guard/SKILL.md); the [Guard-lab guide](lab/guard-lab.md)
|
|
73
|
+
describes the user-controlled experiment CLI.
|
|
55
74
|
|
|
56
75
|
We currently focus on DSH and Kimi Code. Claude Code's adapter and past
|
|
57
76
|
reports remain available; testing new Claude versions is paused. For other
|
|
@@ -121,8 +140,10 @@ coverage rather than treating every historical result as current acceptance.
|
|
|
121
140
|
|
|
122
141
|
| Document / 文档 | Scope / 范围 |
|
|
123
142
|
|---|---|
|
|
143
|
+
| [0.2.8](releases/release-notes-0.2.8.md) | MCP 接入诊断、真实协议中断验证、安装与验收边界 |
|
|
144
|
+
| [0.2.7](releases/release-notes-0.2.7.md) | Cleanup、删除准入与MCP的版本范围、升级影响和准备阶段验证 |
|
|
124
145
|
| [0.2.6](releases/release-notes-0.2.6.md) | 正式版范围、升级影响与验收;Kimi 反馈/doctor、DSH 预检与版本扩展 |
|
|
125
|
-
| [
|
|
146
|
+
| [Changes and maintenance details](releases/unreleased.md) | 0.2.8 维护、0.2.7 范围及 0.2.6 历史,保留原验收边界 |
|
|
126
147
|
| [0.2.5](releases/release-notes-0.2.5.md) | 正式版范围;累计 RC 维护、明确反馈与升级影响 |
|
|
127
148
|
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 已发布的稳定线回收站保护回补;不含完整 RC 累计内容 |
|
|
128
149
|
| [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md) | 已发布的研究/文档预发布版与零模型示例 |
|
|
@@ -144,7 +165,7 @@ Current behavior is defined by the Core, Skills and current guides.
|
|
|
144
165
|
|
|
145
166
|
| Document / 文档 | Scope / 范围 |
|
|
146
167
|
|---|---|
|
|
147
|
-
| [Friction log](history/friction.md) | F1–
|
|
168
|
+
| [Friction log](history/friction.md) | F1–F34 实现发现与修复经验 |
|
|
148
169
|
| [Unguarded deletion note](history/development-note-unguarded-deletion.md) | 去标识化事故探索与恢复方向 |
|
|
149
170
|
| [Secret Guard analysis](history/secret-guard-analysis.md) | 实现前的需求分析 |
|
|
150
171
|
| [Secret Guard design](history/secret-guard-design.md) | 早期设计候选与原范围 |
|