repoward 0.1.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.
repoward/pipeline.py ADDED
@@ -0,0 +1,333 @@
1
+ """The single guarded call path. Every tool attempt goes through `Pipeline.call`."""
2
+
3
+ import json
4
+ import sys
5
+ import time
6
+ import uuid
7
+ from typing import Any
8
+
9
+ import anyio.to_thread
10
+ from mcp.types import CallToolResult, TextContent
11
+ from pydantic import ValidationError
12
+
13
+ from repoward.approvals.store import ApprovalStore, ApprovalStoreError, TooManyPendingError
14
+ from repoward.audit import AuditLog, AuditWriteError
15
+ from repoward.canonical import canonical_json, sha256_hex
16
+ from repoward.catalog import RiskClass
17
+ from repoward.flow import FlowGuard, FlowStoreError
18
+ from repoward.policy.engine import Decision, Effect, decide
19
+ from repoward.policy.loader import CompiledPolicy
20
+ from repoward.principal import Principal
21
+ from repoward.ratelimit import RateLimiter
22
+ from repoward.registry import ToolError, ToolInput, ToolRegistry, ToolSpec
23
+ from repoward.sanitize import redact_for_audit, redact_text, render_output
24
+
25
+ MAX_OUTPUT_CHARS = 100_000
26
+ _MAX_VALIDATION_ERRORS = 5
27
+
28
+
29
+ def _result(text: str, *, is_error: bool = False) -> CallToolResult:
30
+ return CallToolResult(content=[TextContent(type="text", text=text)], is_error=is_error)
31
+
32
+
33
+ def _hash_args(args: Any) -> str:
34
+ try:
35
+ return sha256_hex(canonical_json(args))
36
+ except (TypeError, ValueError):
37
+ return sha256_hex(repr(args).encode("utf-8", "replace"))
38
+
39
+
40
+ def alert(message: str) -> None:
41
+ """Report an operational problem on stderr. In stdio mode, stdout is the protocol."""
42
+ print(f"repoward: {message}", file=sys.stderr, flush=True)
43
+
44
+
45
+ def _describe_invalid_input(exc: ValidationError) -> str:
46
+ """Say what to fix without echoing the input back."""
47
+ details = [
48
+ f"{'.'.join(str(part) for part in error['loc']) or 'arguments'}: {error['msg']}"
49
+ for error in exc.errors(include_url=False, include_input=False, include_context=False)
50
+ ]
51
+ return "Invalid arguments. " + "; ".join(details[:_MAX_VALIDATION_ERRORS])
52
+
53
+
54
+ class Pipeline:
55
+ def __init__(
56
+ self,
57
+ policy: CompiledPolicy,
58
+ registry: ToolRegistry,
59
+ audit: AuditLog,
60
+ limiter: RateLimiter | None = None,
61
+ approvals: ApprovalStore | None = None,
62
+ flow: FlowGuard | None = None,
63
+ ) -> None:
64
+ self._policy = policy
65
+ self._registry = registry
66
+ self._audit = audit
67
+ self._limiter = limiter or RateLimiter(policy.rate_limits)
68
+ self._instance_id = str(uuid.uuid4())
69
+ self._approvals = approvals
70
+ self._flow = flow
71
+ self._degraded = False
72
+
73
+ async def call(
74
+ self,
75
+ principal: Principal,
76
+ tool: str,
77
+ raw_args: dict[str, Any] | None,
78
+ session_id: str | None = None,
79
+ ) -> CallToolResult:
80
+ request_id = str(uuid.uuid4())
81
+ args: Any = raw_args if raw_args is not None else {}
82
+ context: dict[str, Any] = {
83
+ "request_id": request_id,
84
+ "instance_id": self._instance_id,
85
+ "session_id": session_id,
86
+ "principal": principal.id,
87
+ "role": principal.role,
88
+ "tool": redact_for_audit(tool),
89
+ "policy_hash": self._policy.sha256,
90
+ }
91
+
92
+ spec = self._registry.get(tool)
93
+ if spec is None:
94
+ return await self._refuse(context, args, "tool.unknown", "Unknown tool.")
95
+
96
+ try:
97
+ validated = spec.input_model.model_validate(args)
98
+ except ValidationError as exc:
99
+ return await self._refuse(context, args, "input.invalid", _describe_invalid_input(exc))
100
+ normalized = validated.model_dump(mode="json")
101
+
102
+ decision = decide(self._policy, principal, tool, spec.risk, spec.target(validated))
103
+ if decision.effect is Effect.DENY:
104
+ return await self._refuse(context, normalized, decision.rule_id, decision.message)
105
+
106
+ mutating = spec.risk is not RiskClass.READ
107
+ repo = spec.target(validated).repo
108
+ if mutating and self._flow is not None:
109
+ flow_decision = await self._flow.check_write(principal.id, repo)
110
+ decision = self._combine(decision, flow_decision)
111
+ if decision.effect is Effect.DENY:
112
+ return await self._refuse(context, normalized, decision.rule_id, decision.message)
113
+
114
+ hit = self._limiter.check(principal.id, tool)
115
+ if hit is not None:
116
+ message = f"Rate limit reached. Try again in {hit.retry_after_seconds} seconds."
117
+ return await self._refuse(context, normalized, hit.rule_id, message)
118
+
119
+ if mutating and self._degraded:
120
+ return await self._refuse(
121
+ context,
122
+ normalized,
123
+ "audit.degraded",
124
+ "Changes are disabled because the audit log failed. An operator must restart.",
125
+ )
126
+
127
+ rule_id = decision.rule_id
128
+ if decision.effect is Effect.APPROVAL_REQUIRED:
129
+ args_hash = _hash_args(normalized)
130
+ try:
131
+ approval_id = await self._consume_approval(principal, tool, repo, args_hash)
132
+ except ApprovalStoreError as exc:
133
+ alert(str(exc))
134
+ return await self._refuse(
135
+ context,
136
+ normalized,
137
+ "approvals.unavailable",
138
+ "This action needs approval, but approvals are unavailable right now.",
139
+ )
140
+ if approval_id is None:
141
+ return await self._request_approval(
142
+ context, principal, spec, validated, normalized, decision.rule_id, repo
143
+ )
144
+ context = {**context, "approval_id": approval_id}
145
+ rule_id = "approvals.consumed"
146
+
147
+ try:
148
+ await self._write(self._decision_fields(context, normalized, Effect.ALLOW, rule_id))
149
+ except AuditWriteError as exc:
150
+ alert(f"audit decision record failed: {exc}")
151
+ if mutating:
152
+ return _result(
153
+ "The action was not performed because it could not be audited.", is_error=True
154
+ )
155
+
156
+ started = time.monotonic()
157
+ status = "ok"
158
+ error: str | None = None
159
+ try:
160
+ output = await spec.handler(validated)
161
+ if not mutating and self._flow is not None:
162
+ # Saved before the content is returned: unrecorded content is never handed over.
163
+ for kind, source in await self._flow.record_read(principal.id, repo, output.taints):
164
+ await self._record_label(context, kind, source)
165
+ result = _result(render_output(output.text, output.untrusted, MAX_OUTPUT_CHARS))
166
+ except FlowStoreError as exc:
167
+ status = "error"
168
+ error = type(exc).__name__
169
+ alert(f"flow guard could not save state: {exc}")
170
+ result = _result(
171
+ "The content was withheld because it could not be tracked.", is_error=True
172
+ )
173
+ except ToolError as exc:
174
+ status = "error"
175
+ error = redact_text(str(exc))
176
+ result = _result(error, is_error=True)
177
+ except Exception as exc:
178
+ status = "error"
179
+ error = type(exc).__name__
180
+ alert(f"tool {tool} failed: {error}")
181
+ result = _result("The tool failed unexpectedly.", is_error=True)
182
+
183
+ try:
184
+ await self._write(
185
+ {
186
+ "event": "tool_call_outcome",
187
+ "request_id": request_id,
188
+ "result_status": status,
189
+ "duration_ms": int((time.monotonic() - started) * 1000),
190
+ "error": error,
191
+ }
192
+ )
193
+ except AuditWriteError as exc:
194
+ alert(f"audit outcome record failed: {exc}")
195
+ if mutating:
196
+ self._degraded = True
197
+ alert("degraded mode: refusing further changes until restart")
198
+ warning = "Warning: the action ran but its outcome could not be audited."
199
+ result.content.append(TextContent(type="text", text=warning))
200
+ return result
201
+
202
+ @staticmethod
203
+ def _combine(decision: Decision, flow: Decision | None) -> Decision:
204
+ """Apply the flow guard, which can only tighten what policy decided."""
205
+ if flow is None or flow.effect is Effect.ALLOW or decision.effect is Effect.DENY:
206
+ return decision
207
+ if flow.effect is Effect.APPROVAL_REQUIRED and decision.effect is Effect.APPROVAL_REQUIRED:
208
+ return decision
209
+ return flow
210
+
211
+ async def _record_label(self, context: dict[str, Any], kind: str, source: str) -> None:
212
+ try:
213
+ await self._write(
214
+ {
215
+ "event": "flow_label",
216
+ "request_id": context["request_id"],
217
+ "principal": context["principal"],
218
+ "kind": kind,
219
+ "source": source,
220
+ }
221
+ )
222
+ except AuditWriteError as exc:
223
+ alert(f"audit flow label record failed: {exc}")
224
+
225
+ async def _consume_approval(
226
+ self, principal: Principal, tool: str, repo: str | None, args_hash: str
227
+ ) -> str | None:
228
+ if self._approvals is None:
229
+ raise ApprovalStoreError("no approval store is configured")
230
+ return await anyio.to_thread.run_sync(
231
+ self._approvals.consume, principal.id, tool, repo, args_hash
232
+ )
233
+
234
+ async def _request_approval(
235
+ self,
236
+ context: dict[str, Any],
237
+ principal: Principal,
238
+ spec: ToolSpec,
239
+ validated: ToolInput,
240
+ normalized: Any,
241
+ rule_id: str,
242
+ repo: str | None,
243
+ ) -> CallToolResult:
244
+ """Record a request for a human. The tool does not run."""
245
+ assert self._approvals is not None # noqa: S101
246
+ details = ""
247
+ if spec.approval_context is not None:
248
+ try:
249
+ details = await spec.approval_context(validated)
250
+ except Exception as exc:
251
+ details = "Could not fetch details from GitHub."
252
+ alert(f"approval context failed: {type(exc).__name__}")
253
+ if self._flow is not None:
254
+ try:
255
+ note = await self._flow.describe(principal.id)
256
+ except FlowStoreError as exc:
257
+ note = "Flow guard state is unavailable."
258
+ alert(str(exc))
259
+ details = "\n".join(part for part in (details, note) if part)
260
+ try:
261
+ approval = await anyio.to_thread.run_sync(
262
+ self._approvals.request,
263
+ principal.id,
264
+ spec.name,
265
+ repo,
266
+ _hash_args(normalized),
267
+ json.dumps(redact_for_audit(normalized), ensure_ascii=True, sort_keys=True),
268
+ redact_text(details),
269
+ )
270
+ except TooManyPendingError:
271
+ return await self._refuse(
272
+ context,
273
+ normalized,
274
+ "approvals.too_many_pending",
275
+ "Too many approval requests are waiting. Ask a human to review them.",
276
+ )
277
+ except ApprovalStoreError as exc:
278
+ alert(str(exc))
279
+ return await self._refuse(
280
+ context,
281
+ normalized,
282
+ "approvals.unavailable",
283
+ "This action needs approval, but approvals are unavailable right now.",
284
+ )
285
+ await self._record_refusal(
286
+ {**context, "approval_id": approval.id},
287
+ normalized,
288
+ Effect.APPROVAL_REQUIRED,
289
+ rule_id,
290
+ )
291
+ body = {
292
+ "status": "approval_required",
293
+ "approval_id": approval.id,
294
+ "summary": (
295
+ f"{spec.name} was not run. A human must approve request {approval.id}; "
296
+ "then call the tool again with the same arguments."
297
+ ),
298
+ }
299
+ return CallToolResult(
300
+ content=[TextContent(type="text", text=json.dumps(body))],
301
+ structured_content=body,
302
+ )
303
+
304
+ @staticmethod
305
+ def _decision_fields(
306
+ context: dict[str, Any], args: Any, effect: Effect, rule_id: str
307
+ ) -> dict[str, Any]:
308
+ return {
309
+ **context,
310
+ "event": "tool_call_decision",
311
+ "args_redacted": redact_for_audit(args, hide_content=True),
312
+ "args_hash": _hash_args(args),
313
+ "decision": effect.value,
314
+ "rule_id": rule_id,
315
+ }
316
+
317
+ async def _write(self, fields: dict[str, Any]) -> None:
318
+ await anyio.to_thread.run_sync(self._audit.append, fields)
319
+
320
+ async def _record_refusal(
321
+ self, context: dict[str, Any], args: Any, effect: Effect, rule_id: str
322
+ ) -> None:
323
+ """Log an attempt that will not execute. Failing to log never turns it into a yes."""
324
+ try:
325
+ await self._write(self._decision_fields(context, args, effect, rule_id))
326
+ except AuditWriteError as exc:
327
+ alert(f"audit decision record failed: {exc}")
328
+
329
+ async def _refuse(
330
+ self, context: dict[str, Any], args: Any, rule_id: str, message: str
331
+ ) -> CallToolResult:
332
+ await self._record_refusal(context, args, Effect.DENY, rule_id)
333
+ return _result(message, is_error=True)
@@ -0,0 +1 @@
1
+ """Policy models, strict loading and decisions."""
@@ -0,0 +1,101 @@
1
+ """The policy decision. Pure logic with no I/O, and default-deny."""
2
+
3
+ from collections.abc import Sequence
4
+ from dataclasses import dataclass
5
+ from enum import StrEnum
6
+
7
+ from repoward.catalog import RiskClass
8
+ from repoward.policy.loader import CompiledPolicy
9
+ from repoward.principal import Principal
10
+ from repoward.sanitize import contains_secret
11
+
12
+
13
+ class Effect(StrEnum):
14
+ ALLOW = "allow"
15
+ DENY = "deny"
16
+ APPROVAL_REQUIRED = "approval_required"
17
+
18
+
19
+ @dataclass(frozen=True)
20
+ class Target:
21
+ """What a call touches. Paths must already be normalized by the input model."""
22
+
23
+ repo: str | None = None
24
+ paths: Sequence[str] = ()
25
+ write_branches: Sequence[str] = ()
26
+ non_draft: bool = False
27
+ commit_files: int = 0
28
+ commit_bytes: int = 0
29
+ outbound: Sequence[str] = ()
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class Decision:
34
+ effect: Effect
35
+ rule_id: str
36
+ message: str = ""
37
+
38
+
39
+ def decide(
40
+ compiled: CompiledPolicy,
41
+ principal: Principal,
42
+ tool: str,
43
+ risk: RiskClass,
44
+ target: Target,
45
+ ) -> Decision:
46
+ """Decide one call. Messages reach the agent, so they reveal no policy details."""
47
+ role = compiled.roles.get(principal.role)
48
+ if role is None:
49
+ return Decision(Effect.DENY, "role.unknown", "Your role is not permitted to use tools.")
50
+ if tool not in role.tools:
51
+ return Decision(
52
+ Effect.DENY,
53
+ "default.deny",
54
+ f"Tool {tool} is not permitted for role {principal.role}; ask a maintainer.",
55
+ )
56
+ if risk is RiskClass.DANGEROUS:
57
+ switch = compiled.policy.dangerous_tools.get(tool)
58
+ if switch is None or not switch.enabled:
59
+ return Decision(
60
+ Effect.DENY,
61
+ f"dangerous_tools.{tool}.disabled",
62
+ f"Tool {tool} is disabled in this deployment.",
63
+ )
64
+ if target.repo is not None and target.repo.casefold() not in compiled.allowed_repos:
65
+ return Decision(Effect.DENY, "repos.allow", "This repository is not permitted.")
66
+ for path in target.paths:
67
+ if compiled.path_is_denied(path):
68
+ return Decision(Effect.DENY, "paths.deny", "A requested path is not permitted.")
69
+ prefix = compiled.policy.branches.write_prefix
70
+ if any(not branch.startswith(prefix) for branch in target.write_branches):
71
+ return Decision(
72
+ Effect.DENY,
73
+ "branches.write_prefix",
74
+ f"Writes are only permitted on branches starting with {prefix}",
75
+ )
76
+ if target.non_draft and not compiled.policy.pull_requests.allow_non_draft:
77
+ return Decision(
78
+ Effect.DENY,
79
+ "pull_requests.allow_non_draft",
80
+ "Only draft pull requests are permitted.",
81
+ )
82
+ limits = role.commit_limits
83
+ if target.commit_files > limits.max_files or target.commit_bytes > limits.max_bytes:
84
+ return Decision(
85
+ Effect.DENY,
86
+ "roles.commit_limits",
87
+ f"Commits are limited to {limits.max_files} files and {limits.max_bytes} bytes.",
88
+ )
89
+ if any(contains_secret(text) for text in target.outbound):
90
+ return Decision(
91
+ Effect.DENY,
92
+ "secrets.outbound",
93
+ "The content appears to contain a credential, so it was not sent.",
94
+ )
95
+ if tool in role.require_approval:
96
+ return Decision(
97
+ Effect.APPROVAL_REQUIRED,
98
+ f"roles.{principal.role}.require_approval",
99
+ "This action requires human approval.",
100
+ )
101
+ return Decision(Effect.ALLOW, f"roles.{principal.role}.tools")
@@ -0,0 +1,245 @@
1
+ """Strict policy loading. Every problem is reported with its line number."""
2
+
3
+ from dataclasses import dataclass, field
4
+ from pathlib import Path
5
+ from typing import Any
6
+
7
+ import pathspec
8
+ import yaml
9
+ from pydantic import ValidationError
10
+
11
+ from repoward.canonical import sha256_hex
12
+ from repoward.catalog import TOOL_CATALOG, RiskClass
13
+ from repoward.policy.models import CommitLimits, Policy
14
+
15
+ _MAX_POLICY_BYTES = 1_000_000
16
+ _Loc = tuple[str | int, ...]
17
+
18
+
19
+ @dataclass(frozen=True)
20
+ class PolicyIssue:
21
+ message: str
22
+ line: int | None = None
23
+ column: int | None = None
24
+
25
+
26
+ class PolicyError(Exception):
27
+ def __init__(self, issues: list[PolicyIssue]) -> None:
28
+ super().__init__("; ".join(issue.message for issue in issues))
29
+ self.issues = issues
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class ResolvedRole:
34
+ tools: frozenset[str]
35
+ require_approval: frozenset[str]
36
+ commit_limits: CommitLimits = field(default_factory=CommitLimits)
37
+
38
+
39
+ @dataclass(frozen=True)
40
+ class CompiledPolicy:
41
+ policy: Policy
42
+ sha256: str
43
+ roles: dict[str, ResolvedRole]
44
+ allowed_repos: frozenset[str]
45
+ denied_paths: pathspec.PathSpec[Any]
46
+ rate_limits: dict[str, int]
47
+
48
+ def path_is_denied(self, normalized_path: str) -> bool:
49
+ return self.denied_paths.match_file(normalized_path.casefold())
50
+
51
+
52
+ def _issue_at(message: str, mark: yaml.Mark) -> PolicyIssue:
53
+ return PolicyIssue(message, mark.line + 1, mark.column + 1)
54
+
55
+
56
+ def _structure_issues(text: str) -> list[PolicyIssue]:
57
+ """Reject YAML features that can silently change meaning."""
58
+ issues: list[PolicyIssue] = []
59
+ for event in yaml.parse(text, Loader=yaml.SafeLoader):
60
+ if isinstance(event, yaml.AliasEvent) or getattr(event, "anchor", None):
61
+ issues.append(_issue_at("YAML anchors and aliases are not allowed", event.start_mark))
62
+
63
+ def walk(node: yaml.Node) -> None:
64
+ if isinstance(node, yaml.MappingNode):
65
+ seen: set[str] = set()
66
+ for key, value in node.value:
67
+ if key.tag == "tag:yaml.org,2002:merge":
68
+ issues.append(_issue_at("YAML merge keys are not allowed", key.start_mark))
69
+ elif isinstance(key, yaml.ScalarNode):
70
+ if key.value in seen:
71
+ issues.append(_issue_at(f"duplicate key '{key.value}'", key.start_mark))
72
+ seen.add(key.value)
73
+ walk(value)
74
+ elif isinstance(node, yaml.SequenceNode):
75
+ for item in node.value:
76
+ walk(item)
77
+
78
+ if not issues:
79
+ root = yaml.compose(text, Loader=yaml.SafeLoader)
80
+ if root is not None:
81
+ walk(root)
82
+ return issues
83
+
84
+
85
+ def _locate(root: yaml.Node | None, loc: _Loc) -> tuple[int | None, int | None]:
86
+ """Find the deepest YAML node on a path, for error reporting."""
87
+ if root is None:
88
+ return None, None
89
+ node = root
90
+ for part in loc:
91
+ child: yaml.Node | None = None
92
+ if isinstance(node, yaml.MappingNode):
93
+ for key, value in node.value:
94
+ if isinstance(key, yaml.ScalarNode) and key.value == str(part):
95
+ child = value
96
+ break
97
+ elif (
98
+ isinstance(node, yaml.SequenceNode) and isinstance(part, int) and part < len(node.value)
99
+ ):
100
+ child = node.value[part]
101
+ if child is None:
102
+ break
103
+ node = child
104
+ return node.start_mark.line + 1, node.start_mark.column + 1
105
+
106
+
107
+ def _resolve_roles(policy: Policy, problems: list[tuple[str, _Loc]]) -> dict[str, ResolvedRole]:
108
+ resolved: dict[str, ResolvedRole] = {}
109
+ reported: set[str] = set()
110
+
111
+ def fail(name: str, message: str) -> None:
112
+ if name not in reported:
113
+ reported.add(name)
114
+ problems.append((message, ("roles", name, "inherits")))
115
+
116
+ def resolve(name: str, chain: tuple[str, ...]) -> ResolvedRole | None:
117
+ if name in resolved:
118
+ return resolved[name]
119
+ role = policy.roles[name]
120
+ tools = set(role.tools)
121
+ approvals = set(role.require_approval)
122
+ limits = role.commit_limits
123
+ if role.inherits is not None:
124
+ if role.inherits == name or role.inherits in chain:
125
+ fail(name, f"role '{name}' has an inheritance cycle")
126
+ return None
127
+ if role.inherits not in policy.roles:
128
+ fail(name, f"role '{name}' inherits unknown role '{role.inherits}'")
129
+ return None
130
+ parent = resolve(role.inherits, (*chain, name))
131
+ if parent is None:
132
+ return None
133
+ tools |= parent.tools
134
+ approvals |= parent.require_approval
135
+ limits = limits or parent.commit_limits
136
+ result = ResolvedRole(frozenset(tools), frozenset(approvals), limits or CommitLimits())
137
+ resolved[name] = result
138
+ return result
139
+
140
+ for name in policy.roles:
141
+ resolve(name, ())
142
+ return resolved
143
+
144
+
145
+ def _semantic_problems(policy: Policy, resolved: dict[str, ResolvedRole]) -> list[tuple[str, _Loc]]:
146
+ problems: list[tuple[str, _Loc]] = []
147
+ for name, role in policy.roles.items():
148
+ for section, tools in (("tools", role.tools), ("require_approval", role.require_approval)):
149
+ for index, tool in enumerate(tools):
150
+ if tool not in TOOL_CATALOG:
151
+ problems.append((f"unknown tool '{tool}'", ("roles", name, section, index)))
152
+ effective = resolved.get(name)
153
+ if effective is None:
154
+ continue
155
+ for tool in sorted(effective.require_approval - effective.tools):
156
+ problems.append(
157
+ (f"role '{name}' requires approval for '{tool}' but lacks it", ("roles", name))
158
+ )
159
+ for tool in sorted(effective.tools):
160
+ if (
161
+ TOOL_CATALOG.get(tool) is RiskClass.DANGEROUS
162
+ and tool not in effective.require_approval
163
+ ):
164
+ problems.append(
165
+ (f"dangerous tool '{tool}' in role '{name}' needs approval", ("roles", name))
166
+ )
167
+ for tool in policy.dangerous_tools:
168
+ if TOOL_CATALOG.get(tool) is not RiskClass.DANGEROUS:
169
+ problems.append((f"'{tool}' is not a dangerous tool", ("dangerous_tools", tool)))
170
+ if "default" not in policy.rate_limits:
171
+ problems.append(("rate_limits must define 'default'", ("rate_limits",)))
172
+ for tool in policy.rate_limits:
173
+ if tool != "default" and tool not in TOOL_CATALOG:
174
+ problems.append((f"unknown tool '{tool}'", ("rate_limits", tool)))
175
+ if policy.stdio.role not in policy.roles:
176
+ problems.append((f"stdio role '{policy.stdio.role}' is not defined", ("stdio", "role")))
177
+ for index, pattern in enumerate(policy.paths.deny):
178
+ if not pattern.strip() or pattern.startswith("!"):
179
+ problems.append(
180
+ ("path patterns must not be empty or negated", ("paths", "deny", index))
181
+ )
182
+ return problems
183
+
184
+
185
+ def parse_policy(data: bytes) -> CompiledPolicy:
186
+ if len(data) > _MAX_POLICY_BYTES:
187
+ raise PolicyError([PolicyIssue("policy file is too large")])
188
+ try:
189
+ text = data.decode("utf-8")
190
+ except UnicodeDecodeError as exc:
191
+ raise PolicyError([PolicyIssue("policy file must be UTF-8")]) from exc
192
+
193
+ try:
194
+ structure = _structure_issues(text)
195
+ if structure:
196
+ raise PolicyError(structure)
197
+ root = yaml.compose(text, Loader=yaml.SafeLoader)
198
+ raw: Any = yaml.safe_load(text)
199
+ except yaml.MarkedYAMLError as exc:
200
+ mark = exc.problem_mark
201
+ line = mark.line + 1 if mark else None
202
+ column = mark.column + 1 if mark else None
203
+ raise PolicyError([PolicyIssue(f"invalid YAML: {exc.problem}", line, column)]) from exc
204
+ except yaml.YAMLError as exc:
205
+ raise PolicyError([PolicyIssue("invalid YAML")]) from exc
206
+
207
+ try:
208
+ policy = Policy.model_validate(raw)
209
+ except ValidationError as exc:
210
+ issues = []
211
+ for error in exc.errors(include_url=False, include_input=False):
212
+ loc = tuple(error["loc"])
213
+ line, column = _locate(root, loc)
214
+ where = ".".join(str(part) for part in loc)
215
+ issues.append(PolicyIssue(f"{where}: {error['msg']}", line, column))
216
+ raise PolicyError(issues) from exc
217
+
218
+ problems: list[tuple[str, _Loc]] = []
219
+ resolved = _resolve_roles(policy, problems)
220
+ problems += _semantic_problems(policy, resolved)
221
+ if problems:
222
+ issues = []
223
+ for message, loc in problems:
224
+ line, column = _locate(root, loc)
225
+ issues.append(PolicyIssue(message, line, column))
226
+ raise PolicyError(issues)
227
+
228
+ return CompiledPolicy(
229
+ policy=policy,
230
+ sha256=sha256_hex(data),
231
+ roles=resolved,
232
+ allowed_repos=frozenset(repo.casefold() for repo in policy.repos.allow),
233
+ denied_paths=pathspec.PathSpec.from_lines(
234
+ "gitignore", [pattern.casefold() for pattern in policy.paths.deny]
235
+ ),
236
+ rate_limits={tool: limit.per_minute for tool, limit in policy.rate_limits.items()},
237
+ )
238
+
239
+
240
+ def load_policy(path: Path) -> CompiledPolicy:
241
+ try:
242
+ data = path.read_bytes()
243
+ except OSError as exc:
244
+ raise PolicyError([PolicyIssue(f"cannot read policy file: {exc.strerror}")]) from exc
245
+ return parse_policy(data)