# sigstore/model-transparency architecture

> Architecture diagram of the GitHub repository sigstore/model-transparency, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sigstore/model-transparency
- Repository: https://github.com/sigstore/model-transparency

## Overview

Model Transparency is a Python library and CLI for producing and verifying model-integrity signatures. The main workflow hashes model files (or shards) into a manifest, encodes that manifest as a signed payload, and writes a Sigstore bundle; verification checks the signature and recomputes hashes. The README also documents key, certificate, PKCS#11, timestamp-authority, and private Sigstore trust-config options. Edges reflect README statements and source-index references; some lower-level dispatch details were not excerpted, so uncertain wiring is omitted.

Main entry points: [`src/model_signing/signing.py`](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/signing.py) (Signing config), [`src/model_signing/verifying.py`](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/verifying.py) (Verification config), [`src/model_signing/hashing.py`](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/hashing.py) (Hash config), [`src/model_signing/_signing/sign_ec_key.py`](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_ec_key.py) (EC key signer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interface"]
  node_cli["CLI commands<br/>[_cli.py]"]
  node_api["Public API<br/>[__init__.py]"]
end

subgraph group_hash["Hashing and Manifest"]
  node_hash_api["Hash config<br/>[hashing.py]"]
  node_file_ser["File serializer<br/>[file.py]"]
  node_shard_ser["Shard serializer<br/>[file_shard.py]"]
  node_file_hash["File hashing<br/>[io.py]"]
  node_hash_engines["Hash engines<br/>[hashing.py]"]
  node_memory_hash["Memory digests<br/>[memory.py]"]
  node_manifest["Model manifest<br/>[manifest.py]"]
end

subgraph group_sign["Signing and Formats"]
  node_sign_api["Signing config<br/>[signing.py]"]
  node_payload["DSSE payload<br/>[signing.py]"]
  node_sigstore_signer["Sigstore signer<br/>[sign_sigstore.py]"]
  node_key_signer["EC key signer<br/>[sign_ec_key.py]"]
  node_cert_signer["Certificate signer"]
  node_pkcs11_signer["PKCS11 signer<br/>[sign_pkcs11.py]"]
  node_bundle["Bundle and timestamps"]
end

subgraph group_verify["Verification"]
  node_verifier["Verification config<br/>[verifying.py]"]
  node_sigstore_verifier["Sigstore verifier<br/>[sign_sigstore.py]"]
  node_key_verifier["EC key verifier<br/>[sign_ec_key.py]"]
  node_cert_verifier["Certificate verifier"]
end

node_user(("Model user"))
node_model_files["Model files"]
node_signature_file["Signature bundle"]
node_sigstore_services{{"Sigstore services"}}
node_tsa{{"Timestamp authority"}}

node_user -->|"invokes"| node_cli
node_user -->|"calls"| node_api
node_cli -->|"dispatches"| node_api
node_api -->|"configures"| node_sign_api
node_model_files -->|"hashes"| node_hash_api
node_hash_api -->|"selects"| node_file_ser
node_hash_api -->|"selects"| node_shard_ser
node_file_ser -->|"uses"| node_file_hash
node_shard_ser -->|"uses"| node_file_hash
node_file_hash -->|"computes with"| node_hash_engines
node_file_ser -->|"builds items"| node_manifest
node_shard_ser -->|"builds items"| node_manifest
node_sign_api -->|"hashes model"| node_hash_api
node_sign_api -->|"creates payload"| node_payload
node_payload -->|"encodes"| node_manifest
node_sign_api -->|"dispatches to"| node_sigstore_signer
node_sign_api -->|"dispatches to"| node_key_signer
node_sign_api -->|"dispatches to"| node_cert_signer
node_sign_api -->|"dispatches to"| node_pkcs11_signer
node_sigstore_signer -.->|"signs with"| node_sigstore_services
node_key_signer -->|"uses"| node_bundle
node_cert_signer -->|"reuses"| node_key_signer
node_key_signer -->|"requests timestamp"| node_tsa
node_sign_api -->|"writes"| node_signature_file
node_user -->|"requests verification"| node_verifier
node_signature_file -->|"reads"| node_verifier
node_verifier -->|"recomputes hashes"| node_hash_api
node_verifier -->|"compares manifest"| node_manifest
node_verifier -->|"dispatches to"| node_sigstore_verifier
node_verifier -->|"dispatches to"| node_key_verifier
node_verifier -->|"dispatches to"| node_cert_verifier
node_sigstore_verifier -.->|"checks transparency"| node_sigstore_services
node_key_verifier -->|"checks timestamp"| node_bundle
node_cert_verifier -->|"checks timestamp"| node_bundle

click node_cli "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_cli.py"
click node_api "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/__init__.py"
click node_sign_api "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/signing.py"
click node_hash_api "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/hashing.py"
click node_file_ser "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_serialization/file.py"
click node_shard_ser "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_serialization/file_shard.py"
click node_file_hash "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_hashing/io.py"
click node_hash_engines "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_hashing/hashing.py"
click node_memory_hash "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_hashing/memory.py"
click node_manifest "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/manifest.py"
click node_payload "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/signing.py"
click node_sigstore_signer "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_sigstore.py"
click node_key_signer "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_ec_key.py"
click node_cert_signer "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_certificate.py"
click node_pkcs11_signer "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_pkcs11.py"
click node_bundle "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_sigstore_pb.py"
click node_verifier "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/verifying.py"
click node_sigstore_verifier "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_sigstore.py"
click node_key_verifier "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_ec_key.py"
click node_cert_verifier "https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_certificate.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_api,node_user toneBlue
class node_hash_api,node_file_ser,node_shard_ser,node_file_hash,node_hash_engines,node_memory_hash,node_manifest toneAmber
class node_sign_api,node_payload,node_sigstore_signer,node_key_signer,node_cert_signer,node_pkcs11_signer,node_bundle toneMint
class node_verifier,node_sigstore_verifier,node_key_verifier,node_cert_verifier toneRose
class node_model_files,node_signature_file,node_sigstore_services,node_tsa toneIndigo
```

## Components

### User Interface

- [CLI commands](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_cli.py): `src/model_signing/_cli.py`
- [Public API](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/__init__.py): `src/model_signing/__init__.py`

### Hashing and Manifest

- [Hash config](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/hashing.py): `src/model_signing/hashing.py`
- [File serializer](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_serialization/file.py): `src/model_signing/_serialization/file.py`
- [Shard serializer](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_serialization/file_shard.py): `src/model_signing/_serialization/file_shard.py`
- [File hashing](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_hashing/io.py): `src/model_signing/_hashing/io.py`
- [Hash engines](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_hashing/hashing.py): `src/model_signing/_hashing/hashing.py`
- [Memory digests](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_hashing/memory.py): `src/model_signing/_hashing/memory.py`
- [Model manifest](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/manifest.py): `src/model_signing/manifest.py`

### Signing and Formats

- [Signing config](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/signing.py): `src/model_signing/signing.py`
- [DSSE payload](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/signing.py): `src/model_signing/_signing/signing.py`
- [Sigstore signer](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_sigstore.py): `src/model_signing/_signing/sign_sigstore.py`
- [EC key signer](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_ec_key.py): `src/model_signing/_signing/sign_ec_key.py`
- [Certificate signer](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_certificate.py): `src/model_signing/_signing/sign_certificate.py`
- [PKCS11 signer](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_pkcs11.py): `src/model_signing/_signing/sign_pkcs11.py`
- [Bundle and timestamps](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_sigstore_pb.py): `src/model_signing/_signing/sign_sigstore_pb.py`

### Verification

- [Verification config](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/verifying.py): `src/model_signing/verifying.py`
- [Sigstore verifier](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_sigstore.py): `src/model_signing/_signing/sign_sigstore.py`
- [EC key verifier](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_ec_key.py): `src/model_signing/_signing/sign_ec_key.py`
- [Certificate verifier](https://github.com/sigstore/model-transparency/blob/main/src/model_signing/_signing/sign_certificate.py): `src/model_signing/_signing/sign_certificate.py`

### Other components

- **Model user**
- **Model files**
- **Signature bundle**
- **Sigstore services**
- **Timestamp authority**

## Connections

- Model user → CLI commands: invokes (evidence: `README.md`)
- Model user → Public API: calls (evidence: `README.md`)
- CLI commands → Public API: dispatches (evidence: `src/model_signing/_cli.py`)
- Public API → Signing config: configures (evidence: `src/model_signing/__init__.py`)
- Model files → Hash config: hashes (evidence: `README.md`)
- Hash config → File serializer: selects (evidence: `src/model_signing/hashing.py`)
- Hash config → Shard serializer: selects (evidence: `src/model_signing/hashing.py`)
- File serializer → File hashing: uses (evidence: `src/model_signing/_serialization/file.py`)
- Shard serializer → File hashing: uses (evidence: `src/model_signing/_serialization/file_shard.py`)
- File hashing → Hash engines: computes with (evidence: `src/model_signing/_hashing/io.py`)
- File serializer → Model manifest: builds items (evidence: `src/model_signing/_serialization/file.py`)
- Shard serializer → Model manifest: builds items (evidence: `src/model_signing/_serialization/file_shard.py`)
- Signing config → Hash config: hashes model (evidence: `src/model_signing/signing.py`)
- Signing config → DSSE payload: creates payload (evidence: `src/model_signing/signing.py`)
- DSSE payload → Model manifest: encodes (evidence: `src/model_signing/_signing/signing.py`)
- Signing config → Sigstore signer: dispatches to (evidence: `src/model_signing/signing.py`)
- Signing config → EC key signer: dispatches to (evidence: `src/model_signing/signing.py`)
- Signing config → Certificate signer: dispatches to (evidence: `src/model_signing/signing.py`)
- Signing config → PKCS11 signer: dispatches to (evidence: `src/model_signing/signing.py`)
- Sigstore signer → Sigstore services: signs with (evidence: `README.md`)
- EC key signer → Bundle and timestamps: uses (evidence: `src/model_signing/_signing/sign_ec_key.py`)
- Certificate signer → EC key signer: reuses (evidence: `src/model_signing/_signing/sign_certificate.py`)
- EC key signer → Timestamp authority: requests timestamp
- Signing config → Signature bundle: writes (evidence: `README.md`)
- Model user → Verification config: requests verification (evidence: `README.md`)
- Signature bundle → Verification config: reads (evidence: `README.md`)
- Verification config → Hash config: recomputes hashes (evidence: `README.md`)
- Verification config → Model manifest: compares manifest (evidence: `src/model_signing/verifying.py`)
- Verification config → Sigstore verifier: dispatches to (evidence: `src/model_signing/verifying.py`)
- Verification config → EC key verifier: dispatches to (evidence: `src/model_signing/verifying.py`)
- Verification config → Certificate verifier: dispatches to (evidence: `src/model_signing/verifying.py`)
- Sigstore verifier → Sigstore services: checks transparency (evidence: `README.md`)
- EC key verifier → Bundle and timestamps: checks timestamp (evidence: `src/model_signing/_signing/sign_ec_key.py`)
- Certificate verifier → Bundle and timestamps: checks timestamp (evidence: `src/model_signing/_signing/sign_certificate.py`)