astrbot_plugin_private_comp.../p5_attestation.py

483 行
16 KiB
Python

"""Pure companion-issued, in-process one-shot P5 attestations.
An attestation handle is an opaque capability. The registry retains only
identity anchors for the request, event, and P3 carrier plus bounded metadata
until TTL expiry or consumption. It never inspects or serializes carrier
contents and never accepts raw prose, credentials, session text, or arbitrary
IDs as metadata.
"""
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"
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_context",
"prompt_forward_quote",
"prompt_vision_summary",
"memory_recall",
"bridge_serialize",
"bridge_serialization",
"tool_execution",
"tool_retrieval",
"external_export",
"cross_user_read",
}
)
REASON_CODES = frozenset(
{
"p5_attested",
"p5b_attested",
"p5_nonexecuting",
"evidence_only_nonexecuting",
"untrusted_source_shadowed",
"sanitized_source_shadowed",
"upstream_security_denied",
"upstream_security_shadowed",
"high_risk_sink_denied",
"invalid_segment",
"invalid_source_shadowed",
"legacy_unresolved",
"owner_recovered",
"derived_source",
}
)
_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",
}
DEFAULT_TTL_SECONDS = 30.0
MAX_TTL_SECONDS = 300.0
DEFAULT_MAX_ENTRIES = 1024
MAX_SINKS_PER_HANDLE = 8
_HEX = frozenset("0123456789abcdef")
_HANDLE_CREATION_TOKEN = object()
def provenance_contract_descriptor() -> dict[str, object]:
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:
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()
CONTRACT_FINGERPRINT = PROVENANCE_CONTRACT_FINGERPRINT
class P5AttestationError(ValueError):
"""Raised when metadata is outside the closed attestation contract."""
class P5AttestationHandle:
__slots__ = ("__weakref__",)
def __init__(self, creation_token: object | None = None) -> None:
if creation_token is not _HANDLE_CREATION_TOKEN:
raise TypeError("attestation handles are minted only by the registry")
def __reduce__(self) -> object:
raise TypeError("attestation handles cannot be serialized")
def __reduce_ex__(self, protocol: int) -> object:
raise TypeError("attestation handles cannot be serialized")
def __getstate__(self) -> object:
raise TypeError("attestation handles cannot be serialized")
def __repr__(self) -> str:
return "<P5AttestationHandle opaque>"
def __init_subclass__(cls, **kwargs: object) -> None:
raise TypeError("attestation handles cannot be subclassed")
@dataclass(frozen=True, slots=True)
class P5AttestationSnapshot:
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
sinks: frozenset[str]
class P5AttestationRegistry:
"""Bounded, thread-safe registry with atomic one-shot 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_hash()
self._unloaded = False
@property
def issuer_epoch(self) -> str:
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:
_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")
reasons = _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=reasons,
source_event_ref_hash=source_event_ref_hash,
derived_from_ref_hash=derived_from_ref_hash,
authority_attestation_ref_hash=_new_hash(),
issuer_epoch=self._issuer_epoch,
expires_at=self._clock() + ttl,
sinks=sink_values,
)
return handle
def consume(
self,
handle: object,
request: object,
event: object,
p3_state: object,
sink: object,
) -> P5AttestationSnapshot | None:
if type(handle) is not P5AttestationHandle:
return None
with self._lock:
entry = self._entries.pop(handle, None)
if entry is None or self._unloaded:
return None
if self._clock() >= 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 entry.sinks:
return None
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:
with self._lock:
return self._cleanup_locked(self._clock())
def reset_epoch(self) -> str:
with self._lock:
self._entries.clear()
self._issuer_epoch = _new_hash()
return self._issuer_epoch
def unload(self) -> None:
with self._lock:
self._entries.clear()
self._issuer_epoch = _new_hash()
self._unloaded = True
def pending_count(self) -> int:
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_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")
value = value[7:] if value.startswith("sha256:") else value
if len(value) != 64 or any(char not in _HEX for char in value):
raise P5AttestationError("hash is invalid")
return value
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]) -> frozenset[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 frozenset(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
AttestationError = P5AttestationError
AttestationHandle = P5AttestationHandle
OpaqueAttestationHandle = P5AttestationHandle
AttestationSnapshot = P5AttestationSnapshot
AttestationRegistry = P5AttestationRegistry
__all__ = [
"ATTESTATION_SCHEMA_VERSION",
"AttestationError",
"AttestationHandle",
"AttestationRegistry",
"AttestationSnapshot",
"CONTRACT_FINGERPRINT",
"DEFAULT_MAX_ENTRIES",
"DEFAULT_TTL_SECONDS",
"DISPOSITIONS",
"FIREWALL_STATUSES",
"ISSUER",
"OpaqueAttestationHandle",
"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",
]