Metadata-Version: 2.4
Name: mosaic-credential
Version: 0.1.1
Summary: Python bindings and reference implementation for Mosaic Credential v1
Author-email: Ecch1ch1 <ecch1ch1.ss@proton.me>
License-Expression: MPL-2.0
Project-URL: Homepage, https://github.com/Ecch1ch1/Mosaic-Credentials
Project-URL: Documentation, https://github.com/Ecch1ch1/Mosaic-Credentials/blob/main/SPECIFICATION.md
Project-URL: Repository, https://github.com/Ecch1ch1/Mosaic-Credentials.git
Project-URL: Bug Tracker, https://github.com/Ecch1ch1/Mosaic-Credentials/issues
Keywords: cryptography,authentication,credentials,argon2,security,passwords,zero-trust
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security :: Cryptography
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
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: argon2-cffi>=21.0.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"

# mosaic-credential (Python)

Python bindings and reference implementation for **Mosaic Credential v1** (`mosaic-core` / `mosaic-auth`).

Conforms strictly to the **Mosaic Credential Technical Specification v0.1**.

## Features

- **Structured Secret Composition**: Interleave arbitrary Unicode text (with exact scalar preservation) and arbitrary binary files (BLOBs).
- **Exact Backspace Semantics (§5.1)**: Backspace is represented as `CHAR(U+0008)` as a deliberate secret element rather than automatically discarding preceding input.
- **Canonical MC v1 Streaming Binary Serialization (§6)**.
- **Domain-Separated SHA-256 Prehashing (§8.2)**.
- **Argon2id Verifier Derivation (§8.3)** with compact JSON verifier storage (`VerifierRecord`).
- **Enforces Size Policies (§7)**: Limits on total encoded bits, maximum blob bits, and maximum element counts.
- **Cross-Platform Test Vector Compatibility (§16.4)**: Verified 100% against published test vectors matching Rust and WebAssembly implementations.

## Installation

```bash
pip install mosaic-credential
```

## Quickstart API (§12.3)

```python
from mosaic_credential import CredentialBuilder, Policy, AuthParams, enroll, verify, VerifyResult

# 1. Define application size policy
policy = Policy(
    max_encoded_bits=2_000_000_000,
    max_blob_bits=2_000_000_000,
    max_elements=100_000,
)

# 2. Build the credential
builder = CredentialBuilder(policy)
builder.add_text("Pass")
builder.add_backspace(count=3)
builder.add_blob(b"\x00\x01\x02\x03\x04")
builder.add_text("word")

credential = builder.finalize()

# 3. Enroll (produces compact JSON verifier record)
record = enroll(credential, AuthParams.default())
record_json = record.to_json()
print("Stored record:\n", record_json)

# 4. Verify candidate
candidate_builder = CredentialBuilder(policy)
candidate_builder.add_text("Pass")
candidate_builder.add_backspace(count=3)
candidate_builder.add_blob(b"\x00\x01\x02\x03\x04")
candidate_builder.add_text("word")

result = verify(candidate_builder.finalize(), record)
assert result == VerifyResult.OK
```

## Running Tests

```bash
pytest tests/ -v
```
