Add base64url codec + unified AEAD size metadata (closes #12)

[moisesja]

Summary

Closes #12. Two small ergonomics gaps every JOSE/DIDComm consumer of NetCrypto otherwise re-implements locally. Neither is a correctness gap — both are "every consumer re-implements the same trivial thing" duplication.

G4 — base64url codec

New public static class Base64Url:

string Encode(ReadOnlySpan<byte> data);  // RFC 4648 §5, no '=' padding
byte[] Decode(ReadOnlySpan<char> text);  // tolerates optional padding

A thin wrapper over the BCL System.Buffers.Text.Base64Url (.NET 9+), giving the foundation a single source of truth for the JOSE/JWK byte boundary (protected headers, signatures, JWE iv/ciphertext/tag/encrypted_key, JWK x/y/d, apu/apv).

G5 — unified AEAD size metadata

Each content-encryption cipher now exposes its key/nonce/tag sizes as public const int (they were private const):

Cipher	Key	Nonce/IV	Tag
AesGcmCipher	KeySizeBytes 32	NonceSizeBytes 12	TagSizeBytes 16
AesCbcHmacCipher	KeySizeBytes 64	IvSizeBytes 16	TagSizeBytes 32
XChaCha20Poly1305Cipher	KeySizeBytes 32	NonceSizeBytes 24	TagSizeBytes 16

A JOSE builder must allocate the CEK and IV/nonce before calling Encrypt, so it needs (keyLen, nonceLen, tagLen) per cipher; exposing them lets consumers validate against the source of truth and avoid drift. The IV/nonce name follows each cipher's own parameter (CBC has an IV; GCM/XChaCha have a nonce).

Changes

• Base64Url.cs (new), and KeySizeBytes/NonceSizeBytes/IvSizeBytes/TagSizeBytes promoted to public on the three ciphers, each with XML docs.
• PublicAPI.Unshipped.txt — records the new type, two methods, and nine constants.
• Tests — Base64UrlTests (RFC 7515 Appendix A.1 JOSE vector round-trip, no = padding, URL-safe -/_ alphabet, padding-tolerant decode, FormatException on invalid input, random round-trip 0–64 bytes) and AeadSizeMetadataTests (constant values + each constant matches the bytes its cipher accepts/produces; a key one byte short is rejected).
• Encryption sample — sizes the key/nonce/IV from the new constants and adds a base64url section (also satisfies the FR-17 API-coverage check).
• PRD FR-16b and the CHANGELOG.

Notes for review

• Placement (G4). The issue notes base64url arguably belongs in a future JOSE-enveloping module rather than the primitives library. Since that module doesn't exist yet, it lands here (the issue's AC allows "here or the JOSE module"); easy to relocate later.
• Decode exception. Decode surfaces FormatException on invalid input — idiomatic for a codec (matches Convert.FromBase64String / the BCL Base64Url). NFR-3's "no FormatException from a public method" applies to the crypto key-input contract, not a general-purpose encoder; happy to wrap to ArgumentException if preferred.

Acceptance criteria (issue #12)

• (G4) base64url-no-pad encode/decode available from the foundation package, round-tripping the JOSE test vectors.
• (G5) each AEAD cipher type exposes its key/nonce/tag sizes as public constants.

Verification

• dotnet build -warnaserror clean; full suite 819 tests green; API coverage OK; Encryption sample runs (base64url section included) and exits 0.

🤖 Generated with Claude Code

[moisesja]

Review — looks good to merge ✅

Reviewed the full diff. This is a tight, additive, low-risk change (closes #12) and I have no blocking concerns.

What's solid:

• Scope is minimal and correct. Base64Url is a thin pass-through to the BCL System.Buffers.Text.Base64Url (available on this .NET 10 target), and the AEAD change is purely a private const → public const promotion — no behavioral change to any cipher, no secret material exposed. Promoting constants is API-only and safe.
• Test coverage is thorough. RFC 7515 A.1 JOSE vector round-trip, no-padding assertion, URL-safe -/_ alphabet at indices 62/63, padding-tolerant decode, FormatException on invalid input, and 0–64-byte property round-trips. The AEAD tests don't just pin the literals — they prove each constant matches the bytes the cipher actually accepts/produces, including the one-byte-short rejection. That's exactly the right way to keep the constants from drifting into documentation-only fiction.
• Housekeeping is complete: PublicAPI.Unshipped.txt, CHANGELOG, PRD FR-16b, and the Encryption sample are all updated in lockstep. Sample now sources sizes from the constants instead of magic numbers — good dogfooding of the new surface.

Two design calls you already flagged — both reasonable:

• Decode throwing FormatException. Agreed this is idiomatic for a codec and consistent with Convert.FromBase64String/the BCL Base64Url; NFR-3's no-FormatException contract is about crypto key inputs, not a general encoder. No change needed.
• Placement of base64url in the foundation. Fine to land here given no JOSE module exists yet; the relocation cost later is trivial (one type, two methods).

Nothing blocking, one optional nit: Decode's padding tolerance leans on undocumented-by-you BCL behavior — the Decode_ToleratesTrailingPadding test pins it, so if a future BCL/runtime bump ever tightened that, the test would catch it. No action needed; just noting the guarantee lives in the test rather than the wrapper.

CI: the no-native job is already green; the three build-test matrix jobs (ubuntu/macos/windows) were still in progress at review time. Assuming they go green to match your local dotnet build -warnaserror + 819-test run, this is good to merge.

---

Generated by Claude Code