# AGENTS.md
Guidance for AI coding agents working **in this repository**. If you are an
agent trying to **use `cose2` as a dependency**, read
[docs/agent-guide.md](docs/agent-guide.md) first — it has the per-task API
decision table and the protocol rules you should not guess.
## What this is
`cose2` is a Rust library for COSE ([RFC 9052][cose]) and CWT
([RFC 8392][cwt]), built on [`cbor2`][cbor2]. It models the wire structures and
delegates cryptography to caller-supplied trait implementations, so the default
build has **no cryptographic dependencies**.
- Edition 2021, MSRV **1.85** (`rust-version` in `Cargo.toml`).
- `#![forbid(unsafe_code)]`.
## Setup and verification
There is no codegen or build step beyond Cargo. Run these before proposing any
change; CI (`.github/workflows/ci.yml`) runs the same set:
```sh
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features
RUSTDOCFLAGS='-D warnings' cargo doc --workspace --all-features --no-deps
```
Quick example smoke test:
```sh
cargo run --example custom_crypto_traits
cargo run --example sign1_ring --features crypto-ring
```
## Feature flags
- `default = []` — no crypto backend. The pluggable traits are always available.
- `crypto-ring` — `ring`-based `RingSigner` / `RingVerifier` / `RingMacer` /
`RingEncryptor` (module `crypto`).
- `crypto` — aggregate alias that currently enables `crypto-ring`.
## Repository layout
| `src/lib.rs` | Crate root and public re-exports. |
| `src/iana.rs` | IANA registry constants (algorithms, key params, claims, tags). |
| `src/label.rs`, `src/map.rs` | `Label` (`int`/`tstr`) and the shared `CoseMap`. |
| `src/header.rs`, `src/key.rs` | `Header`; `Key` / `KeySet`. |
| `src/sign1.rs`, `src/sign.rs` | `Sign1Message`; `SignMessage` / `Signature`. |
| `src/mac0.rs`, `src/mac.rs` | `Mac0Message`; `MacMessage`. |
| `src/encrypt0.rs`, `src/encrypt.rs` | `Encrypt0Message`; `EncryptMessage`. |
| `src/recipient.rs`, `src/context.rs` | `Recipient`; `KdfContext` / `PartyInfo` / `SuppPubInfo`. |
| `src/traits.rs` | `Signer` / `Verifier` / `Macer` / `Encryptor`. |
| `src/cwt.rs` | `Claims` / `ClaimsMap` / `Validator`. |
| `src/crypto.rs` | `ring` providers (feature `crypto-ring`). |
| `src/error.rs`, `src/tag.rs`, `src/util.rs` | `Error`; CBOR-tag helpers; internal helpers. |
| `examples/`, `tests/`, `docs/` | Runnable examples, integration tests, the consumer agent guide. |
## Invariants to preserve
Do not regress these — they are correctness/compatibility contracts, and several
are load-bearing for cryptographic soundness:
1. **No `unsafe`.** The crate is `#![forbid(unsafe_code)]`.
2. **Default build stays crypto-free.** Any crypto dependency must live behind a
feature flag (`crypto-ring`). Never add an always-on crypto dep.
3. **Reuse decoded protected-header bytes verbatim.** The raw protected header
captured on decode is fed back into `Sig_structure` / `MAC_structure` /
`Enc_structure` so signatures over non-canonical encodings still verify. Do
not re-encode it.
4. **Newly built protected headers and keys serialize canonically** (RFC 8949
§4.2.1) via `cbor2::to_canonical_vec`.
5. **The crate generates no randomness or nonces.** Encryption takes a full `IV`,
or a `Partial IV` combined with `Encryptor::base_iv`.
6. **`external_aad: None` means an empty byte string**, not "ignore AAD". It must
match on create and verify/decrypt.
7. **Detached payload / detached ciphertext are explicit APIs** (`*_detached*`).
Do not hand-encode `nil` and call the embedded helpers.
8. **Keep tests green and coverage high.** The suite targets 100% of lines and
functions (`cargo llvm-cov`); the only uncovered arms are unreachable
serialization error paths. New code paths need tests in `tests/` or inline.
9. **`clippy -D warnings`, `rustdoc -D warnings`, and `rustfmt` must all pass.**
## Adding a `ring` algorithm
The provider→algorithm mapping lives in the helper functions at the bottom of
`src/crypto.rs` (`hmac_algorithm`, `aead_algorithm`, `ecdsa_verification_algorithm`,
`rsa_signing_algorithm`, `rsa_verification_algorithm`). Unsupported algorithms
must return an explicit `unsupported_alg(...)` error rather than silently falling
back to a different primitive. Add the algorithm to
[docs/agent-guide.md](docs/agent-guide.md#crypto-ring-algorithm-recipes) and a
round-trip test in `tests/crypto_ring.rs`.
[cose]: https://datatracker.ietf.org/doc/html/rfc9052
[cwt]: https://datatracker.ietf.org/doc/html/rfc8392
[cbor2]: https://crates.io/crates/cbor2