capglyph — Python SDK for CapGlyph

Python SDK for CapGlyph — image-native credential + stego payload infrastructure.

• Spec: CapGlyph/capglyph-spec v1.0.0 · Core: CapGlyph/capglyph-core v0.1.0
• Conformance: CapGlyph/capglyph-test-vectors 1024/1024

Two-type design

SDK type	Transport	Implementation	Use case
Local SDK	Pure Python (fallback) + maturin/PyO3 from Rust Core	capglyph.local.LocalClient, capglyph.framing	Offline seal/open/validate without server; future DCT/DWT image embed
API SDK	Typed HTTP client (OpenAPI)	capglyph.client.CapglyphClient (httpx or stdlib)	Calling capglyphd (/v1/seal, /v1/open, /v1/embed, /v1/verify, …)

Install

pip install capglyph
# with HTTP client extras
pip install "capglyph[client]"

# from source (isolated monorepo)
pip install -e ../capglyph-sdk-python

# with dev harness
pip install -e ".[dev]"

Requires Python 3.9+.

Quickstart

Local (no server) — seal/open

from capglyph import LocalClient, Params, PayloadType
from capglyph.framing import hex_to_bytes, bytes_to_hex

k_mac = bytes.fromhex("42" * 32)  # HKDF-derived K_mac (capglyph_core::keying)
payload = bytes.fromhex("00112233445566778899aabbccddeeff")

local = LocalClient()  # prefers capglyph._core Rust extension when built, else pure Python
sealed = local.seal(payload, k_mac, Params(version=1, payload_type=PayloadType.Credential))
# or hex convenience
sealed_hex = local.seal_hex("0011...", "42"*32)

res = local.open(sealed, k_mac)
print(res.header)   # FrameHeader(version=1, payload_type=Credential, flags=0, payload_len=16)
print(res.payload.hex())

# preflight without key
hdr = local.validate(sealed)

Pure framing without LocalClient:

from capglyph.framing import seal, open_sealed, Params, PayloadType

sealed = seal(b"credential", Params(payload_type=PayloadType.Credential), k_mac)
header, payload = open_sealed(sealed, k_mac).header, open_sealed(sealed, k_mac).payload

API (capglyphd) — typed client

from capglyph import CapglyphClient

client = CapglyphClient("https://capglyph.example.com", api_key="...")

# Framing via server
sealed = client.seal(payload_hex="001122...", k_mac_hex="42"*32, payload_type=1)
payload = client.open(sealed_hex=sealed["sealed_hex"], k_mac_hex="42"*32)

# Image carrier (DCT/DWT)
with open("cover.png", "rb") as f:
    import base64
    b64 = base64.b64encode(f.read()).decode()
out = client.embed_image(b64, mode="dwt", payload_hex="deadbeef", k_mac_hex="42"*32)
present = client.verify_image(b64, mode="dwt")

Error handling is fail-closed with E_* codes (spec §8):

from capglyph import CapglyphApiError
try:
    client.open(tampered_hex, k_mac_hex)
except CapglyphApiError as e:
    print(e.code)  # E_AUTH_FAILED, E_EXPIRED, ...

Conformance

Vectors: CapGlyph/capglyph-test-vectors 1024 fixtures.

# via pytest (no cargo)
pytest
pytest tests/test_conformance.py -v

# standalone harness (mirrors capglyph-test-vectors/tools/conformance.py)
python -m capglyph.conformance --vectors ../capglyph-test-vectors/vectors
python ../capglyph-test-vectors/tools/conformance.py --vectors ../capglyph-test-vectors/vectors

Expected:

valid     256/256 pass ✓
invalid   128/128 pass ✓
malformed 128/128 pass ✓
tampered  256/256 pass ✓
expired   128/128 pass ✓
revoked   128/128 pass ✓
total    1024/1024 vectors passed — conformance ✓

Vectors resolved via CAPGLYPH_VECTORS or sibling ../capglyph-test-vectors/vectors or /mnt/data/Workspace/Projects/capglyph/capglyph-test-vectors/vectors.

Maturin extension (optional)

The Local SDK will prefer a Rust extension when present (future capglyph-core PyO3 bindings for carrier lattice). Build:

# from isolated monorepo /mnt/data/Workspace/Projects/capglyph
maturin develop -m capglyph-sdk-python/Cargo.toml  # when Cargo.toml with pyo3 is added

Current pyproject.toml is pure-Python (no Rust build); adding Cargo.toml with pyo3 is a follow-up without breaking the pure-Python conformance.

API Reference

• capglyph.framing — seal, open_sealed, validate_frame, cbor_encode/decode/validate, hmac_tag/verify, Params, PayloadType, FrameHeader
• capglyph.local.LocalClient — seal, seal_hex, open, open_hex, validate, using_core, embed_image (TODO), verify_image, extract_image
• capglyph.client.CapglyphClient — seal, open, validate, embed_image, verify_image, extract_image, consume, revoke, info, health
• capglyph.conformance — validate_vector, validate_vectors, find_vectors_root, load_vectors
• capglyph.errors — ErrorCode, CapglyphError, classify_str

Building

pip install -e ".[dev]"
pytest

License

Apache-2.0 — same as CapGlyph/capglyph-core.