tg-bot-plugin-contract-core 0.1.1__py3-none-any.whl

tg_bot_plugin_contract_core/__init__.py

@@ -0,0 +1,39 @@
+"""TG-BOT 插件 bundle 的共享正式合同辅助接口。"""
+
+from .core import (
+    compute_artifact_digest,
+    compute_package_sha256,
+    inspect_bundle,
+    match_signer_identity,
+    validate_bundle_same_profile,
+    validate_bundle_target_profile,
+    verify_bundle,
+    write_reproducible_bundle,
+)
+from .errors import ContractCoreError
+from .models import (
+    ArtifactDescriptor,
+    BundleInspectionResult,
+    BundleVerificationResult,
+    PluginManifest,
+    SignerIdentity,
+    SignerIdentityMatchResult,
+)
+
+__all__ = [
+    "ArtifactDescriptor",
+    "BundleInspectionResult",
+    "BundleVerificationResult",
+    "ContractCoreError",
+    "PluginManifest",
+    "SignerIdentity",
+    "SignerIdentityMatchResult",
+    "compute_artifact_digest",
+    "compute_package_sha256",
+    "inspect_bundle",
+    "match_signer_identity",
+    "validate_bundle_same_profile",
+    "validate_bundle_target_profile",
+    "verify_bundle",
+    "write_reproducible_bundle",
+]

tg_bot_plugin_contract_core/core.py

@@ -0,0 +1,760 @@
+"""TG-BOT 插件 manifest、bundle、digest 与 signer 的核心辅助实现。"""
+
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import importlib.machinery
+import json
+import os
+import tempfile
+import zipfile
+from pathlib import Path, PurePosixPath
+from typing import Any, Mapping, Sequence
+from urllib.parse import urlparse
+
+from .errors import ContractCoreError
+from .models import (
+    ArtifactDescriptor,
+    BundleInspectionResult,
+    BundleVerificationResult,
+    PluginManifest,
+    SignerIdentity,
+    SignerIdentityMatchResult,
+)
+
+MANIFEST_FILE_NAME = "manifest.json"
+SIGNATURE_BUNDLE_PATH = "META-INF/sigstore.bundle.json"
+SBOM_PATH = "META-INF/sbom.json"
+SUPPORTED_BUNDLE_SUFFIX = ".tgpkg"
+FIXED_ZIP_TIMESTAMP = (1980, 1, 1, 0, 0, 0)
+ZIP_FILE_MODE = 0o100644
+ZIP_DIR_MODE = 0o40755
+DEFLATE_COMPRESSLEVEL = 9
+
+_MANIFEST_FIELDS = {
+    "plugin_id",
+    "plugin_version",
+    "name",
+    "description",
+    "category",
+    "runtime_profile_id",
+    "artifact_digest",
+    "entrypoint",
+    "config_schema",
+    "interaction_schema",
+    "declared_scopes",
+    "declared_capabilities",
+}
+_ENTRYPOINT_FIELDS = {"module_path", "symbol"}
+_IGNORED_DIGEST_FILE_NAMES = {MANIFEST_FILE_NAME, ".DS_Store"}
+_IGNORED_DIGEST_PARTS = {"__pycache__"}
+_IGNORED_DIGEST_SUFFIXES = {".pyc", SUPPORTED_BUNDLE_SUFFIX}
+_STORED_SUFFIXES = {
+    ".7z",
+    ".bz2",
+    ".dll",
+    ".dylib",
+    ".gif",
+    ".gz",
+    ".ico",
+    ".jar",
+    ".jpeg",
+    ".jpg",
+    ".mp3",
+    ".mp4",
+    ".pdf",
+    ".png",
+    ".pyd",
+    ".so",
+    ".tgz",
+    ".tgpkg",
+    ".webp",
+    ".woff",
+    ".woff2",
+    ".xz",
+    ".zip",
+}
+_TRUSTED_SIGNER_RULE_FIELDS = {
+    "rule_id",
+    "issuer",
+    "repository_owner",
+    "repository_name",
+    "workflow_ref",
+    "reusable_workflow_ref",
+    "ref_pattern",
+    "status",
+}
+
+
+def stable_json_dumps(payload: Any) -> str:
+    return json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def _clone_json(value: Any) -> Any:
+    return json.loads(stable_json_dumps(value))
+
+
+def _normalize_json_object(raw: Any, *, field_name: str) -> dict[str, Any]:
+    if raw in (None, ""):
+        return {}
+    if isinstance(raw, dict):
+        return _clone_json(raw)
+    raise ContractCoreError("manifest_invalid", f"{field_name} must be an object")
+
+
+def _normalize_json_array(raw: Any, *, field_name: str) -> list[Any]:
+    if raw in (None, ""):
+        return []
+    if isinstance(raw, list):
+        return _clone_json(raw)
+    raise ContractCoreError("manifest_invalid", f"{field_name} must be an array")
+
+
+def _normalize_manifest_payload(
+    payload: Mapping[str, Any],
+    *,
+    require_artifact_digest: bool,
+) -> PluginManifest:
+    if not isinstance(payload, Mapping):
+        raise ContractCoreError("manifest_invalid", "manifest root must be an object")
+    payload_dict = dict(payload)
+
+    unknown_fields = sorted(set(payload_dict) - _MANIFEST_FIELDS)
+    if unknown_fields:
+        raise ContractCoreError(
+            "manifest_unknown_field",
+            f"manifest contains unsupported fields: {', '.join(unknown_fields)}",
+        )
+
+    plugin_id = str(payload_dict.get("plugin_id") or "").strip()
+    plugin_version = str(payload_dict.get("plugin_version") or "").strip()
+    name = str(payload_dict.get("name") or "").strip()
+    description = str(payload_dict.get("description") or "").strip()
+    category = str(payload_dict.get("category") or "").strip()
+    runtime_profile_id = str(payload_dict.get("runtime_profile_id") or "").strip()
+    artifact_digest = str(payload_dict.get("artifact_digest") or "").strip()
+
+    entrypoint_raw = payload_dict.get("entrypoint")
+    if not isinstance(entrypoint_raw, Mapping):
+        raise ContractCoreError("manifest_invalid", "entrypoint must be an object")
+    entrypoint_dict = dict(entrypoint_raw)
+    unknown_entrypoint_fields = sorted(set(entrypoint_dict) - _ENTRYPOINT_FIELDS)
+    if unknown_entrypoint_fields:
+        raise ContractCoreError(
+            "manifest_unknown_field",
+            f"entrypoint contains unsupported fields: {', '.join(unknown_entrypoint_fields)}",
+        )
+    module_path = str(entrypoint_dict.get("module_path") or "").strip()
+    symbol = str(entrypoint_dict.get("symbol") or "").strip()
+
+    if not plugin_id:
+        raise ContractCoreError("manifest_invalid", "plugin_id is required")
+    if not plugin_version:
+        raise ContractCoreError("manifest_invalid", f"plugin {plugin_id} missing plugin_version")
+    if not name:
+        raise ContractCoreError("manifest_invalid", f"plugin {plugin_id} missing name")
+    if not description:
+        raise ContractCoreError("manifest_invalid", f"plugin {plugin_id} missing description")
+    if not category:
+        raise ContractCoreError("manifest_invalid", f"plugin {plugin_id} missing category")
+    if not runtime_profile_id:
+        raise ContractCoreError("manifest_invalid", f"plugin {plugin_id} missing runtime_profile_id")
+    if require_artifact_digest and not artifact_digest:
+        raise ContractCoreError("manifest_invalid", f"plugin {plugin_id} missing artifact_digest")
+    if not module_path or not symbol:
+        raise ContractCoreError(
+            "manifest_invalid",
+            f"plugin {plugin_id} missing entrypoint.module_path or entrypoint.symbol",
+        )
+
+    config_schema = _normalize_json_object(payload_dict.get("config_schema"), field_name="config_schema")
+    interaction_schema = _normalize_json_object(payload_dict.get("interaction_schema"), field_name="interaction_schema")
+    declared_scopes = _normalize_json_array(payload_dict.get("declared_scopes"), field_name="declared_scopes")
+    declared_capabilities = _normalize_json_array(
+        payload_dict.get("declared_capabilities"),
+        field_name="declared_capabilities",
+    )
+
+    normalized_payload = _clone_json(payload_dict)
+    normalized_payload["plugin_id"] = plugin_id
+    normalized_payload["plugin_version"] = plugin_version
+    normalized_payload["name"] = name
+    normalized_payload["description"] = description
+    normalized_payload["category"] = category
+    normalized_payload["runtime_profile_id"] = runtime_profile_id
+    normalized_payload["artifact_digest"] = artifact_digest
+    normalized_payload["entrypoint"] = {"module_path": module_path, "symbol": symbol}
+    normalized_payload["config_schema"] = config_schema
+    normalized_payload["interaction_schema"] = interaction_schema
+    normalized_payload["declared_scopes"] = declared_scopes
+    normalized_payload["declared_capabilities"] = declared_capabilities
+
+    return PluginManifest(
+        plugin_id=plugin_id,
+        plugin_version=plugin_version,
+        name=name,
+        description=description,
+        category=category,
+        runtime_profile_id=runtime_profile_id,
+        artifact_digest=artifact_digest,
+        entrypoint={"module_path": module_path, "symbol": symbol},
+        config_schema=config_schema,
+        interaction_schema=interaction_schema,
+        declared_scopes=declared_scopes,
+        declared_capabilities=declared_capabilities,
+        raw=normalized_payload,
+    )
+
+
+def _coerce_manifest(payload: Mapping[str, Any] | PluginManifest, *, require_artifact_digest: bool) -> PluginManifest:
+    if isinstance(payload, PluginManifest):
+        manifest = payload
+    else:
+        manifest = _normalize_manifest_payload(payload, require_artifact_digest=require_artifact_digest)
+    if require_artifact_digest and not manifest.artifact_digest:
+        raise ContractCoreError("manifest_invalid", f"plugin {manifest.plugin_id} missing artifact_digest")
+    return manifest
+
+
+def _ensure_directory(path_like: str | os.PathLike[str]) -> Path:
+    path = Path(path_like).expanduser().resolve()
+    if not path.exists():
+        raise ContractCoreError("path_missing", f"path not found: {path}")
+    if not path.is_dir():
+        raise ContractCoreError("path_invalid", f"path is not a directory: {path}")
+    return path
+
+
+def _ensure_bundle_path(path_like: str | os.PathLike[str]) -> Path:
+    path = Path(path_like).expanduser().resolve()
+    if not path.is_file():
+        raise ContractCoreError("bundle_missing", f"bundle not found: {path}")
+    if path.suffix != SUPPORTED_BUNDLE_SUFFIX:
+        raise ContractCoreError("bundle_format_invalid", f"unsupported bundle format: {path.name}")
+    return path
+
+
+def _file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        while True:
+            chunk = handle.read(64 * 1024)
+            if not chunk:
+                break
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _should_exclude_from_artifact_digest(path: Path, plugin_dir: Path) -> bool:
+    if not path.is_file():
+        return True
+    relpath = path.relative_to(plugin_dir)
+    if any(part in _IGNORED_DIGEST_PARTS for part in relpath.parts):
+        return True
+    if path.name in _IGNORED_DIGEST_FILE_NAMES:
+        return True
+    if path.suffix in _IGNORED_DIGEST_SUFFIXES:
+        return True
+    relpath_posix = relpath.as_posix()
+    if relpath_posix in {SIGNATURE_BUNDLE_PATH, SBOM_PATH}:
+        return True
+    return False
+
+
+def _build_artifact_descriptor(plugin_dir: Path, manifest_payload: Mapping[str, Any] | PluginManifest) -> ArtifactDescriptor:
+    manifest = _coerce_manifest(manifest_payload, require_artifact_digest=False)
+    manifest_normalized = _clone_json(manifest.raw)
+    manifest_normalized.pop("artifact_digest", None)
+
+    files: list[dict[str, Any]] = []
+    for path in sorted(plugin_dir.rglob("*"), key=lambda candidate: candidate.relative_to(plugin_dir).as_posix()):
+        if _should_exclude_from_artifact_digest(path, plugin_dir):
+            continue
+        relpath = path.relative_to(plugin_dir).as_posix()
+        files.append(
+            {
+                "path": relpath,
+                "sha256": _file_sha256(path),
+                "size": path.stat().st_size,
+            }
+        )
+
+    return ArtifactDescriptor(
+        manifest_normalized=manifest_normalized,
+        files=tuple(files),
+    )
+
+
+def compute_artifact_digest(
+    plugin_dir: str | os.PathLike[str],
+    manifest_payload: Mapping[str, Any] | PluginManifest,
+) -> str:
+    plugin_root = _ensure_directory(plugin_dir)
+    descriptor = _build_artifact_descriptor(plugin_root, manifest_payload)
+    return hashlib.sha256(stable_json_dumps({
+        "manifest_normalized": descriptor.manifest_normalized,
+        "files": list(descriptor.files),
+    }).encode("utf-8")).hexdigest()
+
+
+def compute_package_sha256(bundle_path: str | os.PathLike[str]) -> str:
+    return _file_sha256(_ensure_bundle_path(bundle_path))
+
+
+def _normalize_archive_member(name: str) -> PurePosixPath:
+    relpath = PurePosixPath(str(name or "").strip())
+    if not relpath.parts:
+        raise ContractCoreError("bundle_entry_invalid", "bundle contains an empty archive member")
+    if relpath.is_absolute() or ".." in relpath.parts:
+        raise ContractCoreError("bundle_entry_invalid", f"bundle contains unsafe archive member: {name}")
+    return relpath
+
+
+def _extract_bundle(bundle_path: Path, target_dir: Path) -> tuple[str, ...]:
+    archive_entries: list[str] = []
+    with zipfile.ZipFile(bundle_path) as archive:
+        for info in archive.infolist():
+            relpath = _normalize_archive_member(info.filename)
+            normalized_name = relpath.as_posix()
+            archive_entries.append(normalized_name)
+            destination = target_dir / normalized_name
+            if info.is_dir():
+                destination.mkdir(parents=True, exist_ok=True)
+                continue
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            with archive.open(info, "r") as source, destination.open("wb") as sink:
+                sink.write(source.read())
+    return tuple(sorted(archive_entries))
+
+
+def _resolve_entrypoint_relpath(plugin_dir: Path, module_path: str) -> str:
+    normalized = str(module_path or "").strip().replace("\\", "/").replace(".", "/").strip("/")
+    candidates: list[Path] = []
+    compiled_candidates: list[Path] = []
+    if normalized in {"", "__init__"}:
+        candidates.append(plugin_dir / "__init__.py")
+        compiled_candidates.extend(sorted(plugin_dir.glob("__init__.*")))
+    else:
+        normalized_path = Path(normalized)
+        direct_module = plugin_dir / normalized_path
+        package_module = plugin_dir / normalized_path / "__init__"
+        candidates.append(direct_module.with_suffix(".py"))
+        candidates.append(package_module.with_suffix(".py"))
+        compiled_candidates.extend(sorted(direct_module.parent.glob(f"{direct_module.name}.*")))
+        compiled_candidates.extend(sorted(package_module.parent.glob(f"{package_module.name}.*")))
+    for suffix in importlib.machinery.EXTENSION_SUFFIXES:
+        if normalized in {"", "__init__"}:
+            candidates.append(plugin_dir / f"__init__{suffix}")
+        else:
+            candidates.append(plugin_dir / f"{normalized}{suffix}")
+            candidates.append(plugin_dir / normalized / f"__init__{suffix}")
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate.relative_to(plugin_dir).as_posix()
+    for candidate in compiled_candidates:
+        if candidate.is_file():
+            return candidate.relative_to(plugin_dir).as_posix()
+    raise ContractCoreError(
+        "entrypoint_missing",
+        f"entrypoint module not found for module_path={module_path}",
+    )
+
+
+def inspect_bundle(bundle_path: str | os.PathLike[str]) -> BundleInspectionResult:
+    resolved_bundle_path = _ensure_bundle_path(bundle_path)
+    package_sha256 = compute_package_sha256(resolved_bundle_path)
+
+    with tempfile.TemporaryDirectory(prefix="tg-bot-plugin-contract-core-") as temp_dir_str:
+        extracted_root = Path(temp_dir_str)
+        archive_entries = _extract_bundle(resolved_bundle_path, extracted_root)
+        manifest_path = extracted_root / MANIFEST_FILE_NAME
+        if not manifest_path.is_file():
+            raise ContractCoreError("manifest_missing", "bundle missing manifest.json at archive root")
+        try:
+            manifest_payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise ContractCoreError("manifest_invalid", f"manifest json invalid: {manifest_path}") from exc
+        manifest = _coerce_manifest(manifest_payload, require_artifact_digest=True)
+        artifact_descriptor = _build_artifact_descriptor(extracted_root, manifest)
+        computed_digest = compute_artifact_digest(extracted_root, manifest)
+        if computed_digest != manifest.artifact_digest:
+            raise ContractCoreError(
+                "artifact_digest_mismatch",
+                "artifact_digest mismatch between manifest and extracted runtime",
+            )
+        entrypoint_relpath = _resolve_entrypoint_relpath(extracted_root, manifest.entrypoint["module_path"])
+        signature_bundle_present = (extracted_root / SIGNATURE_BUNDLE_PATH).is_file()
+        return BundleInspectionResult(
+            bundle_path=resolved_bundle_path,
+            bundle_name=resolved_bundle_path.name,
+            plugin_id=manifest.plugin_id,
+            plugin_version=manifest.plugin_version,
+            runtime_profile_id=manifest.runtime_profile_id,
+            artifact_digest=manifest.artifact_digest,
+            package_sha256=package_sha256,
+            manifest=manifest,
+            artifact_descriptor=artifact_descriptor,
+            archive_entries=archive_entries,
+            entrypoint_relpath=entrypoint_relpath,
+            signature_bundle_path=SIGNATURE_BUNDLE_PATH if signature_bundle_present else "",
+            signature_bundle_present=signature_bundle_present,
+        )
+
+
+def _read_archive_member(bundle_path: Path, member_name: str) -> bytes:
+    normalized_name = _normalize_archive_member(member_name).as_posix()
+    with zipfile.ZipFile(bundle_path) as archive:
+        try:
+            with archive.open(normalized_name, "r") as handle:
+                return handle.read()
+        except KeyError as exc:
+            raise ContractCoreError(
+                "bundle_entry_missing",
+                f"bundle missing archive member: {normalized_name}",
+            ) from exc
+
+
+def _certificate_extension_text(
+    certificate: Any,
+    oid_value: str,
+    *,
+    der_encoded_utf8: bool,
+    required: bool = True,
+) -> str:
+    try:
+        from cryptography.x509.oid import ObjectIdentifier
+    except ImportError as exc:
+        raise ContractCoreError("sigstore_dependency_missing", "cryptography is required for signer extraction") from exc
+    try:
+        extension = certificate.extensions.get_extension_for_oid(ObjectIdentifier(oid_value)).value
+    except Exception:
+        if required:
+            raise ContractCoreError("signer_identity_missing", f"certificate missing extension {oid_value}")
+        return ""
+    raw_value = extension.value
+    if der_encoded_utf8:
+        try:
+            from pyasn1.codec.der.decoder import decode as der_decode
+            from pyasn1.type.char import UTF8String
+        except ImportError as exc:
+            raise ContractCoreError("sigstore_dependency_missing", "pyasn1 is required for signer extraction") from exc
+        decoded = der_decode(raw_value, asn1Spec=UTF8String())[0]
+        return str(decoded).strip()
+    return raw_value.decode().strip()
+
+
+def _normalize_github_locator(value: str) -> str:
+    normalized = str(value or "").strip()
+    if not normalized:
+        return ""
+    if normalized.startswith("https://github.com/"):
+        return normalized.removeprefix("https://github.com/").strip("/")
+    if normalized.startswith("http://github.com/"):
+        return normalized.removeprefix("http://github.com/").strip("/")
+    return normalized.strip("/")
+
+
+def _parse_repository_owner_name(value: str) -> tuple[str, str]:
+    normalized = str(value or "").strip()
+    if not normalized:
+        return "", ""
+    if normalized.startswith("http://") or normalized.startswith("https://"):
+        parsed = urlparse(normalized)
+        parts = [part for part in parsed.path.split("/") if part]
+    else:
+        parts = [part for part in normalized.strip("/").split("/") if part]
+    if len(parts) < 2:
+        return "", ""
+    return parts[0], parts[1]
+
+
+def _extract_signer_identity(bundle: Any) -> SignerIdentity:
+    certificate = bundle.signing_certificate
+    issuer = _certificate_extension_text(certificate, "1.3.6.1.4.1.57264.1.8", der_encoded_utf8=True)
+    repository_uri = _certificate_extension_text(
+        certificate,
+        "1.3.6.1.4.1.57264.1.12",
+        der_encoded_utf8=True,
+        required=False,
+    )
+    workflow_repository = _certificate_extension_text(
+        certificate,
+        "1.3.6.1.4.1.57264.1.5",
+        der_encoded_utf8=False,
+        required=False,
+    )
+    repository_owner, repository_name = _parse_repository_owner_name(repository_uri or workflow_repository)
+    workflow_ref = _certificate_extension_text(
+        certificate,
+        "1.3.6.1.4.1.57264.1.6",
+        der_encoded_utf8=False,
+        required=False,
+    )
+    reusable_workflow_ref = _normalize_github_locator(
+        _certificate_extension_text(
+            certificate,
+            "1.3.6.1.4.1.57264.1.18",
+            der_encoded_utf8=True,
+            required=False,
+        )
+    )
+    ref = _certificate_extension_text(
+        certificate,
+        "1.3.6.1.4.1.57264.1.14",
+        der_encoded_utf8=True,
+        required=False,
+    )
+    return SignerIdentity(
+        issuer=issuer,
+        repository_owner=repository_owner,
+        repository_name=repository_name,
+        workflow_ref=workflow_ref,
+        reusable_workflow_ref=reusable_workflow_ref,
+        ref=ref,
+    )
+
+
+def _verify_sigstore_bundle(
+    bundle_path: Path,
+    *,
+    signature_bundle_raw: bytes,
+    offline: bool,
+) -> SignerIdentity:
+    try:
+        from sigstore.models import Bundle as SigstoreBundle
+        from sigstore.verify import Verifier
+        from sigstore.verify.policy import UnsafeNoOp
+    except ImportError as exc:
+        raise ContractCoreError(
+            "sigstore_dependency_missing",
+            "sigstore dependencies are required for bundle verification",
+        ) from exc
+
+    try:
+        sigstore_bundle = SigstoreBundle.from_json(signature_bundle_raw)
+    except Exception as exc:
+        raise ContractCoreError("signature_bundle_invalid", f"failed to parse sigstore bundle: {exc}") from exc
+
+    artifact_bytes = bundle_path.read_bytes()
+    try:
+        verifier = Verifier.production(offline=offline)
+        verifier.verify_artifact(artifact_bytes, sigstore_bundle, UnsafeNoOp())
+    except Exception as exc:
+        raise ContractCoreError("signature_invalid", f"sigstore verification failed: {exc}") from exc
+
+    return _extract_signer_identity(sigstore_bundle)
+
+
+def _coerce_inspection(bundle: str | os.PathLike[str] | BundleInspectionResult) -> BundleInspectionResult:
+    if isinstance(bundle, BundleInspectionResult):
+        return bundle
+    return inspect_bundle(bundle)
+
+
+def verify_bundle(
+    bundle: str | os.PathLike[str] | BundleInspectionResult,
+    *,
+    allow_unsigned_dev: bool = False,
+    offline: bool = False,
+) -> BundleVerificationResult:
+    inspection = _coerce_inspection(bundle)
+    if not inspection.signature_bundle_present:
+        if allow_unsigned_dev:
+            return BundleVerificationResult(
+                inspection=inspection,
+                signer_identity=None,
+                signature_verification_status="unsigned_dev",
+            )
+        raise ContractCoreError(
+            "signature_bundle_missing",
+            f"bundle missing {SIGNATURE_BUNDLE_PATH}",
+        )
+
+    signature_bundle_raw = _read_archive_member(inspection.bundle_path, inspection.signature_bundle_path)
+    signer_identity = _verify_sigstore_bundle(
+        inspection.bundle_path,
+        signature_bundle_raw=signature_bundle_raw,
+        offline=offline,
+    )
+    return BundleVerificationResult(
+        inspection=inspection,
+        signer_identity=signer_identity,
+        signature_verification_status="verified",
+    )
+
+
+def _normalize_trusted_signer_rules(trusted_signer_rules: Sequence[Mapping[str, Any]]) -> list[dict[str, str]]:
+    normalized_rules: list[dict[str, str]] = []
+    for index, rule in enumerate(trusted_signer_rules):
+        if not isinstance(rule, Mapping):
+            raise ContractCoreError(
+                "trusted_signer_rule_invalid",
+                f"trusted signer rule #{index} must be an object",
+            )
+        rule_dict = {str(key): value for key, value in dict(rule).items()}
+        unknown_fields = sorted(set(rule_dict) - _TRUSTED_SIGNER_RULE_FIELDS)
+        if unknown_fields:
+            raise ContractCoreError(
+                "trusted_signer_rule_invalid",
+                f"trusted signer rule #{index} contains unsupported fields: {', '.join(unknown_fields)}",
+            )
+        missing_fields = sorted(field for field in _TRUSTED_SIGNER_RULE_FIELDS if field not in rule_dict)
+        if missing_fields:
+            raise ContractCoreError(
+                "trusted_signer_rule_invalid",
+                f"trusted signer rule #{index} missing fields: {', '.join(missing_fields)}",
+            )
+        normalized_rule = {field: str(rule_dict.get(field) or "").strip() for field in _TRUSTED_SIGNER_RULE_FIELDS}
+        empty_fields = [field for field, value in normalized_rule.items() if not value]
+        if empty_fields:
+            raise ContractCoreError(
+                "trusted_signer_rule_invalid",
+                f"trusted signer rule #{index} has empty fields: {', '.join(sorted(empty_fields))}",
+            )
+        if normalized_rule["status"] not in {"active", "disabled"}:
+            raise ContractCoreError(
+                "trusted_signer_rule_invalid",
+                f"trusted signer rule #{index} has invalid status: {normalized_rule['status']}",
+            )
+        if not normalized_rule["ref_pattern"].startswith("refs/tags/"):
+            raise ContractCoreError(
+                "trusted_signer_rule_invalid",
+                f"trusted signer rule #{index} must use a tag ref pattern",
+            )
+        normalized_rules.append(normalized_rule)
+    return normalized_rules
+
+
+def _coerce_signer_identity(
+    signer_identity: SignerIdentity | BundleVerificationResult | None,
+) -> SignerIdentity | None:
+    if isinstance(signer_identity, BundleVerificationResult):
+        return signer_identity.signer_identity
+    return signer_identity
+
+
+def match_signer_identity(
+    signer_identity: SignerIdentity | BundleVerificationResult | None,
+    trusted_signer_rules: Sequence[Mapping[str, Any]],
+) -> SignerIdentityMatchResult:
+    identity = _coerce_signer_identity(signer_identity)
+    if identity is None:
+        return SignerIdentityMatchResult(
+            signer_identity=None,
+            matched=False,
+            matched_rule_id="",
+            signer_identity_text="",
+            reason="signer_identity_missing",
+        )
+
+    normalized_rules = _normalize_trusted_signer_rules(trusted_signer_rules)
+    signer_identity_text = identity.persistent_value()
+    for rule in normalized_rules:
+        if rule["status"] != "active":
+            continue
+        if identity.issuer != rule["issuer"]:
+            continue
+        if identity.repository_owner != rule["repository_owner"]:
+            continue
+        if identity.repository_name != rule["repository_name"]:
+            continue
+        if identity.workflow_ref != rule["workflow_ref"]:
+            continue
+        if identity.reusable_workflow_ref != rule["reusable_workflow_ref"]:
+            continue
+        if not fnmatch.fnmatch(identity.ref, rule["ref_pattern"]):
+            continue
+        return SignerIdentityMatchResult(
+            signer_identity=identity,
+            matched=True,
+            matched_rule_id=rule["rule_id"],
+            signer_identity_text=signer_identity_text,
+            reason="matched",
+        )
+
+    return SignerIdentityMatchResult(
+        signer_identity=identity,
+        matched=False,
+        matched_rule_id="",
+        signer_identity_text=signer_identity_text,
+        reason="signer_identity_not_trusted",
+    )
+
+
+def validate_bundle_same_profile(
+    bundle: str | os.PathLike[str] | BundleInspectionResult,
+    *,
+    runtime_profile_id: str,
+    allow_unsigned_dev: bool = False,
+    offline: bool = False,
+) -> BundleVerificationResult:
+    result = verify_bundle(
+        bundle,
+        allow_unsigned_dev=allow_unsigned_dev,
+        offline=offline,
+    )
+    expected_runtime_profile_id = str(runtime_profile_id or "").strip()
+    if not expected_runtime_profile_id:
+        raise ContractCoreError("runtime_profile_missing", "runtime_profile_id is required")
+    if result.runtime_profile_id != expected_runtime_profile_id:
+        raise ContractCoreError(
+            "runtime_profile_mismatch",
+            f"bundle runtime profile {result.runtime_profile_id} does not match {expected_runtime_profile_id}",
+        )
+    return result
+
+
+def validate_bundle_target_profile(
+    bundle: str | os.PathLike[str] | BundleInspectionResult,
+    *,
+    target_runtime_profile_id: str,
+    allow_unsigned_dev: bool = False,
+    offline: bool = False,
+) -> BundleVerificationResult:
+    expected_runtime_profile_id = str(target_runtime_profile_id or "").strip()
+    if not expected_runtime_profile_id:
+        raise ContractCoreError("runtime_profile_missing", "target_runtime_profile_id is required")
+    return validate_bundle_same_profile(
+        bundle,
+        runtime_profile_id=expected_runtime_profile_id,
+        allow_unsigned_dev=allow_unsigned_dev,
+        offline=offline,
+    )
+
+
+def _zip_compression_for_path(path: Path) -> int:
+    if path.suffix.lower() in _STORED_SUFFIXES:
+        return zipfile.ZIP_STORED
+    return zipfile.ZIP_DEFLATED
+
+
+def _zip_external_attr(mode: int) -> int:
+    return mode << 16
+
+
+def write_reproducible_bundle(
+    source_dir: str | os.PathLike[str],
+    bundle_path: str | os.PathLike[str],
+) -> Path:
+    source_root = _ensure_directory(source_dir)
+    target_bundle_path = Path(bundle_path).expanduser().resolve()
+    target_bundle_path.parent.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(target_bundle_path, mode="w") as archive:
+        for path in sorted(source_root.rglob("*"), key=lambda current: current.relative_to(source_root).as_posix()):
+            relpath = path.relative_to(source_root)
+            if path.is_symlink():
+                raise ContractCoreError("bundle_entry_invalid", f"symlink entries are not supported: {relpath.as_posix()}")
+            if path.is_dir():
+                continue
+            zip_info = zipfile.ZipInfo(relpath.as_posix(), date_time=FIXED_ZIP_TIMESTAMP)
+            zip_info.create_system = 3
+            zip_info.external_attr = _zip_external_attr(ZIP_FILE_MODE)
+            compression = _zip_compression_for_path(path)
+            zip_info.compress_type = compression
+            file_bytes = path.read_bytes()
+            if compression == zipfile.ZIP_DEFLATED:
+                archive.writestr(zip_info, file_bytes, compress_type=compression, compresslevel=DEFLATE_COMPRESSLEVEL)
+            else:
+                archive.writestr(zip_info, file_bytes, compress_type=compression)
+    return target_bundle_path

tg_bot_plugin_contract_core/errors.py

@@ -0,0 +1,11 @@
+"""TG-BOT 插件合同校验使用的错误类型。"""
+
+from __future__ import annotations
+
+
+class ContractCoreError(ValueError):
+    """带稳定机器可读错误码的结构化校验异常。"""
+
+    def __init__(self, code: str, message: str) -> None:
+        self.code = str(code or "").strip() or "contract_core_error"
+        super().__init__(message)

tg_bot_plugin_contract_core/models.py

@@ -0,0 +1,102 @@
+"""TG-BOT 插件合同辅助层对外暴露的数据模型。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class PluginManifest:
+    plugin_id: str
+    plugin_version: str
+    name: str
+    description: str
+    category: str
+    runtime_profile_id: str
+    artifact_digest: str
+    entrypoint: dict[str, str]
+    config_schema: dict[str, Any]
+    interaction_schema: dict[str, Any]
+    declared_scopes: list[Any]
+    declared_capabilities: list[Any]
+    raw: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactDescriptor:
+    manifest_normalized: dict[str, Any]
+    files: tuple[dict[str, Any], ...]
+
+
+@dataclass(frozen=True, slots=True)
+class SignerIdentity:
+    issuer: str
+    repository_owner: str
+    repository_name: str
+    workflow_ref: str
+    reusable_workflow_ref: str
+    ref: str
+
+    def persistent_value(self) -> str:
+        return (
+            f"issuer={self.issuer},"
+            f"repo={self.repository_owner}/{self.repository_name},"
+            f"workflow_ref={self.workflow_ref},"
+            f"reusable_workflow_ref={self.reusable_workflow_ref},"
+            f"ref={self.ref}"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BundleInspectionResult:
+    bundle_path: Path
+    bundle_name: str
+    plugin_id: str
+    plugin_version: str
+    runtime_profile_id: str
+    artifact_digest: str
+    package_sha256: str
+    manifest: PluginManifest
+    artifact_descriptor: ArtifactDescriptor
+    archive_entries: tuple[str, ...]
+    entrypoint_relpath: str
+    signature_bundle_path: str
+    signature_bundle_present: bool
+
+
+@dataclass(frozen=True, slots=True)
+class BundleVerificationResult:
+    inspection: BundleInspectionResult
+    signer_identity: SignerIdentity | None
+    signature_verification_status: str
+
+    @property
+    def plugin_id(self) -> str:
+        return self.inspection.plugin_id
+
+    @property
+    def plugin_version(self) -> str:
+        return self.inspection.plugin_version
+
+    @property
+    def runtime_profile_id(self) -> str:
+        return self.inspection.runtime_profile_id
+
+    @property
+    def artifact_digest(self) -> str:
+        return self.inspection.artifact_digest
+
+    @property
+    def package_sha256(self) -> str:
+        return self.inspection.package_sha256
+
+
+@dataclass(frozen=True, slots=True)
+class SignerIdentityMatchResult:
+    signer_identity: SignerIdentity | None
+    matched: bool
+    matched_rule_id: str
+    signer_identity_text: str
+    reason: str

tg_bot_plugin_contract_core-0.1.1.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: tg-bot-plugin-contract-core
+Version: 0.1.1
+Summary: TG-BOT 插件的共享 manifest、bundle、digest 与 signer 校验合同层。
+Author: Fire Dragons
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: sigstore>=4.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tg-bot-plugin-contract-core
+
+`tg-bot-plugin-contract-core` 是 TG-BOT 插件 `manifest` 与 `.tgpkg` bundle 的共享正式合同层。
+
+它提供：
+
+- manifest 规范化与合同校验
+- `artifact_digest` 计算
+- 通过 `package_sha256` 计算 canonical `.tgpkg` 字节身份
+- 可复现 bundle 写入
+- bundle 结构检查
+- Sigstore bundle 验签
+- signer identity 提取与 trusted signer 规则匹配
+
+它有意不提供：
+
+- TG-BOT runtime 加载或插件类实例化
+- trusted signer 文件发现或配置加载
+- 超出 bundle 与 signer 合同范围的平台策略决策
+
+## 安装
+
+```bash
+pip install tg-bot-plugin-contract-core
+```
+
+## 发布与验证
+
+- `pull_request` / `main` 分支会执行：
+  - `pytest`
+  - wheel / sdist 构建
+  - wheel 安装 smoke test
+- `tag push v*` 会额外执行：
+  - `tag == project.version` 校验
+  - PyPI 发布
+  - GitHub Release 附件上传
+
+## 公开 API
+
+```python
+from tg_bot_plugin_contract_core import (
+    compute_artifact_digest,
+    compute_package_sha256,
+    inspect_bundle,
+    match_signer_identity,
+    validate_bundle_same_profile,
+    validate_bundle_target_profile,
+    verify_bundle,
+    write_reproducible_bundle,
+)
+```
+
+## 使用示例
+
+```python
+from pathlib import Path
+
+from tg_bot_plugin_contract_core import (
+    compute_artifact_digest,
+    inspect_bundle,
+    match_signer_identity,
+    verify_bundle,
+)
+
+plugin_dir = Path("plugin-staging")
+manifest_payload = {
+    "plugin_id": "demo",
+    "plugin_version": "1.0.0",
+    "name": "demo",
+    "description": "demo plugin",
+    "category": "utility",
+    "runtime_profile_id": "cpython-3.13-linux-x86_64-gnu",
+    "artifact_digest": "",
+    "entrypoint": {"module_path": "__init__", "symbol": "DemoPlugin"},
+    "config_schema": {},
+    "interaction_schema": {},
+    "declared_scopes": [],
+    "declared_capabilities": [],
+}
+
+artifact_digest = compute_artifact_digest(plugin_dir, manifest_payload)
+inspection = inspect_bundle("dist/plugins/demo/demo-1.0.0-cpython-3.13-linux-x86_64-gnu.tgpkg")
+verification = verify_bundle(inspection, allow_unsigned_dev=False)
+match_result = match_signer_identity(verification, trusted_signer_rules=[
+    {
+        "rule_id": "github-release-main",
+        "issuer": "https://token.actions.githubusercontent.com",
+        "repository_owner": "Fire-Dragons",
+        "repository_name": "demo",
+        "workflow_ref": "Fire-Dragons/demo/.github/workflows/release.yml@refs/heads/main",
+        "reusable_workflow_ref": "Fire-Dragons/tg-bot-plugin-buildkit/.github/workflows/release-plugin.yml@refs/tags/v1",
+        "ref_pattern": "refs/tags/v*",
+        "status": "active",
+    }
+])
+```
+
+## 说明
+
+- `verify_bundle()` 会校验 Sigstore 签名材料，并从签名证书中提取 signer identity。
+- `match_signer_identity()` 会基于已解析的 trusted signer 规则执行平台无关的匹配。
+- `allow_unsigned_dev=True` 仅用于受控的本地开发链路。

tg_bot_plugin_contract_core-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+tg_bot_plugin_contract_core/__init__.py,sha256=0B_E_uDK4rzQ-kNNMu23UiKXpHxgVnoTxrURci97UC4,971
+tg_bot_plugin_contract_core/core.py,sha256=_YXVb7Bn9eHtwHVSW-R1w0GGsI5p_yAIVGNsI6Hn0bU,29399
+tg_bot_plugin_contract_core/errors.py,sha256=qX57soRAjO-3DDOp1yu8Bhypwei8G-qVa7yeTBAofxY,360
+tg_bot_plugin_contract_core/models.py,sha256=7jUDGRjgtbmrJmSclZuXlzhEE3fpW2H92O8jlaX2xa4,2561
+tg_bot_plugin_contract_core-0.1.1.dist-info/METADATA,sha256=EYvgqAU2379X1J4ole-lB5_RvAUyovOpPaVXpDh1dwY,3293
+tg_bot_plugin_contract_core-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tg_bot_plugin_contract_core-0.1.1.dist-info/RECORD,,

tg_bot_plugin_contract_core-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any