# Implementation Plan: MailioReceipt v1

**Branch**: `001-mailio-receipt-v1` | **Date**: 2026-02-04 | **Spec**: [spec.md](spec.md)
**Input**: Feature specification from `/specs/001-mailio-receipt-v1/spec.md`

## Summary

Build a Python library for creating, signing, and verifying MailioReceipt v1 records—
cryptographically verifiable, append-only event records for human-agent and agent-agent
workflows. The library provides receipt creation with RFC8785 canonicalization, ES256 JWS
signatures, DID:web identity resolution, chain verification, and approval/revocation
execution checks.

## Technical Context

**Language/Version**: Python 3.10+ (per constitution)
**Primary Dependencies**:
- `cryptography` - ECDSA/ES256 signing and verification (constitution mandates this library)
- `jwcrypto` - JWS compact serialization (or implement using `cryptography` directly)
- `httpx` - DID:web document fetching (async-capable HTTP client)
- `canonicaljson` - RFC8785 JSON canonicalization (or `json-canonicalization`)

**Storage**: N/A (library operates on receipts passed by caller; no persistence)
**Testing**: pytest (per constitution)
**Target Platform**: Any Python 3.10+ environment (Linux, macOS, Windows)
**Project Type**: Single library package
**Performance Goals**: Verify 100-receipt chain in <2 seconds (per SC-002)
**Constraints**: No key storage; cryptographic operations must be deterministic
**Scale/Scope**: Library for individual receipts and chains; caller manages storage

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

### I. Simplicity ✅

| Rule | Status | Evidence |
|------|--------|----------|
| No premature abstractions | ✅ Pass | Flat module structure; extract only after 3+ repetitions |
| No speculative features | ✅ Pass | All 29 FRs map directly to spec requirements |
| Prefer stdlib over third-party | ✅ Pass | Only essential deps: cryptography (mandated), httpx (HTTP), canonicaljson (RFC8785) |
| One way to do things | ✅ Pass | Single `create_receipt()`, single `verify()` API |

### II. Security-First ✅

| Rule | Status | Evidence |
|------|--------|----------|
| Use `cryptography` library | ✅ Pass | ES256 via `cryptography.hazmat.primitives.asymmetric.ec` |
| No key exposure in logs/errors | ✅ Pass | Error messages contain only public identifiers (DIDs) |
| Input validation at boundaries | ✅ Pass | All public functions validate event structure |
| Secure defaults | ✅ Pass | ES256 mandatory; no weak algorithm options |
| Security tests required | ✅ Pass | Crypto tests planned for all signing/verification paths |

### III. Pragmatic Testing ✅

| Rule | Status | Evidence |
|------|--------|----------|
| Crypto tests for all operations | ✅ Pass | Tests for canonicalization, signing, verification, chain traversal |
| Public API happy-path tests | ✅ Pass | Each user story maps to test scenarios |
| Integration tests for e2e flows | ✅ Pass | Full workflow tests: create → approve → verify → execute |
| No mocking crypto primitives | ✅ Pass | Tests use real keys and signatures |

**GATE RESULT**: ✅ All gates pass. Proceeding to Phase 0.

## Project Structure

### Documentation (this feature)

```text
specs/001-mailio-receipt-v1/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output (API contracts)
└── tasks.md             # Phase 2 output (/speckit.tasks command)
```

### Source Code (repository root)

```text
src/
├── mailio_receipt/
│   ├── __init__.py          # Public API exports
│   ├── models.py            # Data classes: Receipt, Event, Actors, Intent, etc.
│   ├── canonicalize.py      # RFC8785 canonicalization
│   ├── signing.py           # JWS signature creation
│   ├── verification.py      # Signature and chain verification
│   ├── did_resolver.py      # DID:web resolution
│   ├── execution.py         # Approval/revocation execution checks
│   ├── errors.py            # Custom exception types
│   └── types.py             # Type aliases and protocols

tests/
├── conftest.py              # Shared fixtures (test keys, sample events)
├── test_models.py           # Model validation tests
├── test_canonicalize.py     # RFC8785 canonicalization tests
├── test_signing.py          # JWS signing tests
├── test_verification.py     # Verification and chain tests
├── test_did_resolver.py     # DID:web resolution tests (with httpx mock server)
├── test_execution.py        # Execution check tests
└── test_integration.py      # End-to-end workflow tests
```

**Structure Decision**: Single library package (`mailio_receipt`) with flat module structure.
No sub-packages until complexity warrants (per Simplicity principle). Tests mirror source
structure for easy navigation.

## Complexity Tracking

> No violations to track. Design adheres to all constitution principles.

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| (none)    | —          | —                                   |
