# -*- coding: utf-8 -*- """Companion-issued, in-process P5-B provenance attestations. This is deliberately a small issuer primitive, not a live sink gate. It creates an opaque one-shot handle which is bound to the *exact* request, event, and P3-state objects that were present when it was minted. A consumer must give those same objects back to :meth:`P5AttestationRegistry.consume` to receive an immutable, metadata-only snapshot. The registry never reads carrier attributes and never accepts source prose, raw event/request/session IDs, media, prompts, or tool arguments. SHA-256 values are normalized to 64 lowercase hexadecimal characters without a ``sha256:`` prefix. It retains opaque carrier references only until the handle expires so it can compare object identity with ``is``. That is intentional: a process-local attestation cannot survive a carrier replacement, serialization, reload, or replay. P5-B's eventual bridge must call ``consume`` itself. A snapshot is evidence, not a transferable credential, and this module is intentionally not wired into ``main.py``, Bridge, or a live gate yet. """ from __future__ import annotations from dataclasses import dataclass import hashlib import json import secrets import threading import time from typing import Callable, Iterable ATTESTATION_SCHEMA_VERSION = "ops.p5.attestation.v1" PROVENANCE_CONTRACT_NAME = "ops.p5.provenance.v1" PROVENANCE_CONTRACT_VERSION = "1.0" ISSUER = "private_companion" # These are frozen P3 compatibility facts. The supplied P3 state is still # identity-bound; we do not inspect its mutable contents as evidence. P3_CONTRACT_NAME = "ops.context_orchestration.v1" P3_CONTRACT_VERSION = "1.0" P3_CONTRACT_FINGERPRINT = "3bb7a12af05bb4d9a47cef9f31e78752cec512b90b1d50ae49feef54470974f8" TRUST_LEVEL_VALUES = ("T0", "T1", "T2", "T3", "T4") SOURCE_KIND_VALUES = ( "policy_config", "verified_authorization", "current_user_intent", "forwarded_text", "quoted_text", "vision_summary", "tool_output", "web_extract", "memory_recall", "derived_summary", "legacy_memory", "unknown", ) FIREWALL_STATUS_VALUES = ("allowed", "sanitized", "blocked", "rejected", "quarantined", "unavailable", "unknown") DISPOSITION_VALUES = ("allow", "shadow_quarantine", "deny_high_risk") TRUST_LEVELS = frozenset(TRUST_LEVEL_VALUES) SOURCE_KINDS = frozenset(SOURCE_KIND_VALUES) FIREWALL_STATUSES = frozenset(FIREWALL_STATUS_VALUES) DISPOSITIONS = frozenset(DISPOSITION_VALUES) SINKS = frozenset({ "prompt_forward_quote", "prompt_vision_summary", "memory_recall", "bridge_serialization", "tool_retrieval", "external_export", "cross_user_read", }) REASON_CODES = frozenset({ "p5b_attested", "evidence_only_nonexecuting", "untrusted_source_shadowed", "sanitized_source_shadowed", "upstream_security_denied", "upstream_security_shadowed", "high_risk_sink_denied", "invalid_source_shadowed", "legacy_unresolved", "owner_recovered", "derived_source", }) DEFAULT_TTL_SECONDS = 30.0 MAX_TTL_SECONDS = 300.0 DEFAULT_MAX_ENTRIES = 1024 MAX_SINKS_PER_HANDLE = 8 _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", } _HEX = frozenset("0123456789abcdef") _HANDLE_CREATION_TOKEN = object() def provenance_contract_descriptor() -> dict[str, object]: """Return a fresh canonical shared-contract descriptor, never an attestation.""" return { "contract_name": PROVENANCE_CONTRACT_NAME, "contract_version": PROVENANCE_CONTRACT_VERSION, "record_fields": [ "contract_name", "contract_version", "contract_fingerprint", "memory_id", "source_kind", "source_trust", "firewall_status", "source_event_ref_hash", "authority_attestation_ref_hash", "provenance_state", "migration_operation_ref", "recovery_operation_ref", "record_revision", ], "provenance_states": ["observed", "legacy_unresolved", "owner_recovered", "invalid"], "trust_levels": list(TRUST_LEVEL_VALUES), "source_kinds": list(SOURCE_KIND_VALUES), "firewall_statuses": list(FIREWALL_STATUS_VALUES), "dispositions": list(DISPOSITION_VALUES), "hash_format": "sha256_hex_lower", "attestation_issuer": ISSUER, "p3_contract_name": P3_CONTRACT_NAME, "p3_contract_version": P3_CONTRACT_VERSION, } def provenance_contract_fingerprint() -> str: """Return the canonical P5 provenance contract SHA-256 fingerprint.""" canonical = json.dumps( provenance_contract_descriptor(), ensure_ascii=True, sort_keys=True, separators=(",", ":") ) return hashlib.sha256(canonical.encode("utf-8")).hexdigest() PROVENANCE_CONTRACT_FINGERPRINT = provenance_contract_fingerprint() class P5AttestationError(ValueError): """Raised when mint input is outside the metadata-only P5-B contract.""" class P5AttestationHandle: """Opaque, non-serializable capability consumed only by its issuer. The object carries no public payload. Registry membership is keyed by the actual handle object, so a copied, reconstructed, dict, or structural lookalike can never be consumed successfully. """ __slots__ = ("__weakref__",) def __init__(self, creation_token: object | None = None) -> None: if creation_token is not _HANDLE_CREATION_TOKEN: raise TypeError("P5 attestation handles are minted only by the registry") def __reduce__(self) -> object: raise TypeError("P5 attestation handles cannot be serialized") def __reduce_ex__(self, protocol: int) -> object: raise TypeError("P5 attestation handles cannot be serialized") def __getstate__(self) -> object: raise TypeError("P5 attestation handles cannot be serialized") def __repr__(self) -> str: return "" def __init_subclass__(cls, **kwargs: object) -> None: raise TypeError("P5 attestation handles cannot be subclassed") @dataclass(frozen=True, slots=True) class P5AttestationSnapshot: """Read-only, metadata-only result from a successful one-shot consume.""" schema_version: str contract_name: str contract_version: str contract_fingerprint: str issuer: str issuer_epoch: str authority_attestation_ref_hash: str request_hash: str session_hash: str source_kind: str source_trust: str firewall_status: str disposition: str reason_codes: tuple[str, ...] source_event_ref_hash: str derived_from_ref_hash: str provenance_state: str p3_contract_name: str p3_contract_version: str p3_contract_fingerprint: str sink: str @dataclass(slots=True) class _Entry: request: object event: object p3_state: object request_hash: str session_hash: str source_kind: str source_trust: str firewall_status: str disposition: str reason_codes: tuple[str, ...] source_event_ref_hash: str derived_from_ref_hash: str authority_attestation_ref_hash: str issuer_epoch: str expires_at: float sink_nonces: dict[str, bytes] sink_uses: dict[str, int] class P5AttestationRegistry: """Bounded issuer registry for one-shot, exact-carrier attestations. ``consume`` removes an authentic handle before it performs any binding checks. A failed attempt therefore cannot be retried with substituted carriers or a different sink, and concurrent consumers cannot both win. Mint a distinct handle for every intended consumption. """ def __init__( self, *, clock: Callable[[], float] | None = None, default_ttl_seconds: float = DEFAULT_TTL_SECONDS, max_entries: int = DEFAULT_MAX_ENTRIES, ) -> None: self._clock = clock or time.monotonic self._default_ttl_seconds = _validate_ttl(default_ttl_seconds) if isinstance(max_entries, bool) or not isinstance(max_entries, int) or max_entries < 1: raise P5AttestationError("registry capacity is invalid") self._max_entries = max_entries self._lock = threading.RLock() self._entries: dict[P5AttestationHandle, _Entry] = {} self._issuer_epoch = _new_reference_hash() self._unloaded = False @property def issuer_epoch(self) -> str: """Current opaque issuer epoch; it is safe metadata, not a handle.""" with self._lock: return self._issuer_epoch def mint( self, request: object, event: object, p3_state: object, *, request_hash: str, session_hash: str, source_kind: str, source_trust: str, firewall_status: str, disposition: str, reason_codes: Iterable[str], source_event_ref_hash: str, sinks: Iterable[str], derived_from_ref_hash: str = "", ttl_seconds: float | None = None, ) -> P5AttestationHandle | None: """Mint an opaque handle or return ``None`` if the bounded issuer is full. Carrier objects are opaque identity anchors only. All externally supplied descriptive values are closed enums or SHA-256 hashes; raw IDs and body-like values are rejected before an entry is created. """ _validate_anchor(request) _validate_anchor(event) _validate_anchor(p3_state) request_hash = _validate_hash(request_hash) session_hash = _validate_hash(session_hash) source_kind = _validate_enum(source_kind, SOURCE_KINDS, "source kind") source_trust = _validate_enum(source_trust, TRUST_LEVELS, "source trust") if _SOURCE_TRUST[source_kind] != source_trust: raise P5AttestationError("source kind and trust do not match") firewall_status = _validate_enum(firewall_status, FIREWALL_STATUSES, "firewall status") disposition = _validate_enum(disposition, DISPOSITIONS, "disposition") if source_trust in {"T3", "T4"} and disposition == "allow": raise P5AttestationError("untrusted source cannot be marked allowed") codes = _validate_reason_codes(reason_codes) source_event_ref_hash = _validate_hash(source_event_ref_hash) if derived_from_ref_hash: derived_from_ref_hash = _validate_hash(derived_from_ref_hash) sink_values = _validate_sinks(sinks) ttl = self._default_ttl_seconds if ttl_seconds is None else _validate_ttl(ttl_seconds) with self._lock: if self._unloaded: return None self._cleanup_locked(self._clock()) if len(self._entries) >= self._max_entries: return None handle = P5AttestationHandle(_HANDLE_CREATION_TOKEN) self._entries[handle] = _Entry( request=request, event=event, p3_state=p3_state, request_hash=request_hash, session_hash=session_hash, source_kind=source_kind, source_trust=source_trust, firewall_status=firewall_status, disposition=disposition, reason_codes=codes, source_event_ref_hash=source_event_ref_hash, derived_from_ref_hash=derived_from_ref_hash, authority_attestation_ref_hash=_new_reference_hash(), issuer_epoch=self._issuer_epoch, expires_at=self._clock() + ttl, sink_nonces={sink: secrets.token_bytes(32) for sink in sink_values}, sink_uses={sink: 0 for sink in sink_values}, ) return handle def consume( self, handle: object, request: object, event: object, p3_state: object, sink: object, ) -> P5AttestationSnapshot | None: """Atomically consume one handle for its exact carriers and one sink. Invalid values, fake handles, expiry, an issuer epoch change, a carrier replacement, a sink mismatch, and every replay return ``None``. No failure returns a partial dictionary or a fallback authorization. """ if type(handle) is not P5AttestationHandle: return None with self._lock: # Pop first: an authentic handle is one attempt only, including a # failed attempt using the wrong object or sink. entry = self._entries.pop(handle, None) if entry is None or self._unloaded: return None now = self._clock() if now >= entry.expires_at or entry.issuer_epoch != self._issuer_epoch: return None if request is not entry.request or event is not entry.event or p3_state is not entry.p3_state: return None if not isinstance(sink, str) or sink not in SINKS: return None # Reading and immediately discarding the sink-specific nonce makes # sink binding explicit while the popped entry enforces global # one-shot use for this opaque handle. if entry.sink_nonces.pop(sink, None) is None or entry.sink_uses.get(sink) != 0: return None entry.sink_uses[sink] = 1 return P5AttestationSnapshot( schema_version=ATTESTATION_SCHEMA_VERSION, contract_name=PROVENANCE_CONTRACT_NAME, contract_version=PROVENANCE_CONTRACT_VERSION, contract_fingerprint=PROVENANCE_CONTRACT_FINGERPRINT, issuer=ISSUER, issuer_epoch=entry.issuer_epoch, authority_attestation_ref_hash=entry.authority_attestation_ref_hash, request_hash=entry.request_hash, session_hash=entry.session_hash, source_kind=entry.source_kind, source_trust=entry.source_trust, firewall_status=entry.firewall_status, disposition=entry.disposition, reason_codes=entry.reason_codes, source_event_ref_hash=entry.source_event_ref_hash, derived_from_ref_hash=entry.derived_from_ref_hash, provenance_state="observed", p3_contract_name=P3_CONTRACT_NAME, p3_contract_version=P3_CONTRACT_VERSION, p3_contract_fingerprint=P3_CONTRACT_FINGERPRINT, sink=sink, ) def cleanup(self) -> int: """Remove only expired entries and return the number removed.""" with self._lock: return self._cleanup_locked(self._clock()) def reset_epoch(self) -> str: """Invalidate every outstanding handle for a controlled issuer reload.""" with self._lock: self._entries.clear() self._issuer_epoch = _new_reference_hash() return self._issuer_epoch def unload(self) -> None: """Permanently invalidate outstanding handles for plugin unload.""" with self._lock: self._entries.clear() self._issuer_epoch = _new_reference_hash() self._unloaded = True def pending_count(self) -> int: """Return the current bounded entry count after expiry cleanup.""" with self._lock: self._cleanup_locked(self._clock()) return len(self._entries) def _cleanup_locked(self, now: float) -> int: expired = [handle for handle, entry in self._entries.items() if now >= entry.expires_at] for handle in expired: self._entries.pop(handle, None) return len(expired) def _new_reference_hash() -> str: return hashlib.sha256(secrets.token_bytes(32)).hexdigest() def _validate_anchor(value: object) -> None: if value is None: raise P5AttestationError("identity anchor is missing") def _validate_hash(value: object) -> str: if not isinstance(value, str): raise P5AttestationError("hash is invalid") candidate = value[7:] if value.startswith("sha256:") else value if len(candidate) != 64 or any(character not in _HEX for character in candidate): raise P5AttestationError("hash is invalid") return candidate def _validate_enum(value: object, permitted: frozenset[str], label: str) -> str: if not isinstance(value, str) or value not in permitted: raise P5AttestationError(f"{label} is invalid") return value def _validate_reason_codes(values: Iterable[str]) -> tuple[str, ...]: if isinstance(values, (str, bytes)): raise P5AttestationError("reason codes are invalid") try: normalized = tuple(values) except TypeError as exc: raise P5AttestationError("reason codes are invalid") from exc if not normalized or len(normalized) > len(REASON_CODES): raise P5AttestationError("reason codes are invalid") if len(normalized) != len(set(normalized)) or any(code not in REASON_CODES for code in normalized): raise P5AttestationError("reason codes are invalid") return tuple(sorted(normalized)) def _validate_sinks(values: Iterable[str]) -> tuple[str, ...]: if isinstance(values, (str, bytes)): raise P5AttestationError("sinks are invalid") try: normalized = tuple(values) except TypeError as exc: raise P5AttestationError("sinks are invalid") from exc if not normalized or len(normalized) > MAX_SINKS_PER_HANDLE: raise P5AttestationError("sinks are invalid") if len(normalized) != len(set(normalized)) or any(sink not in SINKS for sink in normalized): raise P5AttestationError("sinks are invalid") return tuple(sorted(normalized)) def _validate_ttl(value: object) -> float: if isinstance(value, bool) or not isinstance(value, (int, float)): raise P5AttestationError("ttl is invalid") result = float(value) if not (0.0 < result <= MAX_TTL_SECONDS): raise P5AttestationError("ttl is invalid") return result __all__ = [ "ATTESTATION_SCHEMA_VERSION", "DEFAULT_MAX_ENTRIES", "DEFAULT_TTL_SECONDS", "DISPOSITIONS", "FIREWALL_STATUSES", "ISSUER", "P3_CONTRACT_FINGERPRINT", "P3_CONTRACT_NAME", "P3_CONTRACT_VERSION", "P5AttestationError", "P5AttestationHandle", "P5AttestationRegistry", "P5AttestationSnapshot", "PROVENANCE_CONTRACT_FINGERPRINT", "PROVENANCE_CONTRACT_NAME", "PROVENANCE_CONTRACT_VERSION", "REASON_CODES", "SINKS", "SOURCE_KINDS", "TRUST_LEVELS", "provenance_contract_descriptor", "provenance_contract_fingerprint", ]