RFC-0001: Layered Architecture¶

Context¶

Need to serve beginners, professionals, and researchers without cross-contamination of risk.

Decision¶

Adopt a three-layer API design: suite.recipes, suite.core, and suite.experimental, with strict boundaries between layers.

Consequences¶

Pros

Tailored interfaces reduce accidental misuse.
Clear demarcation supports audits and review.
Maps to the pyca/cryptography “hazmat” mental model, easing migration.

Cons

Increases maintenance and coordination overhead.
Requires separate documentation per layer.
Risk of divergence between layers if boundaries erode.

API Design Rules¶

recipes¶

Secure defaults.
Minimal parameters.
Explicit safe algorithms only.
Stable.

core¶

Explicit parameters.
Safe defaults with documented trade-offs.
Stable-ish.

experimental¶

Behind feature flags or extras.
Marked unstable.
Warning banners.

Parameter Strategy¶

Key Derivation Functions¶

Parameter	Default	Allowed Range
Algorithm	Argon2id	Argon2id, scrypt, PBKDF2
Memory cost	64 MiB	32–1024 MiB
Time cost	3	1–10

Padding¶

Parameter	Default	Allowed Range
Scheme	PKCS7	PKCS7, none
Block size	128-bit	64–256-bit

Nonces¶

Parameter	Default	Allowed Range
Length	96 bits	64–128 bits
Reuse policy	Forbid	N/A

Random Number Generation¶

Parameter	Default	Allowed Range
Source	`os.urandom` via `secrets`	System CSPRNG only
Reseed	None	None

Key Sizes¶

Key Type	Default	Allowed Range
AES	256 bits	128, 192, 256
RSA	2048 bits	2048–4096
ECC	P-256	P-256, P-384, P-521

Error Model¶

Base SuiteError for all package errors.
ParameterError for invalid sizes or ranges.
MisuseError for nonce reuse or unsafe options.
UnsupportedAlgorithmError for unavailable primitives. All errors provide actionable messages.

Versioning¶

Semantic Versioning.
Deprecations announced and removed after two minor releases.
Stability notes:
- recipes: stable.
- core: stable with minor optional parameters.
- experimental: unstable; breaking changes permitted at any time.