astrbot_plugin_private_comp.../p5_source_observer.py

343 行
12 KiB
Python

"""Pure, metadata-only P5 source observation for the companion side.
The observer classifies a bounded source segment for a sink. It never reads
or retains prose, prompts, media, credentials, or carrier state. A normal
sink may receive an ``allow`` *observation*, but the result always carries
``execution_authority='none'``; high-risk sinks are fail-closed.
"""
from __future__ import annotations
import hashlib
import re
import unicodedata
from typing import Any
SCHEMA_VERSION = "ops.p5.source_observer.v1"
SOURCE_OBSERVER_SCHEMA_VERSION = SCHEMA_VERSION
FIREWALL_SCHEMA_VERSION = SCHEMA_VERSION
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",
"unknown",
}
)
SINKS = frozenset(
{
"prompt_context",
"prompt_forward_quote",
"prompt_vision_summary",
"memory_recall",
"bridge_serialize",
"bridge_serialization",
"tool_execution",
"tool_retrieval",
"external_export",
"cross_user_read",
}
)
HIGH_RISK_SINKS = frozenset(
{
"tool_execution",
"tool_retrieval",
"external_export",
"cross_user_read",
}
)
SECURITY_STATES = frozenset(
{"allowed", "sanitized", "blocked", "quarantined", "unavailable", "rejected", "unknown"}
)
DISPOSITIONS = frozenset({"allow", "shadow_quarantine", "deny_high_risk"})
MAX_BATCH_SIZE = 64
MAX_FIELDS = 10
MAX_TOKEN_LENGTH = 96
MAX_REFERENCE_LENGTH = 128
MAX_REASON_CODES = 12
_ALLOWED_FIELDS = frozenset(
{
"source_kind",
"trust",
"source_trust",
"sink",
"event_id",
"event_ref",
"source_hash",
"safe_ref_hash",
"security_state",
"firewall_status",
}
)
_PROSE_FIELDS = frozenset(
{
"text",
"content",
"prompt",
"body",
"message",
"raw",
"payload",
"summary",
"media",
"transcript",
"ocr",
"url",
"credentials",
"session_text",
}
)
_TOKEN_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.:@/+-]{0,127}\Z")
_HASH_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",
"unknown": "T4",
}
_DENIED_STATES = frozenset({"blocked", "quarantined", "unavailable", "rejected", "unknown"})
def evaluate_source(segment: object) -> dict[str, Any]:
"""Return a JSON-safe, deterministic source-to-sink observation.
Input references may be a bounded event reference or a SHA-256 reference,
but only a hash is emitted. Supplying both references, arbitrary fields,
or any prose field is invalid and cannot authorize a sink.
"""
normalized, errors, flags = _normalize(segment)
high_risk = normalized["sink"] in HIGH_RISK_SINKS
if errors:
codes = _codes("invalid_segment", *errors)
if high_risk:
return _result(normalized, "deny_high_risk", _codes(*codes, "high_risk_sink_denied"), flags)
return _result(normalized, "shadow_quarantine", _codes(*codes, "invalid_source_shadowed"), flags)
if normalized["security_state"] in _DENIED_STATES:
if high_risk:
return _result(normalized, "deny_high_risk", ["upstream_security_denied", "high_risk_sink_denied"], flags)
return _result(normalized, "shadow_quarantine", ["upstream_security_shadowed"], flags)
if high_risk:
return _result(normalized, "deny_high_risk", ["p5_nonexecuting", "high_risk_sink_denied"], flags)
if flags and normalized["trust"] in {"T0", "T1", "T2"}:
return _result(normalized, "shadow_quarantine", ["normalized_authority_metadata", "normalization_shadowed"], flags)
if normalized["trust"] in {"T3", "T4"}:
return _result(normalized, "shadow_quarantine", ["untrusted_source_shadowed", "p5_nonexecuting"], flags)
if normalized["security_state"] == "sanitized":
return _result(normalized, "shadow_quarantine", ["sanitized_source_shadowed", "p5_nonexecuting"], flags)
return _result(normalized, "allow", ["evidence_only_nonexecuting"], flags)
def evaluate_ingress_segment(segment: object) -> dict[str, Any]:
"""Compatibility alias for callers using the earlier P5-A wording."""
return evaluate_source(segment)
def evaluate_sources(segments: object) -> dict[str, Any]:
"""Evaluate a bounded list without retaining or mutating its members."""
if not isinstance(segments, list):
result = evaluate_source({})
result["reason_codes"] = ["invalid_batch", "invalid_source_shadowed"]
return {"schema_version": SCHEMA_VERSION, "results": [result], "summary": _summary([result])}
if len(segments) > MAX_BATCH_SIZE:
result = evaluate_source({})
result["reason_codes"] = ["batch_limit_exceeded", "invalid_source_shadowed"]
return {"schema_version": SCHEMA_VERSION, "results": [result], "summary": _summary([result])}
results = [evaluate_source(item) for item in segments]
return {"schema_version": SCHEMA_VERSION, "results": results, "summary": _summary(results)}
evaluate_ingress_segments = evaluate_sources
def _normalize(segment: object) -> tuple[dict[str, str], list[str], list[str]]:
result = {
"source_kind": "invalid",
"trust": "invalid",
"sink": "invalid",
"security_state": "not_supplied",
"safe_ref_hash": "",
"safe_ref_kind": "none",
}
if not isinstance(segment, dict):
return result, ["segment_not_object"], []
errors: list[str] = []
if len(segment) > MAX_FIELDS:
errors.append("field_limit_exceeded")
keys = list(segment.keys())
if any(not isinstance(key, str) for key in keys):
errors.append("field_name_invalid")
if any(isinstance(key, str) and key in _PROSE_FIELDS for key in keys):
errors.append("prose_field_forbidden")
if any(isinstance(key, str) and key not in _ALLOWED_FIELDS for key in keys):
errors.append("unknown_field")
flags: list[str] = []
values: dict[str, str] = {}
for field in ("source_kind", "trust", "source_trust", "sink", "security_state", "firewall_status"):
if field not in segment:
continue
value, value_errors, value_flags = _token(segment[field], MAX_TOKEN_LENGTH)
if value_errors:
errors.extend(f"{field}_{code}" for code in value_errors)
else:
values[field] = value
flags.extend(value_flags)
source_kind = values.get("source_kind", "invalid")
trust = values.get("trust", values.get("source_trust", "invalid"))
if "trust" in values and "source_trust" in values and values["trust"] != values["source_trust"]:
errors.append("trust_alias_mismatch")
sink = values.get("sink", "invalid")
security_state = values.get("security_state", values.get("firewall_status", "not_supplied"))
if "security_state" in values and "firewall_status" in values and values["security_state"] != values["firewall_status"]:
errors.append("security_alias_mismatch")
result.update(source_kind=source_kind, trust=trust, sink=sink, security_state=security_state)
if "source_kind" not in segment:
errors.append("source_kind_missing")
if not ("trust" in segment or "source_trust" in segment):
errors.append("trust_missing")
if "sink" not in segment:
errors.append("sink_missing")
if source_kind not in SOURCE_KINDS:
errors.append("source_kind_invalid")
result["source_kind"] = "invalid"
if trust not in TRUST_LEVELS:
errors.append("trust_invalid")
result["trust"] = "invalid"
elif source_kind in _SOURCE_TRUST and _SOURCE_TRUST[source_kind] != trust:
errors.append("source_trust_mismatch")
if sink not in SINKS:
errors.append("sink_invalid")
result["sink"] = "invalid"
if security_state not in SECURITY_STATES and security_state != "not_supplied":
errors.append("security_state_invalid")
result["security_state"] = "not_supplied"
reference_keys = [key for key in ("event_id", "event_ref", "source_hash", "safe_ref_hash") if key in segment]
if len(reference_keys) != 1:
errors.append("reference_required_or_ambiguous")
else:
key = reference_keys[0]
raw = segment[key]
if key in {"source_hash", "safe_ref_hash"}:
if not isinstance(raw, str) or _HASH_RE.fullmatch(raw) is None:
errors.append("source_hash_invalid")
else:
result["safe_ref_hash"] = raw[7:] if raw.startswith("sha256:") else raw
result["safe_ref_kind"] = "source_hash"
else:
value, ref_errors, ref_flags = _token(raw, MAX_REFERENCE_LENGTH)
errors.extend(f"event_ref_{code}" for code in ref_errors)
flags.extend(ref_flags)
if not ref_errors and _TOKEN_RE.fullmatch(value) is None:
errors.append("event_ref_invalid")
elif not ref_errors:
# The raw event reference is deliberately never returned.
result["safe_ref_hash"] = hashlib.sha256(value.encode("utf-8")).hexdigest()
result["safe_ref_kind"] = "event_ref_hash"
return result, _codes(*errors), _codes(*flags)
def _token(value: object, maximum: int) -> tuple[str, list[str], list[str]]:
if not isinstance(value, str):
return "", ["not_string"], []
if len(value) > maximum + 8:
return "", ["too_long"], []
normalized = unicodedata.normalize("NFKC", value)
flags = ["unicode_nfkc"] if normalized != value else []
kept: list[str] = []
format_controls = 0
for char in normalized:
category = unicodedata.category(char)
if category == "Cf":
format_controls += 1
continue
if category == "Cc":
return "", ["control_character"], []
kept.append(char)
if format_controls:
flags.append("format_controls_removed")
value = "".join(kept)
if len(value) > maximum:
return "", ["too_long"], []
return value, [], flags
def _result(normalized: dict[str, str], disposition: str, reasons: list[str], flags: list[str]) -> dict[str, Any]:
return {
"schema_version": SCHEMA_VERSION,
"source_kind": normalized["source_kind"],
"trust": normalized["trust"],
"sink": normalized["sink"],
"security_state": normalized["security_state"],
"disposition": disposition,
"state": disposition,
"reason_codes": _codes(*reasons),
"execution_authority": "none",
"safe_ref_kind": normalized["safe_ref_kind"],
"safe_ref_hash": normalized["safe_ref_hash"],
"normalization_flags": list(flags),
}
def _summary(results: list[dict[str, Any]]) -> dict[str, int]:
return {
"count": len(results),
"allow": sum(item["disposition"] == "allow" for item in results),
"shadow_quarantine": sum(item["disposition"] == "shadow_quarantine" for item in results),
"deny_high_risk": sum(item["disposition"] == "deny_high_risk" for item in results),
}
def _codes(*codes: str) -> list[str]:
return sorted({code for code in codes if code})[:MAX_REASON_CODES]
__all__ = [
"DISPOSITIONS",
"FIREWALL_SCHEMA_VERSION",
"HIGH_RISK_SINKS",
"SCHEMA_VERSION",
"SECURITY_STATES",
"SINKS",
"SOURCE_KINDS",
"SOURCE_OBSERVER_SCHEMA_VERSION",
"TRUST_LEVELS",
"evaluate_ingress_segment",
"evaluate_ingress_segments",
"evaluate_source",
"evaluate_sources",
]