fix(mcp): surface safe diagnostics for opaque mutation internal_error
Mutation tools (create_issue, create_pr, delete_branch, issue-lock) returned reason_code=internal_error / retryable=false with no class, message, HTTP status, or actionable detail. The #699/#701 tool-error boundary intentionally collapses every non-typed exception to a fixed "Internal tool error" and drops the class and message, so a mutation failure is undiagnosable — and the #695 runtime guard blocks standalone reproduction. The true failing stage was therefore invisible by two independent mechanisms. Make the failure observable and actionable without weakening the secret-free contract: - Boundary (internal_error path ONLY): capture a safe exception class (a Python type identifier, never instance text) plus a strictly-redacted `detail` (token/Authorization/Bearer credentials, JSON/kv secret values incl. short passwords, raw URLs/hostnames, and absolute filesystem paths all stripped; whitespace collapsed; length-bounded) and an optional `mutation_stage`. Typed auth/authz/network/config/http paths are unchanged and still emit no detail. - Convert raw exceptions into typed structured errors via a safe `gitea_reason_code` attribute contract: server raisers may self-declare a known reason and the boundary emits it (fixed message) instead of an opaque internal_error. Pre-flight order violations now raise `_PreflightOrderError` (a RuntimeError subclass → preflight_order_violation). - Add a `_mutation_stage` context manager tagging escaping exceptions with the stage name (preflight_purity / resolve_auth / api_*), applied to delete_branch, create_issue, create_pr. Fail-closed identity/repo/worktree/role/permission/lock/lease/ancestry gates are untouched; only error *reporting* changed. New suite test_mutation_error_diagnostics.py (18 tests) pins the redaction, class capture, stage tagging, typed conversion, and adversarial no-leak contract. Existing boundary suite (25), core server (209), and preflight (92) suites stay green. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
This commit is contained in:
Claude Opus 4.8
+185
-2
@@ -23,6 +23,7 @@ from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
import re
|
||||
import sys
|
||||
from typing import Any
|
||||
|
||||
@@ -38,6 +39,9 @@ REASON_CONFIG_ERROR = "config_error"
|
||||
REASON_INTERNAL_ERROR = "internal_error"
|
||||
REASON_UPSTREAM_UNAVAILABLE = "upstream_unavailable"
|
||||
REASON_HTTP_ERROR = "http_error"
|
||||
# Typed structured errors for previously-opaque raw mutation failures.
|
||||
REASON_PREFLIGHT_ORDER = "preflight_order_violation"
|
||||
REASON_MALFORMED_RESPONSE = "malformed_response"
|
||||
|
||||
ERROR_CLASS_AUTHENTICATION = "authentication"
|
||||
ERROR_CLASS_AUTHORIZATION = "authorization"
|
||||
@@ -45,6 +49,7 @@ ERROR_CLASS_NETWORK = "network"
|
||||
ERROR_CLASS_CONFIGURATION = "configuration"
|
||||
ERROR_CLASS_INTERNAL = "internal"
|
||||
ERROR_CLASS_UPSTREAM = "upstream"
|
||||
ERROR_CLASS_PRECONDITION = "precondition"
|
||||
|
||||
# Fixed, secret-free operator messages. Never interpolate HTTP bodies,
|
||||
# Keychain contents, tokens, or arbitrary exception text.
|
||||
@@ -62,12 +67,128 @@ FIXED_MESSAGES: dict[str, str] = {
|
||||
REASON_INTERNAL_ERROR: "Internal tool error",
|
||||
REASON_UPSTREAM_UNAVAILABLE: "Gitea upstream unavailable",
|
||||
REASON_HTTP_ERROR: "Gitea HTTP request failed",
|
||||
REASON_PREFLIGHT_ORDER: (
|
||||
"Mutation blocked: pre-flight order violation (fail closed)"
|
||||
),
|
||||
REASON_MALFORMED_RESPONSE: "Malformed response from Gitea",
|
||||
}
|
||||
|
||||
# Error class for a self-declared safe reason code (``gitea_reason_code``).
|
||||
_REASON_ERROR_CLASS: dict[str, str] = {
|
||||
REASON_AUTH_FAILED: ERROR_CLASS_AUTHENTICATION,
|
||||
REASON_AUTH_INVALID_TOKEN: ERROR_CLASS_AUTHENTICATION,
|
||||
REASON_AUTHZ_INSUFFICIENT_SCOPE: ERROR_CLASS_AUTHORIZATION,
|
||||
REASON_AUTHZ_DENIED: ERROR_CLASS_AUTHORIZATION,
|
||||
REASON_NETWORK_ERROR: ERROR_CLASS_NETWORK,
|
||||
REASON_CONFIG_ERROR: ERROR_CLASS_CONFIGURATION,
|
||||
REASON_UPSTREAM_UNAVAILABLE: ERROR_CLASS_UPSTREAM,
|
||||
REASON_HTTP_ERROR: ERROR_CLASS_INTERNAL,
|
||||
REASON_PREFLIGHT_ORDER: ERROR_CLASS_PRECONDITION,
|
||||
REASON_MALFORMED_RESPONSE: ERROR_CLASS_INTERNAL,
|
||||
REASON_INTERNAL_ERROR: ERROR_CLASS_INTERNAL,
|
||||
}
|
||||
|
||||
# Bounds for the safe diagnostic fields added to the ``internal_error`` path.
|
||||
_DETAIL_LIMIT = 200
|
||||
_CLASS_LIMIT = 120
|
||||
_STAGE_LIMIT = 64
|
||||
|
||||
# Absolute-path prefixes stripped from diagnostic detail (never leak layout).
|
||||
_ABS_PATH_RE = re.compile(r"/(?:Users|home|private|var|tmp|opt|etc|root)/[^\s'\"]*")
|
||||
_DETAIL_SECRET_PREFIXES = ("token ", "Basic ", "Bearer ", "Authorization: ")
|
||||
_SECRET_KEY = (
|
||||
r"token|password|passwd|secret|authorization|api[_-]?key|"
|
||||
r"access[_-]?token|refresh[_-]?token|session|cookie"
|
||||
)
|
||||
_SECRET_JSON_RE = re.compile(
|
||||
r'"(' + _SECRET_KEY + r')"\s*:\s*"[^"]*"', re.IGNORECASE
|
||||
)
|
||||
_SECRET_KV_RE = re.compile(
|
||||
r"\b(" + _SECRET_KEY + r")\s*=\s*[^\s&\"']+", re.IGNORECASE
|
||||
)
|
||||
|
||||
_MUTATION_STAGE_ATTR = "_gitea_mutation_stage"
|
||||
_SELF_DECLARED_REASON_ATTR = "gitea_reason_code"
|
||||
|
||||
_INSTALL_FLAG = "_gitea_auth_boundary_installed"
|
||||
_ORIGINAL_ATTR = "_gitea_auth_boundary_original"
|
||||
|
||||
|
||||
def _safe_str(exc: BaseException) -> str:
|
||||
"""``str(exc)`` that never raises (a poisoned ``__str__`` must not escape)."""
|
||||
try:
|
||||
return str(exc)
|
||||
except Exception:
|
||||
return ""
|
||||
|
||||
|
||||
def _safe_exception_class(exc: BaseException) -> str:
|
||||
"""Fully-qualified type identifier for *exc* — never instance/message text."""
|
||||
try:
|
||||
t = type(exc)
|
||||
mod = getattr(t, "__module__", "") or ""
|
||||
name = getattr(t, "__qualname__", None) or getattr(t, "__name__", "") or ""
|
||||
ident = f"{mod}.{name}" if mod else name
|
||||
return ident[:_CLASS_LIMIT]
|
||||
except Exception:
|
||||
return "unknown"
|
||||
|
||||
|
||||
def _redact_detail(text: Any, limit: int = _DETAIL_LIMIT) -> str:
|
||||
"""Strictly redact free-form exception text for safe diagnostics.
|
||||
|
||||
Removes token/Authorization credentials, raw URLs and hostnames (via the
|
||||
shared audit redactor), and absolute filesystem paths, then collapses
|
||||
whitespace and truncates. Never raises; on any failure returns "".
|
||||
"""
|
||||
if not text:
|
||||
return ""
|
||||
try:
|
||||
out = str(text)
|
||||
# Drop credential-prefixed runs (token/Basic/Bearer/Authorization).
|
||||
for prefix in _DETAIL_SECRET_PREFIXES:
|
||||
idx = 0
|
||||
while True:
|
||||
i = out.find(prefix, idx)
|
||||
if i == -1:
|
||||
break
|
||||
j = i + len(prefix)
|
||||
while j < len(out) and not out[j].isspace():
|
||||
j += 1
|
||||
out = out[:i] + prefix + "[REDACTED]" + out[j:]
|
||||
idx = i + len(prefix) + len("[REDACTED]")
|
||||
# Secret VALUES carried in JSON ("key":"value") or kv (key=value) form,
|
||||
# even short ones (e.g. a password), keyed by a sensitive field name.
|
||||
out = _SECRET_JSON_RE.sub(r'"\1":"[REDACTED]"', out)
|
||||
out = _SECRET_KV_RE.sub(r"\1=[REDACTED]", out)
|
||||
# URLs / query secrets / hostnames.
|
||||
try:
|
||||
import gitea_audit
|
||||
|
||||
out = gitea_audit.redact_urls(out)
|
||||
except Exception:
|
||||
pass
|
||||
# Absolute filesystem paths (workspace layout is not for LLM output).
|
||||
out = _ABS_PATH_RE.sub("[PATH]", out)
|
||||
# Any bare hostname the URL redactor missed (defence in depth).
|
||||
out = re.sub(r"\b[\w.-]+\.(?:cc|net|com|org|io|dev|local)\b", "[HOST]", out)
|
||||
out = " ".join(out.split())
|
||||
return out[:limit]
|
||||
except Exception:
|
||||
return ""
|
||||
|
||||
|
||||
def _safe_mutation_stage(exc: BaseException) -> str | None:
|
||||
"""Return the bounded, redacted mutation stage tagged on *exc* (or None)."""
|
||||
try:
|
||||
raw = getattr(exc, _MUTATION_STAGE_ATTR, None)
|
||||
if not raw:
|
||||
return None
|
||||
return _redact_detail(raw, limit=_STAGE_LIMIT) or None
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
|
||||
def fixed_message(reason_code: str) -> str:
|
||||
"""Return the fixed sanitized message for *reason_code* (fail closed)."""
|
||||
return FIXED_MESSAGES.get(reason_code, FIXED_MESSAGES[REASON_INTERNAL_ERROR])
|
||||
@@ -154,9 +275,34 @@ def classify_exception(exc: BaseException) -> dict[str, Any]:
|
||||
}
|
||||
|
||||
|
||||
def _self_declared_classification(exc: BaseException) -> dict[str, Any] | None:
|
||||
"""Honor a safe ``gitea_reason_code`` attribute set by server-side raisers.
|
||||
|
||||
Converts a raw exception that self-declares a **known** reason code into a
|
||||
typed structured error (fixed message) instead of an opaque internal_error.
|
||||
Unknown / non-string / secret values are ignored (fail closed to internal).
|
||||
"""
|
||||
reason = getattr(exc, _SELF_DECLARED_REASON_ATTR, None)
|
||||
if not isinstance(reason, str) or reason not in FIXED_MESSAGES:
|
||||
return None
|
||||
if reason == REASON_INTERNAL_ERROR:
|
||||
return None
|
||||
return {
|
||||
"reason_code": reason,
|
||||
"error_class": _REASON_ERROR_CLASS.get(reason, ERROR_CLASS_INTERNAL),
|
||||
"http_status": None,
|
||||
"message": fixed_message(reason),
|
||||
"transport_survives": True,
|
||||
}
|
||||
|
||||
|
||||
def _classify_exception_impl(exc: BaseException) -> dict[str, Any]:
|
||||
import gitea_auth
|
||||
|
||||
declared = _self_declared_classification(exc)
|
||||
if declared is not None:
|
||||
return declared
|
||||
|
||||
if isinstance(exc, gitea_auth.GiteaAuthError):
|
||||
code = getattr(exc, "reason_code", None) or REASON_AUTH_INVALID_TOKEN
|
||||
if code not in (
|
||||
@@ -233,13 +379,23 @@ def _classify_exception_impl(exc: BaseException) -> dict[str, Any]:
|
||||
return _classify_exception_impl(cause)
|
||||
|
||||
# No message-substring authentication heuristics (reviewer finding #3).
|
||||
return {
|
||||
# Unexpected failure → internal_error, now carrying SAFE diagnostics so the
|
||||
# failure is actionable: a type identifier + strictly-redacted detail +
|
||||
# optional mutation-stage tag. The operator ``message`` stays the fixed
|
||||
# constant; none of these fields carry secrets/bodies/paths/env.
|
||||
result = {
|
||||
"reason_code": REASON_INTERNAL_ERROR,
|
||||
"error_class": ERROR_CLASS_INTERNAL,
|
||||
"http_status": None,
|
||||
"message": fixed_message(REASON_INTERNAL_ERROR),
|
||||
"transport_survives": True,
|
||||
"exception_class": _safe_exception_class(exc),
|
||||
"detail": _redact_detail(_safe_str(exc)),
|
||||
}
|
||||
stage = _safe_mutation_stage(exc)
|
||||
if stage:
|
||||
result["mutation_stage"] = stage
|
||||
return result
|
||||
|
||||
|
||||
def build_structured_error_payload(
|
||||
@@ -277,6 +433,19 @@ def build_structured_error_payload(
|
||||
payload["tool"] = tool_name[:120]
|
||||
if profile_name and isinstance(profile_name, str):
|
||||
payload["profile"] = profile_name[:80]
|
||||
# Safe diagnostics — internal_error path only. These make an otherwise
|
||||
# opaque crash actionable without leaking secrets. Re-derived here from
|
||||
# the fixed message gate above; typed reasons never carry them.
|
||||
if payload["reason_code"] == REASON_INTERNAL_ERROR:
|
||||
exc_cls = classification.get("exception_class")
|
||||
if isinstance(exc_cls, str) and exc_cls:
|
||||
payload["exception_class"] = exc_cls[:_CLASS_LIMIT]
|
||||
detail = classification.get("detail")
|
||||
if isinstance(detail, str):
|
||||
payload["detail"] = _redact_detail(detail)
|
||||
stage = classification.get("mutation_stage")
|
||||
if isinstance(stage, str) and stage:
|
||||
payload["mutation_stage"] = stage[:_STAGE_LIMIT]
|
||||
return payload
|
||||
except Exception:
|
||||
return {
|
||||
@@ -316,7 +485,21 @@ def log_sanitized_daemon_reason(
|
||||
status = classification.get("http_status")
|
||||
if isinstance(status, int):
|
||||
parts.append(f"http_status={status}")
|
||||
# Intentionally no detail= / message= field — secrets lived there.
|
||||
# Safe diagnostics — internal_error path ONLY. Typed reasons still emit
|
||||
# no detail= (secrets lived there). class/detail/stage are re-redacted
|
||||
# here as defence in depth.
|
||||
if reason == REASON_INTERNAL_ERROR:
|
||||
exc_cls = classification.get("exception_class")
|
||||
if isinstance(exc_cls, str) and exc_cls:
|
||||
parts.append(f"exception_class={exc_cls[:_CLASS_LIMIT]}")
|
||||
stage = classification.get("mutation_stage")
|
||||
if isinstance(stage, str) and stage:
|
||||
parts.append(
|
||||
f"mutation_stage={_redact_detail(stage, limit=_STAGE_LIMIT)}"
|
||||
)
|
||||
detail = classification.get("detail")
|
||||
if isinstance(detail, str) and detail:
|
||||
parts.append(f"detail={_redact_detail(detail)}")
|
||||
line = " ".join(parts)
|
||||
stream.write(line + "\n")
|
||||
if hasattr(stream, "flush"):
|
||||
|
||||
Reference in New Issue
Block a user