security: complete a cryptographic review of environment encryption and narrow claims

[chrisbbreuer]

Context

The audited environment-encryption path is described as experimental and uses a simplified public/private-key construction. It should not be recommended as a production secret-management boundary until its threat model and cryptography receive focused review.

Source: https://github.com/stacksjs/white-paper/blob/main/docs/reference/roadmap.md

Scope

• Document assets, adversaries, trust boundaries, key lifecycle, CI/deploy flow, and compromise scenarios.
• Review primitive selection, nonce/IV handling, authentication, key derivation, encoding, error behavior, and rotation.
• Decide whether to replace the construction with a reviewed standard/library or narrow/remove the feature claim.
• Add known-answer, tamper, wrong-key, malformed-input, rotation, and missing-key tests.
• Ensure logs/errors never reveal plaintext, key material, or misleading success.
• Publish migration guidance for existing encrypted environment files.

Deliverables

• Threat model and cryptographic design review.
• Decision record: replace, harden, or deprecate.
• Security tests and external-review notes.
• Key rotation/recovery guidance.
• Updated documentation with precise guarantees and non-guarantees.

Acceptance criteria

• The construction has an explicit authenticity/integrity story
• Nonce/key reuse and malformed-input behavior are tested
• Missing/wrong keys fail clearly without passing ciphertext into config
• Rotation and revocation procedures are documented
• Existing users have migration guidance
• Production recommendations match reviewed evidence
• Independent security review is requested before broad claims

[chrisbbreuer]

PR #2064 implements the RFC 0005 envelope: ephemeral-static X25519, HKDF-SHA-256, AES-256-GCM, authenticated metadata, strict parsing, generic failures, legacy read-only migration, and rollback-safe rotation. Focused crypto/migration/rotation tests pass (81). Claims are narrowed in SECURITY.md and the whitepaper. RFC review is tracked in stacksjs/rfcs#6 and independent review remains #2061, so this issue stays open.

[chrisbbreuer]

The core cryptographic work merged in #2064: authenticated X25519 + HKDF-SHA-256 + AES-256-GCM envelope v2, tamper/wrong-key/malformed-input tests, rotation, legacy-read migration, threat model, and narrowed experimental claims. The issue remains open for the genuine external gate in #2061 and the public RFC decision in stacksjs/rfcs#6. No production recommendation is being made before those reviews.

[chrisbbreuer]

Status check as part of the 1.0 sweep. The implementation work on this list is done; the acceptance criterion that is not is the one that cannot be self-certified.

Done, and verifiable here:

• Explicit authenticity/integrity story. Envelope v2 is ephemeral-static X25519 for recipient confidentiality, HKDF-SHA-256 to separate the shared secret, and AES-256-GCM for authenticated encryption. Written up in storage/framework/core/env/SECURITY.md, including the threat model's non-guarantees.
• Nonce/key reuse and malformed input tested. tests/crypto.test.ts carries 27 cases; the env package is 253/253 across 18 files, covering known-answer, tamper, wrong-key, malformed-input, rotation and missing-key paths.
• Missing/wrong keys fail clearly without passing ciphertext into config, and the canonical parser fails generically rather than distinguishing failure modes to a caller.
• Rotation and recovery documented, decrypt-then-re-encrypt with legacy-reader isolation, along with the migration path for existing files.
• Claims narrowed. SECURITY.md opens with Status: experimental pending RFC ratification and independent cryptographic review, which is the correct claim to be making and should stay until it is not.

Not done, and not doable from here:

• Independent security review. The implementing maintainer cannot approve their own construction; that is the whole point of the criterion. Tracked as the gate in security: obtain independent review of environment envelope v2 #2061, which wants reviewer identity and independence recorded, the exact reviewed commit, findings classified by severity, and a final recommendation on RFC 0005.

So the honest position is: the cryptography is implemented, tested and documented as experimental, and it stays experimental - in the docs and in any conformance report - until #2061 completes. Leaving open, blocked on that.