Diogenes Developer SDK Reference¶

The Diogenes Developer SDK provides a high-level Python API for document signing, verification, trust evaluation, and webhook management. It wraps the core Diogenes modules behind a clean facade so you can integrate cryptographic provenance into your application with minimal boilerplate.

Installation¶

Install from the repository with development dependencies:

pip install -e ".[dev]"

Or install just the core package:

pip install -e .

The SDK is included in the diogenes package at diogenes.sdk.

Quickstart¶

from diogenes.sdk import DiogenesSDK, generate_key_pair, compute_fingerprint
from diogenes.core.transparency_log import TransparencyLogService
from diogenes.core.schemas import EventType
from diogenes.core.keys import _serialize_public_key, compute_fingerprint as core_fp

# 1. Set up a transparency log
log = TransparencyLogService()

# 2. Generate and register a key pair
private_key, public_key = generate_key_pair("ed25519")
fp = core_fp(public_key)
log.append_entry(EventType.KEY_REGISTRATION, {
    "fingerprint": fp,
    "algorithm": "ed25519",
    "public_key": _serialize_public_key(public_key),
})

# 3. Create the SDK client
sdk = DiogenesSDK(transparency_log=log)

# 4. Sign a document
manifest, attestation = sdk.sign("Hello, Diogenes!", private_key)

# 5. Verify the document
result = sdk.verify(manifest, source_bytes="Hello, Diogenes!")
print(result.overall.value)  # "valid"

See examples/sdk_quickstart.py for a complete runnable example including trust evaluation and webhooks.

Core Classes¶

`DiogenesSDK`¶

The primary entry point. Wraps signing, verification, and trust evaluation.

from diogenes.sdk import DiogenesSDK

Constructor¶

DiogenesSDK(
    transparency_log: TransparencyLogService,
    endorsement_service: EndorsementService | None = None,
    trust_config: TrustConfiguration | None = None,
)

Parameter	Required	Description
`transparency_log`	Yes	The transparency log service for key registration and attestation recording.
`endorsement_service`	No	Required for `evaluate_trust()` and `explain_trust()`.
`trust_config`	No	Required for `evaluate_trust()` and `explain_trust()`.

Methods¶

`sign(content, private_key, attestation_type="authorship", predecessors=None, intent_statement=None)`¶

Sign content and produce a manifest with an attestation.

Parameter	Type	Default	Description
`content`	`bytes \\| str`	--	The document content to sign.
`private_key`	`PrivateKey`	--	The signer's private key (must be registered).
`attestation_type`	`str`	`"authorship"`	One of: `authorship`, `editorial`, `review`, `publication`, `custodial_transcription`, `translation`, `compilation`.
`predecessors`	`list[str] \\| None`	`None`	Predecessor attestation IDs for DAG chaining.
`intent_statement`	`str \\| None`	`None`	Human-readable intent statement.

Returns: tuple[Manifest, Attestation]

Raises: SigningError if signing fails.

manifest, attestation = sdk.sign("My document", private_key)
print(attestation.id, attestation.signature)

`verify(manifest, source_bytes=None)`¶

Verify a signed manifest.

Parameter	Type	Default	Description
`manifest`	`Manifest`	--	The signed manifest to verify.
`source_bytes`	`bytes \\| str \\| None`	`None`	Original content for hash verification. If `None`, hash-only verification is used.

Returns: VerificationResult with overall, layer1 (crypto), layer2 (key status), and optionally layer3 (trust) results.

Raises: VerificationError if verification encounters an error.

result = sdk.verify(manifest, source_bytes="My document")
assert result.overall.value == "valid"

`evaluate_trust(fingerprint)`¶

Evaluate trust for a key fingerprint using the configured trust anchors and endorsement graph.

Parameter	Type	Description
`fingerprint`	`str`	SHA-256 fingerprint of the public key (with `sha256:` prefix).

Returns: TrustPathReport with aggregate_score, threshold_met, and contributing_paths.

Raises: TrustEvaluationError if trust evaluation is not configured or fails.

report = sdk.evaluate_trust("sha256:abc123...")
print(report.threshold_met, report.aggregate_score)

`explain_trust(fingerprint)`¶

Get a human-readable trust explanation for a key.

Parameter	Type	Description
`fingerprint`	`str`	SHA-256 fingerprint of the public key.

Returns: TrustExplanation with trusted, score, summary, contributing_paths, and recommendations.

Raises: TrustEvaluationError if trust evaluation is not configured or fails.

explanation = sdk.explain_trust("sha256:abc123...")
print(explanation.summary)
# "Yes, you should trust this key. It scores 0.90 against ..."

Key Management¶

`generate_key_pair(algorithm="ed25519")`¶

Generate a cryptographic key pair.

Parameter	Type	Default	Description
`algorithm`	`str`	`"ed25519"`	One of `"ed25519"`, `"ecdsa-p256"`, `"rsa-2048"`.

Returns: tuple[PrivateKey, PublicKey]

from diogenes.sdk import generate_key_pair
private_key, public_key = generate_key_pair("ed25519")

`compute_fingerprint(public_key)`¶

Compute the SHA-256 fingerprint of a public key.

Returns: Hex-encoded string (64 characters).

from diogenes.sdk import compute_fingerprint
fp = compute_fingerprint(public_key)
# "a1b2c3d4e5f6..."

`serialize_private_key(key, password=None)`¶

Serialize a private key to PEM format, optionally encrypted.

from diogenes.sdk import serialize_private_key
pem = serialize_private_key(private_key, password=b"secret")

`load_private_key(data, password=None)`¶

Load a private key from PEM-encoded bytes.

from diogenes.sdk import load_private_key
key = load_private_key(pem_bytes, password=b"secret")

Trust Configuration¶

`load_trust_config(source)`¶

Load a TrustConfiguration from a JSON string.

from diogenes.sdk import load_trust_config
config = load_trust_config('{"direct_signer_anchors": [{"fingerprint": "sha256:abc", "weight": 0.9}], "minimum_threshold": 0.5}')

Raises: TrustConfigError on invalid JSON or validation failure.

`load_trust_config_file(path)`¶

Load a TrustConfiguration from a JSON file on disk.

from diogenes.sdk import load_trust_config_file
config = load_trust_config_file("trust-policy.json")

Raises: TrustConfigError on file read or validation failure.

Webhook Management¶

`WebhookClient`¶

Client for managing webhook subscriptions against the Diogenes REST API.

from diogenes.sdk import WebhookClient

Constructor¶

WebhookClient(
    base_url: str,
    api_key: str | None = None,
    http_client: httpx.Client | None = None,
)

Parameter	Type	Default	Description
`base_url`	`str`	--	Base URL of the Diogenes server (e.g. `http://localhost:8000`).
`api_key`	`str \\| None`	`None`	Optional API key for authentication.
`http_client`	`httpx.Client \\| None`	`None`	Optional pre-configured HTTP client.

Supports context manager usage:

with WebhookClient("http://localhost:8000") as client:
    subs = client.list_webhooks()

`create_webhook(url, events=None, secret=None, key_fingerprint=None, document_hash=None)`¶

Create a new webhook subscription.

Parameter	Type	Default	Description
`url`	`str`	--	Callback URL to receive events.
`events`	`list[str] \\| None`	`None`	Event types to subscribe to. Empty list = all events.
`secret`	`str \\| None`	`None`	Shared secret for HMAC-SHA256 payload signatures.
`key_fingerprint`	`str \\| None`	`None`	Filter events by key fingerprint.
`document_hash`	`str \\| None`	`None`	Filter events by document hash.

Returns: WebhookSubscription

Raises: WebhookError on failure.

sub = client.create_webhook(
    url="https://example.com/hook",
    events=["attestation.created", "key.registered"],
    secret="my-shared-secret",
)
print(sub.id)

`list_webhooks()`¶

List all active webhook subscriptions.

Returns: list[WebhookSubscription]

subs = client.list_webhooks()
for sub in subs:
    print(sub.id, sub.url, sub.events)

`get_webhook(subscription_id)`¶

Get a single webhook subscription by ID.

Returns: WebhookSubscription

Raises: WebhookError if not found.

sub = client.get_webhook(42)
print(sub.active, sub.healthy)

`delete_webhook(subscription_id)`¶

Delete (deactivate) a webhook subscription.

Raises: WebhookError if not found.

client.delete_webhook(42)

`WebhookSubscription`¶

Data class representing a webhook subscription.

Field	Type	Description
`id`	`int`	Unique identifier.
`url`	`str`	Callback URL.
`events`	`list[str]`	Subscribed event types.
`key_fingerprint`	`str \\| None`	Key fingerprint filter.
`document_hash`	`str \\| None`	Document hash filter.
`active`	`bool`	Whether the subscription is active.
`healthy`	`bool`	Whether the endpoint is healthy.
`retry_count`	`int`	Consecutive delivery failures.
`created_at`	`str \\| None`	ISO-8601 creation timestamp.

Exceptions¶

All SDK exceptions inherit from DiogenesSDKError.

Exception	When raised
`DiogenesSDKError`	Base class for all SDK errors.
`SigningError`	Signing fails (e.g. unregistered or revoked key).
`VerificationError`	Verification encounters an error.
`TrustConfigError`	Trust configuration loading or validation fails.
`TrustEvaluationError`	Trust evaluation not configured or fails.
`KeyOperationError`	Key operation fails.
`WebhookError`	Webhook API call fails.

from diogenes.sdk import DiogenesSDKError, SigningError, WebhookError

try:
    sdk.sign("doc", unregistered_key)
except SigningError as e:
    print(f"Signing failed: {e}")

Supported Event Types¶

The following event types can be used when creating webhook subscriptions:

Event	Description
`attestation.created`	A new attestation was signed and recorded.
`key.registered`	A new key was registered on the transparency log.
`key.revoked`	A key was revoked.
`endorsement.created`	A new endorsement was accepted.
`endorsement.revoked`	An endorsement was revoked.

Architecture Notes¶

The SDK is a facade over the core Diogenes modules (diogenes.core.*). Advanced users can import core modules directly for lower-level access.
Signing and verification are synchronous operations.
The WebhookClient uses httpx for HTTP and is safe for use in both sync and async contexts (via httpx.Client).
Trust evaluation uses a web-of-trust model with configurable anchors and thresholds, not a certificate authority.

Diogenes Developer SDK Reference¶

Installation¶

Quickstart¶

Core Classes¶

DiogenesSDK¶

Constructor¶

Methods¶

sign(content, private_key, attestation_type="authorship", predecessors=None, intent_statement=None)¶

verify(manifest, source_bytes=None)¶

evaluate_trust(fingerprint)¶

explain_trust(fingerprint)¶

Key Management¶

generate_key_pair(algorithm="ed25519")¶

compute_fingerprint(public_key)¶

serialize_private_key(key, password=None)¶

load_private_key(data, password=None)¶

Trust Configuration¶

load_trust_config(source)¶

load_trust_config_file(path)¶

Webhook Management¶

WebhookClient¶

Constructor¶

create_webhook(url, events=None, secret=None, key_fingerprint=None, document_hash=None)¶

list_webhooks()¶

get_webhook(subscription_id)¶

delete_webhook(subscription_id)¶

WebhookSubscription¶

Exceptions¶

Supported Event Types¶

Architecture Notes¶

`DiogenesSDK`¶

`sign(content, private_key, attestation_type="authorship", predecessors=None, intent_statement=None)`¶

`verify(manifest, source_bytes=None)`¶

`evaluate_trust(fingerprint)`¶

`explain_trust(fingerprint)`¶

`generate_key_pair(algorithm="ed25519")`¶

`compute_fingerprint(public_key)`¶

`serialize_private_key(key, password=None)`¶

`load_private_key(data, password=None)`¶

`load_trust_config(source)`¶

`load_trust_config_file(path)`¶

`WebhookClient`¶

`create_webhook(url, events=None, secret=None, key_fingerprint=None, document_hash=None)`¶

`list_webhooks()`¶

`get_webhook(subscription_id)`¶

`delete_webhook(subscription_id)`¶

`WebhookSubscription`¶