Metadata-Version: 2.5
Name: capglyph
Version: 0.1.3
Summary: CapGlyph Python SDK — Local (pure Python + maturin/WASM) + API (capglyphd) with conformance vectors
Project-URL: Repository, https://github.com/CapGlyph/capglyph-sdk-python
Project-URL: Homepage, https://github.com/CapGlyph/capglyph-spec
Author: CapGlyph Authors
License: Apache-2.0
License-File: LICENSE
Keywords: capglyph,cbor,credential,hmac,stego,watermark
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Provides-Extra: client
Requires-Dist: httpx>=0.27; extra == 'client'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# capglyph — Python SDK for CapGlyph

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

- Spec: [`CapGlyph/capglyph-spec` v1.0.0](https://github.com/CapGlyph/capglyph-spec) · Core: [`CapGlyph/capglyph-core` v0.1.0](https://github.com/CapGlyph/capglyph-core)
- Conformance: [`CapGlyph/capglyph-test-vectors` 1024/1024](https://github.com/CapGlyph/capglyph-test-vectors)

## 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

```bash
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

```python
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`:

```python
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

```python
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):

```python
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.

```bash
# 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:

```bash
# 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

```bash
pip install -e ".[dev]"
pytest
```

## License

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