capglyph — Python SDK for CapGlyph

Pure-Python framing helpers and an HTTP client surface. The manifest declares 0.1.3 and Python 3.9+; these are checkout metadata, not confirmation of PyPI publication or a tested interpreter matrix.

Target: spec v1.0.1, wire v1. Reference core: capglyph-core. Fixtures: 1024 byte-level cases.

Current support

Surface	Implementation	Boundary
Local framing	framing.py, LocalClient	Generic deterministic outer CBOR/HMAC; Credential semantics require explicit validation
Credential validation	validate_credential_payload	Checks exact 19-byte {0: bstr16} and zero flags
Optional native loader	local.py tries capglyph._core	No PyO3 extension/build manifest is supplied; package uses Hatchling, not maturin
Local images	embed_image, verify_image, extract_image	Raise NotImplementedError
HTTP	client.py, CapglyphClient	Generic routes do not match the reference server

CarryCtx records CGPY-0001 completed and CGPY-0002 (local image support) ready. Those historical status labels do not establish current public HTTP interoperability or a finished image SDK.

Development environment

From this repository, use an isolated environment:

uv venv
uv pip install -e ".[dev,client]"

The optional client extra supplies httpx; without it, the HTTP wrapper uses urllib. The framing example needs no external cryptographic library. A registry install is appropriate only after checking the available version. Do not run maturin expecting it to create missing binding source.

Local Credential example

Fixed key/token bytes below are public demonstration values. Production requires an unpredictable token and a trusted 32-byte K_mac derived according to the specified key schedule; repeated bytes are not a derivation example.

from capglyph import LocalClient, Params, PayloadType, validate_credential_payload

k_mac = bytes.fromhex("42" * 32)
payload = bytes.fromhex("a10050000102030405060708090a0b0c0d0e0f")
params = Params(payload_type=PayloadType.Credential, flags=0)
validate_credential_payload(payload, params.flags)
client = LocalClient(prefer_core=False)
sealed = client.seal(payload, k_mac, params)
opened = client.open(sealed, k_mac)
if opened.header.payload_type != PayloadType.Credential:
    raise ValueError("expected Credential")
validate_credential_payload(opened.payload, opened.header.flags)
print(len(sealed), opened.header.payload_len)  # 57 19
print(opened.payload[3:].hex())

open/open_sealed authenticate before decoding the outer frame but do not call the Credential validator. validate/validate_frame are structural preflight, not MAC verification. Authenticated bytes do not establish image ownership, expiry, revocation, scope or consumption authorization.

HTTP compatibility

Current SDK methods send:

• POST /v1/seal, /v1/open, /v1/validate.
• POST /v1/embed, /v1/verify, /v1/extract, /v1/info.
• POST /v1/consume, /v1/revoke; GET /health.

The reference capglyphd exposes /v1/version and credential/message route families instead. Its consume operation requires idempotency and authorization context absent from this generic helper. No adapter is supplied. Use the reference API directly until alignment, or a separately implemented endpoint matching these precise client contracts. Do not send production keys to an untrusted service.

An api_key produces an Authorization header; it does not add an authentication policy to the server. CapglyphApiError reflects remote details when available, not a guarantee that every generic endpoint uses the stable wire errors.

Conformance and quality checks

uv run pytest
uv run ruff check capglyph tests
uv run ruff format --check capglyph tests

The harness resolves CAPGLYPH_VECTORS or sibling ../capglyph-test-vectors/vectors. The 1024 cases cover framing, semantics, key fixtures and mocked policy, not image transport, ECC correction, database concurrency or HTTP-route compatibility. These commands are verification instructions, not a fresh pass claim by the documentation audit.

API reference

• framing.py: PayloadType, FrameHeader, Params, seal, open_sealed, validate_frame, validate_credential_payload.
• local.py: LocalClient, byte/hex framing and unsupported image methods.
• client.py: CapglyphClient, CapglyphApiError, client_from_env.
• conformance.py: vector validation helpers.

License

Apache-2.0. See LICENSE.