Skip to main content

ATP DID primitives for Python (experimental)

Offline Python counterpart of @atpdeveloper/did-atp. The distribution name is atp-did; check PyPI for release availability. This module is experimental. Python 3.9+ for base primitives; no base runtime dependencies. Optional signing is experimental and currently exercised on Linux/Python 3.12. This is not the full Python identity SDK.

From the repository root:

python -m pip install ./packages/did-atp-python
from atp_did import build_atp_v2_did, parse_atp_v2_path_did, verify_atp_v2_key_bindings

# Format demonstration only. Supply real public keys in an application.
ed, pq = bytes(32), bytes(1952)
did = build_atp_v2_did('example.com', ['agents', 'demo'], ed, pq)
assert parse_atp_v2_path_did(did).path == ('agents', 'demo')
assert verify_atp_v2_key_bindings(did, ed, pq)

The public functions use snake_case equivalents of the TypeScript primitives: atp_base64_url, atp_jwk_thumbprint, atp_e1_fingerprint, atp_pq1_fingerprint, build_atp_v2_did, parse_atp_v2_path_did, is_atp_v2_path_did, and verify_atp_v2_key_bindings. Parsed results are immutable dataclasses, with a tuple path. Parse errors carry invalid_format, invalid_domain, invalid_path or invalid_bindings in code. Builders reject malformed inputs; binding checks throw on malformed DIDs/keys and return false on a valid identifier with mismatching keys. JWK thumbprints select required public members and ignore optional/private members.

A matching fingerprint does not prove key possession, cryptographic signature validity, trust, current status or authorization. The base module has no key generation or signing. There is no network resolver, keystore, mandate verifier, sandbox or host adapter. The optional crypto module below adds key generation and signing. No W3C certification or full SDK parity is claimed. Community Group drafts and implementation releases have separate lifecycles.

Tests reuse the existing canonical vectors and shared malformed-identifier cases:

PYTHONPATH=packages/did-atp-python/src python -m unittest discover -s packages/did-atp-python/tests
npm ci --prefix packages/did-atp
npm test --prefix packages/did-atp

Optional signing (experimental)

python -m pip install './packages/did-atp-python[crypto]'
from atp_did import build_atp_v2_did
from atp_did.crypto import generate_hybrid_key_pair, sign_hybrid, verify_hybrid

keys = generate_hybrid_key_pair()
did = build_atp_v2_did('example.com', ['agents', 'demo'],
                       keys.public_keys.ed25519, keys.public_keys.ml_dsa65)
message = b'example challenge bytes'
signature = sign_hybrid(message, keys)
assert verify_hybrid(message, signature, keys.public_keys)
assert not verify_hybrid(message + b'!', signature, keys.public_keys)

sign_ed25519 / verify_ed25519 and sign_ml_dsa65 / verify_ml_dsa65 use raw key/signature bytes. Strings are encoded as UTF-8 without normalization; objects are not implicitly JSON-serialized. Signing rejects bad key sizes; verification returns false for malformed inputs or invalid signatures. verify_hybrid requires BOTH signatures over identical bytes. Its dataclass is a local helper, not a new interoperable ATP proof-envelope specification. The SDK's individual algorithm methods are the interoperability reference.

Backends: cryptography (Ed25519) and pinned pqcrypto 0.3.4 (PQClean ML-DSA-65). The latter is pinned because its tested API differs from pqcrypto 1.x. This is pure ML-DSA with an empty FIPS 204 context, not a prehashed variant. Public keys are 32/1952 bytes; signatures are 64/3309 bytes. No custom signature algorithm is implemented. Backend error conditions are not a reason to downgrade.

Key generation uses backend cryptographic randomness. Secret fields are omitted from repr, but raw keys remain in process memory: there is no secure keystore, encrypted export, guaranteed zeroization or key rotation in this milestone. Never log or persist the KeyPair. Callers must bind messages to their own challenge, audience, action, nonce and expiry and enforce replay protection; a valid signature alone grants no authority. No blanket adversarial equivalence between Ed25519 backends or security certification is claimed.

The optional suite checks both directions against published atp-sdk@6.0.2, using ephemeral random keys and public signatures only (no secret fixture files). CI installs that version in an isolated temporary directory and sets ATP_SDK_MODULE to its module URL, then runs with ATP_TEST_CRYPTO=1. The base matrix still runs without optional dependencies. Broader crypto platform/Python support must be verified before promotion or publication.

Local encrypted key file and onboarding example

From the repository root, install the optional extra and run:

python -m pip install './packages/did-atp-python[crypto]'
python packages/did-atp-python/examples/local_identity.py ./my-agent.keys.json --domain example.com --agent demo

The example prompts for a passphrase (at least 16 characters), generates fresh Ed25519 and ML-DSA-65 keys, creates an encrypted file with exclusive creation and mode 0600, reloads it, builds the DID from its public keys and checks a local signature round trip. It refuses to overwrite an existing file. Keep the passphrase in a separate password manager; losing it loses access to the keys. The example uses example.com as a format placeholder and does not register or publish a DID, establish domain control, prove third-party trust, or grant permission. Never commit the key file or use the demo challenge for a real request.

atp_did.keyfile.save_key_file(path, key_pair, passphrase) and load_key_file(path, passphrase) use scrypt (N=131072, r=8, p=1) and AES-256-GCM with random salt and nonce and a versioned authenticated envelope. Reading rejects symlinks on supported Unix systems, group/world-accessible files, oversized files, bad passphrases, tampering and mismatched key pairs. This is application-level encryption, not OS keychain or HSM protection: passphrases and raw secrets are present in process memory without guaranteed zeroization, and host compromise can expose them. There is no key rotation, recovery, migration, or cross-device synchronization. Use a managed keystore for production deployments and design scoped challenge and replay checks before using signatures for actions.

Metadata

Release files for atp-did 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for atp-did 0.1.0
File Size Uploaded Provenance Actions
atp_did-0.1.0.tar.gz 12.9 kB With provenance Details for atp_did-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for atp-did 0.1.0
File Interpreter ABI Platform Actions
atp_did-0.1.0-py3-none-any.whl Python 3 none any Details for atp_did-0.1.0-py3-none-any.whl

Total release size: 25.9 kB

Release files / atp_did-0.1.0.tar.gz

Download URL atp_did-0.1.0.tar.gz
Size 12.9 kB
Tags Source
SHA-256 checksum
How to use checksums
752f5d64e6fc8469020605fc0bf99261f32d7f2ce03cdbec91ae3c24b7702736
BLAKE2b-256 checksum
How to use checksums
1d4df8cfc0ac2ef463607752994b3c08ee55d81f2a1de8ba066f0de91846aa1b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / atp_did-0.1.0-py3-none-any.whl

Download URL atp_did-0.1.0-py3-none-any.whl
Size 13.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4629d7568521102d0cfafc0605778c670c61cb819634b743c27373ec399df431
BLAKE2b-256 checksum
How to use checksums
592b096d6664e0d684ec0e654d5970ff40cd7e6d04360985852bdbcda0c0e1ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for atp-did 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for atp_did-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page