Skip to content

Commit ea4c90a

Browse files
committed
fix(stack-encrypt): address the review of hiding ExpectedContext
The previous commit put #[doc(hidden)] on the re-export of ExpectedContext only. rustc and rustdoc read the attribute on the definition, so two things still showed the type: - rustc listed ExpectedContext<T> among the implementors of AllowsNoContext and AcceptsContext in every E0277 a caller gets for a wrong context. - rustdoc for crates that name the type (eql-bindings, and any crate using the derives with a context field) linked it to a page that is never generated. On docs.rs that is a 404 on about 50 EQL type pages. The attribute is now on the struct as well. Six trybuild snapshots lose the ExpectedContext<T> lines. In eql-bindings' docs the type name is now plain text. Also: - eql-bindings: the JsonTreeDocument DecryptInto impl no longer links to the hidden type. Its doc says what the caller passes. The impl itself is unchanged, so eql-bindings' API is the same. - CHANGELOG: the upgrade note used T for both the context type and the plaintext type. It now names them C and P, says that code naming the type still compiles but is outside semver, names decrypt_from for no check, and says eql-bindings also names the type. - tests/derive_plan.rs: the empty stored context test now checks that the error is the empty-context refusal, not just any error. - ADR-0012, the API plan and attributes.md no longer say the type is public, or that the whole plan item is done.
1 parent 6516dc1 commit ea4c90a

14 files changed

Lines changed: 39 additions & 57 deletions

‎docs/plans/2026-10-24-stack-encrypt-api-plan.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1739,10 +1739,11 @@ records only the work.
17391739
and with it every chain state and its `.context(..)`, `.extend(..)`,
17401740
and `.keyset(..)`. A stored part passed on decrypt is checked against
17411741
the row before any key is fetched. That check is what `ExpectedContext`
1742-
does today. It stops being a public type. Done in the third pull
1743-
request for #1488: it is hidden from the documentation, and is public
1744-
only so that code the derives emit can name it. A caller passes a
1745-
`NonEmpty<T>` or nothing.
1742+
does today. It stops being a public type. That last step is done
1743+
(#1612): the type is hidden from the documentation and from compile
1744+
errors, and is public only so that code the derives emit can name it.
1745+
A caller passes a `NonEmpty<T>` or nothing. The rest of this item is
1746+
not done.
17461747
- **Why.** The typed API already pairs its entry points (#1404). A value
17471748
for the context reads the same on both layers. A builder state for the
17481749
context, and a part added later in a chain, are the mistakes the context

‎packages/eql/crates/eql-bindings/src/v4/json_tree.rs‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -514,8 +514,10 @@ impl EncryptFrom<Value> for JsonTreeDocument {
514514
}
515515
}
516516

517-
/// Opens to the plaintext document, under the stored identifier, which an
518-
/// [`ExpectedContext`] may require to be the column the caller expects.
517+
/// Opens to the plaintext document, under the stored identifier. A caller
518+
/// that passes the column it expects, as a `NonEmpty<Identifier>`, has the
519+
/// stored identifier checked against it before any key is requested. A
520+
/// caller that passes nothing opens under the stored identifier unchecked.
519521
impl DecryptInto<Value> for JsonTreeDocument {
520522
type Context = ExpectedContext<Identifier>;
521523
fn decryption<K: 'static>(self, context: Self::Context) -> Decryption<Value, K> {

‎packages/stack-encrypt-derive/docs/attributes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ The plaintext type must implement `Zeroize`.
102102
### The context a call takes
103103

104104
Each kind of record decides whether the caller must pass a context, may
105-
pass one, or must not pass one. Its `ContextInput` type says which:
105+
pass one, or must not pass one. This table shows which:
106106

107107
| Record | Encrypt input | Decrypt input | Example call |
108108
|---|---|---|---|

‎packages/stack-encrypt/CHANGELOG.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -92,12 +92,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
9292
- **`target::ExpectedContext` is no longer part of the API** (#1488). It
9393
is the check that a `#[stash(context_field)]` record runs on decrypt:
9494
the stored context must equal the one the caller expects, if the caller
95-
names one. It is now hidden from the documentation. It stays public only
96-
so that code the derives emit can name it.
97-
- To upgrade, do not name the type. Pass the `NonEmpty<T>` you expect,
98-
or `()` for no check, and let `Into` convert it:
99-
`cipher.decrypt_as(record, expected.into())`, or
100-
`T::decrypt_from_with_context(record, &cipher, expected)`.
95+
names one. It is now hidden from the documentation and from the lists
96+
of implementors in compile errors. It stays public only so that code
97+
the derives emit, and the EQL types in `eql-bindings`, can name it.
98+
Code that names it still compiles, but the type is outside semver and
99+
may change in any release.
100+
- To upgrade, do not name the type. For a record whose context field
101+
has type `C` and whose plaintext has type `P`, pass the
102+
`NonEmpty<C>` you expect, or `()` for no check, and let `Into`
103+
convert it: `cipher.decrypt_as(record, expected.into())`, or
104+
`P::decrypt_from_with_context(record, &cipher, expected)`. For no
105+
check, `P::decrypt_from(record, &cipher)` also works.
101106
- `ValuePlan::decryption_with_context` takes an `Option<NonEmpty<C>>`
102107
in place of an `ExpectedContext<C>`. `None` checks only that the
103108
stored context is not empty.

‎packages/stack-encrypt/docs/adr/0012-owned-record-declarations.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -265,8 +265,10 @@ These are deliberate. Each one is documented where the caller meets it.
265265
### What is not done yet
266266

267267
- A caller's scope or row binding, declared on the record. See decision 3.
268-
- `ExpectedContext` stays public until the plan's `Planned` value replaces
269-
it. A context passed on decrypt will then be checked the same way.
268+
- The plan's `Planned` value does not yet check a context passed on
269+
decrypt the way `ExpectedContext` does. `ExpectedContext` is no longer
270+
documented: the derives still emit it, and a caller passes a
271+
`NonEmpty<T>` or nothing.
270272
- Configured targets, such as a JSON index with options, cannot be fields of
271273
an owned record yet. Their plaintext, `serde_json::Value`, does not
272274
implement `Zeroize`.

‎packages/stack-encrypt/src/target/context.rs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -914,6 +914,11 @@ impl DeclaredContext {
914914
/// descriptor is HMAC'd into the tag, so altering a stored identifier makes
915915
/// the retrieve fail rather than succeed, and nobody reaches a key they are
916916
/// not entitled to. See ADR-0004.
917+
// Hidden here, on the definition, and not only on the re-export. rustc
918+
// reads this attribute when it lists the types that implement a trait in a
919+
// compile error, and rustdoc reads it when another crate's docs name the
920+
// type. On the re-export alone, the type still showed in both.
921+
#[doc(hidden)]
917922
#[derive(Clone, Debug)]
918923
pub struct ExpectedContext<T>(Option<NonEmpty<T>>);
919924
impl<T> Default for ExpectedContext<T> {

‎packages/stack-encrypt/src/target/mod.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -187,7 +187,7 @@ pub(crate) use self::core::{bind_pending, seal_pending};
187187
/// The check a `#[stash(context_field)]` record runs on decrypt. It is not
188188
/// part of the API: the derives and the EQL types name it, and a caller
189189
/// passes a `NonEmpty<T>` or nothing. It is public only so that code the
190-
/// derives emit in another crate can name it.
190+
/// derives emit in another crate can name it. The definition is hidden too.
191191
#[doc(hidden)]
192192
pub use context::ExpectedContext;
193193
pub use context::{

‎packages/stack-encrypt/tests/derive_plan.rs‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ use stack_encrypt::target::{
2020
Encryption, IndexSpec,
2121
};
2222
use stack_encrypt::{
23-
nonempty, DecryptInto, EncryptFrom, Error, NonEmpty, Plan, PlanError, StackCipherText,
23+
nonempty, DecryptInto, EmptyError, EncryptFrom, Error, NonEmpty, Plan, PlanError,
24+
StackCipherText,
2425
};
2526

2627
// --- A `plaintext = T` record ------------------------------------------------
@@ -745,7 +746,12 @@ async fn a_context_field_plan_refuses_an_empty_stored_context_before_any_request
745746
let refused = keyset
746747
.run_decryption(plan.decryption_with_context((String::new(), sealed), None))
747748
.await;
748-
assert!(refused.is_err(), "{:?}", refused.ok());
749+
// The empty-context refusal, not a mismatch: with no expected context
750+
// there is nothing for the stored one to differ from.
751+
assert!(
752+
matches!(&refused, Err(Error::Other(error)) if error.is::<EmptyError>()),
753+
"{refused:?}"
754+
);
749755
assert_eq!(retrieves.load(AtomicOrdering::SeqCst), 0);
750756
}
751757

‎packages/stack-encrypt/tests/ui/owned_collection_context.stderr‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,6 @@ help: the following other types implement trait `AllowsNoContext`
1717
...
1818
| impl AllowsNoContext for DeclaredScopes {
1919
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `DeclaredScopes`
20-
...
21-
| impl<T> AllowsNoContext for ExpectedContext<T> {
22-
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `ExpectedContext<T>`
2320
note: required by a bound in `stack_encrypt::EncryptInto::encrypt_into`
2421
--> src/target/conversion.rs
2522
|
@@ -48,9 +45,6 @@ help: the following other types implement trait `AllowsNoContext`
4845
...
4946
| impl AllowsNoContext for DeclaredScopes {
5047
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `DeclaredScopes`
51-
...
52-
| impl<T> AllowsNoContext for ExpectedContext<T> {
53-
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `ExpectedContext<T>`
5448
note: required by a bound in `stack_encrypt::DecryptFrom::decrypt_from`
5549
--> src/target/conversion.rs
5650
|
@@ -74,9 +68,6 @@ help: the following other types implement trait `AcceptsContext`
7468
...
7569
| impl<C> AcceptsContext for OptionalContext<C> {
7670
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `OptionalContext<C>`
77-
...
78-
| impl<T> AcceptsContext for ExpectedContext<T> {
79-
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `ExpectedContext<T>`
8071

8172
error[E0277]: the trait bound `NoCallerContext: AcceptsContext` is not satisfied
8273
--> tests/ui/owned_collection_context.rs:44:51
@@ -94,9 +85,6 @@ help: the following other types implement trait `AcceptsContext`
9485
...
9586
| impl<C> AcceptsContext for OptionalContext<C> {
9687
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `OptionalContext<C>`
97-
...
98-
| impl<T> AcceptsContext for ExpectedContext<T> {
99-
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `ExpectedContext<T>`
10088
note: required by a bound in `stack_encrypt::DecryptFrom::decrypt_from_with_context`
10189
--> src/target/conversion.rs
10290
|

‎packages/stack-encrypt/tests/ui/owned_record_required_context.stderr‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,6 @@ help: the following other types implement trait `AllowsNoContext`
1515
...
1616
| impl AllowsNoContext for DeclaredScopes {
1717
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `DeclaredScopes`
18-
...
19-
| impl<T> AllowsNoContext for ExpectedContext<T> {
20-
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `ExpectedContext<T>`
2118
note: required by a bound in `stack_encrypt::EncryptInto::encrypt_into`
2219
--> src/target/conversion.rs
2320
|
@@ -46,9 +43,6 @@ help: the following other types implement trait `AllowsNoContext`
4643
...
4744
| impl AllowsNoContext for DeclaredScopes {
4845
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `DeclaredScopes`
49-
...
50-
| impl<T> AllowsNoContext for ExpectedContext<T> {
51-
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `ExpectedContext<T>`
5246
note: required by a bound in `stack_encrypt::DecryptFrom::decrypt_from`
5347
--> src/target/conversion.rs
5448
|

0 commit comments

Comments
 (0)