From c6dd3e769a91e3c32561479e48779d52f5a9bf9e Mon Sep 17 00:00:00 2001 From: YokiiroBW Date: Thu, 30 Jul 2026 16:54:48 +0800 Subject: [PATCH] feat(p4): add host-bound manual review queue --- _conf_schema.json | 13 +- core_store.py | 6 + main.py | 217 ++++++- p4_manual_review.py | 864 ++++++++++++++++++++++++++++ tests/test_p4_manual_review.py | 586 +++++++++++++++++++ tests/test_p4_manual_review_hook.py | 195 +++++++ unified_person_registry.py | 335 +++++++++++ 7 files changed, 2213 insertions(+), 3 deletions(-) create mode 100644 p4_manual_review.py create mode 100644 tests/test_p4_manual_review.py create mode 100644 tests/test_p4_manual_review_hook.py diff --git a/_conf_schema.json b/_conf_schema.json index 98ac663..32d9b0c 100644 --- a/_conf_schema.json +++ b/_conf_schema.json @@ -9188,12 +9188,23 @@ "p4_b_safety_config": { "description": "P4-B 实效前置隔离门", "type": "object", - "hint": "默认关闭以保持旧版本兼容。开启后只隔离旧 relationship_score 直写,不启用 P4 实效、禁闭或 owner 命令。", + "hint": "默认关闭以保持旧版本兼容。人工审核仅记录独立队列和审计,不启用 P4 实效、禁闭、释放、恢复或 owner 命令。owner 白名单必须与 AstrBot event.get_sender_id() 运行时身份同时匹配。", "items": { "enable_p4_b_legacy_score_isolation": { "description": "隔离旧关系分直写", "type": "bool", "default": false + }, + "enable_p4_manual_review": { + "description": "启用 P4 人工审核候选观察与审计入口", + "type": "bool", + "default": false + }, + "p4_manual_review_owner_ids": { + "description": "P4 人工审核 owner ID 白名单", + "type": "list", + "hint": "仅作 allowlist;运行时仍必须由 AstrBot event.get_sender_id() 返回相同单行 ID。兼容逗号或空白分隔字符串,不能用页面、请求、模型文本或事件字段自证授权。", + "default": [] } } }, diff --git a/core_store.py b/core_store.py index 3868afa..feebcf8 100644 --- a/core_store.py +++ b/core_store.py @@ -623,6 +623,10 @@ class CoreStoreMixin: return self._unified_person_registry().audit_events(limit=limit) def _apply_unified_person_lifecycle(self, method: str, *args: Any, **kwargs: Any) -> dict[str, Any]: + if method in {"record_p4_manual_review_candidate", "record_p4_manual_review_decision"} and not bool( + getattr(self, "enable_p4_manual_review", False) + ): + return {"ok": False, "code": "p4_review_disabled", "live_effect_permitted": False} registry = self._unified_person_registry() operation = getattr(registry, method, None) if not callable(operation) or method not in { @@ -633,6 +637,8 @@ class CoreStoreMixin: "split_merged_people", "record_p4_shadow_event", "record_p4_effect_event", + "record_p4_manual_review_candidate", + "record_p4_manual_review_decision", }: return {"ok": False, "code": "unsupported_lifecycle_operation"} result = operation(*args, **kwargs) diff --git a/main.py b/main.py index df3515e..8b3ea91 100644 --- a/main.py +++ b/main.py @@ -18,7 +18,7 @@ import time import unicodedata import zoneinfo from copy import deepcopy -from datetime import date, datetime, timedelta +from datetime import date, datetime, timedelta, timezone from email.utils import parsedate_to_datetime from http.cookies import SimpleCookie from pathlib import Path @@ -142,6 +142,14 @@ from .p5_provenance_attestation import FIREWALL_STATUSES, P5AttestationRegistry from .p5c_gate import RAW_IMAGE_PROVIDER_SINK, p5c_gate_allows from .p5d_security_events import p5d_security_event_allows from .p6_readonly_projection import build_p6_readonly_status +from .p4_manual_review import ( + build_p3_review_proof, + _new_p4_review_attestation_registry, + P4ReviewAttestationRegistry, + parse_owner_allowlist, + runtime_owner_identity, + runtime_scope_identity, +) from .segmented_message import flatten_component_chunks, split_plain_component_chain_detailed from .token_budget import TokenBudgetMixin from .balance_awareness import BalanceAwarenessMixin @@ -199,6 +207,9 @@ from .planning import ( ) P4_SHADOW_OBSERVER_PRIORITY = FINALIZE - 1000 +# P4 manual review is a distinct, default-off observer after P3 finalization. +# Its queue is deliberately independent from both P4-A shadow and P4-B effect. +P4_MANUAL_REVIEW_OBSERVER_PRIORITY = P4_SHADOW_OBSERVER_PRIORITY - 1 # P5-A must publish source disposition before MemoryCompanion's P3 hook (-20), # but after the companion context has assembled its known prompt sources. P5_SOURCE_OBSERVER_PRIORITY = MEMORY_CONTEXT + 1 @@ -1945,6 +1956,13 @@ class PrivateCompanionPlugin( # legacy direct score writes while the separate effect ledger is # prepared and remains default-off for rollback compatibility. self.enable_p4_b_legacy_score_isolation = self._cfg_bool(c, "enable_p4_b_legacy_score_isolation", False) + # Manual P4 review is independently default-off. These configured + # IDs are an allowlist only; the review write path always obtains its + # actor from the actual AstrBot event.get_sender_id() runtime call. + self.enable_p4_manual_review = self._cfg_bool(c, "enable_p4_manual_review", False) + self.p4_manual_review_owner_ids = parse_owner_allowlist( + self._cfg_raw(c, "p4_manual_review_owner_ids", []) + ) # P5-A only observes source metadata. It never rewrites a prompt, # changes a live tool set, or changes retrieval/response behaviour. self.enable_p5_source_observer = self._cfg_bool(c, "enable_p5_source_observer", False) @@ -8322,7 +8340,10 @@ wakeup_type={_single_line(wakeup.get('type'), 40)} score={_single_line(wakeup.ge def _safe_event_sender_id(event: AstrMessageEvent | None) -> str: if event is None: return "" - getter = getattr(event, "get_sender_id", None) + try: + getter = getattr(event, "get_sender_id", None) + except Exception: + return "" if callable(getter): try: return _single_line(getter(), 80) @@ -9897,6 +9918,75 @@ wakeup_type={_single_line(wakeup.get('type'), 40)} score={_single_line(wakeup.ge """Expose the P5-D reject-only boundary without creating a live hook.""" return p5d_security_event_allows(self, operation, *opaque) + @staticmethod + def _p4_manual_review_runtime_sender_id(event: AstrMessageEvent | None) -> str: + """Read a sender only from AstrBot's direct runtime API, never fields.""" + if event is None: + return "" + try: + getter = getattr(event, "get_sender_id", None) + except Exception: + return "" + if not callable(getter): + return "" + try: + return _single_line(getter(), 160) + except Exception: + return "" + + def _p4_manual_review_owner_runtime_identity(self, event: AstrMessageEvent | None) -> dict[str, Any]: + """Expose the P4 owner double gate without treating config as a credential.""" + return runtime_owner_identity(event, getattr(self, "p4_manual_review_owner_ids", ())) + + def _p4_manual_review_attestation_registry(self) -> P4ReviewAttestationRegistry: + """Return the host-owned, one-shot P3 observer attestation issuer.""" + registry = getattr(self, "_p4_manual_review_registry", None) + if isinstance(registry, P4ReviewAttestationRegistry): + return registry + registry = _new_p4_review_attestation_registry() + setattr(self, "_p4_manual_review_registry", registry) + return registry + + def submit_p4_manual_review_decision( + self, + event: AstrMessageEvent | None, + *, + person_id: str, + candidate_id: str, + operation_id: str, + decision: str, + reason_code: str, + ) -> dict[str, Any]: + """Write an audit-only manual P4 conclusion through the runtime gate. + + This is an explicit host/API seam, not a model command, page action, + or automatic effect. The registry repeats the direct event identity + proof so a caller cannot bypass this method through a forged payload. + """ + if not bool(getattr(self, "enable_p4_manual_review", False)): + return {"ok": False, "code": "p4_review_disabled", "live_effect_permitted": False} + owner = self._p4_manual_review_owner_runtime_identity(event) + if owner.get("accepted") is not True: + return { + "ok": False, + "code": str(owner.get("code") or "p4_review_owner_runtime_unavailable"), + "live_effect_permitted": False, + } + try: + return self._apply_unified_person_lifecycle( + "record_p4_manual_review_decision", + event, + getattr(self, "p4_manual_review_owner_ids", ()), + person_id, + candidate_id, + operation_id=operation_id, + decision=decision, + reason_code=reason_code, + ) + except Exception as exc: + logger.debug("[PrivateCompanion] P4 manual review decision rejected: %s", _single_line(exc, 160)) + return {"ok": False, "code": "p4_review_runtime_error", "live_effect_permitted": False} + def _p4_b_apply_legacy_relationship_delta( self, user: Any, @@ -10390,6 +10480,129 @@ wakeup_type={_single_line(wakeup.get('type'), 40)} score={_single_line(wakeup.ge _single_line(result.get("code") if isinstance(result, dict) else "", 120) or "unknown", ) + @staticmethod + def _p4_manual_review_expiry(created_at: str) -> str: + """Return the fixed observer queue TTL, or an empty value on failure.""" + if not isinstance(created_at, str) or not created_at: + return "" + try: + parsed = datetime.fromisoformat( + created_at[:-1] + "+00:00" if created_at.endswith("Z") else created_at + ) + except (TypeError, ValueError): + return "" + if parsed.tzinfo is None: + return "" + return (parsed.astimezone(timezone.utc) + timedelta(hours=24)).isoformat(timespec="seconds").replace("+00:00", "Z") + + @filter.on_llm_request(priority=P4_MANUAL_REVIEW_OBSERVER_PRIORITY) + async def observe_p4_manual_review_candidate(self, event: AstrMessageEvent, req: ProviderRequest, *args, **kwargs): + """Queue a P3-finalized candidate only; never settle any P4 effect.""" + if self is None or event is None or req is None: + return + if not bool(getattr(self, "enable_p4_manual_review", False)): + return + try: + state = read_context_state(request=req, event=event) + except Exception: + return + if not isinstance(state, dict) or state.get("phase") != "finalized" or state.get("finalized") is not True: + return + security = state.get("security") + if not isinstance(security, dict) or security.get("status") not in {"allowed", "sanitized"}: + return + if security.get("response_policy") == "deny": + return + created_at = state.get("created_at") + expires_at = self._p4_manual_review_expiry(created_at) + if not isinstance(created_at, str) or not expires_at: + return + # The target identity must also be rooted in the direct AstrBot getter; + # never fall back to event fields, P3 carrier values, or request data. + sender_id = self._p4_manual_review_runtime_sender_id(event) + if not sender_id: + return + scope = runtime_scope_identity(event) + scope_kind = str(scope.get("scope_kind") or "") + scope_id = str(scope.get("scope_id") or "") + if not scope_kind or not scope_id: + return + try: + message_id = self._event_message_id(event) + except Exception: + return + if not message_id: + return + try: + authority = self._memory_companion_unified_person_authority( + event, + expected_user_id=sender_id, + ) + except Exception: + return + projection = authority.get("unified_person_projection") if isinstance(authority, dict) else None + source_identity = authority.get("unified_person_source_identity") if isinstance(authority, dict) else None + if not isinstance(projection, dict) or not isinstance(source_identity, dict): + return + person_id = _single_line(projection.get("person_id"), 160) + assurance = projection.get("identity_assurance") + if ( + not person_id + or projection.get("profile_status") != "active" + or assurance not in {"verified", "explicit_linked"} + ): + return + p3_proof = build_p3_review_proof( + state, + person_id=person_id, + identity_assurance=assurance, + scope_kind=scope_kind, + scope_id=scope_id, + ) + if p3_proof is None: + return + digest = hashlib.sha256(message_id.encode("utf-8", errors="ignore")).hexdigest() + candidate = { + "candidate_id": f"p4.review.candidate:{digest}", + "event_id": f"p4.review.event:{digest}", + "person_id": person_id, + "created_at": created_at, + "expires_at": expires_at, + "reason_code": "p3_finalized_observed", + "scope_kind": scope_kind, + "scope_id": scope_id, + "p3_proof": p3_proof, + } + operation_id = f"p4.review.candidate:{person_id}:{digest}" + try: + producer_attestation = self._p4_manual_review_attestation_registry().mint( + req, + event, + state, + candidate, + operation_id=operation_id, + ) + if producer_attestation is None: + return + result = self._apply_unified_person_lifecycle( + "record_p4_manual_review_candidate", + person_id, + candidate, + operation_id=operation_id, + producer_attestation=producer_attestation, + producer_request=req, + producer_event=event, + producer_state=state, + ) + except Exception as exc: + logger.debug("[PrivateCompanion] P4 manual review candidate skipped: %s", _single_line(exc, 160)) + return + if not isinstance(result, dict) or not result.get("ok"): + logger.debug( + "[PrivateCompanion] P4 manual review candidate rejected: code=%s", + _single_line(result.get("code") if isinstance(result, dict) else "", 120) or "unknown", + ) + @filter.on_llm_response() async def normalize_tts_enhancement_response(self, event: AstrMessageEvent, resp: LLMResponse, *args, **kwargs): """恢复降级为正文的生图调用,并规范化 TTS 标签。""" diff --git a/p4_manual_review.py b/p4_manual_review.py new file mode 100644 index 0000000..3c721a6 --- /dev/null +++ b/p4_manual_review.py @@ -0,0 +1,864 @@ +# -*- coding: utf-8 -*- +"""Default-off P4 manual-review contracts and isolated queue helpers. + +This module intentionally knows nothing about P4 shadow settlement, P4 effect +preparation, model output, pages, request carriers, or live enforcement. A +review decision is only an audited queue record; it never causes a punishment, +release, recovery, reply, or memory write. +""" +from __future__ import annotations + +from copy import deepcopy +from dataclasses import dataclass +from datetime import datetime, timezone +import hashlib +import json +import re +import threading +import time +import unicodedata +from typing import Any + +try: + from .context_orchestration import ( + CONTRACT_NAME as P3_CONTRACT_NAME, + CONTRACT_VERSION as P3_CONTRACT_VERSION, + LAYERS as P3_LAYERS, + contract_fingerprint as p3_contract_fingerprint, + ) +except ImportError: + from context_orchestration import ( + CONTRACT_NAME as P3_CONTRACT_NAME, + CONTRACT_VERSION as P3_CONTRACT_VERSION, + LAYERS as P3_LAYERS, + contract_fingerprint as p3_contract_fingerprint, + ) + + +P4_REVIEW_VERSION = 1 +P4_REVIEW_ALLOWED_SECURITY_STATUSES = frozenset({"allowed", "sanitized"}) +P4_REVIEW_ALLOWED_ASSURANCES = frozenset({"verified", "explicit_linked"}) +P4_REVIEW_ALLOWED_DECISIONS = frozenset({"approve", "reject"}) +P4_REVIEW_ALLOWED_POLICIES = frozenset({"inherit", "allow"}) + +_MAX_ID_LENGTH = 160 +_MAX_REASON_LENGTH = 120 +_REASON_RE = re.compile(r"[a-z0-9][a-z0-9_.:-]{0,119}\Z") +_OWNER_PLACEHOLDERS = frozenset({"", "none", "null", "undefined", "default"}) +_ATTESTATION_CREATION_TOKEN = object() +_HANDLE_CREATION_TOKEN = object() +P4_REVIEW_ATTESTATION_DEFAULT_TTL_SECONDS = 30.0 +P4_REVIEW_ATTESTATION_MAX_ENTRIES = 1024 + + +class P4ReviewProducerAttestationHandle: + """Opaque, non-serializable, one-shot P3 observer attestation.""" + + __slots__ = ("_registry",) + + def __init__(self, creation_token: object, registry: object) -> None: + if creation_token is not _HANDLE_CREATION_TOKEN: + raise TypeError("P4 review attestations are minted only by the host registry") + self._registry = registry + + def __reduce__(self) -> object: + raise TypeError("P4 review attestations cannot be serialized") + + def __reduce_ex__(self, protocol: int) -> object: + raise TypeError("P4 review attestations cannot be serialized") + + def __getstate__(self) -> object: + raise TypeError("P4 review attestations cannot be serialized") + + def __repr__(self) -> str: + return "" + + def __init_subclass__(cls, **kwargs: object) -> None: + raise TypeError("P4 review attestations cannot be subclassed") + + +@dataclass(slots=True) +class _ProducerAttestationEntry: + request: object + event: object + p3_state: object + candidate_fingerprint: str + candidate_id: str + event_id: str + person_id: str + scope_kind: str + scope_id: str + operation_id: str + expires_at: float + + +class P4ReviewAttestationRegistry: + """Host-owned bounded issuer for exact-carrier, one-shot P4 review handles.""" + + def __init__( + self, + creation_token: object | None = None, + *, + clock: Any | None = None, + default_ttl_seconds: float = P4_REVIEW_ATTESTATION_DEFAULT_TTL_SECONDS, + max_entries: int = P4_REVIEW_ATTESTATION_MAX_ENTRIES, + ) -> None: + if creation_token is not _ATTESTATION_CREATION_TOKEN: + raise TypeError("P4 review attestation registries are host-owned") + if isinstance(default_ttl_seconds, bool) or not isinstance(default_ttl_seconds, (int, float)): + raise TypeError("P4 review attestation TTL is invalid") + if default_ttl_seconds <= 0 or default_ttl_seconds > 300: + raise ValueError("P4 review attestation TTL is invalid") + if isinstance(max_entries, bool) or not isinstance(max_entries, int) or max_entries < 1: + raise ValueError("P4 review attestation capacity is invalid") + self._clock = clock or time.monotonic + self._default_ttl_seconds = float(default_ttl_seconds) + self._max_entries = max_entries + self._lock = threading.RLock() + self._entries: dict[P4ReviewProducerAttestationHandle, _ProducerAttestationEntry] = {} + self._unloaded = False + + def mint( + self, + request: object, + event: object, + p3_state: object, + candidate: Any, + *, + operation_id: Any, + ttl_seconds: float | None = None, + ) -> P4ReviewProducerAttestationHandle | None: + """Mint only after binding all live carriers and the normalized candidate.""" + if request is None or event is None or p3_state is None: + return None + try: + operation_id = _required_id(operation_id) + normalized, code = normalize_review_candidate( + candidate, + now=datetime.min.replace(tzinfo=timezone.utc), + ) + except Exception: + return None + if not operation_id or normalized is None or code: + return None + try: + ttl = self._default_ttl_seconds if ttl_seconds is None else float(ttl_seconds) + except (TypeError, ValueError): + return None + if ttl <= 0 or ttl > 300: + return None + proof = build_p3_review_proof( + p3_state, + person_id=normalized["person_id"], + identity_assurance=normalized["p3_proof"]["identity_assurance"], + scope_kind=normalized["scope_kind"], + scope_id=normalized["scope_id"], + ) + if proof is None or proof != normalized["p3_proof"]: + return None + with self._lock: + self._cleanup_locked(self._clock()) + if self._unloaded or len(self._entries) >= self._max_entries: + return None + handle = P4ReviewProducerAttestationHandle(_HANDLE_CREATION_TOKEN, self) + self._entries[handle] = _ProducerAttestationEntry( + request=request, + event=event, + p3_state=p3_state, + candidate_fingerprint=candidate_fingerprint(normalized), + candidate_id=normalized["candidate_id"], + event_id=normalized["event_id"], + person_id=normalized["person_id"], + scope_kind=normalized["scope_kind"], + scope_id=normalized["scope_id"], + operation_id=operation_id, + expires_at=self._clock() + ttl, + ) + return handle + + def consume( + self, + handle: object, + request: object, + event: object, + p3_state: object, + candidate: Any, + *, + operation_id: Any, + ) -> dict[str, str] | None: + """Consume once; wrong carriers, candidate, operation or expiry fail closed.""" + if type(handle) is not P4ReviewProducerAttestationHandle: + return None + try: + if handle._registry is not self: + return None + except Exception: + return None + with self._lock: + entry = self._entries.pop(handle, None) + if entry is None or self._unloaded or self._clock() >= entry.expires_at: + return None + if request is not entry.request or event is not entry.event or p3_state is not entry.p3_state: + return None + try: + operation_id = _required_id(operation_id) + normalized, code = normalize_review_candidate( + candidate, + now=datetime.min.replace(tzinfo=timezone.utc), + ) + except Exception: + return None + if ( + not operation_id + or operation_id != entry.operation_id + or normalized is None + or code + or normalized["candidate_id"] != entry.candidate_id + or normalized["event_id"] != entry.event_id + or normalized["person_id"] != entry.person_id + or normalized["scope_kind"] != entry.scope_kind + or normalized["scope_id"] != entry.scope_id + or candidate_fingerprint(normalized) != entry.candidate_fingerprint + ): + return None + return { + "candidate_fingerprint": entry.candidate_fingerprint, + "candidate_id": entry.candidate_id, + "event_id": entry.event_id, + "person_id": entry.person_id, + "scope_kind": entry.scope_kind, + "scope_id": entry.scope_id, + "operation_id": entry.operation_id, + } + + def pending_count(self) -> int: + with self._lock: + self._cleanup_locked(self._clock()) + return len(self._entries) + + def unload(self) -> None: + with self._lock: + self._entries.clear() + self._unloaded = True + + def _cleanup_locked(self, now: float) -> None: + for handle, entry in list(self._entries.items()): + if now >= entry.expires_at: + self._entries.pop(handle, None) + + +def _new_p4_review_attestation_registry( + *, + clock: Any | None = None, + default_ttl_seconds: float = P4_REVIEW_ATTESTATION_DEFAULT_TTL_SECONDS, + max_entries: int = P4_REVIEW_ATTESTATION_MAX_ENTRIES, +) -> P4ReviewAttestationRegistry: + """Create the host-owned issuer used by the P3 observer.""" + return P4ReviewAttestationRegistry( + _ATTESTATION_CREATION_TOKEN, + clock=clock, + default_ttl_seconds=default_ttl_seconds, + max_entries=max_entries, + ) + + +def consume_p4_review_producer_attestation( + handle: Any, + request: object, + event: object, + p3_state: object, + candidate: Any, + *, + operation_id: Any, +) -> dict[str, str] | None: + if type(handle) is not P4ReviewProducerAttestationHandle: + return None + try: + registry = handle._registry + except Exception: + return None + if not isinstance(registry, P4ReviewAttestationRegistry): + return None + return registry.consume( + handle, + request, + event, + p3_state, + candidate, + operation_id=operation_id, + ) + + +def _canonical(value: Any) -> str: + return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + + +def _single_line_id(value: Any, *, limit: int = _MAX_ID_LENGTH) -> str: + """Normalize one runtime/config ID without accepting a carrier-like value.""" + if isinstance(value, bool) or not isinstance(value, (str, int)): + return "" + text = unicodedata.normalize("NFKC", str(value)).strip() + if not text or len(text) > limit or text.lower() in _OWNER_PLACEHOLDERS: + return "" + # IDs are deliberately one token: no newline, whitespace, NUL, or other + # control/format character may survive configuration parsing. + if any(character.isspace() or unicodedata.category(character).startswith("C") for character in text): + return "" + return text + + +def parse_owner_allowlist(value: Any) -> tuple[str, ...]: + """Parse a config-only owner allowlist, accepting list/string separators. + + The output is merely an allowlist. It is never a runtime credential: a + later gate must still obtain its actor from ``event.get_sender_id()``. + """ + raw_items: list[Any] = [] + if isinstance(value, str): + raw_items.extend(piece for piece in re.split(r"[\s,,;;]+", value) if piece) + elif isinstance(value, (list, tuple, set, frozenset)): + for item in value: + if isinstance(item, str): + raw_items.extend(piece for piece in re.split(r"[\s,,;;]+", item) if piece) + else: + raw_items.append(item) + else: + raw_items.append(value) + result: list[str] = [] + for raw in raw_items: + owner_id = _single_line_id(raw) + if owner_id and owner_id not in result: + result.append(owner_id) + return tuple(result) + + +def runtime_owner_identity(event: Any, configured_owner_ids: Any) -> dict[str, Any]: + """Accept only a direct AstrBot runtime sender matching the config allowlist. + + This intentionally does not inspect a dict, page field, request carrier, + model text, ``event.sender_id``, or ``event.user_id``. A test double is + valid only when it exposes a callable ``get_sender_id`` method. + """ + allowlist = parse_owner_allowlist(configured_owner_ids) + if not allowlist: + return {"accepted": False, "code": "p4_review_owner_allowlist_empty", "actor_id": ""} + if event is None: + return {"accepted": False, "code": "p4_review_owner_runtime_missing", "actor_id": ""} + try: + getter = getattr(event, "get_sender_id", None) + except Exception: + return {"accepted": False, "code": "p4_review_owner_runtime_unavailable", "actor_id": ""} + if not callable(getter): + return {"accepted": False, "code": "p4_review_owner_runtime_missing", "actor_id": ""} + try: + actor_id = _single_line_id(getter()) + except Exception: + return {"accepted": False, "code": "p4_review_owner_runtime_unavailable", "actor_id": ""} + if not actor_id: + return {"accepted": False, "code": "p4_review_owner_runtime_invalid", "actor_id": ""} + if actor_id not in allowlist: + return {"accepted": False, "code": "p4_review_owner_not_allowed", "actor_id": ""} + return { + "accepted": True, + "code": "p4_review_owner_runtime_verified", + "actor_id": actor_id, + "allowlist_size": len(allowlist), + } + + +def runtime_scope_identity(event: Any) -> dict[str, str]: + """Read a scope only from direct AstrBot runtime methods. + + Group IDs must never fall back to raw payload fields or unified message + origins. Unknown or exceptional scope identity is therefore rejected. + """ + if event is None: + return {"scope_kind": "", "scope_id": ""} + try: + group_getter = getattr(event, "get_group_id", None) + except Exception: + return {"scope_kind": "", "scope_id": ""} + if not callable(group_getter): + return {"scope_kind": "", "scope_id": ""} + try: + group_id = _single_line_id(group_getter()) + except Exception: + return {"scope_kind": "", "scope_id": ""} + if not group_id: + return {"scope_kind": "", "scope_id": ""} + try: + platform_getter = getattr(event, "get_platform_name", None) + except Exception: + return {"scope_kind": "", "scope_id": ""} + if not callable(platform_getter): + return {"scope_kind": "", "scope_id": ""} + try: + platform_id = _single_line_id(platform_getter()) + except Exception: + return {"scope_kind": "", "scope_id": ""} + if not platform_id: + return {"scope_kind": "", "scope_id": ""} + return {"scope_kind": "group", "scope_id": f"{platform_id}:{group_id}"} + + +def _timestamp(value: Any) -> tuple[str, datetime | None]: + if not isinstance(value, str) or not value or len(value) > 80 or "\x00" in value: + return "", None + text = value.strip() + if not text or any(character.isspace() for character in text[:-1]): + return "", None + try: + parsed = datetime.fromisoformat(text[:-1] + "+00:00" if text.endswith("Z") else text) + except (TypeError, ValueError): + return "", None + if parsed.tzinfo is None: + return "", None + utc = parsed.astimezone(timezone.utc) + return utc.isoformat(timespec="seconds").replace("+00:00", "Z"), utc + + +def _reason_code(value: Any) -> str: + if not isinstance(value, str): + return "" + code = value.strip().lower() + return code if len(code) <= _MAX_REASON_LENGTH and _REASON_RE.fullmatch(code) else "" + + +def _required_id(value: Any) -> str: + return _single_line_id(value, limit=_MAX_ID_LENGTH) + + +def build_p3_review_proof( + state: Any, + *, + person_id: Any, + identity_assurance: Any, + scope_kind: Any, + scope_id: Any, +) -> dict[str, Any] | None: + """Project only a validated P3 final state into the review contract.""" + if not isinstance(state, dict): + return None + if ( + state.get("contract_name") != P3_CONTRACT_NAME + or state.get("contract_version") != P3_CONTRACT_VERSION + or state.get("contract_fingerprint") != p3_contract_fingerprint() + or state.get("phase") != "finalized" + or state.get("finalized") is not True + or state.get("completed_layers") != list(P3_LAYERS) + ): + return None + normalized_person_id = _required_id(person_id) + assurance = str(identity_assurance or "").strip() + normalized_scope_kind = str(scope_kind or "").strip().lower() + normalized_scope_id = _required_id(scope_id) + security = state.get("security") + if ( + not normalized_person_id + or assurance not in P4_REVIEW_ALLOWED_ASSURANCES + or normalized_scope_kind != "group" + or not normalized_scope_id + or state.get("scope") != normalized_scope_kind + or not isinstance(security, dict) + or security.get("status") not in P4_REVIEW_ALLOWED_SECURITY_STATUSES + or security.get("response_policy") not in P4_REVIEW_ALLOWED_POLICIES + ): + return None + security_event_id = security.get("event_id") + if not isinstance(security_event_id, str) or len(security_event_id) > 180 or "\x00" in security_event_id: + return None + created_at = state.get("created_at") + normalized_created_at, _ = _timestamp(created_at) + if not normalized_created_at: + return None + return { + "contract_name": P3_CONTRACT_NAME, + "contract_version": P3_CONTRACT_VERSION, + "contract_fingerprint": p3_contract_fingerprint(), + "completed_layers": list(P3_LAYERS), + "phase": "finalized", + "finalized": True, + "security_status": security["status"], + "response_policy": security["response_policy"], + "security_event_id": security_event_id, + "person_id": normalized_person_id, + "identity_assurance": assurance, + "scope_kind": normalized_scope_kind, + "scope_id": normalized_scope_id, + "created_at": normalized_created_at, + } + + +def normalize_review_candidate(candidate: Any, *, now: datetime | None = None) -> tuple[dict[str, Any] | None, str]: + """Validate the immutable, observer-produced review-candidate contract.""" + if not isinstance(candidate, dict): + return None, "p4_review_candidate_invalid" + candidate_id = _required_id(candidate.get("candidate_id")) + event_id = _required_id(candidate.get("event_id")) + person_id = _required_id(candidate.get("person_id")) + scope_kind = str(candidate.get("scope_kind") or "").strip().lower() + scope_id = _required_id(candidate.get("scope_id")) + reason_code = _reason_code(candidate.get("reason_code")) + created_at, created_when = _timestamp(candidate.get("created_at")) + expires_at, expires_when = _timestamp(candidate.get("expires_at")) + proof = candidate.get("p3_proof") + if not all((candidate_id, event_id, person_id, scope_kind, scope_id, reason_code, created_at, expires_at)): + return None, "p4_review_candidate_missing_required_field" + if scope_kind != "group": + return None, "p4_review_candidate_scope_invalid" + if created_when is None or expires_when is None or expires_when <= created_when: + return None, "p4_review_candidate_time_invalid" + if not isinstance(proof, dict): + return None, "p4_review_candidate_p3_proof_invalid" + proof_created_at, proof_when = _timestamp(proof.get("created_at")) + proof_fingerprint = proof.get("contract_fingerprint") + proof_layers = proof.get("completed_layers") + proof_policy = proof.get("response_policy") + proof_event_id = proof.get("security_event_id") + proof_scope_kind = str(proof.get("scope_kind") or "").strip().lower() + proof_scope_id = _required_id(proof.get("scope_id")) + if ( + proof.get("contract_name") != P3_CONTRACT_NAME + or proof.get("contract_version") != P3_CONTRACT_VERSION + or proof_fingerprint != p3_contract_fingerprint() + or proof_layers != list(P3_LAYERS) + or proof.get("phase") != "finalized" + or proof.get("finalized") is not True + or proof.get("security_status") not in P4_REVIEW_ALLOWED_SECURITY_STATUSES + or proof_policy not in P4_REVIEW_ALLOWED_POLICIES + or not isinstance(proof_event_id, str) + or len(proof_event_id) > 180 + or "\x00" in proof_event_id + or proof.get("person_id") != person_id + or proof.get("identity_assurance") not in P4_REVIEW_ALLOWED_ASSURANCES + or proof_scope_kind != scope_kind + or proof_scope_id != scope_id + or proof_created_at != created_at + or proof_when is None + ): + return None, "p4_review_candidate_p3_proof_invalid" + clock = now or datetime.now(timezone.utc) + if expires_when <= clock.astimezone(timezone.utc): + return None, "p4_review_candidate_expired" + return { + "candidate_id": candidate_id, + "event_id": event_id, + "person_id": person_id, + "scope_kind": scope_kind, + "scope_id": scope_id, + "created_at": created_at, + "expires_at": expires_at, + "reason_code": reason_code, + "p3_proof": { + "phase": "finalized", + "finalized": True, + "contract_name": P3_CONTRACT_NAME, + "contract_version": P3_CONTRACT_VERSION, + "contract_fingerprint": p3_contract_fingerprint(), + "completed_layers": list(P3_LAYERS), + "security_status": proof["security_status"], + "response_policy": proof_policy, + "security_event_id": proof_event_id, + "person_id": person_id, + "identity_assurance": proof["identity_assurance"], + "scope_kind": scope_kind, + "scope_id": scope_id, + "created_at": created_at, + }, + }, "" + + +def candidate_fingerprint(candidate: dict[str, Any]) -> str: + return hashlib.sha256(_canonical(candidate).encode("utf-8")).hexdigest() + + +def decision_fingerprint(record: dict[str, Any], *, candidate_fp: str) -> str: + return hashlib.sha256( + _canonical( + { + "candidate_fingerprint": candidate_fp, + "candidate_id": record.get("candidate_id"), + "event_id": record.get("event_id"), + "person_id": record.get("person_id"), + "scope_kind": record.get("scope_kind"), + "scope_id": record.get("scope_id"), + "actor_id": record.get("actor_id"), + "decision": record.get("decision"), + "reason_code": record.get("reason_code"), + "occurred_at": record.get("occurred_at"), + "operation_id": record.get("operation_id"), + } + ).encode("utf-8") + ).hexdigest() + + +def ensure_review_container(root: dict[str, Any]) -> tuple[dict[str, Any] | None, str]: + """Create an additive ``unified_person.p4_review`` container once. + + Existing malformed containers fail closed rather than being replaced. + """ + if not isinstance(root, dict): + return None, "p4_review_corrupt" + container = root.get("p4_review") + if container is None: + container = { + "version": P4_REVIEW_VERSION, + "candidates": {}, + "event_index": {}, + "decisions": {}, + } + root["p4_review"] = container + return container, "" + if not isinstance(container, dict): + return None, "p4_review_corrupt" + if container.get("version") != P4_REVIEW_VERSION: + return None, "p4_review_corrupt" + for key in ("candidates", "event_index", "decisions"): + if not isinstance(container.get(key), dict): + return None, "p4_review_corrupt" + return container, "" + + +def queue_candidate( + container: dict[str, Any], + candidate: dict[str, Any], + *, + operation_id: str, + recorded_at: str, +) -> tuple[dict[str, Any] | None, str]: + """Append a candidate to only the separate review queue.""" + candidates = container.get("candidates") + event_index = container.get("event_index") + if not isinstance(candidates, dict) or not isinstance(event_index, dict): + return None, "p4_review_corrupt" + fingerprint = candidate_fingerprint(candidate) + candidate_id = candidate["candidate_id"] + event_id = candidate["event_id"] + known = candidates.get(candidate_id) + if known is not None: + if not isinstance(known, dict) or known.get("candidate_fingerprint") != fingerprint: + return None, "p4_review_candidate_id_conflict" + indexed_known = event_index.get(candidate["event_id"]) + if ( + not isinstance(indexed_known, dict) + or indexed_known.get("candidate_id") != candidate_id + or indexed_known.get("candidate_fingerprint") != fingerprint + ): + return None, "p4_review_candidate_integrity_error" + return deepcopy(known), "p4_review_candidate_duplicate" + indexed = event_index.get(event_id) + if indexed is not None: + if not isinstance(indexed, dict) or indexed.get("candidate_fingerprint") != fingerprint: + return None, "p4_review_event_id_conflict" + return None, "p4_review_candidate_id_conflict" + record = { + **deepcopy(candidate), + "candidate_fingerprint": fingerprint, + "recorded_at": recorded_at, + "operation_id": operation_id, + } + candidates[candidate_id] = record + event_index[event_id] = {"candidate_id": candidate_id, "candidate_fingerprint": fingerprint} + return deepcopy(record), "p4_review_candidate_recorded" + + +def queue_decision( + container: dict[str, Any], + *, + person_id: str, + candidate_id: str, + actor_id: str, + scope_kind: str, + scope_id: str, + decision: str, + reason_code: str, + operation_id: str, + occurred_at: str, + now: datetime | None = None, +) -> tuple[dict[str, Any] | None, str]: + """Append an audited conclusion without any live P4 effect.""" + candidates = container.get("candidates") + event_index = container.get("event_index") + decisions = container.get("decisions") + if not isinstance(candidates, dict) or not isinstance(event_index, dict) or not isinstance(decisions, dict): + return None, "p4_review_corrupt" + candidate = candidates.get(candidate_id) + if not isinstance(candidate, dict): + return None, "p4_review_candidate_not_found" + normalized, code = normalize_review_candidate(candidate, now=now) + if normalized is None: + return None, code + stored_fingerprint = candidate.get("candidate_fingerprint") + if stored_fingerprint != candidate_fingerprint(normalized): + return None, "p4_review_candidate_integrity_error" + indexed = event_index.get(normalized["event_id"]) + if ( + not isinstance(indexed, dict) + or indexed.get("candidate_id") != candidate_id + or indexed.get("candidate_fingerprint") != stored_fingerprint + ): + return None, "p4_review_candidate_integrity_error" + if normalized["person_id"] != person_id: + return None, "p4_review_candidate_person_mismatch" + if normalized["scope_kind"] != scope_kind or normalized["scope_id"] != scope_id: + return None, "p4_review_candidate_scope_mismatch" + existing = decisions.get(candidate_id) + if existing is not None: + if not isinstance(existing, dict): + return None, "p4_review_corrupt" + expected_existing = { + "candidate_id": candidate_id, + "event_id": normalized["event_id"], + "person_id": normalized["person_id"], + "scope_kind": normalized["scope_kind"], + "scope_id": normalized["scope_id"], + "actor_id": existing.get("actor_id"), + "decision": existing.get("decision"), + "reason_code": existing.get("reason_code"), + "occurred_at": existing.get("occurred_at"), + "operation_id": existing.get("operation_id"), + } + if ( + existing.get("candidate_fingerprint") != stored_fingerprint + or existing.get("event_id") != expected_existing["event_id"] + or existing.get("person_id") != expected_existing["person_id"] + or existing.get("scope_kind") != expected_existing["scope_kind"] + or existing.get("scope_id") != expected_existing["scope_id"] + or existing.get("decision_fingerprint") != decision_fingerprint(expected_existing, candidate_fp=stored_fingerprint) + ): + return None, "p4_review_decision_integrity_error" + if existing.get("decision") != decision: + return None, "p4_review_decision_conflict" + if ( + existing.get("actor_id") != actor_id + or existing.get("reason_code") != reason_code + or existing.get("scope_kind") != scope_kind + or existing.get("scope_id") != scope_id + ): + return None, "p4_review_decision_conflict" + return deepcopy(existing), "p4_review_decision_duplicate" + record = { + "candidate_id": candidate_id, + "event_id": normalized["event_id"], + "person_id": person_id, + "scope_kind": scope_kind, + "scope_id": scope_id, + "actor_id": actor_id, + "decision": decision, + "reason_code": reason_code, + "occurred_at": occurred_at, + "operation_id": operation_id, + } + record["candidate_fingerprint"] = stored_fingerprint + record["decision_fingerprint"] = decision_fingerprint(record, candidate_fp=stored_fingerprint) + decisions[candidate_id] = record + return deepcopy(record), "p4_review_decision_recorded" + + +def validate_review_operation_replay( + container: Any, + *, + action: str, + result: dict[str, Any], + payload: dict[str, Any], +) -> str: + """Re-check the ledger envelope before returning a cached operation result.""" + if not result.get("ok"): + return "" + if not isinstance(container, dict): + return "p4_review_corrupt" + candidates = container.get("candidates") + event_index = container.get("event_index") + decisions = container.get("decisions") + if not isinstance(candidates, dict) or not isinstance(event_index, dict) or not isinstance(decisions, dict): + return "p4_review_corrupt" + candidate_id = payload.get("candidate_id") + if not isinstance(candidate_id, str) and isinstance(payload.get("candidate"), dict): + candidate_id = payload["candidate"].get("candidate_id") + if not isinstance(candidate_id, str): + return "p4_review_candidate_integrity_error" + stored_candidate = candidates.get(candidate_id) + if not isinstance(stored_candidate, dict): + return "p4_review_candidate_integrity_error" + normalized_candidate, candidate_code = normalize_review_candidate( + stored_candidate, + now=datetime.min.replace(tzinfo=timezone.utc), + ) + stored_candidate_fp = stored_candidate.get("candidate_fingerprint") + if ( + normalized_candidate is None + or candidate_code + or stored_candidate_fp != candidate_fingerprint(normalized_candidate) + or normalized_candidate["person_id"] != payload.get("person_id") + or not isinstance(event_index.get(normalized_candidate["event_id"]), dict) + or event_index[normalized_candidate["event_id"]].get("candidate_id") != candidate_id + or event_index[normalized_candidate["event_id"]].get("candidate_fingerprint") != stored_candidate_fp + ): + return "p4_review_candidate_integrity_error" + if ( + result.get("candidate_id") is not None + and result.get("candidate_id") != candidate_id + ) or ( + result.get("person_id") is not None + and result.get("person_id") != normalized_candidate["person_id"] + ): + return "p4_review_candidate_integrity_error" + if action == "record_p4_manual_review_candidate": + if result.get("event_id") is not None and result.get("event_id") != normalized_candidate["event_id"]: + return "p4_review_candidate_integrity_error" + return "" + if action != "record_p4_manual_review_decision": + return "" + stored_decision = decisions.get(candidate_id) + if not isinstance(stored_decision, dict): + return "p4_review_decision_integrity_error" + expected_decision = { + "candidate_id": candidate_id, + "event_id": normalized_candidate["event_id"], + "person_id": normalized_candidate["person_id"], + "scope_kind": normalized_candidate["scope_kind"], + "scope_id": normalized_candidate["scope_id"], + "actor_id": stored_decision.get("actor_id"), + "decision": stored_decision.get("decision"), + "reason_code": stored_decision.get("reason_code"), + "occurred_at": stored_decision.get("occurred_at"), + "operation_id": stored_decision.get("operation_id"), + } + if ( + stored_decision.get("candidate_fingerprint") != stored_candidate_fp + or any(stored_decision.get(key) != value for key, value in expected_decision.items() if key not in {"candidate_id", "actor_id", "decision", "reason_code", "occurred_at", "operation_id"}) + or stored_decision.get("decision_fingerprint") != decision_fingerprint(expected_decision, candidate_fp=stored_candidate_fp) + or stored_decision.get("actor_id") != payload.get("actor_id") + or stored_decision.get("decision") != payload.get("decision") + or stored_decision.get("reason_code") != payload.get("reason_code") + or stored_decision.get("scope_kind") != payload.get("scope_kind") + or stored_decision.get("scope_id") != payload.get("scope_id") + ): + return "p4_review_decision_integrity_error" + return "" + + +def normalize_decision_request( + *, + person_id: Any, + candidate_id: Any, + decision: Any, + reason_code: Any, + operation_id: Any, +) -> tuple[dict[str, str] | None, str]: + normalized_person_id = _required_id(person_id) + normalized_candidate_id = _required_id(candidate_id) + normalized_operation_id = _required_id(operation_id) + normalized_reason_code = _reason_code(reason_code) + normalized_decision = decision.strip().lower() if isinstance(decision, str) else "" + if not all((normalized_person_id, normalized_candidate_id, normalized_operation_id, normalized_reason_code)): + return None, "p4_review_decision_invalid" + if normalized_decision not in P4_REVIEW_ALLOWED_DECISIONS: + return None, "p4_review_decision_invalid" + return { + "person_id": normalized_person_id, + "candidate_id": normalized_candidate_id, + "decision": normalized_decision, + "reason_code": normalized_reason_code, + "operation_id": normalized_operation_id, + }, "" diff --git a/tests/test_p4_manual_review.py b/tests/test_p4_manual_review.py new file mode 100644 index 0000000..31e7485 --- /dev/null +++ b/tests/test_p4_manual_review.py @@ -0,0 +1,586 @@ +# -*- coding: utf-8 -*- +"""Pure P4 manual-review boundary tests: no P4 live effect is exercised.""" +from __future__ import annotations + +from copy import deepcopy +from datetime import datetime, timedelta, timezone +import importlib +from pathlib import Path +import sys +import types +import unittest + + +ROOT = Path(__file__).resolve().parents[1] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +from p4_manual_review import ( + P3_CONTRACT_NAME, + P3_CONTRACT_VERSION, + P3_LAYERS, + _new_p4_review_attestation_registry, + p3_contract_fingerprint, + parse_owner_allowlist, + runtime_owner_identity, +) +from unified_person_contract import empty_unified_person_store +from unified_person_registry import UnifiedPersonRegistry + + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _host_stub # noqa: E402 + +_host_stub.install() +_PACKAGE = "_p4_manual_review_core_store_companion" +if _PACKAGE not in sys.modules: + package = types.ModuleType(_PACKAGE) + package.__path__ = [str(ROOT)] + sys.modules[_PACKAGE] = package +core_store_module = importlib.import_module(f"{_PACKAGE}.core_store") +core_review_module = importlib.import_module(f"{_PACKAGE}.p4_manual_review") +context_module = importlib.import_module(f"{_PACKAGE}.context_orchestration") + + +def identity(subject_id: str) -> dict[str, str]: + return { + "companion_instance_id": "companion-a", + "bot_account_id": "bot-a", + "adapter_instance_id": "telegram-main", + "subject_namespace": "telegram.user", + "platform_subject_id": subject_id, + } + + +def timestamp(value: datetime) -> str: + return value.astimezone(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z") + + +def candidate( + person_id: str, + *, + token: str = "one", + assurance: str = "verified", + created_offset: timedelta = timedelta(), + expires_in: timedelta = timedelta(hours=1), + scope_id: str = "aiocqhttp:group-1", +) -> dict: + created = (datetime.now(timezone.utc) + created_offset).replace(microsecond=0) + created_at = timestamp(created) + return { + "candidate_id": f"candidate-{token}", + "event_id": f"event-{token}", + "person_id": person_id, + "scope_kind": "group", + "scope_id": scope_id, + "created_at": created_at, + "expires_at": timestamp(created + expires_in), + "reason_code": "p3_finalized_observed", + "p3_proof": { + "contract_name": P3_CONTRACT_NAME, + "contract_version": P3_CONTRACT_VERSION, + "contract_fingerprint": p3_contract_fingerprint(), + "completed_layers": list(P3_LAYERS), + "phase": "finalized", + "finalized": True, + "security_status": "allowed", + "response_policy": "inherit", + "security_event_id": "", + "person_id": person_id, + "identity_assurance": assurance, + "scope_kind": "group", + "scope_id": scope_id, + "created_at": created_at, + }, + } + + +class _RuntimeEvent: + def __init__(self, sender_id: object = "owner-a", *, raises: bool = False, group_id: str = "group-1", platform: str = "aiocqhttp") -> None: + self._sender_id = sender_id + self._raises = raises + self._group_id = group_id + self._platform = platform + # These forged event fields must never be read by the owner gate. + self.sender_id = "forged-field-owner" + self.user_id = "forged-field-owner" + + def get_group_id(self): + return self._group_id + + def get_platform_name(self): + return self._platform + + def get_sender_id(self): + if self._raises: + raise RuntimeError("runtime unavailable") + return self._sender_id + + +def _make_candidate_attestation(raw: dict, operation_id: str, review_module=None): + state = _build_p3_state(raw) + request = object() + event = _RuntimeEvent("sender-42") + registry = (review_module or sys.modules["p4_manual_review"])._new_p4_review_attestation_registry() + handle = registry.mint(request, event, state, raw, operation_id=operation_id) + return handle, request, event, state + + +def _build_p3_state(raw: dict) -> dict: + state = context_module.new_context_state(scope="group", created_at=raw["created_at"]) + context_module.update_security(state, status=raw["p3_proof"]["security_status"], response_policy=raw["p3_proof"]["response_policy"]) + for layer in context_module.LAYERS: + context_module.complete_layer(state, layer) + context_module.finalize_state(state) + return state + + +class _CoreStoreHost(core_store_module.CoreStoreMixin): + def __init__(self, data: dict) -> None: + self.data = data + self.save_calls = 0 + self.enable_p4_manual_review = True + + def _schedule_data_save(self) -> None: + self.save_calls += 1 + + +class P4ManualReviewOwnerGateTests(unittest.TestCase): + def test_config_allowlist_parses_only_safe_single_line_ids(self) -> None: + self.assertEqual( + ("owner-a", "owner-b", "owner-c", "123"), + parse_owner_allowlist([" owner-a, owner-b\nowner-c ", 123, "owner-a"]), + ) + self.assertEqual((), parse_owner_allowlist({"owner": "not-a-list"})) + self.assertEqual((), parse_owner_allowlist(["owner-a\x00evil", "\n"])) + + def test_runtime_owner_requires_direct_get_sender_id_and_allowlist_match(self) -> None: + accepted = runtime_owner_identity(_RuntimeEvent("owner-a"), "owner-a, owner-b") + self.assertTrue(accepted["accepted"]) + self.assertEqual("owner-a", accepted["actor_id"]) + + cases = [ + ({"get_sender_id": lambda: "owner-a", "sender_id": "owner-a"}, "p4_review_owner_runtime_missing"), + (_RuntimeEvent("intruder"), "p4_review_owner_not_allowed"), + (_RuntimeEvent("owner-a\nforged"), "p4_review_owner_runtime_invalid"), + (_RuntimeEvent(raises=True), "p4_review_owner_runtime_unavailable"), + (None, "p4_review_owner_runtime_missing"), + ] + for event, code in cases: + with self.subTest(code=code): + result = runtime_owner_identity(event, ["owner-a"]) + self.assertFalse(result["accepted"]) + self.assertEqual(code, result["code"]) + + +class P4ManualReviewAttestationTests(unittest.TestCase): + def _mint(self, *, registry=None, operation_id="attestation-op"): + raw = candidate("person-attestation", token=operation_id) + state = _build_p3_state(raw) + request = object() + event = _RuntimeEvent("sender-42") + registry = registry or _new_p4_review_attestation_registry() + handle = registry.mint(request, event, state, raw, operation_id=operation_id) + self.assertIsNotNone(handle) + return registry, handle, request, event, state, raw + + def test_attestation_binds_exact_carriers_candidate_and_operation_once(self) -> None: + registry, handle, request, event, state, raw = self._mint() + snapshot = registry.consume(handle, request, event, state, raw, operation_id="attestation-op") + self.assertIsInstance(snapshot, dict) + self.assertEqual("attestation-op", snapshot["operation_id"]) + self.assertIsNone(registry.consume(handle, request, event, state, raw, operation_id="attestation-op")) + + def test_wrong_carrier_or_candidate_consumes_handle_and_cannot_retry(self) -> None: + registry, handle, request, event, state, raw = self._mint() + wrong_candidate = deepcopy(raw) + wrong_candidate["reason_code"] = "different_reason" + self.assertIsNone( + registry.consume(handle, request, event, state, wrong_candidate, operation_id="attestation-op") + ) + self.assertIsNone(registry.consume(handle, request, event, state, raw, operation_id="attestation-op")) + + def test_fake_handle_and_expiry_fail_closed(self) -> None: + registry, handle, request, event, state, raw = self._mint() + self.assertIsNone(registry.consume(object(), request, event, state, raw, operation_id="attestation-op")) + now = [0.0] + expiring = _new_p4_review_attestation_registry(clock=lambda: now[0], default_ttl_seconds=1.0) + expiring_handle, expiring_request, expiring_event, expiring_state, expiring_raw = self._mint( + registry=expiring, operation_id="expiring-op" + )[1:] + now[0] = 2.0 + self.assertIsNone( + expiring.consume( + expiring_handle, + expiring_request, + expiring_event, + expiring_state, + expiring_raw, + operation_id="expiring-op", + ) + ) + + +class P4ManualReviewRegistryTests(unittest.TestCase): + def setUp(self) -> None: + self.store = {"unified_person": empty_unified_person_store()} + self.registry = UnifiedPersonRegistry(self.store) + + def _person(self, subject: str = "reviewer-target", *, assurance: str = "verified") -> str: + result = self.registry.upsert_observed_identity(identity(subject), operation_id=f"observe-{subject}") + self.assertTrue(result["ok"]) + person_id = result["person_id"] + self.store["unified_person"]["profiles"][person_id]["identity_assurance"] = assurance + return person_id + + def _queue(self, person_id: str, token: str = "one", *, operation_id: str | None = None, **kwargs) -> dict: + raw = candidate(person_id, token=token, **kwargs) + return self._record_candidate(person_id, raw, operation_id=operation_id or f"queue-{token}") + + @staticmethod + def _p3_state(raw: dict) -> dict: + state = context_module.new_context_state(scope="group", created_at=raw["created_at"]) + context_module.update_security(state, status=raw["p3_proof"]["security_status"], response_policy=raw["p3_proof"]["response_policy"]) + for layer in context_module.LAYERS: + context_module.complete_layer(state, layer) + context_module.finalize_state(state) + return state + + def _record_candidate(self, person_id: str, raw: dict, *, operation_id: str) -> dict: + attestation, request, event, state = self._mint(raw, operation_id=operation_id) + return self.registry.record_p4_manual_review_candidate( + person_id, + raw, + operation_id=operation_id, + producer_attestation=attestation, + producer_request=request, + producer_event=event, + producer_state=state, + ) + + def _mint(self, raw: dict, *, operation_id: str): + request = object() + event = _RuntimeEvent("sender-42") + state = self._p3_state(raw) + registry = _new_p4_review_attestation_registry() + attestation = registry.mint(request, event, state, raw, operation_id=operation_id) + return attestation, request, event, state + + def test_candidate_queue_is_additive_and_ignores_forged_self_authorization(self) -> None: + person_id = self._person() + profile_before = deepcopy(self.store["unified_person"]["profiles"][person_id]) + raw = candidate(person_id) + raw.update({"authorized": True, "approved": True, "owner": "forged-owner"}) + result = self._record_candidate(person_id, raw, operation_id="queue-one") + + self.assertTrue(result["ok"]) + self.assertEqual("p4_review_candidate_recorded", result["code"]) + self.assertFalse(result["live_effect_permitted"]) + self.assertFalse(result["effect_applied"]) + self.assertEqual(profile_before, self.store["unified_person"]["profiles"][person_id]) + root = self.store["unified_person"] + self.assertIn("p4_review", root) + self.assertNotIn("p4_shadow", root) + self.assertNotIn("p4_effect", root) + saved = root["p4_review"]["candidates"]["candidate-one"] + self.assertNotIn("authorized", saved) + self.assertNotIn("approved", saved) + self.assertNotIn("owner", saved) + self.assertEqual("p4_manual_review_candidate_recorded", self.registry.audit_events()[-1]["action"]) + + def test_candidate_requires_observer_token_and_exact_p3_policy(self) -> None: + person_id = self._person("producer-boundary") + raw = candidate(person_id, token="producer-boundary") + denied = self.registry.record_p4_manual_review_candidate( + person_id, raw, operation_id="producer-missing" + ) + self.assertEqual("p4_review_producer_unavailable", denied["code"]) + original = candidate(person_id, token="producer-forged-policy") + attestation, request, event, state = self._mint(original, operation_id="producer-forged-policy") + forged = deepcopy(original) + forged["p3_proof"]["response_policy"] = "forged-policy" + invalid = self.registry.record_p4_manual_review_candidate( + person_id, + forged, + operation_id="producer-forged-policy", + producer_attestation=attestation, + producer_request=request, + producer_event=event, + producer_state=state, + ) + self.assertEqual("p4_review_candidate_p3_proof_invalid", invalid["code"]) + + def test_missing_unknown_inactive_low_assurance_cross_person_and_expired_candidates_fail_closed(self) -> None: + missing = self.registry.record_p4_manual_review_candidate( + "person-missing", {"candidate_id": "only"}, operation_id="missing-fields" + ) + self.assertEqual("p4_review_candidate_missing_required_field", missing["code"]) + self.assertNotIn("p4_review", self.store["unified_person"]) + + person_id = self._person("unknown-check") + unknown = self._record_candidate("person-other", candidate("person-other", token="unknown"), operation_id="unknown") + self.assertEqual("person_not_found", unknown["code"]) + + cross_person = self._record_candidate(person_id, candidate("person-other", token="cross"), operation_id="cross") + self.assertEqual("p4_review_candidate_person_mismatch", cross_person["code"]) + + self.store["unified_person"]["profiles"][person_id]["profile_status"] = "suspended" + inactive = self._queue(person_id, "inactive") + self.assertEqual("person_not_active", inactive["code"]) + self.store["unified_person"]["profiles"][person_id]["profile_status"] = "active" + + self.store["unified_person"]["profiles"][person_id]["identity_assurance"] = "observed" + low_assurance = self._queue(person_id, "low") + self.assertEqual("p4_review_person_assurance_insufficient", low_assurance["code"]) + self.store["unified_person"]["profiles"][person_id]["identity_assurance"] = "verified" + + expired = self._queue( + person_id, + "expired", + created_offset=timedelta(hours=-2), + expires_in=timedelta(hours=1), + ) + self.assertEqual("p4_review_candidate_expired", expired["code"]) + self.assertNotIn("p4_review", self.store["unified_person"]) + + def test_candidate_idempotence_duplicate_and_conflicts_do_not_overwrite(self) -> None: + person_id = self._person("idempotence") + raw = candidate(person_id, token="idempotence") + first = self._record_candidate(person_id, raw, operation_id="candidate-op") + self.assertTrue(first["ok"]) + snapshot = deepcopy(self.store) + + repeated = self._record_candidate(person_id, deepcopy(raw), operation_id="candidate-op") + self.assertTrue(repeated["ok"]) + self.assertTrue(repeated["idempotent"]) + self.assertEqual(snapshot, self.store) + + duplicate = self._record_candidate(person_id, deepcopy(raw), operation_id="candidate-duplicate-op") + self.assertTrue(duplicate["ok"]) + self.assertTrue(duplicate["candidate_duplicate"]) + self.assertFalse(duplicate["changed"]) + conflict_snapshot = deepcopy(self.store) + + conflicting_candidate = deepcopy(raw) + conflicting_candidate["reason_code"] = "different_reason" + conflict = self._record_candidate(person_id, conflicting_candidate, operation_id="candidate-conflict-op") + self.assertEqual("p4_review_candidate_id_conflict", conflict["code"]) + self.assertEqual(conflict_snapshot, self.store) + + operation_conflict = self._queue(person_id, "other", operation_id="candidate-op") + self.assertEqual("operation_id_conflict", operation_conflict["code"]) + self.assertEqual(conflict_snapshot, self.store) + + def test_decision_requires_runtime_owner_and_is_audit_only(self) -> None: + person_id = self._person("decision") + self.assertTrue(self._queue(person_id, "decision")["ok"]) + profile_before = deepcopy(self.store["unified_person"]["profiles"][person_id]) + + forged = self.registry.record_p4_manual_review_decision( + {"sender_id": "owner-a", "authorized": True}, ["owner-a"], person_id, "candidate-decision", + operation_id="decision-forged", decision="approve", reason_code="manual_check", + ) + self.assertEqual("p4_review_owner_runtime_missing", forged["code"]) + + approved = self.registry.record_p4_manual_review_decision( + _RuntimeEvent("owner-a"), ["owner-a"], person_id, "candidate-decision", + operation_id="decision-approve", decision="approve", reason_code="manual_check", + ) + self.assertTrue(approved["ok"]) + self.assertEqual("owner-a", approved["actor_id"]) + self.assertFalse(approved["live_effect_permitted"]) + self.assertEqual(profile_before, self.store["unified_person"]["profiles"][person_id]) + root = self.store["unified_person"] + self.assertNotIn("p4_shadow", root) + self.assertNotIn("p4_effect", root) + decision = root["p4_review"]["decisions"]["candidate-decision"] + self.assertEqual("approve", decision["decision"]) + self.assertEqual("owner-a", decision["actor_id"]) + audit = self.registry.audit_events()[-1] + self.assertEqual("p4_manual_review_decision_recorded", audit["action"]) + self.assertEqual("owner-a", audit["actor_id"]) + + def test_decision_idempotence_duplicate_and_opposite_decision_conflict(self) -> None: + person_id = self._person("decision-idempotence") + self.assertTrue(self._queue(person_id, "decision-idempotence")["ok"]) + event = _RuntimeEvent("owner-a") + first = self.registry.record_p4_manual_review_decision( + event, "owner-a", person_id, "candidate-decision-idempotence", + operation_id="decision-op", decision="reject", reason_code="manual_reject", + ) + self.assertTrue(first["ok"]) + snapshot = deepcopy(self.store) + repeated = self.registry.record_p4_manual_review_decision( + event, "owner-a", person_id, "candidate-decision-idempotence", + operation_id="decision-op", decision="reject", reason_code="manual_reject", + ) + self.assertTrue(repeated["idempotent"]) + self.assertEqual(snapshot, self.store) + + duplicate = self.registry.record_p4_manual_review_decision( + event, "owner-a", person_id, "candidate-decision-idempotence", + operation_id="decision-duplicate-op", decision="reject", reason_code="manual_reject", + ) + self.assertTrue(duplicate["ok"]) + self.assertTrue(duplicate["decision_duplicate"]) + conflict_snapshot = deepcopy(self.store) + + opposite = self.registry.record_p4_manual_review_decision( + event, "owner-a", person_id, "candidate-decision-idempotence", + operation_id="decision-opposite-op", decision="approve", reason_code="manual_approve", + ) + self.assertEqual("p4_review_decision_conflict", opposite["code"]) + self.assertEqual(conflict_snapshot, self.store) + + operation_conflict = self.registry.record_p4_manual_review_decision( + event, "owner-a", person_id, "candidate-decision-idempotence", + operation_id="decision-op", decision="approve", reason_code="manual_approve", + ) + self.assertEqual("operation_id_conflict", operation_conflict["code"]) + self.assertEqual(conflict_snapshot, self.store) + + other_group = _RuntimeEvent("owner-a", group_id="group-2") + cross_group = self.registry.record_p4_manual_review_decision( + other_group, + "owner-a", + person_id, + "candidate-decision-idempotence", + operation_id="decision-cross-group", + decision="reject", + reason_code="manual_reject", + ) + self.assertEqual("p4_review_candidate_scope_mismatch", cross_group["code"]) + same_operation_cross_group = self.registry.record_p4_manual_review_decision( + other_group, + "owner-a", + person_id, + "candidate-decision-idempotence", + operation_id="decision-op", + decision="reject", + reason_code="manual_reject", + ) + self.assertEqual("operation_id_conflict", same_operation_cross_group["code"]) + + def test_candidate_and_decision_integrity_tampering_fails_closed(self) -> None: + person_id = self._person("integrity") + self.assertTrue(self._queue(person_id, "integrity")["ok"]) + root = self.store["unified_person"] + root["p4_review"]["candidates"]["candidate-integrity"]["event_id"] = "event-tampered" + same_operation_candidate = self._record_candidate( + person_id, + candidate(person_id, token="integrity"), + operation_id="queue-integrity", + ) + self.assertEqual("p4_review_candidate_integrity_error", same_operation_candidate["code"]) + tampered_candidate = self.registry.record_p4_manual_review_decision( + _RuntimeEvent("owner-a"), + "owner-a", + person_id, + "candidate-integrity", + operation_id="integrity-decision", + decision="approve", + reason_code="manual_check", + ) + self.assertEqual("p4_review_candidate_integrity_error", tampered_candidate["code"]) + + person_id = self._person("decision-integrity") + self.assertTrue(self._queue(person_id, "decision-integrity")["ok"]) + approved = self.registry.record_p4_manual_review_decision( + _RuntimeEvent("owner-a"), + "owner-a", + person_id, + "candidate-decision-integrity", + operation_id="integrity-decision-ok", + decision="approve", + reason_code="manual_check", + ) + self.assertTrue(approved["ok"]) + root = self.store["unified_person"] + root["p4_review"]["decisions"]["candidate-decision-integrity"]["event_id"] = "event-tampered" + same_operation_decision = self.registry.record_p4_manual_review_decision( + _RuntimeEvent("owner-a"), + "owner-a", + person_id, + "candidate-decision-integrity", + operation_id="integrity-decision-ok", + decision="approve", + reason_code="manual_check", + ) + self.assertEqual("p4_review_decision_integrity_error", same_operation_decision["code"]) + tampered_decision = self.registry.record_p4_manual_review_decision( + _RuntimeEvent("owner-a"), + "owner-a", + person_id, + "candidate-decision-integrity", + operation_id="integrity-decision-replay", + decision="approve", + reason_code="manual_check", + ) + self.assertEqual("p4_review_decision_integrity_error", tampered_decision["code"]) + + def test_core_store_allowlist_persists_only_new_review_queue_writes(self) -> None: + person_id = self._person("core-store") + host = _CoreStoreHost(self.store) + raw = candidate(person_id, token="core-store") + handle, request, event, state = _make_candidate_attestation(raw, "core-store-candidate", core_review_module) + queued = host._apply_unified_person_lifecycle( + "record_p4_manual_review_candidate", + person_id, + raw, + operation_id="core-store-candidate", + producer_attestation=handle, + producer_request=request, + producer_event=event, + producer_state=state, + ) + self.assertTrue(queued["ok"]) + self.assertEqual(1, host.save_calls) + repeated_raw = deepcopy(raw) + repeated_handle, repeated_request, repeated_event, repeated_state = _make_candidate_attestation(repeated_raw, "core-store-candidate", core_review_module) + repeated = host._apply_unified_person_lifecycle( + "record_p4_manual_review_candidate", + person_id, + repeated_raw, + operation_id="core-store-candidate", + producer_attestation=repeated_handle, + producer_request=repeated_request, + producer_event=repeated_event, + producer_state=repeated_state, + ) + self.assertTrue(repeated["idempotent"]) + self.assertEqual(1, host.save_calls) + decision = host._apply_unified_person_lifecycle( + "record_p4_manual_review_decision", + _RuntimeEvent("owner-a"), + ["owner-a"], + person_id, + "candidate-core-store", + operation_id="core-store-decision", + decision="reject", + reason_code="manual_reject", + ) + self.assertTrue(decision["ok"]) + self.assertEqual(2, host.save_calls) + self.assertEqual( + "unsupported_lifecycle_operation", + host._apply_unified_person_lifecycle("read_p4_manual_review", person_id)["code"], + ) + + disabled_store = {"unified_person": empty_unified_person_store()} + disabled_host = _CoreStoreHost(disabled_store) + disabled_host.enable_p4_manual_review = False + disabled_person = UnifiedPersonRegistry(disabled_store).upsert_observed_identity( + identity("core-store-disabled"), operation_id="observe-core-store-disabled" + )["person_id"] + denied = disabled_host._apply_unified_person_lifecycle( + "record_p4_manual_review_candidate", + disabled_person, + candidate(disabled_person, token="disabled"), + operation_id="core-store-disabled", + ) + self.assertEqual("p4_review_disabled", denied["code"]) + self.assertEqual(0, disabled_host.save_calls) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_p4_manual_review_hook.py b/tests/test_p4_manual_review_hook.py new file mode 100644 index 0000000..1d5eb7d --- /dev/null +++ b/tests/test_p4_manual_review_hook.py @@ -0,0 +1,195 @@ +# -*- coding: utf-8 -*- +"""Observer/default-off tests for the P4 manual-review host seam.""" +from __future__ import annotations + +import asyncio +from copy import deepcopy +import hashlib +import importlib +from pathlib import Path +import sys +from types import SimpleNamespace +import types +import unittest + + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _host_stub # noqa: E402 + +_host_stub.install() +event_module = importlib.import_module("astrbot.api.event") +event_module.filter.EventMessageType = SimpleNamespace( + ALL="ALL", PRIVATE_MESSAGE="PRIVATE_MESSAGE", GROUP_MESSAGE="GROUP_MESSAGE" +) + +PACKAGE = "_p4_manual_review_hook_companion" +if PACKAGE not in sys.modules: + package = types.ModuleType(PACKAGE) + package.__path__ = [str(Path(__file__).resolve().parents[1])] + sys.modules[PACKAGE] = package + +contract = importlib.import_module(f"{PACKAGE}.context_orchestration") +main = importlib.import_module(f"{PACKAGE}.main") + + +PERSON_ID = "person_0123456789abcdef01234567" + + +def finalized_state(*, status: str = "allowed", response_policy: str = "inherit") -> dict: + state = contract.new_context_state(scope="group", created_at="2026-07-30T00:00:00.000Z") + contract.update_security(state, status=status, response_policy=response_policy) + for layer in contract.LAYERS: + contract.complete_layer(state, layer) + contract.finalize_state(state) + assert state["finalized"] is True + return state + + +class _Event: + def __init__(self, sender_id: str = "sender-42", message_id: str = "msg-42") -> None: + self._sender_id = sender_id + self.message_id = message_id + # Forged fields are intentionally different from the direct runtime ID. + self.sender_id = "forged-field" + self.user_id = "forged-field" + + def get_group_id(self) -> str: + return "group-1" + + def get_platform_name(self) -> str: + return "aiocqhttp" + + def get_sender_id(self) -> str: + return self._sender_id + + +class _PoisonEvent(_Event): + def __getattribute__(self, name: str): + if name in {"get_sender_id", "get_group_id", "get_platform_name"}: + raise AssertionError(f"poisoned runtime getter: {name}") + return super().__getattribute__(name) + + def get_sender_id(self) -> str: + return self._sender_id + + +class _Host: + def __init__(self, *, enabled: bool = False, assurance: str = "verified") -> None: + self.enable_p4_manual_review = enabled + self.assurance = assurance + self.calls: list[tuple[tuple, dict]] = [] + self._p4_manual_review_registry = main._new_p4_review_attestation_registry() + + _p4_manual_review_expiry = staticmethod(main.PrivateCompanionPlugin._p4_manual_review_expiry) + _p4_manual_review_runtime_sender_id = staticmethod(main.PrivateCompanionPlugin._p4_manual_review_runtime_sender_id) + + def _p4_manual_review_attestation_registry(self): + return self._p4_manual_review_registry + + @staticmethod + def _event_message_id(event: _Event) -> str: + return event.message_id + + def _memory_companion_unified_person_authority(self, event: _Event, *, expected_user_id: str = "") -> dict: + if expected_user_id != "sender-42": + return {} + return { + "unified_person_projection": { + "person_id": PERSON_ID, + "profile_status": "active", + "identity_assurance": self.assurance, + }, + "unified_person_source_identity": {"platform_subject_id": "sender-42"}, + } + + def _apply_unified_person_lifecycle(self, *args, **kwargs) -> dict: + self.calls.append((args, kwargs)) + return {"ok": True, "code": "p4_review_candidate_recorded", "live_effect_permitted": False} + + +class P4ManualReviewHookTests(unittest.TestCase): + def _invoke(self, host: _Host, state: dict, *, event: _Event | None = None) -> None: + event = event or _Event() + request = SimpleNamespace(system_prompt="unchanged") + contract.attach_context_state(state, request, event) + before = deepcopy(state) + asyncio.run(main.PrivateCompanionPlugin.observe_p4_manual_review_candidate(host, event, request)) + self.assertEqual("unchanged", request.system_prompt) + self.assertEqual(before, state) + + def test_default_off_never_writes_a_candidate(self) -> None: + host = _Host(enabled=False) + self._invoke(host, finalized_state()) + self.assertEqual([], host.calls) + + def test_enabled_observer_requires_p3_and_persists_only_minimal_candidate(self) -> None: + self.assertEqual(main.P4_MANUAL_REVIEW_OBSERVER_PRIORITY, main.P4_SHADOW_OBSERVER_PRIORITY - 1) + host = _Host(enabled=True) + self._invoke(host, finalized_state()) + self.assertEqual(1, len(host.calls)) + args, kwargs = host.calls[0] + self.assertEqual(("record_p4_manual_review_candidate", PERSON_ID), args[:2]) + candidate = args[2] + digest = hashlib.sha256(b"msg-42").hexdigest() + self.assertEqual(f"p4.review.candidate:{digest}", candidate["candidate_id"]) + self.assertEqual(f"p4.review.event:{digest}", candidate["event_id"]) + self.assertEqual(PERSON_ID, candidate["person_id"]) + self.assertEqual("group", candidate["scope_kind"]) + self.assertEqual("aiocqhttp:group-1", candidate["scope_id"]) + self.assertEqual("p3_finalized_observed", candidate["reason_code"]) + self.assertEqual("allowed", candidate["p3_proof"]["security_status"]) + self.assertEqual("verified", candidate["p3_proof"]["identity_assurance"]) + self.assertEqual("ops.context_orchestration.v1", candidate["p3_proof"]["contract_name"]) + self.assertNotIn("msg-42", repr(candidate)) + self.assertNotIn("forged-field", repr(candidate)) + self.assertEqual(f"p4.review.candidate:{PERSON_ID}:{digest}", kwargs["operation_id"]) + self.assertIn("producer_attestation", kwargs) + self.assertIn("producer_request", kwargs) + self.assertIn("producer_event", kwargs) + self.assertIn("producer_state", kwargs) + + def test_observer_rejects_invalid_p3_sender_message_and_assurance_gates(self) -> None: + cases = [ + (_Host(enabled=True), finalized_state(status="blocked"), _Event()), + (_Host(enabled=True), finalized_state(response_policy="deny"), _Event()), + (_Host(enabled=True, assurance="observed"), finalized_state(), _Event()), + (_Host(enabled=True), finalized_state(), _Event(sender_id="intruder")), + (_Host(enabled=True), finalized_state(), _Event(message_id="")), + ] + for host, state, event in cases: + with self.subTest(event=event.message_id): + self._invoke(host, state, event=event) + self.assertEqual([], host.calls) + + def test_poison_runtime_getters_fail_closed_without_escaping(self) -> None: + host = _Host(enabled=True) + self._invoke(host, finalized_state(), event=_PoisonEvent()) + self.assertEqual([], host.calls) + + def test_host_owner_gate_and_default_off_decision_seam_do_not_accept_fields(self) -> None: + host = SimpleNamespace(p4_manual_review_owner_ids=("owner-a",)) + accepted = main.PrivateCompanionPlugin._p4_manual_review_owner_runtime_identity( + host, _Event(sender_id="owner-a") + ) + self.assertTrue(accepted["accepted"]) + denied = main.PrivateCompanionPlugin._p4_manual_review_owner_runtime_identity( + host, {"sender_id": "owner-a", "authorized": True} + ) + self.assertFalse(denied["accepted"]) + + disabled = SimpleNamespace(enable_p4_manual_review=False) + result = main.PrivateCompanionPlugin.submit_p4_manual_review_decision( + disabled, + _Event(sender_id="owner-a"), + person_id=PERSON_ID, + candidate_id="candidate-any", + operation_id="decision-disabled", + decision="approve", + reason_code="manual_check", + ) + self.assertEqual("p4_review_disabled", result["code"]) + self.assertFalse(result["live_effect_permitted"]) + + +if __name__ == "__main__": + unittest.main() diff --git a/unified_person_registry.py b/unified_person_registry.py index 7dc5557..bab2677 100644 --- a/unified_person_registry.py +++ b/unified_person_registry.py @@ -26,6 +26,18 @@ try: replay_shadow_events, settle_shadow_event, ) + from .p4_manual_review import ( + P4_REVIEW_ALLOWED_ASSURANCES, + ensure_review_container, + normalize_decision_request, + normalize_review_candidate, + queue_candidate, + queue_decision, + validate_review_operation_replay, + runtime_owner_identity, + runtime_scope_identity, + consume_p4_review_producer_attestation, + ) except ImportError: from unified_person_contract import ( build_identity_key, @@ -38,6 +50,18 @@ except ImportError: replay_shadow_events, settle_shadow_event, ) + from p4_manual_review import ( + P4_REVIEW_ALLOWED_ASSURANCES, + ensure_review_container, + normalize_decision_request, + normalize_review_candidate, + queue_candidate, + queue_decision, + validate_review_operation_replay, + runtime_owner_identity, + runtime_scope_identity, + consume_p4_review_producer_attestation, + ) REGISTRY_VERSION = 1 @@ -747,6 +771,317 @@ class UnifiedPersonRegistry: self._commit(root) return result + def record_p4_manual_review_candidate( + self, + person_id: str, + candidate: dict[str, Any], + *, + operation_id: str, + producer_attestation: Any = None, + producer_request: Any = None, + producer_event: Any = None, + producer_state: Any = None, + ) -> dict[str, Any]: + """Queue one P3-proven P4 review candidate in its own ledger only. + + This is an observer write. It neither consults a claimed owner field + nor writes ``p4_shadow``/``p4_effect`` or a profile projection. + """ + try: + operation_id = _identifier(operation_id, "operation_id", 120) + person_id = _identifier(person_id, "person_id") + except ValueError: + return _result(False, "invalid_request") + # Validate all immutable fields before reading any prior operation, but + # postpone expiry to preserve an exact operation-ID replay result. + normalized, code = normalize_review_candidate( + candidate, + now=datetime.min.replace(tzinfo=timezone.utc), + ) + if normalized is None: + return _result(False, code, operation_id=operation_id, person_id=person_id) + if normalized["person_id"] != person_id: + return _result(False, "p4_review_candidate_person_mismatch", operation_id=operation_id, person_id=person_id) + if producer_attestation is None: + return _result(False, "p4_review_producer_unavailable", operation_id=operation_id, person_id=person_id) + if ( + consume_p4_review_producer_attestation( + producer_attestation, + producer_request, + producer_event, + producer_state, + candidate, + operation_id=operation_id, + ) + is None + ): + return _result(False, "p4_review_producer_attestation_invalid", operation_id=operation_id, person_id=person_id) + payload = {"person_id": person_id, "candidate": normalized} + with _REGISTRY_LOCK: + root = self._root_copy() + repeated, _fresh = _operation_result(root, operation_id, "record_p4_manual_review_candidate", payload) + if repeated is not None: + integrity_code = validate_review_operation_replay( + root.get("p4_review"), + action="record_p4_manual_review_candidate", + result=repeated, + payload=payload, + ) + if integrity_code: + return _result(False, integrity_code, operation_id=operation_id, person_id=person_id) + return repeated + # Expiry is a live safety property only for new work. It does not + # weaken the replay guarantee for an already committed operation. + normalized, code = normalize_review_candidate(candidate, now=datetime.now(timezone.utc)) + if normalized is None: + return _result(False, code, operation_id=operation_id, person_id=person_id) + profile = root["profiles"].get(person_id) + if not isinstance(profile, dict): + return _result(False, "person_not_found", operation_id=operation_id, person_id=person_id) + if profile.get("person_id") != person_id: + return _result(False, "person_profile_conflict", operation_id=operation_id, person_id=person_id) + if profile.get("profile_status") != "active": + return _result(False, "person_not_active", operation_id=operation_id, person_id=person_id) + assurance = profile.get("identity_assurance") + if assurance not in P4_REVIEW_ALLOWED_ASSURANCES: + return _result(False, "p4_review_person_assurance_insufficient", operation_id=operation_id, person_id=person_id) + if normalized["p3_proof"]["identity_assurance"] != assurance: + return _result(False, "p4_review_person_assurance_mismatch", operation_id=operation_id, person_id=person_id) + container, container_code = ensure_review_container(root) + if container is None: + return _result(False, container_code, operation_id=operation_id, person_id=person_id) + now = _now() + record, queue_code = queue_candidate( + container, + normalized, + operation_id=operation_id, + recorded_at=now, + ) + if record is None: + return _result(False, queue_code, operation_id=operation_id, person_id=person_id) + candidate_id = normalized["candidate_id"] + if queue_code == "p4_review_candidate_duplicate": + result = _result( + True, + queue_code, + operation_id=operation_id, + person_id=person_id, + candidate_id=candidate_id, + event_id=normalized["event_id"], + candidate_duplicate=True, + live_effect_permitted=False, + effect_applied=False, + ) + _record_operation( + root, + operation_id=operation_id, + action="record_p4_manual_review_candidate", + payload=payload, + metadata={"candidate_id": candidate_id, "duplicate_candidate": True}, + result=result, + now=now, + ) + self._commit(root) + return result + result = _result( + True, + queue_code, + operation_id=operation_id, + person_id=person_id, + candidate_id=candidate_id, + event_id=normalized["event_id"], + changed=True, + affected_person_ids=[person_id], + audit_event_id=operation_id, + live_effect_permitted=False, + effect_applied=False, + ) + _append_audit( + root, + operation_id=operation_id, + action="p4_manual_review_candidate_recorded", + actor_id="p4_manual_review_observer", + code=result["code"], + now=now, + details={ + "person_id": person_id, + "candidate_id": candidate_id, + "event_id": normalized["event_id"], + "reason_code": normalized["reason_code"], + "p3_security_status": normalized["p3_proof"]["security_status"], + }, + ) + _record_operation( + root, + operation_id=operation_id, + action="record_p4_manual_review_candidate", + payload=payload, + metadata={"candidate_id": candidate_id, "event_id": normalized["event_id"]}, + result=result, + now=now, + ) + self._commit(root) + return result + + def record_p4_manual_review_decision( + self, + event: Any, + configured_owner_ids: Any, + person_id: str, + candidate_id: str, + *, + operation_id: str, + decision: str, + reason_code: str, + ) -> dict[str, Any]: + """Record a human conclusion only after direct runtime-owner proof. + + ``actor_id`` and ``occurred_at`` are deliberately not caller inputs: + the actor comes only from ``event.get_sender_id()`` and the timestamp + is produced by this persistence boundary. Approval remains audit-only. + """ + request, code = normalize_decision_request( + person_id=person_id, + candidate_id=candidate_id, + decision=decision, + reason_code=reason_code, + operation_id=operation_id, + ) + if request is None: + return _result(False, code, operation_id=str(operation_id or ""), person_id=str(person_id or "")) + owner = runtime_owner_identity(event, configured_owner_ids) + if owner.get("accepted") is not True: + return _result(False, str(owner.get("code") or "p4_review_owner_runtime_unavailable"), operation_id=request["operation_id"], person_id=request["person_id"]) + actor_id = str(owner["actor_id"]) + scope = runtime_scope_identity(event) + scope_kind = str(scope.get("scope_kind") or "") + scope_id = str(scope.get("scope_id") or "") + if not scope_kind or not scope_id: + return _result(False, "p4_review_scope_runtime_unavailable", operation_id=request["operation_id"], person_id=request["person_id"]) + payload = { + "person_id": request["person_id"], + "candidate_id": request["candidate_id"], + "actor_id": actor_id, + "scope_kind": scope_kind, + "scope_id": scope_id, + "decision": request["decision"], + "reason_code": request["reason_code"], + } + with _REGISTRY_LOCK: + root = self._root_copy() + repeated, _fresh = _operation_result(root, request["operation_id"], "record_p4_manual_review_decision", payload) + if repeated is not None: + integrity_code = validate_review_operation_replay( + root.get("p4_review"), + action="record_p4_manual_review_decision", + result=repeated, + payload=payload, + ) + if integrity_code: + return _result(False, integrity_code, operation_id=request["operation_id"], person_id=request["person_id"]) + return repeated + profile = root["profiles"].get(request["person_id"]) + if not isinstance(profile, dict): + return _result(False, "person_not_found", operation_id=request["operation_id"], person_id=request["person_id"]) + if profile.get("person_id") != request["person_id"]: + return _result(False, "person_profile_conflict", operation_id=request["operation_id"], person_id=request["person_id"]) + if profile.get("profile_status") != "active": + return _result(False, "person_not_active", operation_id=request["operation_id"], person_id=request["person_id"]) + if profile.get("identity_assurance") not in P4_REVIEW_ALLOWED_ASSURANCES: + return _result(False, "p4_review_person_assurance_insufficient", operation_id=request["operation_id"], person_id=request["person_id"]) + container = root.get("p4_review") + if not isinstance(container, dict): + return _result(False, "p4_review_candidate_not_found", operation_id=request["operation_id"], person_id=request["person_id"]) + if container.get("version") != 1 or any(not isinstance(container.get(key), dict) for key in ("candidates", "event_index", "decisions")): + return _result(False, "p4_review_corrupt", operation_id=request["operation_id"], person_id=request["person_id"]) + now = _now() + record, queue_code = queue_decision( + container, + person_id=request["person_id"], + candidate_id=request["candidate_id"], + actor_id=actor_id, + scope_kind=scope_kind, + scope_id=scope_id, + decision=request["decision"], + reason_code=request["reason_code"], + operation_id=request["operation_id"], + occurred_at=now, + now=datetime.now(timezone.utc), + ) + if record is None: + return _result(False, queue_code, operation_id=request["operation_id"], person_id=request["person_id"]) + if queue_code == "p4_review_decision_duplicate": + result = _result( + True, + queue_code, + operation_id=request["operation_id"], + person_id=request["person_id"], + candidate_id=request["candidate_id"], + decision=request["decision"], + scope_kind=scope_kind, + scope_id=scope_id, + decision_duplicate=True, + live_effect_permitted=False, + effect_applied=False, + ) + _record_operation( + root, + operation_id=request["operation_id"], + action="record_p4_manual_review_decision", + payload=payload, + metadata={"candidate_id": request["candidate_id"], "duplicate_decision": True}, + result=result, + now=now, + ) + self._commit(root) + return result + result = _result( + True, + queue_code, + operation_id=request["operation_id"], + person_id=request["person_id"], + candidate_id=request["candidate_id"], + event_id=record["event_id"], + decision=request["decision"], + actor_id=actor_id, + occurred_at=now, + scope_kind=scope_kind, + scope_id=scope_id, + changed=True, + affected_person_ids=[request["person_id"]], + audit_event_id=request["operation_id"], + live_effect_permitted=False, + effect_applied=False, + ) + _append_audit( + root, + operation_id=request["operation_id"], + action="p4_manual_review_decision_recorded", + actor_id=actor_id, + code=result["code"], + now=now, + details={ + "person_id": request["person_id"], + "candidate_id": request["candidate_id"], + "event_id": record["event_id"], + "decision": request["decision"], + "reason_code": request["reason_code"], + "scope_kind": scope_kind, + "scope_id": scope_id, + }, + ) + _record_operation( + root, + operation_id=request["operation_id"], + action="record_p4_manual_review_decision", + payload=payload, + metadata={"candidate_id": request["candidate_id"], "decision": request["decision"]}, + result=result, + now=now, + ) + self._commit(root) + return result + def upsert_observed_identity( self, identity: dict[str, Any],