Security Recommendations
========================

This page is the practical answer to:

**"Which Epicrypt option should I choose for a new application?"**

Quick Picks
-----------

If you are starting fresh, prefer these defaults:

- Password hashing: ``PasswordHasher`` with ``SecurityProfile::MODERN``
- Password upgrades: ``verifyAndRehash()``
- App payload encryption: ``DataProtection\StringProtector``
- Large file encryption: ``DataProtection\FileProtector``
- Envelope-style protected storage: ``DataProtection\EnvelopeProtector``
- API tokens with one shared secret: ``Token\Jwt\SymmetricJwt``
- API tokens with separate signer/verifier trust: ``Token\Jwt\AsymmetricJwt``
- Revocable random bearer tokens: ``Token\Opaque\OpaqueToken``
- Small signed action/reset payloads: ``Token\Payload\SignedPayload``
- Browser workflow tokens: ``Security`` domain helpers such as ``PasswordResetToken`` and ``SignedUrl``
- New ciphertext formats: modern ``DataProtection`` APIs

Public Surface First
--------------------

For new applications, start from these domains first:

- ``Password``
- ``Token``
- ``DataProtection``
- ``Security``

Treat these as lower-level or advanced:

- ``Crypto`` for direct primitive control

Choose the Right Tool
---------------------

Passwords
^^^^^^^^^

Use:

- ``PasswordHasher`` for stored user passwords
- ``PasswordStrength`` for quality feedback
- ``verifyAndRehash()`` when you want login-time hash upgrades

Prefer:

- ``SecurityProfile::MODERN``
- default Argon2id-based hashing

Avoid:

- custom password hashing logic
- storing app secrets as password hashes when you actually need reversible protection

Secrets and Stored Sensitive Values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use:

- ``WrappedSecretManager`` for secrets that must be unwrapped later
- ``SecureSecretSerializer`` for structured secret-bearing data
- ``KeyRing`` plus rewrap helpers during rotation windows

Prefer:

- one active master secret
- short fallback windows for previous key versions

Protected Data
^^^^^^^^^^^^^^

Use:

- ``StringProtector`` for ordinary application payloads
- ``EnvelopeProtector`` when you want a structured encoded envelope
- ``FileProtector`` for large files and streaming-safe encryption
- ``FileProtector::reencryptWithAnyKey()`` when rotating protected files across key versions

Prefer:

- re-encrypting artifacts under the active key when fallback keys match
- ``decryptWithAnyKey()`` or ``reencryptWithAnyKey()`` only during rotation windows
- result helpers like ``decryptWithAnyKeyResult()`` when rotation code needs to know which key matched

Avoid:

- using low-level crypto primitives directly unless you really need them

Tokens
^^^^^^

Use:

- ``SymmetricJwt`` when issuer and verifier share one secret
- ``AsymmetricJwt`` when the signer should keep a private key and verifiers should only need public keys
- ``OpaqueToken`` when token contents should stay server-side
- ``SignedPayload`` for compact signed internal flows

Prefer:

- ``kid`` plus key-set mode when rotating JWT signing keys
- ``KeyRing``-based verification helpers during short transition windows
- ``verifyWithAnyKeyResult()`` when callers need to know whether a fallback key matched

Avoid:

- mixing symmetric and asymmetric expectations in one verification path
- exposing sensitive state in JWT claims when opaque tokens fit better

Crypto Primitives
^^^^^^^^^^^^^^^^^

Use:

- ``AeadCipher`` for authenticated encryption of short payloads
- ``SecretBoxCipher`` when you specifically want secretbox semantics
- ``SecretStream`` or ``FileProtector`` for large file workflows
- ``Mac`` for shared-secret integrity
- ``Signature`` for public/private signature verification

Prefer:

- ``AeadAlgorithm::XCHACHA20_POLY1305_IETF`` for new AEAD usage
- higher-level ``DataProtection`` APIs unless the primitive is truly what you need

Key Material and Derivation
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use:

- ``KeyMaterialGenerator`` for fresh random keys
- ``KeyDeriver`` for derived keys
- purpose-aware key generation helpers when available

Prefer:

- generated keys for encryption keys
- derived keys when the design specifically needs deterministic derivation
- explicit context/info separation for derived subkeys

Key Rotation
------------

Use key-ring helpers during planned key rollover.

Prefer this pattern:

1. issue new artifacts with the active key
2. keep decode/verify paths able to read active and fallback keys during rollout
3. re-encrypt or re-issue under the active key when a fallback key matches
4. remove fallback keys after the rollover window closes

In particular:

- prefer ``StringProtector`` and ``EnvelopeProtector`` for new protected data
- follow the key rotation cookbook for active-key and fallback-key rollout patterns

Binary vs Base64URL
-------------------

Most public Epicrypt APIs expect Base64URL strings by default.

Use explicit context flags only when you are intentionally passing raw binary values, for example:

- ``key_is_binary``
- ``nonce_is_binary``
- ``salt_is_binary``

When possible, keep one format per application boundary instead of mixing both styles in the same layer.

Simple Rule of Thumb
--------------------

- If a higher-level ``Password``, ``Security``, ``Token`` or ``DataProtection`` API fits your use case, choose it first.
- Reach for ``Crypto`` primitives only when you need direct cryptographic control.
- Prefer modern defaults and active-key rotation.