astrbot_plugin_private_comp.../p5_provenance_attestation.py

524 行
19 KiB
Python

# -*- 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 "<P5AttestationHandle opaque>"
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",
]