Skip to content

Commit 064428e

Browse files
committed
feat(stack-encrypt): split the context into scopes and bindings
Every part of a context is a scope or a binding. Search terms derive under the query context, the scopes; the data key and the AAD derive under the stored context, the scopes then the bindings. A value bound to its row is still found by a query under its tenant and column, and fails to open in another row. Until now every part was in both, so a developer chose between binding a value to its row and searching it. The kind of a part is in no derivation: a record with no binding stores the bytes it stored before, and the frozen vectors do not move. The owned derives list a record's parts as scope(..) and bind(..), typed for the caller or read from a passthrough field, and refuse a part the record does not list at compile time. The dynamic grammar and Go gain a plan-level bind key and Cipher.Bind; Extend becomes Scope, with the old name kept as a deprecated alias. A new conformance profile, record-bindings-v1, pins the stored context, the term and a ciphertext for both languages. Closes #1487
1 parent ea41543 commit 064428e

48 files changed

Lines changed: 4099 additions & 577 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎conformance/stack-encrypt/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ these rules.
3939
| `record-contexts-v1.cases.json` | cases | `tests/context_conformance.rs` | `context_conformance_test.go` |
4040
| `record-contexts-v1.expected.rust-native.json` | expected | `tests/context_conformance.rs` (writes it) | `context_conformance_test.go` |
4141
| `record-context-boundaries-v1.cases.json` | cases | `tests/context_conformance.rs` | `context_conformance_test.go` |
42+
| `record-bindings-v1.cases.json` | cases | `tests/binding_conformance.rs` | `binding_conformance_test.go` |
43+
| `record-bindings-v1.expected.rust-native.json` | expected | `tests/binding_conformance.rs` (writes it) | `binding_conformance_test.go` |
4244
| `record-values-v1.cases.json` | cases | `tests/value_conformance.rs` | `value_conformance_test.go` |
4345
| `record-query-refusals-v1.cases.json` | cases | `tests/query_refusal_conformance.rs` | `query_refusal_conformance_test.go` |
4446
| `record-raw-frames-v1.cases.json` | cases | `tests/raw_frame_conformance.rs` | `raw_frame_conformance_test.go` |
@@ -116,7 +118,7 @@ disposable database setup, intentional SQL differences and version reports.
116118

117119
## Context composition and expectations
118120

119-
The [context contract](context-contract.md) covers ordered extensions, canonical
121+
The [context contract](context-contract.md) covers ordered scopes, bindings, canonical
120122
context encodings, typed/generated API calls, stored-context expectations,
121123
tampering and preflight boundaries. The required command runs the new
122124
`context_conformance` Rust binary and `TestContextConformance` /

‎conformance/stack-encrypt/context-contract.md‎

Lines changed: 38 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -20,19 +20,29 @@ Caller input has two distinct purposes:
2020
For a record storing its own context, an expected label checks that stored
2121
value. It does not replace or extend it. A caller label on a plan with a
2222
literal base is refused.
23-
- An **extension** appends to the resolved field context for encryption,
23+
- A **scope** appends to the resolved field context for encryption,
2424
decryption and search. Each call appends in order. Rust
2525
`.extend(7u64).extend(nonempty!("eu"))` and Go
26-
`.Extend(uint64(7)).Extend("eu")` produce `((label)/7u64)/eu`.
27-
Rust `.extend(())` and Go `.Extend()` append nothing. A Rust
26+
`.Scope(uint64(7)).Scope("eu")` produce `((label)/7u64)/eu`.
27+
Rust `.extend(())` and Go `.Scope()` append nothing. A Rust
2828
`DeclaredContext` containing several parts appends all of those parts.
29+
Go `Extend` is the deprecated name of `Scope`. Earlier text called a
30+
scope an extension.
31+
- A **binding** appends after every scope, for encryption and decryption
32+
only. It is in the stored context, which the data key and the AAD derive
33+
under, and in no query context, which the search terms derive under. Rust
34+
`Scope::new(7u64).bind(9u128)` and Go `.Scope(uint64(7)).Bind(uint64(9))`
35+
produce the stored context `((label)/7u64)/9u64` and the query context
36+
`(label)/7u64`. A query that carries a binding is refused before any key
37+
is requested. `record-bindings-v1` (`v1/record-bindings-v1.cases.json`)
38+
specifies this, and both languages are required to run it.
2939

3040
Grouping is significant. Rust `.extend(NonEmpty::from(7u64).with("eu"))` adds
3141
one composite part, producing `(label)/(7u64/eu)`. This has different AAD and
32-
terms from separate extensions. Nested `ContextPiece` values are supported by
33-
Rust's lower-level context APIs; the dynamic record grammar and Go `Extend`
34-
accept scalar extension parts only. Their refusal of a grouped extension is
35-
part of the supported API boundary, not permission to flatten it.
42+
terms from separate scopes. Nested `ContextPiece` values are supported by
43+
Rust's lower-level context APIs; the dynamic record grammar and Go `Scope`
44+
accept scalar parts only. Their refusal of a grouped part is part of the
45+
supported API boundary, not permission to flatten it.
3646

3747
Previously, repeated Rust chain extensions replaced earlier parts. Records
3848
written by those chains still require the
@@ -117,10 +127,27 @@ checks and Rust typed/dynamic cross-opening. The required native `plan_grammar`
117127
binary additionally covers missing caller bases, conflicting sources, invalid
118128
labels, caller-derived queries and empty-batch validation before keyset loading.
119129

130+
## Bindings
131+
132+
`record-bindings-v1` specifies the split between the query context and the
133+
stored context. Each case has a unique `id`, a nonempty `label`, ordered
134+
`scopes`, and nonempty ordered `bind` parts, in the part form above. Every
135+
case encrypts and queries the string `hello` in the `text` field, with the
136+
all-zero deterministic seed.
137+
138+
`v1/record-bindings-v1.expected.rust-native.json` pins, per case, the
139+
descriptor of the stored context, the equality term, one ciphertext, and the
140+
contexts text a plan prints. Rust checks that the term equals the term of the
141+
same plan with no binding, that the key is requested under the stored
142+
context's descriptor, that a query on the bound plan is refused, that the
143+
frozen ciphertext opens under its binding and under no other, and the
144+
contexts text. Go seals and opens through `Scope` and `Bind`, compares its
145+
term and the cipher's contexts text with the vector, opens the Rust
146+
ciphertext, and refuses a query through a cipher with a binding.
147+
120148
## Future roles
121149

122150
This profile describes the current shared context: it feeds the data-key
123-
descriptor, ciphertext AAD and index PRF context. It does not introduce separate
124-
ciphertext-binding and search-scope contexts. That API design remains separate work;
125-
any future split needs explicit compatibility rules and new profile coverage.
126-
It also does not assert plaintext erasure in Go, Python or TypeScript heaps.
151+
descriptor, ciphertext AAD and index PRF context. The split between the
152+
stored context and the query context is in the bindings profile above.
153+
Neither profile asserts plaintext erasure in Go, Python or TypeScript heaps.
Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
{
2+
"version": 1,
3+
"profile": "record-bindings-v1",
4+
"required_capabilities": [
5+
"composition",
6+
"typed-extensions",
7+
"bindings",
8+
"frozen-open"
9+
],
10+
"cases": [
11+
{
12+
"id": "bind-row",
13+
"label": "users",
14+
"scopes": [],
15+
"bind": [
16+
{
17+
"type": "uint64",
18+
"text": "9"
19+
}
20+
]
21+
},
22+
{
23+
"id": "scope-then-bind",
24+
"label": "users",
25+
"scopes": [
26+
{
27+
"type": "uint64",
28+
"text": "42"
29+
}
30+
],
31+
"bind": [
32+
{
33+
"type": "uint64",
34+
"text": "9"
35+
}
36+
]
37+
},
38+
{
39+
"id": "two-scopes-then-bind",
40+
"label": "users",
41+
"scopes": [
42+
{
43+
"type": "uint64",
44+
"text": "42"
45+
},
46+
{
47+
"type": "string",
48+
"text": "eu"
49+
}
50+
],
51+
"bind": [
52+
{
53+
"type": "bytes",
54+
"text": "0102"
55+
}
56+
]
57+
},
58+
{
59+
"id": "scope-then-two-binds",
60+
"label": "tenants/acme",
61+
"scopes": [
62+
{
63+
"type": "int64",
64+
"text": "-3"
65+
}
66+
],
67+
"bind": [
68+
{
69+
"type": "uint64",
70+
"text": "9"
71+
},
72+
{
73+
"type": "string",
74+
"text": "row-a"
75+
}
76+
]
77+
}
78+
]
79+
}
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"version": 1,
3+
"profile": "record-bindings-v1",
4+
"producer": "rust-native",
5+
"cases": {
6+
"bind-row": {
7+
"descriptor": "(users/text)/9u64",
8+
"equality": "7cc383b27a53f75bd06bf941c370a09932a18a89ca0673f9bf00fb33e69c6310",
9+
"ciphertext": "010000000000000000000000000000000096223155634bc8c5d219bc3eb34c73c520009d802d87ef86313ecd30ef6808a4965070a3a64193df36cb51ad183c4e139f2402e53fba89758f1c90e2e82c19e4e185dd172d44e7c23026233169997981b758a73277",
10+
"contexts": "text\n query context: users / text\n stored context: (users / text) / 9u64\n"
11+
},
12+
"scope-then-bind": {
13+
"descriptor": "((users/text)/42u64)/9u64",
14+
"equality": "3be6f2b8c1c1b96d008101a3e1cd90a7114001fa0cd73ed9c76867b4b402f772",
15+
"ciphertext": "0100000000000000000000000000000000f9c0da3e24b68af03533cfba6a9a507e2000076185c49aa3f46d6a2b4658ce65fd558f6ba8cc57e3cc8f35c8d86d2816678e02120f210e87ac66b1482aa3901864447ff3ab943adc19bfcfdbfbbc5f224094e0c2d3",
16+
"contexts": "text\n query context: (users / text) / 42u64\n stored context: ((users / text) / 42u64) / 9u64\n"
17+
},
18+
"scope-then-two-binds": {
19+
"descriptor": "(((tenants/acme/text)/18446744073709551613u64)/9u64)/row-a",
20+
"equality": "f497f570e70d0de22160b1ec71fe3397ac79d715dd338e96dbfce8cbaedb039a",
21+
"ciphertext": "010000000000000000000000000000000071c7ceaea40be16ca3e267d2f845e2df2000100b8c046189c664ee7236eb08363302107e960d5dffe304815489a0d9961c02023fa7bc75ace10e7b201f386fe90d382cedddeaa9050a138c588de8846cabd6864962",
22+
"contexts": "text\n query context: (tenants / acme / text) / -3i64\n stored context: (((tenants / acme / text) / -3i64) / 9u64) / row-a\n"
23+
},
24+
"two-scopes-then-bind": {
25+
"descriptor": "(((users/text)/42u64)/eu)/b64:AQI=",
26+
"equality": "62040e9c1194a8b7de427afa05baed8fbc944da6d1ad710f97d87073233aa1ee",
27+
"ciphertext": "01000000000000000000000000000000003208155c8b6cda75a7cc6438736eb1ad2000198dfcb486d1accb1284b01fbd4b7ee89a08c946c0a77f72b7123736b0d1e57e0211195eba17603642be4b2cb04df15b68e453c9590e9ef4413ad29fbc5b46569d1656",
28+
"contexts": "text\n query context: ((users / text) / 42u64) / eu\n stored context: (((users / text) / 42u64) / eu) / 0x0102\n"
29+
}
30+
}
31+
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1682,7 +1682,7 @@ receive.
16821682
instead of "extension". The frozen vectors do not change, because no key
16831683
on the wire names the operation.
16841684
- **Done already.** Nothing. Today every part is in both contexts.
1685-
- **Tracked in.** Issue #1487 is open. It is exactly this item. Issue #1067 is open and related.
1685+
- **Tracked in.** Issue #1487 is open. It is exactly this item. Its pull request adds the binding kind to the derive, the dynamic grammar, and Go, and the `record-bindings-v1` conformance profile. Issue #1067 is open and related.
16861686
- **Finished when** these are all true, in Rust and in Go:
16871687
- a record with a binding row ID encrypts;
16881688
- a column query finds it;

‎languages/golang/CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,21 @@ listed under **Breaking**. Releases are tagged `languages/golang/vX.Y.Z`.
1010

1111
## [Unreleased]
1212

13+
### Breaking
14+
15+
- **`Cipher.Extend` is now `Cipher.Scope`, and `Cipher.Bind` is new**
16+
(#1487). A scope narrows the data and the queries over it. A binding ties
17+
a ciphertext to its row: it is in the stored context, after every scope,
18+
and in no query context. So `cipher.Scope(tenant).Bind(rowID)` seals a
19+
row that a query through `cipher.Scope(tenant)` still finds, and that
20+
opens only through a cipher with the same binding. A query through a
21+
cipher with a binding is refused as `ErrEncoding`. `Extend` and
22+
`Extension` stay as deprecated aliases of `Scope` and `Scopes` until
23+
0.1.0. The stored bytes of a cipher with no binding do not change.
24+
- The plan wire form has a plan-level `bind` key, a list of parts, beside
25+
the field specs. `record.Plan` has a `Bind` field. An EQL type refuses a
26+
binding, as it refuses an extension.
27+
1328
### Added
1429

1530
- `Checker.Contexts` and `Cipher.Contexts` show the contexts a plan's
Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
package encrypt_test
2+
3+
import (
4+
"bytes"
5+
"context"
6+
"encoding/hex"
7+
"errors"
8+
"path/filepath"
9+
"reflect"
10+
"testing"
11+
12+
"github.com/cipherstash/stack/languages/golang/encrypt"
13+
"github.com/cipherstash/stack/languages/golang/internal/record"
14+
)
15+
16+
type bindingCase struct {
17+
ID string `json:"id"`
18+
Label string `json:"label"`
19+
Scopes []contextPart `json:"scopes"`
20+
Bind []contextPart `json:"bind"`
21+
}
22+
type bindingVector struct {
23+
Descriptor string `json:"descriptor"`
24+
Equality string `json:"equality"`
25+
Ciphertext string `json:"ciphertext"`
26+
Contexts string `json:"contexts"`
27+
}
28+
29+
// A binding is in the stored context, after the scopes, and in no query
30+
// context. Go seals and opens through Scope and Bind, and its term, its
31+
// contexts text and the Rust ciphertext agree with the Rust vectors.
32+
func TestBindingConformance(t *testing.T) {
33+
ctx := context.Background()
34+
client, err := encrypt.NewDeterministicClient(ctx, [32]byte{})
35+
skipMissingConformanceGuest(t, err)
36+
if err != nil {
37+
t.Fatal(err)
38+
}
39+
t.Cleanup(func() { _ = client.Close() })
40+
root := filepath.Join("..", "..", "..", "conformance", "stack-encrypt", "v1")
41+
var corpus struct {
42+
Version int `json:"version"`
43+
Profile string `json:"profile"`
44+
RequiredCapabilities []string `json:"required_capabilities"`
45+
Cases []bindingCase `json:"cases"`
46+
}
47+
readConformanceJSON(t, filepath.Join(root, "record-bindings-v1.cases.json"), &corpus)
48+
if corpus.Version != 1 || corpus.Profile != "record-bindings-v1" || len(corpus.Cases) == 0 || !reflect.DeepEqual(corpus.RequiredCapabilities, []string{"composition", "typed-extensions", "bindings", "frozen-open"}) {
49+
t.Fatal("unsupported bindings profile")
50+
}
51+
var expected struct {
52+
Version int `json:"version"`
53+
Profile string `json:"profile"`
54+
Producer string `json:"producer"`
55+
Cases map[string]bindingVector `json:"cases"`
56+
}
57+
readConformanceJSON(t, filepath.Join(root, "record-bindings-v1.expected.rust-native.json"), &expected)
58+
if expected.Version != 1 || expected.Profile != corpus.Profile || expected.Producer == "" || len(expected.Cases) != len(corpus.Cases) {
59+
t.Fatal("unsupported bindings vectors")
60+
}
61+
parts := func(t *testing.T, inputs []contextPart) []any {
62+
t.Helper()
63+
out := make([]any, 0, len(inputs))
64+
for _, part := range inputs {
65+
switch part.Type {
66+
case "bytes":
67+
b, err := hex.DecodeString(part.Text)
68+
if err != nil {
69+
t.Fatal(err)
70+
}
71+
out = append(out, b)
72+
case "string", "int32", "int64", "uint64":
73+
out = append(out, conformanceValue(t, conformanceInput(part)))
74+
default:
75+
t.Fatal("unsupported context part")
76+
}
77+
}
78+
return out
79+
}
80+
seen := map[string]bool{}
81+
for _, c := range corpus.Cases {
82+
if c.ID == "" || seen[c.ID] {
83+
t.Fatal("empty or repeated case ID")
84+
}
85+
seen[c.ID] = true
86+
t.Run(c.ID, func(t *testing.T) {
87+
want, ok := expected.Cases[c.ID]
88+
if !ok {
89+
t.Fatal("missing vector")
90+
}
91+
decode := func(s string) []byte {
92+
t.Helper()
93+
b, e := hex.DecodeString(s)
94+
if e != nil {
95+
t.Fatal(e)
96+
}
97+
return b
98+
}
99+
label, e := record.ParseContext(c.Label)
100+
if e != nil {
101+
t.Fatal(e)
102+
}
103+
p := &record.Plan{Context: label, Fields: []record.Field{{Name: "text", Kind: record.String, Outputs: []record.Output{record.Ciphertext, record.Equality}}}}
104+
source := []record.Source{{"text": "hello"}}
105+
scoped := client.DefaultKeyset().Scope(parts(t, c.Scopes)...)
106+
bound := scoped.Bind(parts(t, c.Bind)...)
107+
108+
// The cipher prints the contexts Rust pinned.
109+
shown, e := bound.Contexts(ctx, p)
110+
if e != nil {
111+
t.Fatal(e)
112+
}
113+
if shown != want.Contexts {
114+
t.Fatalf("contexts differ from Rust's:\n%s\nwant:\n%s", shown, want.Contexts)
115+
}
116+
117+
// A fresh row's term is the pinned one: the binding is not in
118+
// the query context.
119+
fresh, e := bound.Seal(ctx, p, source)
120+
if e != nil {
121+
t.Fatal(e)
122+
}
123+
if !bytes.Equal(fresh[0]["text"].Terms[record.Equality], decode(want.Equality)) {
124+
t.Fatal("stored term differs")
125+
}
126+
// A query under the scopes alone derives it. A query through the
127+
// bound cipher is refused.
128+
query, e := scoped.QueryTerm(ctx, p, "text", "eq", "hello")
129+
if e != nil {
130+
t.Fatal(e)
131+
}
132+
if len(query.Terms) != 1 || !bytes.Equal(query.Terms[0], decode(want.Equality)) {
133+
t.Fatal("query differs")
134+
}
135+
if _, e := bound.QueryTerm(ctx, p, "text", "eq", "hello"); !errors.Is(e, encrypt.ErrEncoding) {
136+
t.Fatalf("a query with a binding: %v", e)
137+
}
138+
139+
// The Rust ciphertext opens under the binding, and under no
140+
// other. A tampered binding and a binding left out both fail.
141+
frozen := []record.Sealed{{"text": {Ciphertext: decode(want.Ciphertext), Terms: map[record.Output][]byte{record.Equality: decode(want.Equality)}}}}
142+
for _, stored := range [][]record.Sealed{fresh, frozen} {
143+
opened, e := bound.Open(ctx, p, stored)
144+
if e != nil || !reflect.DeepEqual(opened, source) {
145+
t.Fatalf("open: %v; values differ: %v", e, !reflect.DeepEqual(opened, source))
146+
}
147+
tampered := make([]any, len(c.Bind))
148+
for i := range tampered {
149+
tampered[i] = "tampered"
150+
}
151+
if _, e := scoped.Bind(tampered...).Open(ctx, p, stored); e == nil {
152+
t.Fatal("a tampered binding opened the row")
153+
}
154+
if _, e := scoped.Open(ctx, p, stored); e == nil {
155+
t.Fatal("a binding left out opened the row")
156+
}
157+
}
158+
})
159+
}
160+
}

0 commit comments

Comments
 (0)