Metadata-Version: 2.4
Name: provbind
Version: 0.2.0
Summary: Bind AI and research artifacts to exact source bytes with verifiable provenance manifests.
Author: ProvBind contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/yunying24/provbind
Project-URL: Repository, https://github.com/yunying24/provbind
Project-URL: Issues, https://github.com/yunying24/provbind/issues
Keywords: ai,agents,provenance,verification,research,integrity,sha256
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# ProvBind

[![PyPI](https://img.shields.io/pypi/v/provbind)](https://pypi.org/project/provbind/)
[![Python](https://img.shields.io/pypi/pyversions/provbind)](https://pypi.org/project/provbind/)
[![CI](https://github.com/yunying24/provbind/actions/workflows/ci.yml/badge.svg)](https://github.com/yunying24/provbind/actions/workflows/ci.yml)
[![CodeQL](https://github.com/yunying24/provbind/actions/workflows/codeql.yml/badge.svg)](https://github.com/yunying24/provbind/actions/workflows/codeql.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Bind AI and research artifacts to the exact source bytes that produced them.**

ProvBind is a small, local-first provenance verifier for AI agents, research pipelines, coding agents, and automated reports. It creates a closed JSON manifest that binds an artifact to one or more source files using SHA-256 digests and an independently recomputable `binding_id`.

```bash
pip install provbind
```

> Version **0.2.0** is prepared as the current source release for 2026-08-08. PyPI may briefly continue to show 0.1.0 until the tagged Trusted Publishing workflow completes.

If an agent says “this output was based on these sources,” ProvBind turns that claim into something another process can verify later.

> ProvBind proves byte identity and binding. It does **not** prove that a source is true, that an agent reasoned correctly, that a person authored a file, or that a timestamp is externally trusted.

## 30-second demo

Create one source and one derived artifact:

```bash
printf 'source bytes\n' > source.txt
printf 'derived output\n' > report.md
```

Seal the exact bytes and verify them:

```bash
provbind seal report.md --source source.txt -o provbind.json
provbind verify provbind.json
```

Expected result:

```text
PASS artifact:report.md — artifact bytes match
PASS local_file:source.txt — source bytes match
VERIFIED
```

Now change the artifact:

```bash
printf '\ntampered\n' >> report.md
provbind verify provbind.json
```

ProvBind fails closed with `NOT VERIFIED` and exit code `2`.

## Use it after Codex or another agent

The agent produces the artifact; ProvBind independently binds the result to the inputs that actually exist afterward:

```text
Codex / another agent
        │
        │ produces artifact
        ▼
  exact artifact bytes ─────┐
                            │
  exact source bytes ───────┼──> ProvBind manifest
                            │
                            ▼
                      independent verify
```

A complete Codex example is in [`examples/codex`](examples/codex), including:

- a constrained prompt;
- a credential-free checked-in provenance fixture;
- a workflow using the official `openai/codex-action@v1` interface;
- a CI-enforced intentional tamper failure.

The core verifier has no model-vendor dependency. The same `seal` and `verify` flow works for outputs produced by people, scripts, Codex, or other agents.

## Why

Agent workflows increasingly read files, Git repositories, documents, and research inputs before producing code or reports. A normal output file does not preserve enough evidence to answer basic questions later:

- Was this the exact source file the agent used?
- Did a GitHub source come from a fixed commit, or from a branch that later moved?
- Did the source change after the output was produced?
- Did someone edit the provenance record itself?
- Can CI fail closed when the evidence shape is unknown?

ProvBind turns those questions into deterministic checks.

## Exact GitHub sources

GitHub sources must use an **exact 40-hex commit SHA**. Branches, tags, and abbreviated SHAs are rejected.

```bash
provbind seal report.md \
  --github-source openai/openai-python@0123456789abcdef0123456789abcdef01234567:README.md \
  -o provbind.json
```

For private repositories, set `GITHUB_TOKEN` in the environment.

In v0.2, a v2 GitHub source records and verifies both portable byte identity and Git-native repository membership:

- exact commit SHA;
- root tree SHA;
- path resolved through tree objects;
- final Git blob SHA and regular-file mode;
- Git blob SHA-1 recomputed from the returned blob bytes;
- SHA-256 and byte size over those same bytes.

The release-gate fixture in [`examples/github-v2`](examples/github-v2) exercises this path against the real public GitHub API using the immutable v0.1.0 release commit, and CI requires the independently observed blob identity to match before verification succeeds.

This is intentional:

```text
main              -> rejected
v1.2.3            -> rejected
abc1234           -> rejected
40-hex commit SHA -> accepted
```

A provenance record should bind immutable source identity, not a mutable name.

## Commands

### `provbind seal`

Create a new manifest. In v0.2, v2 is the default; use `--schema v1` only when you explicitly need the frozen legacy output shape.

```bash
provbind seal ARTIFACT \
  --source LOCAL_SOURCE \
  --github-source OWNER/REPO@COMMIT:PATH \
  --root . \
  -o provbind.json

provbind seal ARTIFACT --source LOCAL_SOURCE --schema v1 -o provbind-v1.json
```

Both `--source` and `--github-source` are repeatable. At least one source is required.

### `provbind verify`

Recompute artifact and source evidence and compare it with the sealed claims. Verification is schema-driven, so existing v1 manifests remain supported while v2 GitHub sources use the stronger Git object chain.

```bash
provbind verify provbind.json --root .
provbind verify provbind.json --root . --json
```

Exit codes:

- `0`: verified
- `2`: invalid manifest, unavailable evidence, repository-membership mismatch, or byte mismatch

### `provbind inspect`

Inspect a manifest without fetching or re-reading its sources.

```bash
provbind inspect provbind.json
```

For v2 GitHub sources, inspection includes the sealed tree SHA, blob SHA, and Git file mode.

### `provbind diff`

Compare two valid manifests.

```bash
provbind diff old.json new.json
```

The diff reports artifact changes and source additions, removals, or changes.

## Manifest model

ProvBind supports two closed schema versions:

- `provbind-manifest-v1` — frozen v0.1 byte-binding contract;
- `provbind-manifest-v2` — v0.2 contract with Git-native identity for GitHub sources.

A v1 manifest looks like this:

```json
{
  "schema_version": "provbind-manifest-v1",
  "binding_id": "...",
  "created_at": "2026-08-08T01:00:00Z",
  "artifact": {
    "path": "report.md",
    "sha256": "...",
    "size": 15
  },
  "sources": [
    {
      "kind": "local_file",
      "path": "source.txt",
      "sha256": "...",
      "size": 13
    }
  ],
  "producer": "provbind/0.1.0"
}
```

A v2 `github_file` source additionally seals `git_tree_sha`, `git_blob_sha`, and `git_mode` alongside the exact commit/path and SHA-256/size.

`binding_id` is the SHA-256 of ProvBind's canonical JSON encoding of:

```text
schema_version + artifact claim + ordered source claims
```

`created_at` is intentionally excluded from `binding_id`, so the same artifact/source claim has the same binding identity even if the manifest is regenerated at a different time.

The schemas are published at [`schemas/provbind-manifest-v1.schema.json`](schemas/provbind-manifest-v1.schema.json) and [`schemas/provbind-manifest-v2.schema.json`](schemas/provbind-manifest-v2.schema.json). Runtime validation is implemented without third-party dependencies and is stricter than simply parsing JSON.

## Fail-closed design

ProvBind intentionally accepts a small closed evidence model:

- `local_file`
- `github_file`

Unknown top-level fields are rejected. Unknown fields inside artifact/source objects are rejected. Unknown source kinds are rejected. Duplicate source identities are rejected. Parent-directory traversal in local paths is rejected. GitHub mutable refs are rejected. In v2, symlink/submodule/tree final objects are also rejected until they have an explicit reviewed contract.

New source types should be introduced through a new reviewed schema/version rather than silently accepted by old verifiers.

## GitHub Actions

The v0.2.0 composite Action is addressed by its release tag:

```yaml
- uses: yunying24/provbind@v0.2.0
  with:
    manifest: provbind.json
    root: .
```

The existing `v0.1.0` tag remains available for workflows intentionally pinned to the v0.1 implementation.

The action installs ProvBind from the checked-out action source and runs verification. A failing binding fails the workflow.

You can also install the CLI directly in any CI system:

```yaml
- run: pip install provbind
- run: provbind verify provbind.json --root .
```

## Threat model

ProvBind is designed to detect:

- source bytes changing after a manifest was created;
- artifact bytes changing after a manifest was created;
- provenance claim edits that are not accompanied by a recomputed binding;
- use of mutable GitHub refs in a byte-binding claim;
- malformed or unexpectedly widened manifest shapes;
- in v2, mismatch between exact commit/tree/path/blob membership and the sealed GitHub claim.

ProvBind does not currently defend against an attacker who can replace the artifact, every source, and the manifest together. That requires an external trust anchor such as a signed release, transparency log, trusted CI attestation, or another independent publication channel. Those are roadmap items, not current claims.

## Design principles

1. **Exact bytes over labels.** A source name is not evidence of source identity.
2. **Immutable refs over mutable refs.** GitHub bindings use exact commit SHAs.
3. **Closed schemas over permissive parsing.** Unknown evidence shapes fail closed.
4. **Separate verification from correctness.** Matching bytes do not make content true.
5. **Local-first verification.** Local-file verification requires no service or account.
6. **Small trusted core.** ProvBind has zero runtime Python dependencies.

## Use cases

- bind an AI-generated research memo to its input corpus;
- bind a coding-agent patch/report to exact repository files;
- preserve source identity for automated market or technical reports;
- fail CI when evidence or generated outputs drift;
- attach a portable provenance manifest to releases or audit artifacts.

## Examples

- [`examples/basic`](examples/basic) — minimal local-file example.
- [`examples/codex`](examples/codex) — agent generation + independent provenance verification.
- [`examples/github-v2`](examples/github-v2) — real public exact-commit Git tree/blob membership verification.

```bash
provbind verify examples/basic/provbind.json --root examples/basic
provbind verify examples/codex/provbind.json --root examples/codex
```

## Project status

ProvBind is **alpha**. Version `0.2.0` is prepared as the current source release after completing the v2 Git identity gate: 72 compatibility/adversarial tests, package smoke testing, the Codex positive/tamper contract, a real public exact-commit GitHub v2 fixture, and CodeQL. PyPI may briefly lag at 0.1.0 until release publication completes.

See [`ROADMAP.md`](ROADMAP.md) for planned work, including signed attestations, HTTP content-addressed sources, reusable policy profiles, and integrations for coding/research agents.

## Contributing

Issues, test cases, source adapters, security review, and integration examples are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md).

## Security

Please report security-sensitive findings privately as described in [`SECURITY.md`](SECURITY.md).

## License

MIT. See [`LICENSE`](LICENSE).
