Repository navigation
Conversation
Nothing explained how to build a binding on Stack Encrypt. The knowledge was spread over the dynamic module's docs, the Go guest's module docs, stack-guest-abi, ADR-0007 and ADR-0008, and an author had to reconstruct it from the Go SDK. A Python integration has started without it. The guide ships in the crate docs as `dynamic::guide`, included from `docs/language-integration.md`, so it renders on docs.rs beside the API it describes. It is ordered contract before API: the binding versus the language SDK; native versus WebAssembly; the three operations and the Go guest's exports; the plan grammar; control messages versus plaintext, both frames, neither a tree; the plaintext hygiene rules and the heap tests that prove them; the step loop, the token import and the cancellation contract; the status table and se_last_error; versioning and the frozen stored-rows fixtures; one int32 stored as EQL v4 IntegerEq, traced through encrypt, query and decrypt with the bytes from the committed fixtures; and a checklist for a new binding. The frame format stays in vitaminc-aead-frame's documentation and is linked, not restated. The frame bytes in the worked example are asserted by doctests, so the guide fails the build if the engine's bytes move. The stored row and the query term are quoted from fixtures the Go SDK and Rust both read, named by file and key. Linked from the crate docs, the SDK design principles and the Go SDK's README. Closes #1254.
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configuration
You can disable this status message by setting the Use the checkbox below for a quick retry:
Comment |
|
Mutation testing (cargo-mutants,
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0df55a0ca5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | 2 | `ENCODING` | malformed input at the boundary; fix the caller | | ||
| | 3 | `STATE` | a call out of order: before init, after shutdown, an unknown handle | | ||
| | 4 | `INTERNAL` | a bug in the guest; report it | | ||
| | 5 | `KMS_UNAUTHORIZED` | refresh the token and retry; the only retryable one | |
There was a problem hiding this comment.
Calling KMS_UNAUTHORIZED “the only retryable one” incorrectly rules out retrying transient failures reported as KMS_TRANSPORT, such as a timeout or connection failure. The status contract in packages/stack-guest-abi/src/status.rs only designates code 5 as the sole status to handle by refreshing the token; code 9 may still be retryable through the normal transport policy. A binding author following this table would unnecessarily surface recoverable network failures, so qualify this as “the only one retryable after a token refresh” rather than the only retryable status.
Useful? React with 👍 / 👎.
This branch has not been deployed
1 participant
Summary
A guide to building a language integration on Stack Encrypt, for an author who is new to CipherStash: what a binding is and what it is not, what crosses it, what the engine expects of the host, and how to prove the result. The Go SDK is the reference, and every rule names where in it the rule is kept. It ships in the crate documentation as
stack_encrypt::dynamic::guide, so it renders on docs.rs next to the API it describes.Stack Encrypt is the Rust encryption engine. Every language other than Rust reaches it through the
dynamicmodule. Until now the knowledge needed to do that was spread over module docs, the Go guest,stack-guest-abiand two ADRs, and a Python integration has started without it.Changes
packages/stack-encrypt/docs/language-integration.md: the guide. Twelve sections, ordered contract before API: binding versus language SDK; native versus WebAssembly; the three operations with the exactdynamiccalls and the Go guest's exports (step loop included); the plan grammar; control messages versus plaintext (both frames, no value tree); plaintext hygiene and the heap tests; keys, the token import and the cancellation contract; errors (the status table,se_last_error, no values in messages); versioning and the frozen stored-rows fixtures; oneint32as EQL v4IntegerEqtraced end to end with real bytes; a checklist; where the wire format lives (linked, not restated).packages/stack-encrypt/src/dynamic/mod.rs:pub mod guideincludes the file as docs.packages/stack-encrypt/src/lib.rs,docs/sdk-design-principles.md,languages/golang/encrypt/README.md: one pointer each.packages/stack-encrypt/CHANGELOG.md: Unreleased entry.Verification
mise run doc:stack-encrypt(rustdoc, warnings as errors): clean. Every intra-doc link resolves.cargo test -p stack-encrypt --doc --all-features: 46 passed, including the two doctests in the guide. The worked example's frame bytes (theint32value, the row, the plan) are asserted, not quoted, so the guide fails the build if the engine's bytes move.cargo nextest run -p stack-encrypt --all-features: 684 passed.cargo fmt --check: clean.packages/eql/tests/encryption/fixtures/v4_rows.json(row 1,age) andv4_queries.json(age), named in the text so a reader can check them.Related
Closes #1254.
Review notes
nexttoday.vitaminc-aead-frame's docs and the conformance-corpus issue in that repository.