libtea

Python client library for the Transparency Exchange API (TEA) v0.4.0.

TEA is an open standard for discovering and retrieving software transparency artifacts (SBOMs, VEX, build metadata) for any software product or component. A TEI identifier resolves via DNS to the right endpoint, similar to how email uses MX records — so consumers can fetch artifacts without knowing which server hosts them.

Specification:Ecma TC54-TG1 | OpenAPI spec

Status: Alpha — API is subject to change.

Features

Auto-discovery via .well-known/tea and TEI URNs
Flexible version negotiation — connects to older server versions within the same major series
Products, components, releases, and versioned collections
Search by PURL, CPE, or TEI identifier
Pagination auto-iterators for search results
Bulk parallel fetch for products, releases, and artifacts
Common Lifecycle Enumeration (CLE) — ECMA-428 lifecycle events
Artifact download with on-the-fly checksum verification (MD5 through BLAKE2b)
Optional TTL response caching
Endpoint failover with SemVer-compatible version selection
SSRF protection — blocks private IPs, cloud metadata endpoints, DNS rebinding
Bearer token and HTTP basic auth authentication
Bearer token isolation — tokens are never sent to artifact download hosts
TeaClientProtocol for dependency inversion and test doubles
Typed Pydantic v2 models with full camelCase/snake_case conversion
Structured exception hierarchy with error context
CLI with rich-formatted output, JSON mode, and verbose logging
Conformance test suite for validating TEA server compliance (programmatic, CLI, and pytest plugin)
Server-side helpers (tea_datetime_serializer) for TEA API implementations
Unfiltered listing endpoints (list_products, list_product_releases)

Installation

pip install libtea

To include the CLI (tea-cli):

pip install libtea[cli]

To run conformance tests against a TEA server:

pip install libtea[conformance]

Quick start

fromlibteaimportTeaClient# Auto-discover the sbomify TEA server from its .well-known/teawithTeaClient.from_well_known("trust.sbomify.com") asclient:
# Discover a product by TEIresults=client.discover(
"urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"
)
forinfoinresults:
print(info.product_release_uuid, info.servers)
# Get a product releasepr=client.get_product_release(results[0].product_release_uuid)
print(pr.version, pr.product_name)

Or connect directly to a known endpoint:

client=TeaClient(
base_url="https://trust.sbomify.com/tea/v0.4.0",
timeout=30.0,
)

Using from_well_known, you can also override the spec version and timeout:

client=TeaClient.from_well_known(
"trust.sbomify.com",
timeout=15.0,
version="0.4.0", # default
)

Usage

Discovery

fromlibteaimportTeaClient# Discover sbomify products via TEIwithTeaClient.from_well_known("trust.sbomify.com") asclient:
results=client.discover(
"urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"
)
forinfoinresults:
print(info.product_release_uuid, info.servers)

Low-level discovery functions are also available:

fromlibtea.discoveryimportparse_tei, fetch_well_known, select_endpoint# Parse a TEI URNtei_type, domain, identifier=parse_tei(
"urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"
)
# Fetch and select an endpoint manuallywell_known=fetch_well_known("trust.sbomify.com")
endpoint=select_endpoint(well_known, "0.4.0")
print(endpoint.url, endpoint.priority)

Supported TEI types: uuid, purl, hash, swid, eanupc, gtin, asin, udi.

Search

withTeaClient.from_well_known("trust.sbomify.com") asclient:
# Search by PURLresults=client.search_products("PURL", "pkg:github/sbomify/sbomify")
forproductinresults.results:
print(product.name, product.uuid)
# Search product releases (with pagination)releases=client.search_product_releases(
"PURL", "pkg:github/sbomify/sbomify",
page_offset=0, page_size=100,
)
print(releases.total_results)

Listing (unfiltered)

withTeaClient.from_well_known("trust.sbomify.com") asclient:
# List all products (no identifier filter)products=client.list_products(page_size=50)
forproductinproducts.results:
print(product.name, product.uuid)
# List all product releasesreleases=client.list_product_releases(page_size=50)
print(releases.total_results)

Auto-paginated iterators

For iterating over large result sets without manual page management:

withTeaClient.from_well_known("trust.sbomify.com") asclient:
# Iterate all matching products (handles pagination automatically)forproductinclient.iter_products("PURL", "pkg:github/sbomify/sbomify"):
print(product.name)
# Iterate all product releases by identifierforreleaseinclient.iter_product_releases("PURL", "pkg:github/sbomify/sbomify"):
print(release.version)
# Iterate all releases for a specific product UUIDforreleaseinclient.iter_releases_for_product("product-uuid"):
print(release.version, release.created_date)

Bulk parallel fetch

Fetch multiple resources by UUID in parallel:

withTeaClient.from_well_known("trust.sbomify.com") asclient:
products=client.get_products(["uuid-1", "uuid-2", "uuid-3"])
releases=client.get_product_releases_bulk(["uuid-1", "uuid-2"])
artifacts=client.get_artifacts(["uuid-1", "uuid-2"])

Results are returned in the same order as the input UUIDs. Use max_workers=1 for serial execution.

Products and releases

withTeaClient.from_well_known("trust.sbomify.com") asclient:
product=client.get_product("product-uuid")
print(product.name, product.identifiers)
releases=client.get_product_releases("product-uuid", page_size=25)
forreleaseinreleases.results:
print(release.version, release.created_date)
# Single product releasepr=client.get_product_release("release-uuid")
print(pr.version, pr.components)
# Product release collectionslatest=client.get_product_release_collection_latest("release-uuid")
all_versions=client.get_product_release_collections("release-uuid")
specific=client.get_product_release_collection("release-uuid", 3)

Components

withTeaClient.from_well_known("trust.sbomify.com") asclient:
component=client.get_component("component-uuid")
releases=client.get_component_releases("component-uuid")
# Get a component release with its latest collectioncr=client.get_component_release("release-uuid")
print(cr.release.version, len(cr.latest_collection.artifacts))

Collections and artifacts

withTeaClient.from_well_known("trust.sbomify.com") asclient:
collection=client.get_component_release_collection_latest("release-uuid")
forartifactincollection.artifacts:
print(artifact.name, artifact.type)
# All collection versions for a component releaseall_versions=client.get_component_release_collections("release-uuid")
# Specific collection versioncollection_v3=client.get_component_release_collection("release-uuid", 3)

Downloading artifacts with checksum verification

frompathlibimportPathwithTeaClient.from_well_known("trust.sbomify.com") asclient:
artifact=client.get_artifact("artifact-uuid")
fmt=artifact.formats[0]
# Downloads and verifies checksums on-the-fly; returns the dest pathpath=client.download_artifact(
fmt.url,
Path("sbom.json"),
verify_checksums=fmt.checksums,
)

Supported checksum algorithms: MD5, SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384, SHA3-512, BLAKE2b-256, BLAKE2b-384, BLAKE2b-512. BLAKE3 is recognized in the model but not verifiable (Python's hashlib has no BLAKE3 support — a clear error is raised).

Artifact downloads use a separate unauthenticated HTTP session so the bearer token is never leaked to third-party hosts (CDNs, Maven Central, etc.). On checksum mismatch, the downloaded file is automatically deleted.

Common Lifecycle Enumeration (CLE)

withTeaClient.from_well_known("trust.sbomify.com") asclient:
# Get lifecycle events for a product releasecle=client.get_product_release_cle("release-uuid")
foreventincle.events:
print(event.type, event.effective)
# CLE is available for all entity typesclient.get_product_cle("product-uuid")
client.get_component_cle("component-uuid")
client.get_component_release_cle("release-uuid")

Authentication

fromlibteaimportTeaClient# Bearer tokenclient=TeaClient.from_well_known("trust.sbomify.com", token="your-token")
# HTTP basic authclient=TeaClient.from_well_known("trust.sbomify.com", basic_auth=("user", "password"))

Response caching

Enable optional TTL-based caching to avoid repeated API calls:

# Cache GET responses for 5 minutesclient=TeaClient("https://trust.sbomify.com/tea/v0.4.0", cache_ttl=300)
product=client.get_product("uuid") # HTTP callproduct=client.get_product("uuid") # served from cacheclient.clear_cache() # manually invalidate

Only JSON API responses are cached — artifact downloads are never cached.

Private network access

By default, artifact downloads are blocked from private/internal IPs (SSRF protection). For local development:

client=TeaClient.from_well_known(
"trust.local",
scheme="http",
allow_private_ips=True, # allows downloads from 127.0.0.1, 10.x, etc.
)

Scheme validation and cloud metadata endpoint blocking are always enforced.

Testing with TeaClientProtocol

Use the TeaClientProtocol for dependency inversion in consumer code:

fromlibteaimportTeaClientProtocoldeffetch_sbom(client: TeaClientProtocol, product_uuid: str):
"""Accepts any object matching the TeaClient interface."""product=client.get_product(product_uuid)
returnproduct.name

This allows using mock objects in tests without depending on the concrete TeaClient class.

CLI

The tea-cli command provides a terminal interface for all TEA operations. Install with pip install libtea[cli]. See the full CLI reference for detailed documentation.

Global options

These flags can be placed before or after the subcommand name. They appear under each subcommand's --help output.

--json Output raw JSON instead of rich-formatted tables
--verbose, -v Show verbose output (libtea debug logs)
--debug, -d Show debug output (full HTTP firehose including urllib3)
--allow-private-ips Allow artifact downloads from private/internal IPs
--version Show version

All commands also accept connection options: --base-url, --domain, --token, --auth, --use-http, --port.

Discover

# Discover sbomify product releases via TEI
tea-cli discover "urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"# UUIDs only (for scripting)
tea-cli discover -q "urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"# JSON output
tea-cli --json discover "urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"

Inspect (full flow)

# TEI -> discovery -> releases -> components -> artifacts in one shot
tea-cli inspect "urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"# Limit component resolution
tea-cli inspect --max-components 10 "urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"

Search

# Search products by PURL
tea-cli search-products --id-type PURL --id-value "pkg:github/sbomify/sbomify" \
--domain trust.sbomify.com
# Search product releases
tea-cli search-releases --id-type PURL --id-value "pkg:github/sbomify/sbomify" \
--domain trust.sbomify.com --page-size 50

Products and releases

# Get product details
tea-cli get-product <product-uuid> --domain trust.sbomify.com
# List releases for a product
tea-cli get-product-releases <product-uuid> --domain trust.sbomify.com
# Get a specific release (product or component)
tea-cli get-release <release-uuid> --domain trust.sbomify.com
tea-cli get-release <release-uuid> --component --domain trust.sbomify.com

Components

# Get component details
tea-cli get-component <component-uuid> --domain trust.sbomify.com
# List component releases
tea-cli get-component-releases <component-uuid> --domain trust.sbomify.com

Collections and artifacts

# Get latest collection (default) or specific version
tea-cli get-collection <release-uuid> --domain trust.sbomify.com
tea-cli get-collection <release-uuid> --version 3 --domain trust.sbomify.com
# List all collection versions
tea-cli list-collections <release-uuid> --domain trust.sbomify.com
# Get artifact metadata
tea-cli get-artifact <artifact-uuid> --domain trust.sbomify.com

Download

# Download an artifact with checksum verification
tea-cli download "https://cdn.example.com/sbom.json" ./sbom.json \
--checksum "SHA-256:abc123..." \
--domain trust.sbomify.com

Lifecycle (CLE)

# Get lifecycle events for different entity types
tea-cli get-cle <uuid> --entity product-release --domain trust.sbomify.com
tea-cli get-cle <uuid> --entity product --domain trust.sbomify.com
tea-cli get-cle <uuid> --entity component --domain trust.sbomify.com
tea-cli get-cle <uuid> --entity component-release --domain trust.sbomify.com

Conformance

# Run conformance checks against a TEA server
tea-cli conformance --base-url https://tea.example.com/v1
# With TEI for discovery-driven testing
tea-cli conformance --base-url https://tea.example.com/v1 --tei "urn:tei:..."# JSON output for CI pipelines
tea-cli conformance --base-url https://tea.example.com/v1 --json

Environment variables

Variable	Description
`TEA_BASE_URL`	TEA server base URL (alternative to `--base-url`)
`TEA_TOKEN`	Bearer token (alternative to `--token`)
`TEA_AUTH`	Basic auth as `USER:PASSWORD` (alternative to `--auth`)

Shell completion

# Bash (add to ~/.bashrc)eval"$(_TEA_CLI_COMPLETE=bash_source tea-cli)"# Zsh (add to ~/.zshrc)eval"$(_TEA_CLI_COMPLETE=zsh_source tea-cli)"# Fish (add to ~/.config/fish/completions/tea-cli.fish)
_TEA_CLI_COMPLETE=fish_source tea-cli |source

Conformance testing

The conformance suite validates that a TEA server correctly implements the specification. It runs 26 checks covering discovery, products, releases, components, artifacts, CLE, and cross-cutting concerns (UUID format, pagination, camelCase).

Programmatic

fromlibtea.conformanceimportrun_conformanceresult=run_conformance(
"https://tea.example.com/v1",
tei="urn:tei:purl:example.com:pkg:pypi/mylib",
)
print(f"{result.passed} passed, {result.failed} failed, {result.skipped} skipped")

CLI

tea-cli conformance --base-url https://tea.example.com/v1 --tei "urn:tei:..."
tea-cli conformance --base-url https://tea.example.com/v1 --json

pytest plugin

pytest --tea-base-url https://tea.example.com/v1 --tea-tei "urn:tei:..."

The plugin generates one test per conformance check. See the conformance docs for the full check reference.

Server helpers

For TEA server implementations that use libtea models as response schemas:

fromdatetimeimportdatetime, timezonefromlibtea.serverimporttea_datetime_serializer# Serialize to TEA spec format: "2024-03-20T15:30:00Z"tea_datetime_serializer(datetime.now(timezone.utc))

Error handling

All exceptions inherit from TeaError:

fromlibtea.exceptionsimportTeaError, TeaNotFoundError, TeaChecksumErrortry:
product=client.get_product("unknown-uuid")
exceptTeaNotFoundErrorasexc:
print(exc.error_type) # "OBJECT_UNKNOWN" or "OBJECT_NOT_SHAREABLE"exceptTeaError:
print("Something went wrong")

Exception hierarchy:

Exception	When
`TeaConnectionError`	Network failure or timeout
`TeaAuthenticationError`	HTTP 401/403
`TeaNotFoundError`	HTTP 404 (`.error_type` has the TEA error code)
`TeaRequestError`	Other HTTP 4xx
`TeaServerError`	HTTP 5xx
`TeaDiscoveryError`	Invalid TEI, `.well-known` failure, or no compatible endpoint
`TeaChecksumError`	Checksum mismatch (`.algorithm`, `.expected`, `.actual`)
`TeaValidationError`	Malformed server response
`TeaInsecureTransportWarning`	Warning emitted when using plaintext HTTP

Using a bearer token over plaintext HTTP raises ValueError immediately — HTTPS is required for authenticated requests.

Requirements

Python >= 3.11
requests >= 2.32.4 for HTTP
Pydantic >= 2.1.0 for data models
semver >= 3.0.4 for version selection

Optional:

CLI: click >= 8.0, rich >= 13.0.0
Conformance: pytest >= 8.0.0

Not yet supported

Publisher API (spec is consumer-only in v0.4.0)
Async client

Development

This project uses uv for dependency management.

uv sync # Install dependencies
uv run pytest # Run tests (with coverage)
uv run ruff check .# Lint
uv run ruff format --check .# Format check
uv build # Build wheel and sdist

License

Apache 2.0 — see LICENSE for details.

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
src/libtea		src/libtea
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
libtea.cdx.json		libtea.cdx.json
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

libtea

Features

Installation

Quick start

Usage

Discovery

Search

Listing (unfiltered)

Auto-paginated iterators

Bulk parallel fetch

Products and releases

Components

Collections and artifacts

Downloading artifacts with checksum verification

Common Lifecycle Enumeration (CLE)

Authentication

Response caching

Private network access

Testing with TeaClientProtocol

CLI

Global options

Discover

Inspect (full flow)

Search

Products and releases

Components

Collections and artifacts

Download

Lifecycle (CLE)

Conformance

Environment variables

Shell completion

Conformance testing

Programmatic

CLI

pytest plugin

Server helpers

Error handling

Requirements

Not yet supported

Development

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages