Document example for the encryption model

Context

Document and demonstrate the factor-bound alias encryption model. A KEK alias can be created under an authenticated principal, shared with another principal, or shared through a high-entropy passphrase without making the passphrase mere authorization metadata.

The factors do not need to be concatenated directly into a key. Completing the principal's factor chain unlocks the principal key material, which can then unwrap the alias KEK envelope. A passphrase recipient derives the key needed to unwrap its own envelope.

Required flows

Principal-to-passphrase sharing

1. An authenticated principal creates or controls an alias.
2. The principal re-wraps that alias for a passphrase.
3. A caller with the passphrase can create an anonymous passphrase session and use the alias.
4. The principal grants a replacement passphrase and revokes the old grant.
5. The old passphrase can no longer unwrap or use the alias; the replacement still can.

Principal-to-principal sharing

1. An authenticated principal creates an alias.
2. The principal creates or selects another principal.
3. The owner re-wraps the alias KEK for the recipient principal.
4. The recipient completes its configured factors and can use the alias through its session.
5. A caller that has not completed the recipient factor chain cannot use that envelope.

Acceptance criteria

• Add an executable example covering both flows, including successful encrypt/decrypt operations.
• Alias sharing wraps the existing KEK for each recipient; it must not create an unrelated alias or copy plaintext data.
• Session-protected aliases do not persist an RMK-readable plaintext KEK representation.
• Passphrase grants use KMS.SecretPolicy; low-entropy passphrases fail before an envelope is stored.
• Revoking one passphrase grant does not revoke independent grants for the same alias.
• Existing RMK-only aliases and ciphertext formats remain compatible.
• Trusted local calls without a session retain their current behavior for existing RMK-only aliases.
• Document the trust model, revocation semantics, and the role of principal factors in unlocking key material.

Out of scope

• Password-reset or principal-key recovery workflows.
• Changing the ciphertext payload format.
• Adding a new password-hashing or KDF dependency.
• Automatic rotation of session-protected KEKs.