Metadata-Version: 2.4
Name: swarmauri_signing_pep458
Version: 0.11.0.dev1
Summary: PEP 458 compatible detached signing provider for Swarmauri
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: supply-chain,tuf,pep458,signing,swarmauri,sdk,standards,cryptography,metadata-signing,repository-metadata,detached-signature,signature-format,supply-chain-security
Author: Jacob Stewart
Author-email: jacob@swarmauri.com
Requires-Python: >=3.10,<3.15
Classifier: Development Status :: 1 - Planning
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Topic :: Security :: Cryptography
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Requires-Dist: cryptography (>=41.0.0)
Requires-Dist: swarmauri_base
Requires-Dist: swarmauri_core
Project-URL: Documentation, https://github.com/swarmauri/swarmauri-sdk/tree/main/pkgs/standards/swarmauri_signing_pep458#readme
Project-URL: Homepage, https://github.com/swarmauri/swarmauri-sdk
Project-URL: Source, https://github.com/swarmauri/swarmauri-sdk/tree/main/pkgs/standards/swarmauri_signing_pep458
Description-Content-Type: text/markdown

![Swarmauri Logo](https://raw.githubusercontent.com/swarmauri/swarmauri-sdk/master/assets/swarmauri_sdk_brand.png)

<p align="center">
    <a href="https://pepy.tech/project/swarmauri_signing_pep458/">
        <img src="https://static.pepy.tech/badge/swarmauri_signing_pep458/month" alt="PyPI - Downloads"/></a>
    <a href="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/standards/swarmauri_signing_pep458/">
        <img alt="Hits" src="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/standards/swarmauri_signing_pep458.svg"/></a>
    <a href="https://pypi.org/project/swarmauri_signing_pep458/">
        <img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue" alt="PyPI - Python Version"/></a>
    <a href="https://pypi.org/project/swarmauri_signing_pep458/">
        <img src="https://img.shields.io/pypi/l/swarmauri_signing_pep458" alt="PyPI - License"/></a>
    <a href="https://pypi.org/project/swarmauri_signing_pep458/">
        <img src="https://img.shields.io/pypi/v/swarmauri_signing_pep458?label=swarmauri_signing_pep458&color=green" alt="PyPI - swarmauri_signing_pep458"/></a>
    <a href="https://discord.gg/N4UpBuQv8T">
        <img src="https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white" alt="Discord"/></a></p>

# swarmauri_signing_pep458

`swarmauri_signing_pep458` packages a detached signature provider that implements
[PEP 458](https://peps.python.org/pep-0458/) style signing for The Update Framework
(TUF) metadata. It brings canonical JSON, multi-algorithm support, and quorum-aware
verification to the Swarmauri runtime so supply-chain aware components can produce
and validate repository metadata with a uniform API.

## Key Features

- **PEP 458 compatible format** ? Signatures emit the `tuf/pep458` envelope with
  `method`, `keyid`, and base64-encoded payloads so the metadata aligns with the
  specification's detached signature requirements.
- **Deterministic canonicalization** ? Canonicalizes envelopes using TUF's
  lexicographically-sorted JSON encoding to guarantee byte-for-byte reproducibility.
- **Multiple signature algorithms** ? Supports Ed25519 for online roles and
  RSA-PSS-SHA256 for offline root-style metadata, allowing you to mix schemes per
  role.
- **Quorum aware verification** ? Enforces `min_signers`, explicit key-id allow
  lists, and algorithm restrictions during verification to help model offline
  threshold signing policies.
- **Flexible key inputs** ? Accepts cryptography key objects, PEM encoded key
  material, or Swarmauri `KeyRef` dictionaries for both signing and verification.

## Installation

### Using `uv`

```bash
uv add swarmauri_signing_pep458
```

### Using `pip`

```bash
pip install swarmauri_signing_pep458
```

## Quick Start

```python
import asyncio
from cryptography.hazmat.primitives.asymmetric import ed25519
from swarmauri_signing_pep458 import Pep458Signer

async def main() -> None:
    signer = Pep458Signer()
    private = ed25519.Ed25519PrivateKey.generate()
    keyref = {"kind": "cryptography_obj", "obj": private, "alg": "Ed25519"}

    payload = b"release metadata"
    signatures = await signer.sign_bytes(keyref, payload)

    is_valid = await signer.verify_bytes(
        payload,
        signatures,
        opts={"pubkeys": [private.public_key()]},
    )
    print(f"Signature valid? {is_valid}")

asyncio.run(main())
```

## Signature Format

Each signature returned by the signer follows this shape:

```json
{
  "format": "tuf/pep458",
  "method": "ed25519",
  "alg": "Ed25519",
  "keyid": "base64(SHA256(method || SPKI))",
  "sig": "base64(signature-bytes)"
}
```

Use the `method` label when matching public keys and verifying thresholds for a
particular TUF role.

## Verification Policy Hints

The `verify_bytes` and `verify_envelope` APIs accept a `require` mapping with the
following helpful keys:

- `min_signers`: Require at least _n_ distinct key ids to validate.
- `algs`: Restrict verification to a subset of algorithms, e.g. `("Ed25519",)`. The
  values are normalized case-insensitively.
- `kids`: Whitelist key identifiers allowed to satisfy the policy.
- `pubkeys`: Explicit public key materials to use when verifying (PEM strings,
  cryptography objects, or `{"kind": "pem", "pub": ...}` dictionaries).

## Relationship to the Cipher Suite

Pair this package with `swarmauri_cipher_suite_pep458` to describe repository role
policies, canonicalization settings, and default algorithm choices across the
Swarmauri ecosystem.

## Development

- Format the code with `ruff format .` and lint with `ruff check . --fix`.
- Run the asynchronous unit tests with `pytest` once cryptography dependencies are
  available.
- Contributions should include updates to documentation fragments and policy tables
  when new capabilities are added.

## License

This project is licensed under the [Apache License 2.0](LICENSE).



