# -*- coding: utf-8 -*- """Pure P5-A source-to-sink shadow firewall contract. This module is deliberately detached from AstrBot, prompts, persistence, and tool execution. It accepts only small, typed metadata segments and returns a new JSON-compatible advisory record. ``allow`` therefore means that a normal sink may retain the segment as *non-executing evidence*; it never grants an execution capability. P5-A callers must not treat this module as a live gate. The contract accepts exactly these input fields:: { "source_kind": "forwarded_text", "trust": "T3", "event_id": "message-123", # or ``source_hash`` "sink": "prompt_context", "security_state": "allowed", # optional P2/P3 state } No input prose field is accepted. Results expose only enum metadata and a stable event id or SHA-256 digest; invalid untrusted values are never echoed back into the audit projection. """ from __future__ import annotations from copy import deepcopy import re import unicodedata from typing import Any FIREWALL_SCHEMA_VERSION = "p5.ingress_firewall.v1" # Public sets are immutable so an importing runtime cannot quietly extend the # contract in-process. New sources or sinks require a versioned P5 decision. TRUST_LEVELS = frozenset({"T0", "T1", "T2", "T3", "T4"}) SOURCE_KINDS = frozenset({ "policy_config", "verified_authorization", "current_user_intent", "forwarded_text", "quoted_text", "vision_summary", "tool_output", "web_extract", "memory_recall", "derived_summary", "legacy_memory", }) SINKS = frozenset({ "prompt_context", "memory_recall", "bridge_serialize", "tool_execution", "external_export", "cross_user_read", }) HIGH_RISK_SINKS = frozenset({"tool_execution", "external_export", "cross_user_read"}) SECURITY_STATES = frozenset({ "allowed", "sanitized", "blocked", "quarantined", "unavailable", "rejected", }) MAX_BATCH_SIZE = 64 MAX_FORMAT_CONTROLS = 8 MAX_SOURCE_KIND_CHARS = 48 MAX_TRUST_CHARS = 8 MAX_EVENT_ID_CHARS = 128 MAX_SOURCE_HASH_CHARS = 71 MAX_SINK_CHARS = 48 MAX_SECURITY_STATE_CHARS = 20 _ALLOWED_FIELDS = frozenset({"source_kind", "trust", "event_id", "source_hash", "sink", "security_state"}) _PROSE_FIELDS = frozenset({ "content", "text", "prompt", "body", "message", "raw", "payload", "summary", "html", "media", "transcript", "ocr", "url", }) _EVENT_ID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.:@/+-]{0,127}\Z") _SHA256_RE = re.compile(r"sha256:[0-9a-f]{64}\Z") _SOURCE_TRUST = { "policy_config": "T0", "verified_authorization": "T1", "current_user_intent": "T2", "forwarded_text": "T3", "quoted_text": "T3", "vision_summary": "T3", "tool_output": "T3", "web_extract": "T3", "memory_recall": "T4", "derived_summary": "T4", "legacy_memory": "T4", } _DENIED_SECURITY_STATES = frozenset({"blocked", "quarantined", "unavailable", "rejected"}) _FORMAT_CONTROL_CATEGORIES = frozenset({"Cf"}) def evaluate_ingress_segment(segment: object) -> dict[str, Any]: """Return a deterministic, non-executing P5-A disposition for one segment. The input is not mutated. Invalid, missing, unknown, and source/trust mismatches become ``shadow_quarantine`` for ordinary sinks and ``deny_high_risk`` for tool/export/cross-user sinks. Every high-risk sink is denied in P5-A, including T0/T1/T2, because this phase creates evidence only and has no execution authority. """ normalized, errors, normalization_flags = _normalize_segment(segment) audit = _audit_projection(normalized, normalization_flags) sink = normalized["sink"] high_risk = sink in HIGH_RISK_SINKS if errors: reason_codes = _stable_codes("invalid_segment", *errors) if high_risk: reason_codes = _stable_codes(*reason_codes, "high_risk_sink_denied") disposition = "deny_high_risk" else: reason_codes = _stable_codes(*reason_codes, "invalid_source_shadowed") disposition = "shadow_quarantine" return _result(disposition, reason_codes, audit) security_state = normalized["security_state"] if security_state in _DENIED_SECURITY_STATES: reason_codes = ["upstream_security_denied"] if high_risk: reason_codes.append("high_risk_sink_denied") return _result("deny_high_risk", reason_codes, audit) reason_codes.append("upstream_security_shadowed") return _result("shadow_quarantine", reason_codes, audit) # A non-ASCII-normalized authority label is safe to observe but cannot be # silently upgraded to an ordinary allow result. if normalization_flags and normalized["trust"] in {"T0", "T1", "T2"}: if high_risk: return _result( "deny_high_risk", ["normalized_authority_metadata", "high_risk_sink_denied"], audit, ) return _result( "shadow_quarantine", ["normalized_authority_metadata", "normalization_shadowed"], audit, ) if high_risk: # This includes T0/T1/T2 by design. The audit flag below makes the # absence of execution authority mechanically visible to future users. return _result( "deny_high_risk", ["p5a_nonexecuting", "high_risk_sink_denied"], audit, ) if normalized["trust"] in {"T3", "T4"}: return _result( "shadow_quarantine", ["untrusted_source_shadowed", "p5a_nonexecuting"], audit, ) if security_state == "sanitized": return _result( "shadow_quarantine", ["sanitized_source_shadowed", "p5a_nonexecuting"], audit, ) return _result("allow", ["evidence_only_nonexecuting"], audit) def evaluate_ingress_segments(segments: object) -> dict[str, Any]: """Evaluate a bounded batch without changing the input collection. A non-list or an oversized batch returns one deterministic invalid result rather than iterating unbounded data. Each normal batch member is handled by :func:`evaluate_ingress_segment` independently. """ if not isinstance(segments, list): return { "schema_version": FIREWALL_SCHEMA_VERSION, "results": [ _result( "shadow_quarantine", ["invalid_batch", "invalid_source_shadowed"], _empty_audit(), ) ], "summary": {"count": 0, "allow": 0, "shadow_quarantine": 1, "deny_high_risk": 0}, } if len(segments) > MAX_BATCH_SIZE: return { "schema_version": FIREWALL_SCHEMA_VERSION, "results": [ _result( "shadow_quarantine", ["batch_limit_exceeded", "invalid_source_shadowed"], _empty_audit(), ) ], "summary": {"count": 0, "allow": 0, "shadow_quarantine": 1, "deny_high_risk": 0}, } results = [evaluate_ingress_segment(item) for item in segments] summary = { "count": len(results), "allow": sum(result["disposition"] == "allow" for result in results), "shadow_quarantine": sum(result["disposition"] == "shadow_quarantine" for result in results), "deny_high_risk": sum(result["disposition"] == "deny_high_risk" for result in results), } return {"schema_version": FIREWALL_SCHEMA_VERSION, "results": results, "summary": summary} def _result(disposition: str, reason_codes: list[str] | tuple[str, ...], audit: dict[str, Any]) -> dict[str, Any]: return { "schema_version": FIREWALL_SCHEMA_VERSION, "disposition": disposition, "reason_codes": list(reason_codes), "execution_authority": "none", "audit": audit, } def _normalize_segment(segment: object) -> tuple[dict[str, str], list[str], list[str]]: base = { "source_kind": "invalid", "trust": "invalid", "event_id": "", "source_hash": "", "sink": "invalid", "security_state": "", } if not isinstance(segment, dict): return base, ["segment_not_object"], [] # Never mutate or retain the supplied mapping. Its keys are also bounded # before comparing them, so values cannot smuggle raw prose through an # otherwise unknown key. errors: list[str] = [] if len(segment) > len(_ALLOWED_FIELDS): errors.append("field_limit_exceeded") raw_keys = list(segment.keys()) if any(not isinstance(key, str) for key in raw_keys): errors.append("field_name_invalid") prose_keys = sorted(key for key in raw_keys if isinstance(key, str) and key in _PROSE_FIELDS) if prose_keys: errors.append("prose_field_forbidden") unknown_keys = sorted( key for key in raw_keys if isinstance(key, str) and key not in _ALLOWED_FIELDS ) if unknown_keys: errors.append("unknown_field") flags: list[str] = [] for field, maximum in ( ("source_kind", MAX_SOURCE_KIND_CHARS), ("trust", MAX_TRUST_CHARS), ("event_id", MAX_EVENT_ID_CHARS), ("source_hash", MAX_SOURCE_HASH_CHARS), ("sink", MAX_SINK_CHARS), ("security_state", MAX_SECURITY_STATE_CHARS), ): if field not in segment: continue value, value_errors, value_flags = _normalize_token(segment.get(field), maximum) if value_errors: errors.extend(f"{field}_{code}" for code in value_errors) continue base[field] = value flags.extend(value_flags) for required in ("source_kind", "trust", "sink"): if required not in segment: errors.append(f"{required}_missing") event_present = "event_id" in segment hash_present = "source_hash" in segment if event_present == hash_present: errors.append("reference_required_or_ambiguous") # An ambiguous reference is not audit-safe. Do not select or echo one # of the caller values merely because it happened to be syntactically # valid. base["event_id"] = "" base["source_hash"] = "" elif event_present and not _EVENT_ID_RE.fullmatch(base["event_id"]): errors.append("event_id_invalid") base["event_id"] = "" elif hash_present and not _SHA256_RE.fullmatch(base["source_hash"]): errors.append("source_hash_invalid") base["source_hash"] = "" if base["source_kind"] not in SOURCE_KINDS: errors.append("source_kind_invalid") base["source_kind"] = "invalid" if base["trust"] not in TRUST_LEVELS: errors.append("trust_invalid") base["trust"] = "invalid" elif base["source_kind"] != "invalid" and _SOURCE_TRUST[base["source_kind"]] != base["trust"]: errors.append("source_trust_mismatch") if base["sink"] not in SINKS: errors.append("sink_invalid") base["sink"] = "invalid" if "security_state" in segment: if base["security_state"] not in SECURITY_STATES: errors.append("security_state_invalid") base["security_state"] = "" # Repeated fields must not change result ordering. A normalized marker is # retained only as a small enum, never as a copy of caller text. return base, _stable_codes(*errors), _stable_codes(*flags) def _normalize_token(value: object, maximum: int) -> tuple[str, list[str], list[str]]: if not isinstance(value, str): return "", ["not_string"], [] if len(value) > maximum + MAX_FORMAT_CONTROLS: return "", ["too_long"], [] normalized = unicodedata.normalize("NFKC", value) flags: list[str] = [] if normalized != value: flags.append("unicode_nfkc") format_controls = 0 visible_controls = 0 kept: list[str] = [] for character in normalized: category = unicodedata.category(character) if category in _FORMAT_CONTROL_CATEGORIES: format_controls += 1 continue if category == "Cc": visible_controls += 1 continue kept.append(character) if format_controls: flags.append("format_controls_removed") if visible_controls: return "", ["control_character"], [] if format_controls > MAX_FORMAT_CONTROLS: return "", ["format_control_limit"], [] result = "".join(kept) if len(result) > maximum: return "", ["too_long"], [] return result, [], flags def _audit_projection(normalized: dict[str, str], normalization_flags: list[str]) -> dict[str, Any]: reference_kind = "none" reference = "" if normalized["event_id"]: reference_kind, reference = "event_id", normalized["event_id"] elif normalized["source_hash"]: reference_kind, reference = "source_hash", normalized["source_hash"] return { "source_kind": normalized["source_kind"], "trust": normalized["trust"], "sink": normalized["sink"], "security_state": normalized["security_state"] or "not_supplied", "reference_kind": reference_kind, "reference": reference, "normalization_flags": list(normalization_flags), } def _empty_audit() -> dict[str, Any]: return { "source_kind": "invalid", "trust": "invalid", "sink": "invalid", "security_state": "not_supplied", "reference_kind": "none", "reference": "", "normalization_flags": [], } def _stable_codes(*codes: str) -> list[str]: return sorted({code for code in codes if code})