Repository navigation
Description
Background
Stack Encrypt (packages/stack-encrypt) is the Rust engine that every CipherStash language SDK runs on. Every value is encrypted under a context: a list of parts, such as a table name, a column name and a tenant ID. A value decrypts only under the context it was encrypted under.
Stack Encrypt has two ways to write the declared part of a context:
- Scope parts. A record declares
scope = "users", and a caller addsScope::new(tenant). feat(stack-encrypt): split the context into scopes and bindings #1591 added them. Label. An older type that holds a path of names, such asusers/email, and is parsed from text.IntoLabelis the trait that converts a value to one.
The Stack Encrypt API plan removes Label and IntoLabel: a plan's context is its declared scope parts. The naming review then reuses the name Label for a different thing, the key tag. #1488 tracks the removal.
Problem
Label is still public and widely used, so the context of a value can be written in two ways. A developer who passes a path where parts are expected, or the reverse, gets a context that does not match, and a query that finds nothing.
What is still there, at commit 775d37645 (the head of #1659):
- The type.
pub struct Label(packages/stack-encrypt/src/descriptor.rs:485) andpub trait IntoLabel(src/plan/build.rs:27). - Stack Encrypt. 17 source files name
Label. The largest users are the plan builder (plan/build.rs,plan/value.rs,plan/chain.rs),descriptor.rs,json/derive.rsand the dynamic plans (dynamic/record.rs,dynamic/query.rs,dynamic/target.rs,dynamic/planned.rs). eql-bindings, the Rust crate with the types for values stored by EQL (Encrypt Query Language, the SQL library in the customer's database). It converts aLabelof two names to a table and a column (packages/eql/crates/eql-bindings/src/encryption.rs:157), and its query checks and resolver take a&Label(encryption/query.rs:254,316,340,encryption/resolver.rs:9).- The Go guest, the WebAssembly module the Go SDK runs the engine in. It takes the context a caller expects on decrypt as path text and parses it into a
Label(languages/golang/encrypt/guest/src/options.rs:87and208to213,ops.rs:222and599). - Tests. 17 files in
packages/stack-encrypt/testsand 9 inpackages/eql/tests.
#1659 added new uses of Label in the JSON query path (src/dynamic/json_query.rs), because a field's column is still a Label there.
Proposal
- Decide the type that names a field's column in a plan once
Labelis gone. The plan says a context is its declared scope parts. Write the decision in the pull request. - Move the dynamic plans (
dynamic/record.rs,dynamic/query.rs,dynamic/target.rs,dynamic/planned.rs,dynamic/json_query.rs) andjson/derive.rsto that type. - Move
eql-bindingsto it: the column of an EQL type comes from the scope parts, not from aLabelof two names. - Change the Go guest to take the expected context as parts, not as path text. This changes the frame the Go host sends, so change the host in the same pull request. Do not change the Go module's public API here.
- Delete
Label,IntoLabeland the code that parses a path. - Add a "Breaking" entry to the CHANGELOG that says how to upgrade.
The plan builder is the largest user of Label. It is deleted by #1662, so do this issue after that one.
Acceptance
- No public type or trait is named
LabelorIntoLabelfor a context path. - The Go guest takes no context as path text.
- The stored bytes do not change. A context made of the same names gives the same bytes as before. The frozen stored-bytes tests pass with no fixture change.
- The Go module's tests and the cross-language conformance checks pass.
Relationship to other work
- Sub-issue of stack-encrypt refactor: remove transitional traits and redundant execution APIs #1488.
- Do it after stack-encrypt: the plan chain and builder are still a second way to run a plan — remove them, and run their tests through
Planned#1662, which removes the plan chain and the builder. - stack-encrypt refactor: finalize crate ownership, naming and coordinated migration #1489 applies the naming review. It lists the removal of
Labeltoo, and says it happens once, in stack-encrypt refactor: remove transitional traits and redundant execution APIs #1488. It also removes Go'sContextLabel()(languages/golang/encrypt/cipher.go:175), which is a change to the Go public API and is not part of this issue. - stack-encrypt: bindings send a serialised
Planned, and the conformance corpus is written as one #1594 makes the language SDKs send a serialisedPlanned. The frame change in step 4 should fit the frame that issue defines.
Activity
docs(stack-encrypt): refresh the API plan's tracking lines
coderdan commentedon Nov 15, 2026
On hold. The type this issue removes holds a field's declared path: the record's scope and the field's name, stored in EQL's
i. The context naming work now under way may give that path a new name and a defined mode, so renaming or removingLabelhere would only be undone. It stays as it is until that work settles the name. RemovingLabel::parseand sending the Go guest a list of names in place of path text would fit with the serialisedPlannedof #1594.