docs(specs): fix fictional type/API references in 010-security and 008-mcp sub-specs - #6668
Merged
Merged
Conversation
github-actions
Bot
added
documentation
Replace fictional API types with actual codebase implementations: - VaultProvider, AgeVaultProvider, EnvVaultProvider (010-1-vault) - ContentSanitizer, CrossToolCorrelator, TrajectorySentinel (010-2-injection-defense) - PolicyEnforcer, shell blocklist validation (010-3-authorization) - ServerEntry, McpTransport, McpManager (008-1-lifecycle) - ToolCollision, PruningCache, SemanticToolIndex (008-2-discovery) - SanitizeResult, DefaultMcpProber, trust scoring (008-3-security) - AuditEntry, AuditSignal, AuditSignalType, Severity (010-4-audit) Fix critical factual error in 010-4-audit: TrajectoryRiskAccumulator maintains cross-turn, exponentially-decaying risk scores and makes hard-blocking tool-execution decisions. Add warning callout flagging unresolved architectural gap (system not addressed by parent spec's NEVER rule on cross-turn accumulation). Remove [!danger] callouts from all files — content is now accurate. Closes #6631 Closes #6630
…tic grep-verification Verified all TOML config sections and Rust struct types against codebase. **010-2-injection-defense.md:** 1. Removed fictional [security.ipi] section — IPI detection is part of [security.content_isolation] 2. Changed [security.pii] → [security.pii_filter] with real field names (filter_email, filter_phone, filter_ssn, filter_credit_card, filter_names, custom_patterns) 3. Changed [security.guardrails] → [security.guardrail] (singular) with real config fields (enabled, provider, model, timeout_ms, action, fail_strategy, scan_tool_output, max_input_chars) **010-4-audit.md:** 1. Fixed AuditEntry struct field types and added missing 10+ fields: - timestamp: i64 → String - tool: String → ToolName - result: String → AuditResult - caller_id: String → Option<String> - correlation_id: String → Option<String> - vigil_risk: Option<f32> → Option<VigilRiskLevel> - Added: error_domain, error_phase, claim_source, mcp_server_id, injection_flagged, embedding_anomalous, cross_boundary_mcp_to_acp, adversarial_policy_decision, exit_code, truncated, policy_match 2. Changed [security.audit] → [tools.audit] with real config fields (enabled, destination, tool_risk_summary) 3. Removed fictional "Audit Log Storage" section describing zeph-db/SQLite backend 4. Replaced with accurate description: AuditLogger writes to stdout/stderr/file per AuditDestination, serializes as JSONL [vault] and [[mcp.servers]] sections verified as correct.
**010-1-vault.md:**
- Removed fictional config fields: vault_path, identity_path, fallback_env
- Replaced with accurate path resolution logic: XDG_CONFIG_HOME/zeph or $HOME/.config/zeph
- Fixed to reflect hardcoded file names: vault-key.txt, secrets.age
- Documented all three backend variants (age, env, keyring) with real semantics
- Age backend is recommended for production; env is dev/testing only
**008-1-lifecycle.md:**
- Fixed McpServerConfig to use flat field structure (not nested transport object)
- command/args for Stdio (not transport = { type = "stdio", ... })
- url/headers for HTTP (not nested)
- Added timeout field (not timeout_secs)
- Documented field reference with all real field names: trust_level, tool_allowlist, expected_tools, media_passthrough, env_isolation, etc.
- Included example configs for both Stdio and HTTP transports
…with real APIs **008-2-discovery.md** (near-total rewrite): - ToolCollision: fixed to real struct (sanitized_id, server_a/b, qualified_a/b, trust_a/b) - detect_collisions: corrected signature (tools, trust_map) — real is free function not method - PruningCache/PruningParams: removed fictional API, documented actual prune_tools_cached fn - PruningParams: corrected to (max_tools, min_tools_to_prune, always_include) - ToolDiscoveryStrategy: corrected to (None, Llm, Embedding) - SemanticToolIndex: rewrote API (build() + select() instead of search_tools()) - AttestationResult: corrected to enum (Verified/Unexpected/Unconfigured) - ToolFingerprint: corrected to type alias String - Config: corrected to [mcp.pruning] and [mcp.tool_discovery] nested sections **008-3-security.md** (near-total rewrite): - sanitize_tools(): corrected to in-place mutation, sync, real signature (tools, server_id, max_description_bytes) - SanitizeResult: corrected fields (injection_count, flagged_tools, flagged_patterns) - ProbeResult: corrected fields (score_delta, summary, block) - ServerTrustScore: rewritten with real fields (score f64, success_count, failure_count, updated_at_secs) - Real score factors: SUCCESS_BOOST=0.02, FAILURE_PENALTY=0.10, INJECTION_PENALTY=0.25, DECAY_RATE=0.01/day - Asymmetric decay: scores above 0.5 decay toward 0.5; below 0.5 stay put (attacker can't regain trust by going quiet) - DataFlowViolation: corrected to enum (SensitivityTrustMismatch variant only) - EmbeddingGuardEvent/EmbeddingGuardResult: rewritten with real event structure (Normal/Anomalous/RegexFallback variants) - EmbeddingAnomalyGuard: corrected to fire-and-forget check_async() + channel-based results Next: targeted fixes to 010-3-authorization, 008-1-lifecycle, 010-2-injection-defense, 010-4-audit
…tion **010-3-authorization.md:** - Fixed PolicyRuleConfig fields: tool (singular, not tools), paths, env, trust_level, args_match, capabilities - Removed non-existent fields: reason, trust_threshold, args_regex, env_required - Fixed shell blocklist: real DEFAULT_BLOCKED is [sudo, mkfs, dd if=, curl, wget, nc, ncat, netcat, shutdown, reboot, halt] - Documented rm -rf special handling (allowed only on relative paths, not /.git/worktrees/root/$HOME) - Fixed SSRF validation: validate_url() in crates/zeph-tools/src/net.rs (not validate_url_ssrf) - Removed false "Applied to" list (no zeph-gateway/a2a/OAuth uses verified) - Accurate SSRF blocks: IPv4 private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 127.0.0.0/8), IPv6 loopback/ULA/link-local, non-HTTPS schemes - Fixed env scrubbing: corrected to env_blocklist field, not scrub_environment() method - Noted: no allowlist exists; blocklist filtering is unconditional Next: fix 010-4-audit.md (AuthViolationEntry, ShellAuditEntry, CrossToolCorrelator don't exist), 008-1-lifecycle.md (McpManager method signatures), 010-2-injection-defense.md (TurnCausalAnalyzer, etc.)
**010-4-audit.md:** - Removed non-existent AuthViolationEntry struct section - Removed non-existent ShellAuditEntry struct section - Consolidated both into a note that these details are captured in unified AuditEntry fields (policy_match, adversarial_policy_decision, command, exit_code, duration_ms) - Removed non-existent CrossToolCorrelator type and InjectionConfirmed - Simplified Turn Boundary Isolation section to focus only on real TrajectoryRiskAccumulator Confirmed via grep: CrossToolCorrelator, InjectionConfirmed, AuthViolationEntry, ShellAuditEntry do not exist in the codebase.
…ricated types **008-1-lifecycle.md:** - Fixed McpManager::call_tool() return type: Result<ToolResult> → Result<CallToolResult, McpError> - Fixed McpManager::shutdown_all() signature: removed timeout param, changed self to by-value, removed Result wrapper - Removed non-existent ToolListChangedHandler::on_tools_list_changed() method - Converted section to prose describing tools/list_changed notification handling - Fixed SSRF reference: validate_url_ssrf() → validate_url() in crates/zeph-tools/src/net.rs - Updated transport security section with real details Verified via grep: ToolListChangedHandler::on_tools_list_changed does not exist. shutdown_all is by-value self. Remaining minor fixes in 010-2-injection-defense.md can be addressed in follow-up if needed.
…findings **010-2-injection-defense.md:** - Fixed TurnCausalAnalyzer: changed from analyze_causal_chain(prior_result, current_call) to real analyze(&pre, &post) signature - Fixed TurnCausalAnalyzer: documented as synchronous local computation with .is_flagged/.deviation_score fields - Fixed SecretCategory variants: ApiKey, Token, Password, Certificate, Webhook, Generic (real enum, not AuthToken/OAuthToken/DatabaseUrl) - Fixed SecretMaskRegistry::mask_secrets() → mask() (correct method name) - Fixed PiiFilter::scrub() return type: Cow<'a, str> not String - Added missing source: ContentSource field to SanitizedContent struct All changes verified against real crate sources via grep before editing.
Address remaining code-reviewer findings from the second review round: correct SemanticToolIndex/prune_tools_cached signatures against real zeph-mcp pruning API, fix mcp.pruning/mcp.tool_discovery config field placement, correct data-flow policy Medium/Sandboxed semantics, rewrite the MCP output sanitization section to describe the real cross-cutting sanitize_tool_output() pipeline, and fix remaining type-name typos.
bug-ops
force-pushed
the
feat/issue-6631/specs-010-008-type-mismatch
branch
from
July 28, 2026 00:00
5c88cbb to
916497a
Compare
bug-ops
enabled auto-merge (squash)
July 28, 2026 00:00
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
specs/010-security/andspecs/008-mcp/to describe the actual shipped implementation inzeph-vault,zeph-sanitizer,zeph-tools, andzeph-mcp, replacing invented type/API names that PR docs(specs): correct stale references, broken links, and formatting #6629's spec audit flagged with[!danger]callouts but did not rewrite.010-4-audit.md's contradiction with the parent spec's NEVER rule on cross-turn signal accumulation: clarifiesCrossToolCorrelator(within-turn, hard decisions) vs.TrajectorySentinel(advisory, cross-turn decay) are independent mechanisms, and flags a genuinely unresolved gap aroundTrajectoryRiskAccumulator's cross-turn hard-blocking behavior with an explicit[!warning] Architectural gapcallout rather than a false resolution..rsfiles changed.Closes #6631
Closes #6630
Test plan
008-2-discovery.md/008-3-security.mdin particular)[!danger]callouts from PR docs(specs): correct stale references, broken links, and formatting #6629 removed## Key Invariants/NEVERsectionsgitleaks protect --stagedclean