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` 仅用于受控的本地开发链路。
