Repository navigation
Open
Labels
Milestone
Description
Background
Stack Encrypt (packages/stack-encrypt) is the Rust engine that every CipherStash language SDK runs on. It has two APIs for encrypting and decrypting a value:
- The owned API. The traits
EncryptTargetandDecryptSource, and entry points such askeyset.encrypt(..)andvalue.encrypt_into(&keyset). It takes the plaintext by value and wipes it from memory after use. - The old API. The traits
EncryptFromandDecryptInto, their derives, and the entry pointsencrypt_asanddecrypt_as.
The Stack Encrypt API plan keeps the owned API and removes the old one. #1488 tracks that work.
Problem
The old API is still public, and most of the code still uses it. A developer who reads the crate finds two ways to encrypt a record and cannot tell which to use.
What is still there, at commit 775d37645 (the head of #1659):
- The traits.
EncryptFrom(src/target/operations.rs:40) andDecryptInto(operations.rs:73). - The entry points.
encrypt_as(operations.rs:1482) anddecrypt_as(operations.rs:1575and1598). - The derives.
#[derive(EncryptFrom)]and#[derive(DecryptInto)](packages/stack-encrypt-derive/src/lib.rs:331and343). - The owned derives emit the old traits too.
#[derive(EncryptTarget)]also emitsEncryptFrom(owned_encrypt.rs:634).#[derive(DecryptSource)]also emitsDecryptIntoand opens each field throughDecryptField, which is built onDecryptInto(owned_decrypt.rs:114to122,285,323). - Implementations in
stack-encrypt.StackCipherText, the term types,Vec,Option, tuples,Encrypted<Terms>and the JSON targets (operations.rs:1307,1616to1848,tuples.rs:83and116,index.rs:649and661,json/derive.rs:1367to1514). - Implementations in
eql-bindings, the Rust crate with the types for values stored by EQL (Encrypt Query Language, the SQL library in the customer's database):encryption.rs:260,293,342,470,530, andv4/json_tree.rs:522to672. - Tests. 304 calls to
encrypt_asordecrypt_asinpackages/stack-encrypt/tests, and 188 inpackages/eql/tests. 105deriveattributes inpackages/stack-encrypt/testsname an old derive.
Most of these test calls were moved to encrypt_as and decrypt_as by #1613, which removed target::legacy. They have to move once more.
Proposal
- Move the tests to the owned API. A test that checks behaviour both APIs share calls the owned entry point. A test that only checks the old derive is deleted, once an owned test covers the same behaviour. List each deleted test and the test that replaces it in the pull request.
- Change
#[derive(DecryptSource)]to open a field throughDecryptSource, not throughDecryptFieldandDecryptInto. Stop both owned derives from emitting the old traits. - Move
eql-bindingsto the owned traits only. Delete itsEncryptFromandDecryptIntoimplementations. - Delete
EncryptFrom,DecryptInto,DecryptField,encrypt_as,decrypt_asand the two old derives. - Keep
encrypt_treeanddecrypt_tree. They are explicit structural operations and are not part of the old API. - Keep an entry point for a borrowed value that stands alone, as the plan says.
- Add a "Breaking" entry to the CHANGELOG that says how to upgrade.
Do the work in more than one pull request if it is easier to review: tests first, then the deletion.
Acceptance
- No file in
packages/stack-encrypt,packages/stack-encrypt-derive,packages/eqlorlanguages/golangnamesEncryptFrom,DecryptInto,encrypt_asordecrypt_as, except the CHANGELOG and the decision records. - The stored bytes do not change. The frozen stored-bytes tests pass with no fixture change.
- The Go module's tests and the cross-language conformance checks pass.
- The mutation test job passes on the changed lines.
Relationship to other work
- Sub-issue of stack-encrypt refactor: remove transitional traits and redundant execution APIs #1488.
- Blocked by stack-encrypt: five JSON targets implement only the old
EncryptFromandDecryptInto— addEncryptTargetandDecryptSource#1660, which gives the remaining JSON targets the owned traits. Those targets have only the old traits today. - The plan chain is bounded on
EncryptFrom(src/plan/chain.rs:532,src/plan/build.rs:946), and#[derive(EncryptFrom)]emits the plan builder's types (packages/stack-encrypt-derive/src/encrypt.rs:88and176). So the chain and the builder go before the traits, or in the same pull request. stack-encrypt: the plan chain and builder are still a second way to run a plan — remove them, and run their tests throughPlanned#1662 covers them. - refactor(stack-encrypt)!: remove target::legacy #1613 removed
target::legacy, the first part of this removal. eql-bindingsbuilds against thestack-encrypton crates.io when it is published. Astack-encryptrelease without the old traits must come before theeql-bindingsrelease that stops using them.
Activity
coderdan commentedon Nov 15, 2026
A correction to the proposal above, found while doing the work in #1666.
Step 4 says to delete
DecryptField. It stays. A derived record usesDecryptField(withDecryptable) to find which of a field's outputs can be opened: a term cannot, a ciphertext can. Nothing else in the owned API answers that. What changes is what it is built on: it now opens throughDecryptSource, and no longer throughDecryptInto.Everything else in the proposal is done in #1666, in one pull request with #1662, because neither compiles without the other.
fix(stack-encrypt,eql-bindings): address the review of the removal
docs(stack-encrypt): drop two more mentions of the plan builder and t…
feat(stack-encrypt,eql-bindings): open every JSON target through the …
refactor(stack-encrypt,eql-bindings)!: remove the plan chain, the bui…
fix(stack-encrypt,eql-bindings): address the review of the removal
docs(stack-encrypt): drop two more mentions of the plan builder and t…