astrbot_plugin_private_comp.../reference_asset_gate.py

245 行
9.9 KiB
Python

"""Conservative local gate for structured image-reference assets (REQ-021 Q5).
This module intentionally does not import the cross-plugin P5 attestation
contract. A structured reference asset is a local, administrator-registered
file only; it grants a one-shot image-model input for one generation and
nothing else.
"""
from __future__ import annotations
import hashlib
import re
import secrets
import time
from dataclasses import dataclass
from pathlib import Path
from typing import Any
CONTRACT_NAME = "ops.p5.reference_asset_sink.v1"
ROLE_ORDER = ("identity", "outfit", "pose", "scene", "style")
ALLOWED_EXTENSIONS = frozenset({".png", ".jpg", ".jpeg", ".webp"})
MAX_ASSET_BYTES = 20 * 1024 * 1024
MAX_INPUT_ASSETS = 4
TICKET_TTL_SECONDS = 90
_ASSET_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$")
@dataclass(frozen=True)
class ManagedReferenceAsset:
asset_id: str
role: str
path: Path
prompt_label: str
outfit_lock_default: bool
continuation_match: bool
new_topic_enabled: bool
edit_enabled: bool
@dataclass(frozen=True)
class ReferenceAssetPlan:
generation_id: str
mode: str
assets: tuple[ManagedReferenceAsset, ...]
prompt_constraint: str
@property
def primary_asset(self) -> ManagedReferenceAsset | None:
return next((item for item in self.assets if item.role == "identity"), None)
def public_projection(self) -> dict[str, Any]:
return {
"contract": CONTRACT_NAME,
"enabled": True,
"mode": self.mode,
"asset_ids": [item.asset_id for item in self.assets],
"roles": [item.role for item in self.assets],
"total": len(self.assets),
}
@dataclass(frozen=True)
class ReferenceAssetTicket:
"""Opaque in-memory capability. It has no serializer by design."""
nonce: str
class ReferenceAssetGate:
"""Validate managed assets and mediate their only allowed sink."""
def __init__(self, data_dir: str | Path, *, now: Any = time.time) -> None:
self._root = (Path(data_dir) / "photo_reference_assets").resolve()
self._now = now
self._tickets: dict[str, dict[str, Any]] = {}
@property
def root(self) -> Path:
return self._root
@staticmethod
def _text(value: Any, limit: int = 160) -> str:
return " ".join(str(value or "").split())[:limit]
@staticmethod
def _bool(value: Any, default: bool = False) -> bool:
if isinstance(value, bool):
return value
if value is None or str(value).strip() == "":
return default
return str(value).strip().lower() in {"1", "true", "yes", "on", "enabled"}
def _resolve_registered_path(self, value: Any) -> Path | None:
raw = self._text(value, 240).replace("\\", "/")
if not raw or raw.startswith(("/", "//")) or ":" in raw or ".." in raw.split("/"):
return None
try:
candidate = (self._root / raw).resolve()
candidate.relative_to(self._root)
except (OSError, ValueError):
return None
return candidate
@staticmethod
def _sha256(path: Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as stream:
for block in iter(lambda: stream.read(1024 * 1024), b""):
digest.update(block)
return digest.hexdigest()
def validate_entry(self, raw: Any) -> tuple[ManagedReferenceAsset | None, str]:
if not isinstance(raw, dict):
return None, "entry_not_object"
asset_id = self._text(raw.get("id") or raw.get("asset_id"), 80)
role = self._text(raw.get("role"), 24).lower()
digest = self._text(raw.get("sha256"), 80).lower()
path = self._resolve_registered_path(raw.get("file") or raw.get("relative_path"))
if not _ASSET_ID_RE.fullmatch(asset_id):
return None, "invalid_id"
if role not in ROLE_ORDER:
return None, "invalid_role"
if not re.fullmatch(r"[0-9a-f]{64}", digest):
return None, "invalid_hash"
if path is None:
return None, "outside_managed_directory"
try:
if not path.is_file():
return None, "file_missing"
if path.suffix.lower() not in ALLOWED_EXTENSIONS:
return None, "unsupported_extension"
if path.stat().st_size > MAX_ASSET_BYTES:
return None, "file_too_large"
if not secrets.compare_digest(self._sha256(path), digest):
return None, "hash_mismatch"
except OSError:
return None, "file_unreadable"
return ManagedReferenceAsset(
asset_id=asset_id,
role=role,
path=path,
prompt_label=self._text(raw.get("label"), 80),
outfit_lock_default=self._bool(raw.get("outfit_lock_default"), False),
continuation_match=self._bool(raw.get("continuation_match"), False),
new_topic_enabled=self._bool(raw.get("new_topic_enabled"), True),
edit_enabled=self._bool(raw.get("edit_enabled"), False),
), "ok"
def inspect(self, entries: Any) -> dict[str, Any]:
items = entries if isinstance(entries, list) else []
result: list[dict[str, Any]] = []
valid: dict[str, ManagedReferenceAsset] = {}
seen_roles: set[str] = set()
for raw in items[:16]:
asset, status = self.validate_entry(raw)
raw_id = self._text(raw.get("id") if isinstance(raw, dict) else "", 80)
raw_role = self._text(raw.get("role") if isinstance(raw, dict) else "", 24).lower()
asset_id = raw_id if _ASSET_ID_RE.fullmatch(raw_id) else ""
role = raw_role if raw_role in ROLE_ORDER else ""
if asset and asset.role in seen_roles:
asset, status = None, "duplicate_role"
if asset:
seen_roles.add(asset.role)
valid[asset.role] = asset
asset_id, role = asset.asset_id, asset.role
result.append({"id": asset_id, "role": role, "status": status, "valid": status == "ok"})
return {"items": result, "valid_by_role": valid}
def plan(self, entries: Any, *, generation_id: str, mode: str) -> tuple[ReferenceAssetPlan | None, str]:
mode = self._text(mode, 24).lower()
if mode not in {"continuation", "edit", "new_topic"}:
return None, "invalid_mode"
generation_id = self._text(generation_id, 120)
if not generation_id:
return None, "missing_generation_id"
inspected = self.inspect(entries)
by_role: dict[str, ManagedReferenceAsset] = inspected["valid_by_role"]
identity = by_role.get("identity")
if identity is None:
return None, "missing_verified_identity"
selected: list[ManagedReferenceAsset] = [identity]
outfit = by_role.get("outfit")
if outfit and (outfit.outfit_lock_default if mode == "continuation" else mode == "new_topic"):
selected.append(outfit)
for role in ("pose", "scene"):
asset = by_role.get(role)
if asset and ((mode == "continuation" and asset.continuation_match) or (mode == "new_topic" and asset.new_topic_enabled) or (mode == "edit" and asset.edit_enabled)):
selected.append(asset)
style = by_role.get("style")
if style and ((mode == "continuation" and style.continuation_match) or (mode == "new_topic" and style.new_topic_enabled) or (mode == "edit" and style.edit_enabled)):
selected.append(style)
selected.sort(key=lambda item: ROLE_ORDER.index(item.role))
selected = selected[:MAX_INPUT_ASSETS]
constraints = [item for item in selected if item.role != "identity"]
prompt_constraint = ""
if constraints:
names = ", ".join(item.role for item in constraints)
prompt_constraint = f"Managed visual constraints: keep the approved {names} reference consistent."
return ReferenceAssetPlan(generation_id=generation_id, mode=mode, assets=tuple(selected), prompt_constraint=prompt_constraint), "ok"
def issue(self, plan: ReferenceAssetPlan, *, backend: str) -> ReferenceAssetTicket | None:
if not isinstance(plan, ReferenceAssetPlan) or not plan.primary_asset:
return None
nonce = secrets.token_urlsafe(24)
ticket = ReferenceAssetTicket(nonce=nonce)
self._tickets[nonce] = {
"ticket": ticket,
"plan": plan,
"backend": self._text(backend, 24).lower(),
"expires_at": float(self._now()) + TICKET_TTL_SECONDS,
"consumed": False,
}
return ticket
def consume(
self,
ticket: ReferenceAssetTicket,
*,
generation_id: str,
backend: str,
capacity: int,
) -> tuple[list[str], str]:
record = self._tickets.get(getattr(ticket, "nonce", ""))
if not record or record.get("ticket") is not ticket:
return [], "unknown_ticket"
if record["consumed"] or float(self._now()) > float(record["expires_at"]):
return [], "expired_or_consumed_ticket"
plan: ReferenceAssetPlan = record["plan"]
if generation_id != plan.generation_id or self._text(backend, 24).lower() != record["backend"]:
return [], "scope_mismatch"
if capacity <= 0:
return [], "invalid_capacity"
record["consumed"] = True
paths = [str(item.path) for item in plan.assets[:max(1, min(capacity, MAX_INPUT_ASSETS))]]
return paths, "ok"
def public_projection(self, entries: Any, *, backend_capacity: int) -> dict[str, Any]:
inspected = self.inspect(entries)
return {
"contract": CONTRACT_NAME,
"managed_directory": "photo_reference_assets",
"items": inspected["items"],
"backend_capacity": max(0, min(int(backend_capacity or 0), MAX_INPUT_ASSETS)),
"max_assets": MAX_INPUT_ASSETS,
}