From 56b811368a93c3e34dde23ffa6705fd78a4e36d1 Mon Sep 17 00:00:00 2001 From: Dan Draper Date: Tue, 17 Nov 2026 22:44:23 +1100 Subject: [PATCH 1/3] feat(golang): encrypttest.NewClient, an offline client for application tests An application whose CI has no CipherStash credentials could not run any test that reaches an encrypting write path: encrypt.Cipher is concrete, Decrypter takes internal types, and the only credential-free client was NewDeterministicClient in export_test.go, out of reach outside the module (#1696). encrypttest.NewClient(t) returns a real *encrypt.Client over the deterministic-kms test build of the guest, so generated code, keysets, Scope, Bind and Decrypter all work unchanged. stack-kms's DeterministicSource derives each data key from a seed and the descriptor and refuses a tag from another descriptor as ZeroKMS's 403, so a wrong context still fails with ErrForbidden and a foreign keyset with ErrForeignKeyset. Every keyset exists, by name or id, with nothing to provision. The default seed is fixed, so fixture loaders and readers in separate test processes share keys; WithSeed chooses another. The constructor needs encrypt's unexported instance, and encrypttest imports encrypt, so encrypt registers it with internal/testclient on init, following the eqlguest pattern. No public function builds a client over a caller-chosen guest, and the production guests refuse a bare seed as malformed config (TestAProductionGuestRefusesASeed). NewClient picks the EQL test build when package eql is linked, as embeddedGuest does, and fails the test outside a test binary (testing.Testing). The test builds move from encrypt/testdata to encrypt/encrypttest/wasm, one location for the package's embed and the hermetic tests, and the Go release now builds, hashes and commits them with the production guests. --- .github/workflows/release-golang.yml | 29 ++- .github/workflows/tests-golang.yml | 27 ++- .gitignore | 9 +- AGENTS.md | 2 +- SECURITY.md | 5 + languages/golang/CHANGELOG.md | 14 ++ languages/golang/encrypt/README.md | 52 +++- .../golang/encrypt/encrypttest/client.go | 162 +++++++++++++ .../golang/encrypt/encrypttest/client_test.go | 222 ++++++++++++++++++ .../golang/encrypt/encrypttest/encrypttest.go | 11 +- .../encrypt/encrypttest/encrypttest_test.go | 3 +- .../encrypttest/internal/withouteql/doc.go | 6 + .../internal/withouteql/withouteql_test.go | 30 +++ .../encrypt/encrypttest/postgres_test.go | 127 ++++++++++ .../golang/encrypt/encrypttest/wasm/README.md | 20 ++ languages/golang/encrypt/eql/guest.go | 4 +- languages/golang/encrypt/eql/wasm/README.md | 3 +- .../encrypt/exchange_conformance_test.go | 4 +- languages/golang/encrypt/export_test.go | 44 +--- languages/golang/encrypt/guest/Cargo.toml | 6 +- .../golang/encrypt/guest/src/deterministic.rs | 7 +- .../encrypt/internal/testclient/testclient.go | 34 +++ languages/golang/encrypt/testclient.go | 52 ++++ languages/golang/encrypt/testclient_test.go | 34 +++ languages/golang/encrypt/wasm/README.md | 7 +- mise.toml | 27 ++- .../__tests__/go-release-artifact.test.mjs | 7 +- .../stack-exchange-conformance.test.mjs | 4 +- .../stack-lifecycle-conformance.test.mjs | 2 +- scripts/stack-conformance.sh | 2 +- scripts/stack-eql-conformance.mjs | 2 +- scripts/stack-exchange-conformance.mjs | 4 +- scripts/stack-lifecycle-conformance.mjs | 2 +- 33 files changed, 856 insertions(+), 108 deletions(-) create mode 100644 languages/golang/encrypt/encrypttest/client.go create mode 100644 languages/golang/encrypt/encrypttest/client_test.go create mode 100644 languages/golang/encrypt/encrypttest/internal/withouteql/doc.go create mode 100644 languages/golang/encrypt/encrypttest/internal/withouteql/withouteql_test.go create mode 100644 languages/golang/encrypt/encrypttest/postgres_test.go create mode 100644 languages/golang/encrypt/encrypttest/wasm/README.md create mode 100644 languages/golang/encrypt/internal/testclient/testclient.go create mode 100644 languages/golang/encrypt/testclient.go create mode 100644 languages/golang/encrypt/testclient_test.go diff --git a/.github/workflows/release-golang.yml b/.github/workflows/release-golang.yml index b8b919d597..87743f37c6 100644 --- a/.github/workflows/release-golang.yml +++ b/.github/workflows/release-golang.yml @@ -2,10 +2,14 @@ name: Release (Go) # Tags a release of the Go module (languages/golang) that `go get` can use. # -# The module embeds three WASI guests built from Rust (encrypt/wasm, -# encrypt/eql/wasm, auth/wasm). They are gitignored on main, and Go fetches a -# module version as the files committed at its tag, so a tag on a main commit -# would build and then fail at `NewClient` with ErrGuestNotBuilt. This +# The module embeds five WASI guests built from Rust: the three production +# guests (encrypt/wasm, encrypt/eql/wasm, auth/wasm) and the two +# deterministic-kms test builds that package encrypttest embeds +# (encrypt/encrypttest/wasm), which give an application's tests a client with +# no ZeroKMS. They are gitignored on main, and Go fetches a module version as +# the files committed at its tag, so a tag on a main commit would build and +# then fail at `NewClient` with ErrGuestNotBuilt, and at +# `encrypttest.NewClient` with its own not-built error. This # workflow builds the guests at the commit it runs on, commits them on a # release-only commit that no branch points at, tags that commit # `languages/golang/v` (the prefix Go requires for a module in a @@ -64,6 +68,8 @@ env: languages/golang/encrypt/wasm/stack_encrypt_guest.wasm languages/golang/encrypt/eql/wasm/stack_encrypt_guest_eql.wasm languages/golang/auth/wasm/stack_auth_guest.wasm + languages/golang/encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm + languages/golang/encrypt/encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm concurrency: group: release-golang @@ -165,14 +171,19 @@ jobs: grep -qF "'go-$VERSION'" release/cipherstash-encrypt-v4.sql \ || { echo "::error::the v4 bundle is not stamped go-$VERSION"; exit 1; } + # The test builds ship too: package encrypttest embeds them. They are + # built here, before the hash, so the hash covers them as it covers the + # production guests. - name: Build the guests run: | mise run wasm:guest:build mise run wasm:guest:build:eql mise run wasm:auth-guest:build + mise run wasm:guest:build:deterministic + mise run wasm:guest:build:eql:deterministic - # Hashed before the test builds and the tests run, and checked again - # after them below, so the guests committed are the ones tested. + # Hashed before the tests run, and checked again after them below, so + # the guests committed are the ones tested. - name: Hash the guests run: | set -euo pipefail @@ -181,12 +192,6 @@ jobs: sha256sum "${guests[@]}" > release-out/guests.sha256 cat release-out/guests.sha256 - # The deterministic test builds the hermetic Go tests load. - - name: Build the test guests - run: | - mise run wasm:guest:build:deterministic - mise run wasm:guest:build:eql:deterministic - - name: Go tests against the guests being released run: mise run go:test diff --git a/.github/workflows/tests-golang.yml b/.github/workflows/tests-golang.yml index 84a616178e..de27dfa1b2 100644 --- a/.github/workflows/tests-golang.yml +++ b/.github/workflows/tests-golang.yml @@ -212,11 +212,12 @@ jobs: - name: stack-encrypt guest release build and import-surface gate run: mise run wasm:guest:build - # The deterministic-kms TEST build, under encrypt/testdata where no - # build or embed sees it: the Go tests open the record fixture Rust - # sealed through it, and run round trips with no ZeroKMS. The tests - # skip when it is absent, so a build that forgets this step would pass - # with less coverage, which is why the job builds it unconditionally. + # The deterministic-kms TEST build, under encrypt/encrypttest/wasm, + # which package encrypttest embeds: the Go tests open the record + # fixture Rust sealed through it, and run round trips with no ZeroKMS. + # The encrypt package's tests skip when it is absent, so a build that + # forgets this step would pass with less coverage, which is why the job + # builds it unconditionally. encrypttest's own tests fail without it. - name: stack-encrypt guest deterministic test build run: mise run wasm:guest:build:deterministic @@ -243,7 +244,7 @@ jobs: # same bytes rather than a stale or rebuilt guest. - name: Record the guests' checksums run: | - for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/testdata/stack_encrypt_guest_deterministic.wasm encrypt/eql/wasm/stack_encrypt_guest_eql.wasm encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm auth/wasm/stack_auth_guest.wasm; do + for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm encrypt/eql/wasm/stack_encrypt_guest_eql.wasm encrypt/encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm auth/wasm/stack_auth_guest.wasm; do (cd languages/golang && openssl dgst -sha256 "$guest" | awk '{print $NF}' > "$guest.sha256" && echo "$guest sha256 $(cat "$guest.sha256")") done @@ -254,12 +255,12 @@ jobs: path: | languages/golang/encrypt/wasm/stack_encrypt_guest.wasm languages/golang/encrypt/wasm/stack_encrypt_guest.wasm.sha256 - languages/golang/encrypt/testdata/stack_encrypt_guest_deterministic.wasm - languages/golang/encrypt/testdata/stack_encrypt_guest_deterministic.wasm.sha256 + languages/golang/encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm + languages/golang/encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm.sha256 languages/golang/encrypt/eql/wasm/stack_encrypt_guest_eql.wasm languages/golang/encrypt/eql/wasm/stack_encrypt_guest_eql.wasm.sha256 - languages/golang/encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm - languages/golang/encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm.sha256 + languages/golang/encrypt/encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm + languages/golang/encrypt/encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm.sha256 languages/golang/auth/wasm/stack_auth_guest.wasm languages/golang/auth/wasm/stack_auth_guest.wasm.sha256 if-no-files-found: error @@ -433,7 +434,7 @@ jobs: - name: The guests are the ones Linux built and checked run: | cd languages/golang - for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/testdata/stack_encrypt_guest_deterministic.wasm encrypt/eql/wasm/stack_encrypt_guest_eql.wasm encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm auth/wasm/stack_auth_guest.wasm; do + for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm encrypt/eql/wasm/stack_encrypt_guest_eql.wasm encrypt/encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm auth/wasm/stack_auth_guest.wasm; do want=$(cat "$guest.sha256") got=$(openssl dgst -sha256 "$guest" | awk '{print $NF}') if [ "$want" != "$got" ]; then @@ -518,7 +519,7 @@ jobs: - name: The guests are the ones wasi-check built and checked run: | cd languages/golang - for guest in encrypt/testdata/stack_encrypt_guest_deterministic.wasm encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm; do + for guest in encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm encrypt/encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm; do want=$(cat "$guest.sha256") got=$(openssl dgst -sha256 "$guest" | awk '{print $NF}') if [ "$want" != "$got" ]; then @@ -595,7 +596,7 @@ jobs: - name: The guests are the ones the wasi-check job built and checked run: | cd languages/golang - for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/testdata/stack_encrypt_guest_deterministic.wasm encrypt/eql/wasm/stack_encrypt_guest_eql.wasm encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm auth/wasm/stack_auth_guest.wasm; do + for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm encrypt/eql/wasm/stack_encrypt_guest_eql.wasm encrypt/encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm auth/wasm/stack_auth_guest.wasm; do want=$(cat "$guest.sha256") got=$(openssl dgst -sha256 "$guest" | awk '{print $NF}') if [ "$want" != "$got" ]; then diff --git a/.gitignore b/.gitignore index 268d67b85b..820e27bf1d 100644 --- a/.gitignore +++ b/.gitignore @@ -118,7 +118,8 @@ languages/golang/auth/wasm/*.wasm languages/golang/encrypt/wasm/*.sha256 languages/golang/encrypt/eql/wasm/*.sha256 languages/golang/auth/wasm/*.sha256 -# The deterministic-kms TEST build of the stack-encrypt guest, from `mise run -# wasm:guest:build:deterministic`; under testdata so no binary embeds it. -languages/golang/encrypt/testdata/*.wasm -languages/golang/encrypt/testdata/*.sha256 +# The deterministic-kms TEST builds of the stack-encrypt guest, from `mise run +# wasm:guest:build:deterministic` and `wasm:guest:build:eql:deterministic`. +# Package encrypttest embeds them; the release commits them on the tag. +languages/golang/encrypt/encrypttest/wasm/*.wasm +languages/golang/encrypt/encrypttest/wasm/*.sha256 diff --git a/AGENTS.md b/AGENTS.md index b3494d5e63..5f1881449d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -92,7 +92,7 @@ Every npm package except EQL lives under `languages/typescript/`: packages in `l links are provenance only. - `packages/stack-auth`, `packages/stack-profile`, `packages/stack-kms`, `packages/stack-encrypt`, `packages/stack-encrypt-derive`, `packages/stack-guest-abi`: The Rust crates imported from `cipherstash/cipherstash-suite` with their history — `stack-auth` and `stack-profile` (published to crates.io, one version group), `stack-kms` (published to crates.io from 0.1.0, its own version group, re-exported by `stack-encrypt` as `stack_encrypt::kms`), `stack-encrypt` and `stack-encrypt-derive` (published to crates.io from 0.1.0, one version group; `eql-bindings`' `stack-encrypt` feature depends on them from the registry), and `stack-guest-abi` (`publish = false`). They are the members of the **root Cargo workspace**, with the three node binding crates below. See "Working on the Rust crates". - `languages/typescript/packages/auth`, `languages/typescript/packages/profile`, `languages/typescript/packages/stack-auth-wasm`: The node bindings of those crates. `@cipherstash/auth` (napi-rs v2) and its six `platforms/*` packages are published to npm from this repository by `release.yml` (`auth-artifacts`, `publish-auth`); a change to what it ships, the `stack-auth` crate included, needs an `@cipherstash/auth` changeset (`require-auth-npm-changeset.yml`). `@cipherstash/profile` and its platforms are private and never published; `@cipherstash/stack-auth-wasm` is private and builds the wasm that `@cipherstash/auth` ships. Their `build` and `test` scripts never invoke cargo; `build:native`, `build:debug` and `test:cargo` do. -- `languages/golang`: The Go module — the SDK `encrypt` with its generated-code support `encrypt/gensupport` and the policy packages `encrypt/policy` and `encrypt/policy/protosource`; the credential package `auth`; the generator `stashgen` and its command `cmd/stashgen`; and `internal` (the shared guest plumbing and the `record` wire model). A wazero host with no cgo. Its two WASI guests (`encrypt/guest`, `auth/guest`) are detached Cargo workspaces built by `mise run wasm:guest:build` and `mise run wasm:auth-guest:build`; `mise run wasm:guest:build:deterministic` builds the seeded TEST build the hermetic Go tests use; the `.wasm` files they embed are gitignored. The stack-encrypt guest has a second build with the EQL types (`mise run wasm:guest:build:eql`, cargo feature `eql`, linking `eql-bindings` by path; `wasm:guest:build:eql:deterministic` is its test build), embedded by `encrypt/eql` and registered on import, so a program whose generated code names an EQL type runs it (ADR-0007, amended). `encrypt/eql`'s types and `Types` table are generated from the EQL catalog by `eql-codegen` (`eql_gen.go`, written by `mise run types:generate` in `packages/eql` and drift-gated by `types:check` and `cargo test -p eql-codegen`). Generated `*_stash.go` files are committed and CI fails when `go generate ./...` changes one. Releases are cut by hand with `.github/workflows/release-golang.yml` (`gh workflow run release-golang.yml -f version=X.Y.Z[-pre] --ref `): because the guests are gitignored on main and Go fetches a version as the files committed at its tag, the workflow builds them, commits them on a release-only commit no branch points at, tags it `languages/golang/vX.Y.Z` and pushes the tag alone, then attaches the EQL v4 SQL bundle to the GitHub release. The ref must carry the EQL v4 bundle, or the build stops at "Build the EQL SQL bundles". `scripts/go-release-version.mjs` refuses, before anything is built, every version Go would refuse (non-canonical semver, `+build` metadata, a v2+ major on a module path with no `/vN` suffix, a version shaped like a pseudo-version), a final version dispatched from anywhere but `main`, and a final version while `languages/golang/go.mod` pins a `github.com/cipherstash/vitaminc/…` module at a pseudo-version (vitaminc's Go bindings have no tags, and a TEMPORARY pin on an unreleased commit must be gone before the module is tagged); a pre-release may come from a branch and may carry such a pin. The build job also refuses a version the Go proxy already lists in `@v/list`, which catches a tag deleted after the proxy fetched it; it never asks the proxy for the version itself before the tag exists, because the proxy would cache "not found" for up to 30 minutes and `verify` would fail after the push. The build checks the `Cargo.lock` of the EQL workspace and both guest workspaces with `--locked` first, since none of those builds passes it. It runs in a job with no write token and hands the guests to a `publish` job that holds `contents: write` and runs only git and gh. `publish` fetches the commit with plain unauthenticated git rather than `actions/checkout`, whose `token` input defaults to the job's writable token, and refuses a release commit whose tree is not the one the build tested. `publish` takes the paths it commits from the workflow's fixed `GUESTS` list, never from the artifact, and refuses a `guests.sha256` that is not exactly one SHA-256 line for each of those three guests: the build job runs third-party code after writing that manifest, so a path read from it could put any file on the tag (`scripts/__tests__/go-release-artifact.test.mjs`). A version is immutable once the Go proxy has fetched it, so a tag is never moved or deleted: if `publish` or `verify` fails after the tag is pushed, use "Re-run failed jobs" on the same run, which keeps a tag that run pushed and creates or completes the release; a new dispatch of the same version is refused. Never tag a main commit by hand: `go get` would fetch a module with no guests. +- `languages/golang`: The Go module — the SDK `encrypt` with its generated-code support `encrypt/gensupport`, its test package `encrypt/encrypttest` (context assertions, and `NewClient`: an offline client over the deterministic test builds, for an application's tests) and the policy packages `encrypt/policy` and `encrypt/policy/protosource`; the credential package `auth`; the generator `stashgen` and its command `cmd/stashgen`; and `internal` (the shared guest plumbing and the `record` wire model). A wazero host with no cgo. Its two WASI guests (`encrypt/guest`, `auth/guest`) are detached Cargo workspaces built by `mise run wasm:guest:build` and `mise run wasm:auth-guest:build`; `mise run wasm:guest:build:deterministic` and `wasm:guest:build:eql:deterministic` build the seeded TEST builds into `encrypt/encrypttest/wasm`, which `encrypttest` embeds and the hermetic Go tests read; the `.wasm` files are gitignored. The stack-encrypt guest has a second build with the EQL types (`mise run wasm:guest:build:eql`, cargo feature `eql`, linking `eql-bindings` by path; `wasm:guest:build:eql:deterministic` is its test build), embedded by `encrypt/eql` and registered on import, so a program whose generated code names an EQL type runs it (ADR-0007, amended). `encrypt/eql`'s types and `Types` table are generated from the EQL catalog by `eql-codegen` (`eql_gen.go`, written by `mise run types:generate` in `packages/eql` and drift-gated by `types:check` and `cargo test -p eql-codegen`). Generated `*_stash.go` files are committed and CI fails when `go generate ./...` changes one. Releases are cut by hand with `.github/workflows/release-golang.yml` (`gh workflow run release-golang.yml -f version=X.Y.Z[-pre] --ref `): because the guests are gitignored on main and Go fetches a version as the files committed at its tag, the workflow builds them, commits them on a release-only commit no branch points at, tags it `languages/golang/vX.Y.Z` and pushes the tag alone, then attaches the EQL v4 SQL bundle to the GitHub release. The ref must carry the EQL v4 bundle, or the build stops at "Build the EQL SQL bundles". `scripts/go-release-version.mjs` refuses, before anything is built, every version Go would refuse (non-canonical semver, `+build` metadata, a v2+ major on a module path with no `/vN` suffix, a version shaped like a pseudo-version), a final version dispatched from anywhere but `main`, and a final version while `languages/golang/go.mod` pins a `github.com/cipherstash/vitaminc/…` module at a pseudo-version (vitaminc's Go bindings have no tags, and a TEMPORARY pin on an unreleased commit must be gone before the module is tagged); a pre-release may come from a branch and may carry such a pin. The build job also refuses a version the Go proxy already lists in `@v/list`, which catches a tag deleted after the proxy fetched it; it never asks the proxy for the version itself before the tag exists, because the proxy would cache "not found" for up to 30 minutes and `verify` would fail after the push. The build checks the `Cargo.lock` of the EQL workspace and both guest workspaces with `--locked` first, since none of those builds passes it. It runs in a job with no write token and hands the guests to a `publish` job that holds `contents: write` and runs only git and gh. `publish` fetches the commit with plain unauthenticated git rather than `actions/checkout`, whose `token` input defaults to the job's writable token, and refuses a release commit whose tree is not the one the build tested. `publish` takes the paths it commits from the workflow's fixed `GUESTS` list, never from the artifact, and refuses a `guests.sha256` that is not exactly one SHA-256 line for each of those five guests (the three production guests and the two test builds `encrypttest` embeds): the build job runs third-party code after writing that manifest, so a path read from it could put any file on the tag (`scripts/__tests__/go-release-artifact.test.mjs`). A version is immutable once the Go proxy has fetched it, so a tag is never moved or deleted: if `publish` or `verify` fails after the tag is pushed, use "Re-run failed jobs" on the same run, which keeps a tag that run pushed and creates or completes the release; a new dispatch of the same version is refused. Never tag a main commit by hand: `go get` would fetch a module with no guests. - `e2e/*`: Cross-package end-to-end tests (package managers, supply chain, Prisma example README) - `e2e/migration-guide`: Unpublished, separately installed npm examples for the Protect/EQL v2 to Stack/EQL v3 guide. See its README before running; Postgres requires a disposable database and DynamoDB persistence is in memory. - `languages/typescript/examples/*`: Working apps (basic, prisma, supabase-worker) diff --git a/SECURITY.md b/SECURITY.md index acaea5909e..27e87ee1ae 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -38,6 +38,11 @@ from the stack-* crates), released by `.github/workflows/release-golang.yml` as `languages/golang/vX.Y.Z` tags. All of these are in scope for security reports on the same terms as the npm packages above. +The Go module's `encrypt/encrypttest` package ships test builds of the +engine whose keys derive from a published seed. Those keys are not secret by +design: the package is for tests only. A way for a production client to load +a test build, or for a test build to reach ZeroKMS, is in scope. + The five stack-* crates are licensed under the PolyForm Internal Use License 1.0.0 (each crate's `LICENSE`), not the repository's MIT licence: they may be used for internal business operations only, and not redistributed. That diff --git a/languages/golang/CHANGELOG.md b/languages/golang/CHANGELOG.md index fd041b636b..1171f06bdb 100644 --- a/languages/golang/CHANGELOG.md +++ b/languages/golang/CHANGELOG.md @@ -10,6 +10,20 @@ listed under **Breaking**. Releases are tagged `languages/golang/vX.Y.Z`. ## [Unreleased] +### Added + +- **`encrypttest.NewClient`: a client for your application's tests that + needs no network and no CipherStash credentials** (#1696). It returns a + real `*encrypt.Client` over a test build of the engine. Each data key + derives from a seed in place of ZeroKMS. Your generated code runs + unchanged, and EQL v4 columns accept the values it writes. Every keyset + exists, selected by name or id. A cipher still refuses another keyset's + value with `ErrForeignKeyset`, and a wrong context fails with + `ErrForbidden`. `encrypttest.WithSeed` chooses the seed. The keys are not + secret, so import `encrypttest` only from `_test.go` files. + The release now ships the two test builds of the engine, under + `encrypt/encrypttest/wasm`. + ## [0.1.0-rc.5] - 2026-11-16 ### Upgrading from rc.4 diff --git a/languages/golang/encrypt/README.md b/languages/golang/encrypt/README.md index aaa936866f..e743d57d50 100644 --- a/languages/golang/encrypt/README.md +++ b/languages/golang/encrypt/README.md @@ -798,6 +798,49 @@ gives an example and a workaround for each: A filter with more than one condition reads each array to `JSONReadOptions.WildcardBound` elements, as the element match does. +## Testing your application + +Package `encrypttest` gives a test a client that needs no network and no +CipherStash credentials. Use it in CI that has no route to ZeroKMS. + +1. Create the client in the test. It closes when the test ends. + + ```go + import "github.com/cipherstash/stack/languages/golang/encrypt/encrypttest" + + func TestSaveUser(t *testing.T) { + client := encrypttest.NewClient(t) + cipher := client.Keyset(encrypt.KeysetName("tenant-42")) + ``` + +2. Call your code with it, as you would call it with a production client. + + ```go + encrypted, err := users.Encrypt(t.Context(), cipher, people) + if err != nil { + t.Fatal(err) + } + // Insert, query with users.Fields.Email.Eq, then read back: + opened, err := users.Decrypt(t.Context(), client, encrypted) + ``` + +The client runs the same engine and generated code as a production client. +Only the key source differs: each data key derives from a seed, not from +ZeroKMS. An EQL v4 column accepts its values, and its query terms match them. + +It fails as a production client fails. A cipher refuses another keyset's +value with `ErrForeignKeyset`. A wrong context fails with `ErrForbidden`. + +Every keyset exists, so a test selects any name or id with nothing to +create. A test therefore never sees `ErrNotFound` for a missing keyset. + +Every client with the default seed opens what another sealed, in any test +process. `encrypttest.WithSeed` chooses another seed. + +Never seal real data with it: anyone with the seed derives every key. Import +`encrypttest` only from `_test.go` files, so it stays out of production +binaries. `NewClient` fails the test outside a test binary. + ## Building The package embeds `wasm/stack_encrypt_guest.wasm`, a build artefact of the @@ -813,9 +856,12 @@ tag, fetches a tree without the builds; it compiles, and `NewClient` returns In a checkout of this repository the builds are not committed: run `mise run wasm:guest:build` (and `mise run wasm:auth-guest:build` for the credential guest) before `go test`, and -`mise run wasm:guest:build:deterministic` for the test build the hermetic -round-trip and fixture tests use. Without the builds `NewClient` returns -`ErrGuestNotBuilt` and the tests skip. +`mise run wasm:guest:build:deterministic` and +`mise run wasm:guest:build:eql:deterministic` for the test builds that +package `encrypttest` embeds. The hermetic round-trip and fixture tests use +them too. Without the builds `NewClient` returns `ErrGuestNotBuilt` and the +tests skip; `encrypttest.NewClient` fails its test. A tagged version carries +the test builds too. ## Licence diff --git a/languages/golang/encrypt/encrypttest/client.go b/languages/golang/encrypt/encrypttest/client.go new file mode 100644 index 0000000000..01c8f7d8e0 --- /dev/null +++ b/languages/golang/encrypt/encrypttest/client.go @@ -0,0 +1,162 @@ +package encrypttest + +import ( + "context" + "crypto/sha256" + "embed" + "testing" + + "github.com/cipherstash/stack/languages/golang/encrypt" + "github.com/cipherstash/stack/languages/golang/encrypt/internal/eqlguest" + "github.com/cipherstash/stack/languages/golang/encrypt/internal/testclient" +) + +// The deterministic-kms test builds of the guest, copied here by `mise run +// wasm:guest:build:deterministic` and `mise run +// wasm:guest:build:eql:deterministic`. They are not committed on main; the +// release workflow commits them on the tag. The directory is embedded so the +// package compiles without them; NewClient reports their absence. +// +//go:embed wasm +var guestFS embed.FS + +const ( + guestPath = "wasm/stack_encrypt_guest_deterministic.wasm" + eqlGuestPath = "wasm/stack_encrypt_guest_eql_deterministic.wasm" +) + +// defaultSeed is the seed NewClient uses without WithSeed. It never +// changes, so values sealed under it in one test process open in another. +var defaultSeed = sha256.Sum256([]byte("github.com/cipherstash/stack/languages/golang/encrypt/encrypttest default seed")) + +// A ClientOption configures [NewClient]. +type ClientOption func(*clientOptions) + +type clientOptions struct { + seed [32]byte +} + +// WithSeed derives every data key from seed in place of the default seed. +// Use it to keep one test's values apart from another's. A value sealed +// under one seed does not open under another, and fails with +// [encrypt.ErrForbidden]. +func WithSeed(seed [32]byte) ClientOption { + return func(o *clientOptions) { o.seed = seed } +} + +// NewClient returns a client for a test that needs no network and no +// CipherStash credentials. It closes the client when the test and its +// subtests finish. It fails the test, and never skips it, when the client +// cannot start. +// +// func TestSaveUser(t *testing.T) { +// client := encrypttest.NewClient(t) +// cipher := client.Keyset(encrypt.KeysetName("tenant-a")) +// +// rows, err := users.Encrypt(t.Context(), cipher, []users.User{{Email: "ada@example.com"}}) +// if err != nil { +// t.Fatal(err) +// } +// // Store rows in PostgreSQL, query them, then read them back: +// back, err := users.Decrypt(t.Context(), client, rows) +// } +// +// The client runs the same engine and generated code as a production +// client. Only the key source differs: each data key derives from a seed and +// from the context the value is sealed under, so the client never calls +// ZeroKMS. An EQL column accepts the values it writes, and its query terms +// match them. +// +// It fails as a production client fails: +// +// - A cipher bound to one keyset refuses a value sealed under another +// keyset with [encrypt.ErrForeignKeyset]. +// - A decrypt under a context other than the value's fails with +// [encrypt.ErrForbidden], as ZeroKMS refuses it. +// - A row whose context field is not the cipher's context fails with +// [encrypt.ErrContextMismatch]. +// +// Every keyset exists. A keyset selected by a name or an id needs nothing +// created first, and [encrypt.KeysetName]("default") selects the default +// keyset. So a test cannot see [encrypt.ErrNotFound] for a missing keyset, +// or [encrypt.ErrForbidden] for a keyset the client has no grant for. The +// client has no token, so it never returns [encrypt.ErrUnauthorized]. +// +// # Seeds +// +// Every client with the default seed opens what any other client with it +// sealed, in any process. So a test that loads fixtures and a test that +// reads them share keys with no setup. The default seed never changes. +// [WithSeed] chooses another. A seed changes the data keys only: search +// terms depend on the keyset alone, so two seeds give a value the same +// terms. +// +// # Not for production +// +// The keys are not secret: anyone with the seed derives every key, and the +// default seed is in this package's source. Never seal real data with this +// client. Nothing it seals opens under a production client, and nothing a +// production client seals opens under it. +// +// Import this package only from _test.go files. Go then links the test +// builds of the engine it embeds into test binaries only. NewClient also +// fails the test outside a test binary, as [testing.Testing] reports. +// +// # Engine builds +// +// A program whose generated code names an EQL type links package +// [github.com/cipherstash/stack/languages/golang/encrypt/eql]. A production +// client in that program runs the engine build with the EQL types, and a +// client from NewClient runs the test build with them. Otherwise both run +// the build without them. +func NewClient(tb testing.TB, opts ...ClientOption) *encrypt.Client { + tb.Helper() + if !testing.Testing() { + tb.Fatal("encrypttest: NewClient runs only in a test binary, because its keys are not secret") + } + o := clientOptions{seed: defaultSeed} + for _, opt := range opts { + opt(&o) + } + wasm, err := testGuest() + if err != nil { + tb.Fatal(err) + } + built, err := testclient.New(context.Background(), wasm, o.seed) + if err != nil { + tb.Fatalf("encrypttest: %v", err) + } + client, ok := built.(*encrypt.Client) + if !ok { + tb.Fatalf("encrypttest: the constructor returned %T, not *encrypt.Client", built) + } + tb.Cleanup(func() { + if err := client.Close(); err != nil { + tb.Errorf("encrypttest: closing the client: %v", err) + } + }) + return client +} + +// testGuest is the test build matching the build a production client in +// this program runs: the one with the EQL types when package eql is linked, +// else the one without. +func testGuest() ([]byte, error) { + path, task := guestPath, "wasm:guest:build:deterministic" + if eqlguest.Linked() { + path, task = eqlGuestPath, "wasm:guest:build:eql:deterministic" + } + wasm, err := guestFS.ReadFile(path) + if err != nil { + return nil, notBuiltError{task: task} + } + return wasm, nil +} + +// notBuiltError is a test build missing from the module. A released module +// carries both; a checkout of the repository needs the build task run. +type notBuiltError struct{ task string } + +func (e notBuiltError) Error() string { + return "encrypttest: the test build of the engine is not in this module; in a checkout of the repository, run `mise run " + e.task + "`" +} diff --git a/languages/golang/encrypt/encrypttest/client_test.go b/languages/golang/encrypt/encrypttest/client_test.go new file mode 100644 index 0000000000..36ef4f2686 --- /dev/null +++ b/languages/golang/encrypt/encrypttest/client_test.go @@ -0,0 +1,222 @@ +package encrypttest_test + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "reflect" + "testing" + + "github.com/cipherstash/stack/languages/golang/encrypt" + "github.com/cipherstash/stack/languages/golang/encrypt/encrypttest" + "github.com/cipherstash/stack/languages/golang/encrypt/internal/eqlguest" + "github.com/cipherstash/stack/languages/golang/encrypt/internal/testusers" +) + +// These tests use the client as an application's tests would: through +// generated code, with no credentials and no network. testusers names an +// EQL type, so this binary links package eql and gets the test build with +// the EQL types. internal/withouteql covers the other build. + +var people = []testusers.User{ + {ID: 1, Age: 34, Email: "alice@example.com", Notes: "likes cats"}, + {ID: 2, Age: 29, Email: "bob@example.com", Notes: "likes dogs"}, +} + +func TestTheBinaryLinksTheEQLBuild(t *testing.T) { + if !eqlguest.Linked() { + t.Fatal("testusers names an EQL type, so package eql must be linked here") + } +} + +func TestRoundTripThroughGeneratedCode(t *testing.T) { + client := encrypttest.NewClient(t) + ctx := t.Context() + cipher := client.DefaultKeyset() + + rows, err := testusers.Encrypt(ctx, cipher, people) + if err != nil { + t.Fatal(err) + } + // The client and the cipher both take the place of a Decrypter. + for name, d := range map[string]encrypt.Decrypter{"client": client, "cipher": cipher} { + back, err := testusers.Decrypt(ctx, d, rows) + if err != nil { + t.Fatalf("through the %s: %v", name, err) + } + if !reflect.DeepEqual(back, people) { + t.Fatalf("through the %s: %+v, want %+v", name, back, people) + } + } + // A query term matches the stored term of the same value only. + probe, err := testusers.Fields.Email.Eq(ctx, cipher, "bob@example.com") + if err != nil { + t.Fatal(err) + } + if !probe.Equal(rows[1].Email.Equality) || probe.Equal(rows[0].Email.Equality) { + t.Error("the equality probe does not single out its row") + } +} + +func TestAnEQLValueAndItsQueryMatch(t *testing.T) { + client := encrypttest.NewClient(t) + ctx := t.Context() + cipher := client.DefaultKeyset() + + contacts := []testusers.Contact{{ID: 1, Email: "ada@example.com", Notes: "first"}} + rows, err := testusers.EncryptContact(ctx, cipher, contacts) + if err != nil { + t.Fatal(err) + } + query, err := testusers.ContactFields.Email.Eq(ctx, cipher, "ada@example.com") + if err != nil { + t.Fatal(err) + } + if hm(t, rows[0].Email) != hm(t, query) { + t.Fatal("the query's equality term does not match the stored value's") + } + back, err := testusers.DecryptContact(ctx, client, rows) + if err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(back, contacts) { + t.Fatalf("%+v, want %+v", back, contacts) + } +} + +// hm reads the equality term from an EQL value or query. +func hm(t *testing.T, value []byte) string { + t.Helper() + var v struct { + HM string `json:"hm"` + } + if err := json.Unmarshal(value, &v); err != nil || v.HM == "" { + t.Fatalf("no hm in %s: %v", value, err) + } + return v.HM +} + +func TestEveryKeysetExistsAndRefusesAnother(t *testing.T) { + client := encrypttest.NewClient(t) + ctx := t.Context() + tenantA := client.Keyset(encrypt.KeysetName("tenant-a")) + tenantB := client.Keyset(encrypt.KeysetName("tenant-b")) + + rows, err := testusers.Encrypt(ctx, tenantB, people) + if err != nil { + t.Fatal(err) + } + if _, err := testusers.Decrypt(ctx, tenantA, rows); !errors.Is(err, encrypt.ErrForeignKeyset) { + t.Fatalf("tenant A's cipher on tenant B's rows: %v, want ErrForeignKeyset", err) + } + idB, err := tenantB.KeysetID(ctx) + if err != nil { + t.Fatal(err) + } + idA, err := tenantA.KeysetID(ctx) + if err != nil { + t.Fatal(err) + } + if idA == idB { + t.Fatal("two keyset names resolved to one keyset") + } + // Selected by id, with nothing created first. + for name, d := range map[string]encrypt.Decrypter{"client": client, "keyset by id": client.Keyset(idB)} { + if _, err := testusers.Decrypt(ctx, d, rows); err != nil { + t.Fatalf("through the %s: %v", name, err) + } + } + // The name "default" is the default keyset. + def, err := client.DefaultKeyset().KeysetID(ctx) + if err != nil { + t.Fatal(err) + } + named, err := client.Keyset(encrypt.KeysetName("default")).KeysetID(ctx) + if err != nil { + t.Fatal(err) + } + if def != named { + t.Fatalf("KeysetName(\"default\") is %v, the default keyset is %v", named, def) + } +} + +func TestAWrongContextFailsAsInProduction(t *testing.T) { + client := encrypttest.NewClient(t) + ctx := t.Context() + cipher := client.DefaultKeyset() + + // A value sealed under one scope does not open under another. + rows, err := testusers.Encrypt(ctx, cipher.Scope("tenant-7"), people) + if err != nil { + t.Fatal(err) + } + if _, err := testusers.Decrypt(ctx, cipher.Scope("tenant-8"), rows); !errors.Is(err, encrypt.ErrForbidden) { + t.Fatalf("under another scope: %v, want ErrForbidden", err) + } + + // A row whose context field is not the cipher's is refused. + notes := []testusers.Note{{Tenant: "tenants/acme", Text: "hello", ID: 1}} + sealed, err := testusers.EncryptNote(ctx, cipher, notes) + if err != nil { + t.Fatal(err) + } + if _, err := testusers.DecryptNote(ctx, cipher.Context("tenants/globex"), sealed); !errors.Is(err, encrypt.ErrContextMismatch) { + t.Fatalf("an acme row through the globex cipher: %v, want ErrContextMismatch", err) + } +} + +func TestTheDefaultSeedIsSharedAcrossClients(t *testing.T) { + writer := encrypttest.NewClient(t) + rows, err := testusers.Encrypt(t.Context(), writer.Keyset(encrypt.KeysetName("fixtures")), people) + if err != nil { + t.Fatal(err) + } + reader := encrypttest.NewClient(t) + back, err := testusers.Decrypt(t.Context(), reader, rows) + if err != nil { + t.Fatalf("a second client with the default seed: %v", err) + } + if !reflect.DeepEqual(back, people) { + t.Fatalf("%+v, want %+v", back, people) + } +} + +func TestAnotherSeedDoesNotOpenTheValues(t *testing.T) { + writer := encrypttest.NewClient(t) + rows, err := testusers.Encrypt(t.Context(), writer.DefaultKeyset(), people) + if err != nil { + t.Fatal(err) + } + other := encrypttest.NewClient(t, encrypttest.WithSeed([32]byte{1})) + if _, err := testusers.Decrypt(t.Context(), other, rows); !errors.Is(err, encrypt.ErrForbidden) { + t.Fatalf("under another seed: %v, want ErrForbidden", err) + } + // The same seed opens them. + same := encrypttest.NewClient(t, encrypttest.WithSeed([32]byte{1})) + resealed, err := testusers.Encrypt(t.Context(), same.DefaultKeyset(), people) + if err != nil { + t.Fatal(err) + } + if _, err := testusers.Decrypt(t.Context(), other, resealed); err != nil { + t.Fatalf("under the same chosen seed: %v", err) + } + // Search terms depend on the keyset, not the seed. + if !bytes.Equal(rows[0].Email.Equality, resealed[0].Email.Equality) { + t.Error("two seeds derived different search terms for one value") + } +} + +func TestTheClientIsClosedWhenTheTestEnds(t *testing.T) { + var client *encrypt.Client + t.Run("uses the client", func(t *testing.T) { + client = encrypttest.NewClient(t) + if _, err := testusers.Encrypt(t.Context(), client.DefaultKeyset(), people); err != nil { + t.Fatal(err) + } + }) + _, err := testusers.Encrypt(context.Background(), client.DefaultKeyset(), people) + if !errors.Is(err, encrypt.ErrState) { + t.Fatalf("after the test that made it ended: %v, want ErrState", err) + } +} diff --git a/languages/golang/encrypt/encrypttest/encrypttest.go b/languages/golang/encrypt/encrypttest/encrypttest.go index c2b22fb2c5..b73301f601 100644 --- a/languages/golang/encrypt/encrypttest/encrypttest.go +++ b/languages/golang/encrypt/encrypttest/encrypttest.go @@ -1,5 +1,12 @@ -// Package encrypttest holds assertions for tests of code that uses package -// encrypt and its generated records. +// Package encrypttest helps test code that uses package encrypt and its +// generated records. Import it only from _test.go files. +// +// [NewClient] gives a test a client that needs no network and no +// CipherStash credentials. It runs the same engine and generated code as a +// production client, with keys derived from a seed in place of ZeroKMS: +// +// client := encrypttest.NewClient(t) +// rows, err := users.Encrypt(t.Context(), client.DefaultKeyset(), people) // // A wrong context loses data silently. A query under the wrong context // matches nothing, and gives no error. [AssertContexts] pins the contexts diff --git a/languages/golang/encrypt/encrypttest/encrypttest_test.go b/languages/golang/encrypt/encrypttest/encrypttest_test.go index 986c0805c7..d6ed32551a 100644 --- a/languages/golang/encrypt/encrypttest/encrypttest_test.go +++ b/languages/golang/encrypt/encrypttest/encrypttest_test.go @@ -32,7 +32,8 @@ func users() gensupport.Declaration { func skipWithoutGuest(t *testing.T) { t.Helper() - if _, err := encrypttest.Contexts(context.Background(), users()); errors.Is(err, encrypt.ErrGuestNotBuilt) { + _, err := encrypttest.Contexts(context.Background(), users()) + if errors.Is(err, encrypt.ErrGuestNotBuilt) || errors.Is(err, encrypt.ErrEQLGuestNotBuilt) { t.Skip(err) } } diff --git a/languages/golang/encrypt/encrypttest/internal/withouteql/doc.go b/languages/golang/encrypt/encrypttest/internal/withouteql/doc.go new file mode 100644 index 0000000000..279a27a9aa --- /dev/null +++ b/languages/golang/encrypt/encrypttest/internal/withouteql/doc.go @@ -0,0 +1,6 @@ +// Package withouteql tests encrypttest in a program that does not link +// package eql, so encrypttest must pick the test build without the EQL types, +// as encrypt.NewClient picks the production build without them. Whether eql +// is linked is fixed for a whole test binary, so this needs a package of its +// own. It holds no code. +package withouteql diff --git a/languages/golang/encrypt/encrypttest/internal/withouteql/withouteql_test.go b/languages/golang/encrypt/encrypttest/internal/withouteql/withouteql_test.go new file mode 100644 index 0000000000..2c391eb4fe --- /dev/null +++ b/languages/golang/encrypt/encrypttest/internal/withouteql/withouteql_test.go @@ -0,0 +1,30 @@ +package withouteql_test + +import ( + "reflect" + "testing" + + "github.com/cipherstash/stack/languages/golang/encrypt/encrypttest" + "github.com/cipherstash/stack/languages/golang/encrypt/internal/eqlguest" + "github.com/cipherstash/stack/languages/golang/encrypt/internal/testmember" + "github.com/cipherstash/stack/languages/golang/encrypt/internal/testpolicy" +) + +func TestRoundTripWithoutTheEQLTypes(t *testing.T) { + if eqlguest.Linked() { + t.Fatal("package eql is linked: this test must not import anything that names an EQL type") + } + client := encrypttest.NewClient(t) + members := []testmember.Member{{ID: 1, Age: 34, Email: "ada@example.com", Notes: "first"}} + rows, err := testpolicy.Encrypt(t.Context(), client.DefaultKeyset(), members) + if err != nil { + t.Fatal(err) + } + back, err := testpolicy.Decrypt(t.Context(), client, rows) + if err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(back, members) { + t.Fatalf("%+v, want %+v", back, members) + } +} diff --git a/languages/golang/encrypt/encrypttest/postgres_test.go b/languages/golang/encrypt/encrypttest/postgres_test.go new file mode 100644 index 0000000000..93566dd188 --- /dev/null +++ b/languages/golang/encrypt/encrypttest/postgres_test.go @@ -0,0 +1,127 @@ +package encrypttest_test + +import ( + "context" + "database/sql" + "os" + "reflect" + "slices" + "testing" + + _ "github.com/jackc/pgx/v5/stdlib" + + "github.com/cipherstash/stack/languages/golang/encrypt" + "github.com/cipherstash/stack/languages/golang/encrypt/encrypttest" + "github.com/cipherstash/stack/languages/golang/encrypt/eql" + "github.com/cipherstash/stack/languages/golang/encrypt/internal/testusers" +) + +// TestEncryptTestClientInPostgres is an application's test end to end: +// create the test client, encrypt with generated code, insert into an EQL v4 +// column, search on the ciphertext, and decrypt what the database returns. +// +// Skipped unless DATABASE_URL is set. With it set, EQL v4 must be installed +// there. `mise run go:test:postgres` sets both and fails on a skip. +func TestEncryptTestClientInPostgres(t *testing.T) { + url := os.Getenv("DATABASE_URL") + if url == "" { + t.Skip("DATABASE_URL is not set") + } + ctx := t.Context() + + // 1. The test client: one cipher for each tenant's keyset. + client := encrypttest.NewClient(t) + cipher := client.Keyset(encrypt.KeysetName("tenant-a")) + + // 2. Encrypt with generated code. + contacts := []testusers.Contact{ + {ID: 1, Email: "ada@example.com", Notes: "first"}, + {ID: 2, Email: "grace@example.com", Notes: "second"}, + } + rows, err := testusers.EncryptContact(ctx, cipher, contacts) + if err != nil { + t.Fatal(err) + } + + // 3. Insert into an EQL v4 column. + conn := postgres(t, ctx, url) + exec := func(stmt string, args ...any) { + t.Helper() + if _, err := conn.ExecContext(ctx, stmt, args...); err != nil { + t.Fatalf("%s: %v", stmt, err) + } + } + exec(`CREATE TEMPORARY TABLE encrypttest_contacts (id bigint PRIMARY KEY, email eql_v4_text_eq NOT NULL, notes bytea NOT NULL)`) + for _, r := range rows { + exec(`INSERT INTO encrypttest_contacts VALUES ($1, $2::text::jsonb::eql_v4_text_eq, $3)`, r.ID, r.Email, []byte(r.Notes.Ciphertext)) + } + + // 4. Search on the ciphertext. + query, err := testusers.ContactFields.Email.Eq(ctx, cipher, "grace@example.com") + if err != nil { + t.Fatal(err) + } + found, err := conn.QueryContext(ctx, `SELECT id, email::text, notes FROM encrypttest_contacts WHERE email = $1::text::jsonb::eql_v4.query_text_eq ORDER BY id`, query) + if err != nil { + t.Fatal(err) + } + defer found.Close() + var read []testusers.EncryptedContact + for found.Next() { + var r testusers.EncryptedContact + var email string + var notes []byte + if err := found.Scan(&r.ID, &email, ¬es); err != nil { + t.Fatal(err) + } + r.Email, r.Notes.Ciphertext = eql.TextEq(email), notes + read = append(read, r) + } + if err := found.Err(); err != nil { + t.Fatal(err) + } + if ids := idsOf(read); !slices.Equal(ids, []int64{2}) { + t.Fatalf("the query found rows %v, want [2]", ids) + } + + // 5. Decrypt and assert. + back, err := testusers.DecryptContact(ctx, client, read) + if err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(back, contacts[1:]) { + t.Fatalf("%+v, want %+v", back, contacts[1:]) + } +} + +func idsOf(rows []testusers.EncryptedContact) []int64 { + ids := make([]int64, len(rows)) + for i, r := range rows { + ids[i] = r.ID + } + return ids +} + +// postgres is one connection to url, which must have EQL v4 installed. One +// connection, because the table is temporary. +func postgres(t *testing.T, ctx context.Context, url string) *sql.Conn { + t.Helper() + db, err := sql.Open("pgx", url) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = db.Close() }) + conn, err := db.Conn(ctx) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = conn.Close() }) + var installed bool + if err := conn.QueryRowContext(ctx, `SELECT to_regnamespace('eql_v4') IS NOT NULL`).Scan(&installed); err != nil { + t.Fatal(err) + } + if !installed { + t.Fatal("EQL v4 is not installed in DATABASE_URL; run `mise run go:test:postgres`") + } + return conn +} diff --git a/languages/golang/encrypt/encrypttest/wasm/README.md b/languages/golang/encrypt/encrypttest/wasm/README.md new file mode 100644 index 0000000000..a670c62f7b --- /dev/null +++ b/languages/golang/encrypt/encrypttest/wasm/README.md @@ -0,0 +1,20 @@ +# Test builds of the engine + +These are the deterministic-kms TEST builds of the stack-encrypt guest +(`../../guest`). Their keys derive from a seed, so a client over them needs no +ZeroKMS, no token and no network. + +- `stack_encrypt_guest_deterministic.wasm`, from + `mise run wasm:guest:build:deterministic`. +- `stack_encrypt_guest_eql_deterministic.wasm`, the same build with the EQL + types, from `mise run wasm:guest:build:eql:deterministic`. + +They are not committed on main. The Go release workflow builds them and commits +them on the release tag, so a module fetched with `go get` carries them. + +Package `encrypttest` embeds this directory, and `encrypttest.NewClient` fails +the test when the build it needs is absent. The `encrypt` package's own tests +read the same files from disk, and skip when they are absent. + +Only a binary that imports `encrypttest` carries these builds. Import it only +from `_test.go` files. diff --git a/languages/golang/encrypt/eql/guest.go b/languages/golang/encrypt/eql/guest.go index d38aee3ec8..a7c4c01046 100644 --- a/languages/golang/encrypt/eql/guest.go +++ b/languages/golang/encrypt/eql/guest.go @@ -10,8 +10,8 @@ import ( // crate in ../guest with its `eql` feature, copied here by // `mise run wasm:guest:build:eql`. It is embedded as a directory so the // package compiles without it; encrypt.NewClient reports its absence. Its -// deterministic-kms test build lives under encrypt/testdata with the other -// test build: nothing test-only is embedded. +// deterministic-kms test build lives under encrypt/encrypttest/wasm with the +// other test build, embedded by package encrypttest and by nothing here. // //go:embed wasm var guestFS embed.FS diff --git a/languages/golang/encrypt/eql/wasm/README.md b/languages/golang/encrypt/eql/wasm/README.md index 10baaac6fd..a187572546 100644 --- a/languages/golang/encrypt/eql/wasm/README.md +++ b/languages/golang/encrypt/eql/wasm/README.md @@ -11,4 +11,5 @@ absent, and the package's tests skip. The same build with the `deterministic-kms` feature too — a TEST build whose keys derive from a seed, so the tests seal and open a `TextEq` field with no ZeroKMS — is written by `mise run wasm:guest:build:eql:deterministic` under -`encrypt/testdata/`, not here: nothing test-only is embedded. +`encrypt/encrypttest/wasm/`, not here: package `encrypttest` embeds it, so +only a binary that imports `encrypttest` carries it. diff --git a/languages/golang/encrypt/exchange_conformance_test.go b/languages/golang/encrypt/exchange_conformance_test.go index 034de9d486..b7de110eff 100644 --- a/languages/golang/encrypt/exchange_conformance_test.go +++ b/languages/golang/encrypt/exchange_conformance_test.go @@ -294,10 +294,10 @@ func exchangeSDK() (sdk, version string) { } // exchangeGuestEngine identifies the engine as the SHA-256 of the named -// guest under testdata, the one this runner loaded. +// guest under encrypttest/wasm, the one this runner loaded. func exchangeGuestEngine(t *testing.T, guest string) exchangeEngine { t.Helper() - module, err := os.ReadFile(filepath.Join("testdata", guest)) + module, err := os.ReadFile(filepath.Join("encrypttest", "wasm", guest)) if err != nil { t.Fatal(err) } diff --git a/languages/golang/encrypt/export_test.go b/languages/golang/encrypt/export_test.go index 53dc819444..080e3dae2b 100644 --- a/languages/golang/encrypt/export_test.go +++ b/languages/golang/encrypt/export_test.go @@ -10,7 +10,6 @@ import ( "github.com/cipherstash/stack/languages/golang/internal/guest" "github.com/cipherstash/stack/languages/golang/internal/record" - "github.com/cipherstash/vitaminc/bindings/go/vcffi" "github.com/tetratelabs/wazero/api" ) @@ -67,10 +66,10 @@ func GuestMemory(t *testing.T, c *Client) []byte { } // deterministicGuestPath is the deterministic-kms test build, which `mise -// run wasm:guest:build:deterministic` writes under testdata: a directory -// `go build` and the package's `//go:embed wasm` ignore, so the test build -// is read from disk here and embedded in no binary. -const deterministicGuestPath = "testdata/stack_encrypt_guest_deterministic.wasm" +// run wasm:guest:build:deterministic` writes where package encrypttest embeds +// it. This package's tests read it from disk: encrypttest imports encrypt, +// so they cannot import encrypttest. +const deterministicGuestPath = "encrypttest/wasm/stack_encrypt_guest_deterministic.wasm" // ErrDeterministicGuestNotBuilt says the test build is absent. var ErrDeterministicGuestNotBuilt = errors.New("encrypt: deterministic guest not built; run `mise run wasm:guest:build:deterministic`") @@ -87,7 +86,7 @@ func NewDeterministicClient(ctx context.Context, seed [32]byte) (*Client, error) if err != nil { return nil, err } - return deterministicClient(ctx, wasm, seed) + return seededClient(ctx, wasm, seed) } // ErrDeterministicEQLGuestNotBuilt says the test build with the EQL types @@ -95,8 +94,8 @@ func NewDeterministicClient(ctx context.Context, seed [32]byte) (*Client, error) var ErrDeterministicEQLGuestNotBuilt = errors.New("encrypt: deterministic eql guest not built; run `mise run wasm:guest:build:eql:deterministic`") // deterministicEQLGuestPath is the test build WITH the EQL types, which -// `mise run wasm:guest:build:eql:deterministic` writes under testdata too. -const deterministicEQLGuestPath = "testdata/stack_encrypt_guest_eql_deterministic.wasm" +// `mise run wasm:guest:build:eql:deterministic` writes beside the other. +const deterministicEQLGuestPath = "encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm" // NewDeterministicEQLClient is NewDeterministicClient over the test build // WITH the EQL types. @@ -105,34 +104,7 @@ func NewDeterministicEQLClient(ctx context.Context, seed [32]byte) (*Client, err if err != nil { return nil, ErrDeterministicEQLGuestNotBuilt } - return deterministicClient(ctx, wasm, seed) -} - -func deterministicClient(ctx context.Context, wasm []byte, seed [32]byte) (*Client, error) { - tr := &transport{rt: refusingTransport{}, token: noToken{}} - inst, err := newInstance(ctx, wasm, tr, guest.BestEffort) - if err != nil { - return nil, err - } - c := newClient(inst, tr) - encoded, err := vcffi.Marshal(seed[:]) - if err != nil { - _ = c.Close() - return nil, err - } - out, err := c.call(ctx, func(ctx context.Context, inst *instance) ([]byte, error) { - return inst.call(ctx, inst.cipherInit, buf(encoded)) - }) - if err != nil { - _ = c.Close() - return nil, fmt.Errorf("encrypt: deterministic cipher init: %w", err) - } - if len(out) != len(KeysetID{}) { - _ = c.Close() - return nil, fmt.Errorf("%w: cipher init returned %d bytes for the keyset id", ErrInternal, len(out)) - } - copy(c.def[:], out) - return c, nil + return seededClient(ctx, wasm, seed) } // RawClient is a guest that was never given a client key: every well-formed diff --git a/languages/golang/encrypt/guest/Cargo.toml b/languages/golang/encrypt/guest/Cargo.toml index 4df0b70ba7..fa3a0e34d1 100644 --- a/languages/golang/encrypt/guest/Cargo.toml +++ b/languages/golang/encrypt/guest/Cargo.toml @@ -28,8 +28,10 @@ crate-type = ["cdylib", "rlib"] # was sealed under: `se_cipher_init` takes the 32-byte seed and nothing # else, and every data key derives from it. No ZeroKMS, no token, no # network. The Go tests load it to open the fixture's records and to run -# hermetic round trips; `mise run wasm:guest:build:deterministic` builds it -# beside the real guest. Never the embedded guest. +# hermetic round trips, and package encrypttest embeds it to give an +# application's tests an offline client; `mise run +# wasm:guest:build:deterministic` builds it into encrypt/encrypttest/wasm. +# Never the guest package encrypt embeds. deterministic-kms = ["stack-kms/test-support"] # The guest build that holds the EQL types (ADR-0007, amended 2026-10-06): # links eql-bindings and installs its by-name dispatch as the engine's diff --git a/languages/golang/encrypt/guest/src/deterministic.rs b/languages/golang/encrypt/guest/src/deterministic.rs index 15567525a5..ca78f0deed 100644 --- a/languages/golang/encrypt/guest/src/deterministic.rs +++ b/languages/golang/encrypt/guest/src/deterministic.rs @@ -6,9 +6,10 @@ //! term bytes, because both run the same code. //! //! It is a test double. The feature that compiles it is off by default, and -//! the build it produces goes under languages/golang/encrypt/testdata, which -//! `go build` and the package's `//go:embed wasm` both ignore, so no Go -//! binary carries it; the tests read it from disk. +//! the build it produces goes under languages/golang/encrypt/encrypttest/wasm. +//! Package `encrypttest` embeds it to give an application's tests an offline +//! client, so only a Go binary that imports `encrypttest` carries it. The +//! production guest embedded by `encrypt` never links this source. pub use stack_kms::DeterministicSource; diff --git a/languages/golang/encrypt/internal/testclient/testclient.go b/languages/golang/encrypt/internal/testclient/testclient.go new file mode 100644 index 0000000000..1593d01284 --- /dev/null +++ b/languages/golang/encrypt/internal/testclient/testclient.go @@ -0,0 +1,34 @@ +// Package testclient is where package encrypt hands package encrypttest the +// one constructor it needs: a client over a given guest build, initialised +// with a seed in place of a client key. The constructor reaches encrypt's +// unexported instance and client, and encrypttest imports encrypt, so encrypt +// registers it here on init. Nothing outside the encrypt tree can import this +// package, so the constructor is in no public API. +package testclient + +import ( + "context" + "errors" +) + +// Constructor builds a client over wasm, a deterministic-kms build of the +// guest, with every key derived from seed. It returns the *encrypt.Client as +// any, because this package cannot import encrypt to name the type. +type Constructor func(ctx context.Context, wasm []byte, seed [32]byte) (any, error) + +var constructor Constructor + +// Register installs encrypt's constructor. Called once, by encrypt's init. +func Register(c Constructor) { constructor = c } + +// errNotRegistered is a program that reached New without package encrypt +// initialised, which the import graph rules out. +var errNotRegistered = errors.New("encrypt: test client constructor not registered") + +// New calls the registered constructor. +func New(ctx context.Context, wasm []byte, seed [32]byte) (any, error) { + if constructor == nil { + return nil, errNotRegistered + } + return constructor(ctx, wasm, seed) +} diff --git a/languages/golang/encrypt/testclient.go b/languages/golang/encrypt/testclient.go new file mode 100644 index 0000000000..152292a094 --- /dev/null +++ b/languages/golang/encrypt/testclient.go @@ -0,0 +1,52 @@ +package encrypt + +import ( + "context" + "fmt" + + "github.com/cipherstash/stack/languages/golang/encrypt/internal/testclient" + "github.com/cipherstash/stack/languages/golang/internal/guest" + "github.com/cipherstash/vitaminc/bindings/go/vcffi" +) + +// Package encrypttest builds its clients through this constructor. It is +// registered with internal/testclient, which only packages under encrypt can +// import, so no public function builds a client over a guest the caller +// chooses. It does nothing without a deterministic-kms build: the guest +// embedded for production refuses a bare seed as its config. +func init() { + testclient.Register(func(ctx context.Context, wasm []byte, seed [32]byte) (any, error) { + return seededClient(ctx, wasm, seed) + }) +} + +// seededClient is a client over wasm, a deterministic-kms build of the +// guest. Its config is the 32-byte seed every key derives from. It has no +// token and a transport that refuses every request, so nothing it does can +// reach the network. +func seededClient(ctx context.Context, wasm []byte, seed [32]byte) (*Client, error) { + tr := &transport{rt: refusingTransport{}, token: noToken{}} + inst, err := newInstance(ctx, wasm, tr, guest.BestEffort) + if err != nil { + return nil, err + } + c := newClient(inst, tr) + encoded, err := vcffi.Marshal(seed[:]) + if err != nil { + _ = c.Close() + return nil, err + } + out, err := c.call(ctx, func(ctx context.Context, inst *instance) ([]byte, error) { + return inst.call(ctx, inst.cipherInit, buf(encoded)) + }) + if err != nil { + _ = c.Close() + return nil, fmt.Errorf("encrypt: deterministic cipher init: %w", err) + } + if len(out) != len(KeysetID{}) { + _ = c.Close() + return nil, fmt.Errorf("%w: cipher init returned %d bytes for the keyset id", ErrInternal, len(out)) + } + copy(c.def[:], out) + return c, nil +} diff --git a/languages/golang/encrypt/testclient_test.go b/languages/golang/encrypt/testclient_test.go new file mode 100644 index 0000000000..97110661da --- /dev/null +++ b/languages/golang/encrypt/testclient_test.go @@ -0,0 +1,34 @@ +package encrypt + +import ( + "context" + "errors" + "testing" +) + +// The constructor package encrypttest reaches is harmless over the guests +// this package and package eql embed for production: they take a client key, +// and refuse a bare seed as malformed config before any key exists. +func TestAProductionGuestRefusesASeed(t *testing.T) { + plain, err := PlainGuest() + if errors.Is(err, ErrGuestNotBuilt) { + t.Skip(err) + } + if err != nil { + t.Fatal(err) + } + guests := map[string][]byte{"the guest without the EQL types": plain} + if withEQL, err := EmbeddedGuest(); err == nil { + guests["the guest the program runs"] = withEQL + } + for name, wasm := range guests { + c, err := seededClient(context.Background(), wasm, [32]byte{7}) + if err == nil { + _ = c.Close() + t.Fatalf("%s took a seed in place of a client key", name) + } + if !errors.Is(err, ErrEncoding) { + t.Fatalf("%s: %v, want ErrEncoding", name, err) + } + } +} diff --git a/languages/golang/encrypt/wasm/README.md b/languages/golang/encrypt/wasm/README.md index fa91f617d7..d9945ee0cc 100644 --- a/languages/golang/encrypt/wasm/README.md +++ b/languages/golang/encrypt/wasm/README.md @@ -5,6 +5,7 @@ the Go package embeds this directory and reports `ErrGuestNotBuilt` from `NewClient` when the module is absent, and its tests skip. -The deterministic-kms TEST build of the same crate lives in `../testdata/` -(`mise run wasm:guest:build:deterministic`), not here: this directory is what -`//go:embed wasm` ships in every binary, and `go build` ignores `testdata`. +The deterministic-kms TEST build of the same crate lives in +`../encrypttest/wasm/` (`mise run wasm:guest:build:deterministic`), not here: +this directory ships in every binary that links `encrypt`, and the test build +ships only in a binary that imports `encrypttest`. diff --git a/mise.toml b/mise.toml index c0a664fa8c..c64db54dd1 100644 --- a/mise.toml +++ b/mise.toml @@ -195,11 +195,13 @@ echo "embedded into languages/golang/encrypt/wasm/stack_encrypt_guest.wasm" # the record fixture's 32-byte seed and derives every key from it, so the Go # tests open the records Rust sealed (packages/stack-encrypt/tests/fixtures/ # record_lowering.json) and run hermetic round trips with no ZeroKMS. It goes -# under encrypt/testdata, which `go build` and the package's `//go:embed -# wasm` both ignore, so no binary ever carries it; the tests read it from -# disk and skip when it is absent. The import-surface gate denies what the real -# build's does; it requires no transport import, because a build with no -# ZeroKMS client has none. +# under encrypt/encrypttest/wasm, which package encrypttest embeds and the +# release commits: applications' tests get an offline client from it. Only +# a program that imports encrypttest carries it, and only test files should. +# The encrypt package's own tests read it from disk and skip when it is +# absent. The import-surface gate denies what the real build's does; it +# requires no transport import, because a build with no ZeroKMS client has +# none. [tasks."wasm:guest:build:deterministic"] description = "Build the deterministic-kms TEST build of the stack-encrypt WASI guest (wasm32-wasip1, release), for the Go fixture and round-trip tests" shell = "bash -c" @@ -218,8 +220,8 @@ python3 "$root/scripts/check-wasm-imports.py" "$module" \\ --require wasi_snapshot_preview1:random_get # No transport imports to require: with no ZeroKMS client in the build the # linker drops the host module altogether, which is the point of the build. -cp "$module" ../testdata/stack_encrypt_guest_deterministic.wasm -echo "test build at languages/golang/encrypt/testdata/stack_encrypt_guest_deterministic.wasm" +cp "$module" ../encrypttest/wasm/stack_encrypt_guest_deterministic.wasm +echo "test build at languages/golang/encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm" """ # The guest build that holds the EQL types (ADR-0007, amended 2026-10-06): @@ -262,8 +264,8 @@ echo "size with EQL types: $(wc -c < ../eql/wasm/stack_encrypt_guest_eql.wasm # The deterministic-kms TEST build with the EQL types: what the hermetic Go # tests of a TextEq field load, as the one above is what the other hermetic -# tests load. Same gate, and the same rule: nothing test-only in an embed, so -# it lands under encrypt/testdata beside the other test build. +# tests load. Same gate, and the same place: encrypt/encrypttest/wasm, which +# package encrypttest embeds and selects when package eql is linked. [tasks."wasm:guest:build:eql:deterministic"] description = "Build the deterministic-kms TEST build of the stack-encrypt WASI guest with the EQL types (features eql,deterministic-kms), for the hermetic Go tests of EQL fields" shell = "bash -c" @@ -280,8 +282,8 @@ python3 "$root/scripts/check-wasm-imports.py" "$module" \\ --deny-prefix wasi_snapshot_preview1:sock_ \\ --deny-prefix wasi_snapshot_preview1:fd_prestat \\ --require wasi_snapshot_preview1:random_get -cp "$module" ../testdata/stack_encrypt_guest_eql_deterministic.wasm -echo "test build at languages/golang/encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm" +cp "$module" ../encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm +echo "test build at languages/golang/encrypt/encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm" """ [tasks."wasm:guest:test"] @@ -391,12 +393,13 @@ TESTS=( TestEQLTypesRoundTripAndQueryInPostgres TestEQLOrderMatchesPlaintextInPostgres TestQueriesRunAgainstPostgres + TestEncryptTestClientInPostgres ) pattern="^($(IFS='|'; echo "${TESTS[*]}"))$" # The tests skip without DATABASE_URL and without their guest builds; -v and # the grep turn either skip into a failure here, where both are provided. DATABASE_URL="$EQL_TEST_DATABASE_URL" CGO_ENABLED=0 go test -count=1 -v \ - -run "$pattern" ./encrypt \ + -run "$pattern" ./encrypt ./encrypt/encrypttest \ | tee "${TMPDIR:-/tmp}/go-test-postgres.log" if grep -q -- '--- SKIP' "${TMPDIR:-/tmp}/go-test-postgres.log"; then echo "error: a PostgreSQL test skipped; build the deterministic guests first" >&2 diff --git a/scripts/__tests__/go-release-artifact.test.mjs b/scripts/__tests__/go-release-artifact.test.mjs index 8d4a217ab4..5e7847207b 100644 --- a/scripts/__tests__/go-release-artifact.test.mjs +++ b/scripts/__tests__/go-release-artifact.test.mjs @@ -118,7 +118,7 @@ function writeManifest(lines) { ) } -/** The tree the release commit should have: HEAD plus the three guests. */ +/** The tree the release commit should have: HEAD plus the guests. */ function expectedTree() { const index = join(repo, '.git', 'expected-index') const env = { ...process.env, GIT_INDEX_FILE: index } @@ -162,12 +162,13 @@ describe.skipIf(!BASH_HAS_MAPFILE)( () => { it('exists, and the publish job takes its paths from GUESTS', () => { expect(COMMIT_STEP).toBeDefined() - expect(GUESTS).toHaveLength(3) + // Three production guests and the two test builds encrypttest embeds. + expect(GUESTS).toHaveLength(5) expect(String(COMMIT_STEP.run)).toContain('"$GUESTS"') }) it.skipIf(!GNU_COREUTILS)( - 'commits the three guests from an honest artifact', + 'commits the five guests from an honest artifact', () => { writeManifest(honestManifest()) const tree = expectedTree() diff --git a/scripts/__tests__/stack-exchange-conformance.test.mjs b/scripts/__tests__/stack-exchange-conformance.test.mjs index 0dee4529f7..5526520936 100644 --- a/scripts/__tests__/stack-exchange-conformance.test.mjs +++ b/scripts/__tests__/stack-exchange-conformance.test.mjs @@ -142,8 +142,8 @@ describe('fresh cross-language artifact exchange', () => { writeFileSync(empty, 'not empty') expect(() => requireGuests(base, ['empty.wasm'])).not.toThrow() expect(GUESTS).toEqual([ - 'encrypt/testdata/stack_encrypt_guest_deterministic.wasm', - 'encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm', + 'encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm', + 'encrypt/encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm', ]) }) diff --git a/scripts/__tests__/stack-lifecycle-conformance.test.mjs b/scripts/__tests__/stack-lifecycle-conformance.test.mjs index cbb53b0b05..9ef0f8bf05 100644 --- a/scripts/__tests__/stack-lifecycle-conformance.test.mjs +++ b/scripts/__tests__/stack-lifecycle-conformance.test.mjs @@ -174,7 +174,7 @@ describe('required lifecycle evidence', () => { ) expect(go.lock_sha256).toBe('sha256:Cargo.lock') expect(Object.keys(go.guests).sort()).toEqual([ - 'encrypt/testdata/stack_encrypt_guest_deterministic.wasm', + 'encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm', 'encrypt/wasm/stack_encrypt_guest.wasm', ]) const rust = selections(index, 'fast', 'rust') diff --git a/scripts/stack-conformance.sh b/scripts/stack-conformance.sh index 1386e3649b..df2bc5039f 100644 --- a/scripts/stack-conformance.sh +++ b/scripts/stack-conformance.sh @@ -10,7 +10,7 @@ fi unset STACK_CONFORMANCE_INPUT STACK_CONFORMANCE_OUTPUT export STACK_CONFORMANCE_REQUIRED=1 -if [[ ! -s languages/golang/encrypt/testdata/stack_encrypt_guest_deterministic.wasm ]]; then +if [[ ! -s languages/golang/encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm ]]; then echo 'Build the test guest first: mise run wasm:guest:build:deterministic' >&2 exit 1 fi diff --git a/scripts/stack-eql-conformance.mjs b/scripts/stack-eql-conformance.mjs index acdbfb1d05..8f220927fb 100644 --- a/scripts/stack-eql-conformance.mjs +++ b/scripts/stack-eql-conformance.mjs @@ -80,7 +80,7 @@ export function main(args = process.argv.slice(2)) { 'stack_encrypt_guest_eql_deterministic.wasm', ].map((name) => [ name, - hash(`languages/golang/encrypt/testdata/${name}`), + hash(`languages/golang/encrypt/encrypttest/wasm/${name}`), ]), ) } diff --git a/scripts/stack-exchange-conformance.mjs b/scripts/stack-exchange-conformance.mjs index 0dcd52519e..bba75d0c9c 100644 --- a/scripts/stack-exchange-conformance.mjs +++ b/scripts/stack-exchange-conformance.mjs @@ -33,8 +33,8 @@ export const CORPUS = /** The guests the Go runner needs, relative to the Go module. */ export const GUESTS = [ - 'encrypt/testdata/stack_encrypt_guest_deterministic.wasm', - 'encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm', + 'encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm', + 'encrypt/encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm', ] /** The language runners this profile enrolls today. */ diff --git a/scripts/stack-lifecycle-conformance.mjs b/scripts/stack-lifecycle-conformance.mjs index bae6d1bfa9..769db35635 100644 --- a/scripts/stack-lifecycle-conformance.mjs +++ b/scripts/stack-lifecycle-conformance.mjs @@ -13,7 +13,7 @@ import { const ENROLLMENT = 'conformance/stack-encrypt/v1/lifecycle-v1.enrollment.json' const GUESTS = [ 'encrypt/wasm/stack_encrypt_guest.wasm', - 'encrypt/testdata/stack_encrypt_guest_deterministic.wasm', + 'encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm', ] export function lifecycleIndex(index) { From bbaa732564d7400244cc2436d075ed0f508d628d Mon Sep 17 00:00:00 2001 From: Dan Draper Date: Tue, 17 Nov 2026 22:58:13 +1100 Subject: [PATCH 2/3] fix(golang): address the review of encrypttest.NewClient - WithSeed's doc no longer promises isolation between tests: search terms depend on the keyset alone, so tests that share a table isolate by keyset name. The README says the same. - One build selector. encrypt.selectBuild picks the production build in embeddedGuest and the test build in the encrypttest constructor, which now takes both test builds, so the two cannot drift apart. - Each test build is read once (sync.OnceValues): embed.FS copies on every read, and an application may call NewClient in every test. - The NewClient tests move to encrypttest/internal/witheql, beside withouteql. encrypttest's own test binary no longer links package eql, so its Contexts tests run against the plain guest again, unchanged. - TestAProductionGuestRefusesASeed checks each production build in its own subtest, so an absent EQL build is a visible skip. - go-binding-test.sh checks for the two test builds up front and names their tasks, since encrypttest's tests fail without them; the go:test description lists all five builds. - The release hashes the production guests before the test builds run and checks them after, so a task that copied a seeded build over a production guest stops the release. - go.mod's pgx comment names the new PostgreSQL test. --- .github/workflows/release-golang.yml | 23 +++++++-- languages/golang/encrypt/README.md | 4 +- .../golang/encrypt/encrypttest/client.go | 42 +++++++++------- .../encrypt/encrypttest/encrypttest_test.go | 3 +- .../encrypttest/internal/witheql/doc.go | 7 +++ .../{ => internal/witheql}/postgres_test.go | 2 +- .../witheql/witheql_test.go} | 4 +- languages/golang/encrypt/guest.go | 29 +++++++++-- .../encrypt/internal/testclient/testclient.go | 15 +++--- languages/golang/encrypt/testclient.go | 11 +++-- languages/golang/encrypt/testclient_test.go | 49 +++++++++++-------- languages/golang/go.mod | 2 +- mise.toml | 4 +- scripts/go-binding-test.sh | 9 ++-- 14 files changed, 136 insertions(+), 68 deletions(-) create mode 100644 languages/golang/encrypt/encrypttest/internal/witheql/doc.go rename languages/golang/encrypt/encrypttest/{ => internal/witheql}/postgres_test.go (99%) rename languages/golang/encrypt/encrypttest/{client_test.go => internal/witheql/witheql_test.go} (98%) diff --git a/.github/workflows/release-golang.yml b/.github/workflows/release-golang.yml index 87743f37c6..9fd708dae3 100644 --- a/.github/workflows/release-golang.yml +++ b/.github/workflows/release-golang.yml @@ -171,16 +171,33 @@ jobs: grep -qF "'go-$VERSION'" release/cipherstash-encrypt-v4.sql \ || { echo "::error::the v4 bundle is not stamped go-$VERSION"; exit 1; } - # The test builds ship too: package encrypttest embeds them. They are - # built here, before the hash, so the hash covers them as it covers the - # production guests. - name: Build the guests run: | mise run wasm:guest:build mise run wasm:guest:build:eql mise run wasm:auth-guest:build + + # The test builds ship too: package encrypttest embeds them. Every + # stack-encrypt build writes the same cargo output and differs only in + # where its task copies it, so the production guests are hashed before + # the test builds run and checked after: a task that copied a seeded + # build over a production guest stops the release here, rather than + # being hashed and tagged as production. + - name: Build the test guests + run: | + set -euo pipefail + read -ra guests <<< "$GUESTS" + production=() + for guest in "${guests[@]}"; do + case "$guest" in + */encrypttest/wasm/*) ;; + *) production+=("$guest") ;; + esac + done + sha256sum "${production[@]}" > "$RUNNER_TEMP/production.sha256" mise run wasm:guest:build:deterministic mise run wasm:guest:build:eql:deterministic + sha256sum -c "$RUNNER_TEMP/production.sha256" # Hashed before the tests run, and checked again after them below, so # the guests committed are the ones tested. diff --git a/languages/golang/encrypt/README.md b/languages/golang/encrypt/README.md index e743d57d50..8d9c10cad4 100644 --- a/languages/golang/encrypt/README.md +++ b/languages/golang/encrypt/README.md @@ -835,7 +835,9 @@ Every keyset exists, so a test selects any name or id with nothing to create. A test therefore never sees `ErrNotFound` for a missing keyset. Every client with the default seed opens what another sealed, in any test -process. `encrypttest.WithSeed` chooses another seed. +process. `encrypttest.WithSeed` chooses another seed. A seed changes the +data keys, not the search terms. To keep tests apart in a shared table, give +each test its own keyset name. Never seal real data with it: anyone with the seed derives every key. Import `encrypttest` only from `_test.go` files, so it stays out of production diff --git a/languages/golang/encrypt/encrypttest/client.go b/languages/golang/encrypt/encrypttest/client.go index 01c8f7d8e0..e89e0c63e6 100644 --- a/languages/golang/encrypt/encrypttest/client.go +++ b/languages/golang/encrypt/encrypttest/client.go @@ -4,10 +4,10 @@ import ( "context" "crypto/sha256" "embed" + "sync" "testing" "github.com/cipherstash/stack/languages/golang/encrypt" - "github.com/cipherstash/stack/languages/golang/encrypt/internal/eqlguest" "github.com/cipherstash/stack/languages/golang/encrypt/internal/testclient" ) @@ -37,9 +37,13 @@ type clientOptions struct { } // WithSeed derives every data key from seed in place of the default seed. -// Use it to keep one test's values apart from another's. A value sealed -// under one seed does not open under another, and fails with +// A value sealed under one seed does not open under another, and fails with // [encrypt.ErrForbidden]. +// +// A seed does not keep one test's rows apart from another's in a shared +// table. Search terms depend on the keyset alone, so a query under one seed +// matches rows another seed wrote under the same keyset. Give each test its +// own keyset name for that: every name is a separate keyset. func WithSeed(seed [32]byte) ClientOption { return func(o *clientOptions) { o.seed = seed } } @@ -89,7 +93,8 @@ func WithSeed(seed [32]byte) ClientOption { // reads them share keys with no setup. The default seed never changes. // [WithSeed] chooses another. A seed changes the data keys only: search // terms depend on the keyset alone, so two seeds give a value the same -// terms. +// terms. To keep tests apart in a shared table, give each its own keyset +// name. // // # Not for production // @@ -118,11 +123,7 @@ func NewClient(tb testing.TB, opts ...ClientOption) *encrypt.Client { for _, opt := range opts { opt(&o) } - wasm, err := testGuest() - if err != nil { - tb.Fatal(err) - } - built, err := testclient.New(context.Background(), wasm, o.seed) + built, err := testclient.New(context.Background(), plainTestBuild, eqlTestBuild, o.seed) if err != nil { tb.Fatalf("encrypttest: %v", err) } @@ -138,14 +139,19 @@ func NewClient(tb testing.TB, opts ...ClientOption) *encrypt.Client { return client } -// testGuest is the test build matching the build a production client in -// this program runs: the one with the EQL types when package eql is linked, -// else the one without. -func testGuest() ([]byte, error) { - path, task := guestPath, "wasm:guest:build:deterministic" - if eqlguest.Linked() { - path, task = eqlGuestPath, "wasm:guest:build:eql:deterministic" - } +// The test builds, each read once: embed.FS copies a file on every read, +// and a suite may call NewClient in every test. Package encrypt picks +// between them by the rule it picks its production build by. +var ( + plainTestBuild = sync.OnceValues(func() ([]byte, error) { + return readTestBuild(guestPath, "wasm:guest:build:deterministic") + }) + eqlTestBuild = sync.OnceValues(func() ([]byte, error) { + return readTestBuild(eqlGuestPath, "wasm:guest:build:eql:deterministic") + }) +) + +func readTestBuild(path, task string) ([]byte, error) { wasm, err := guestFS.ReadFile(path) if err != nil { return nil, notBuiltError{task: task} @@ -158,5 +164,5 @@ func testGuest() ([]byte, error) { type notBuiltError struct{ task string } func (e notBuiltError) Error() string { - return "encrypttest: the test build of the engine is not in this module; in a checkout of the repository, run `mise run " + e.task + "`" + return "the test build of the engine is not in this module; in a checkout of the repository, run `mise run " + e.task + "`" } diff --git a/languages/golang/encrypt/encrypttest/encrypttest_test.go b/languages/golang/encrypt/encrypttest/encrypttest_test.go index d6ed32551a..986c0805c7 100644 --- a/languages/golang/encrypt/encrypttest/encrypttest_test.go +++ b/languages/golang/encrypt/encrypttest/encrypttest_test.go @@ -32,8 +32,7 @@ func users() gensupport.Declaration { func skipWithoutGuest(t *testing.T) { t.Helper() - _, err := encrypttest.Contexts(context.Background(), users()) - if errors.Is(err, encrypt.ErrGuestNotBuilt) || errors.Is(err, encrypt.ErrEQLGuestNotBuilt) { + if _, err := encrypttest.Contexts(context.Background(), users()); errors.Is(err, encrypt.ErrGuestNotBuilt) { t.Skip(err) } } diff --git a/languages/golang/encrypt/encrypttest/internal/witheql/doc.go b/languages/golang/encrypt/encrypttest/internal/witheql/doc.go new file mode 100644 index 0000000000..728384b2d3 --- /dev/null +++ b/languages/golang/encrypt/encrypttest/internal/witheql/doc.go @@ -0,0 +1,7 @@ +// Package witheql tests encrypttest.NewClient in a program that links +// package eql, as an application whose generated code names an EQL type +// does. NewClient must then pick the test build with the EQL types. Whether +// eql is linked is fixed for a whole test binary, so these tests have a +// package of their own, and encrypttest's own tests keep a binary without +// eql. It holds no code. +package witheql diff --git a/languages/golang/encrypt/encrypttest/postgres_test.go b/languages/golang/encrypt/encrypttest/internal/witheql/postgres_test.go similarity index 99% rename from languages/golang/encrypt/encrypttest/postgres_test.go rename to languages/golang/encrypt/encrypttest/internal/witheql/postgres_test.go index 93566dd188..19b4b83c72 100644 --- a/languages/golang/encrypt/encrypttest/postgres_test.go +++ b/languages/golang/encrypt/encrypttest/internal/witheql/postgres_test.go @@ -1,4 +1,4 @@ -package encrypttest_test +package witheql_test import ( "context" diff --git a/languages/golang/encrypt/encrypttest/client_test.go b/languages/golang/encrypt/encrypttest/internal/witheql/witheql_test.go similarity index 98% rename from languages/golang/encrypt/encrypttest/client_test.go rename to languages/golang/encrypt/encrypttest/internal/witheql/witheql_test.go index 36ef4f2686..09b94ff63f 100644 --- a/languages/golang/encrypt/encrypttest/client_test.go +++ b/languages/golang/encrypt/encrypttest/internal/witheql/witheql_test.go @@ -1,4 +1,4 @@ -package encrypttest_test +package witheql_test import ( "bytes" @@ -17,7 +17,7 @@ import ( // These tests use the client as an application's tests would: through // generated code, with no credentials and no network. testusers names an // EQL type, so this binary links package eql and gets the test build with -// the EQL types. internal/withouteql covers the other build. +// the EQL types. ../withouteql covers the other build. var people = []testusers.User{ {ID: 1, Age: 34, Email: "alice@example.com", Notes: "likes cats"}, diff --git a/languages/golang/encrypt/guest.go b/languages/golang/encrypt/guest.go index d13c245689..89b42400e8 100644 --- a/languages/golang/encrypt/guest.go +++ b/languages/golang/encrypt/guest.go @@ -46,13 +46,23 @@ var ErrEQLGuestNotBuilt = errors.New("encrypt: guest module with the EQL types n // when package eql is linked (it registers on import, which cannot fail), // and only that build; else this package's own. func embeddedGuest() ([]byte, error) { + return selectBuild(plainGuest, eqlGuest) +} + +// selectBuild is the one rule for which engine build a client runs: the +// build with the EQL types when package eql is linked, and only that build, +// else the build without them. embeddedGuest applies it to the production +// builds and the encrypttest constructor to the test builds, so a test +// client cannot run a different build from a production client. +func selectBuild(plain, withEQL func() ([]byte, error)) ([]byte, error) { if eqlguest.Linked() { - wasm := eqlguest.Module() - if wasm == nil { - return nil, ErrEQLGuestNotBuilt - } - return wasm, nil + return withEQL() } + return plain() +} + +// plainGuest is this package's own build, the one without the EQL types. +func plainGuest() ([]byte, error) { wasm, err := guestFS.ReadFile(guestPath) if err != nil { return nil, ErrGuestNotBuilt @@ -60,6 +70,15 @@ func embeddedGuest() ([]byte, error) { return wasm, nil } +// eqlGuest is the build with the EQL types that package eql registered. +func eqlGuest() ([]byte, error) { + wasm := eqlguest.Module() + if wasm == nil { + return nil, ErrEQLGuestNotBuilt + } + return wasm, nil +} + // One shared compilation cache: only the first instantiation of a given // module in the process compiles it. Every Client still owns its own // runtime and instance. diff --git a/languages/golang/encrypt/internal/testclient/testclient.go b/languages/golang/encrypt/internal/testclient/testclient.go index 1593d01284..38fcc0b88d 100644 --- a/languages/golang/encrypt/internal/testclient/testclient.go +++ b/languages/golang/encrypt/internal/testclient/testclient.go @@ -11,10 +11,13 @@ import ( "errors" ) -// Constructor builds a client over wasm, a deterministic-kms build of the -// guest, with every key derived from seed. It returns the *encrypt.Client as -// any, because this package cannot import encrypt to name the type. -type Constructor func(ctx context.Context, wasm []byte, seed [32]byte) (any, error) +// Constructor builds a client over a deterministic-kms build of the guest, +// with every key derived from seed. plain and withEQL load the test builds +// without and with the EQL types; the constructor calls the one a +// production client in this program would match. It returns the +// *encrypt.Client as any, because this package cannot import encrypt to +// name the type. +type Constructor func(ctx context.Context, plain, withEQL func() ([]byte, error), seed [32]byte) (any, error) var constructor Constructor @@ -26,9 +29,9 @@ func Register(c Constructor) { constructor = c } var errNotRegistered = errors.New("encrypt: test client constructor not registered") // New calls the registered constructor. -func New(ctx context.Context, wasm []byte, seed [32]byte) (any, error) { +func New(ctx context.Context, plain, withEQL func() ([]byte, error), seed [32]byte) (any, error) { if constructor == nil { return nil, errNotRegistered } - return constructor(ctx, wasm, seed) + return constructor(ctx, plain, withEQL, seed) } diff --git a/languages/golang/encrypt/testclient.go b/languages/golang/encrypt/testclient.go index 152292a094..7fa3a36965 100644 --- a/languages/golang/encrypt/testclient.go +++ b/languages/golang/encrypt/testclient.go @@ -12,10 +12,15 @@ import ( // Package encrypttest builds its clients through this constructor. It is // registered with internal/testclient, which only packages under encrypt can // import, so no public function builds a client over a guest the caller -// chooses. It does nothing without a deterministic-kms build: the guest -// embedded for production refuses a bare seed as its config. +// chooses. It does nothing without a deterministic-kms build: the guests +// embedded for production refuse a bare seed as their config. It picks +// between the two test builds by selectBuild, the rule embeddedGuest uses. func init() { - testclient.Register(func(ctx context.Context, wasm []byte, seed [32]byte) (any, error) { + testclient.Register(func(ctx context.Context, plain, withEQL func() ([]byte, error), seed [32]byte) (any, error) { + wasm, err := selectBuild(plain, withEQL) + if err != nil { + return nil, err + } return seededClient(ctx, wasm, seed) }) } diff --git a/languages/golang/encrypt/testclient_test.go b/languages/golang/encrypt/testclient_test.go index 97110661da..883b801f33 100644 --- a/languages/golang/encrypt/testclient_test.go +++ b/languages/golang/encrypt/testclient_test.go @@ -8,27 +8,34 @@ import ( // The constructor package encrypttest reaches is harmless over the guests // this package and package eql embed for production: they take a client key, -// and refuse a bare seed as malformed config before any key exists. +// and refuse a bare seed as malformed config before any key exists. Each +// build is its own subtest, so a build that is absent shows as a skip and +// never drops out of the check unseen. func TestAProductionGuestRefusesASeed(t *testing.T) { - plain, err := PlainGuest() - if errors.Is(err, ErrGuestNotBuilt) { - t.Skip(err) - } - if err != nil { - t.Fatal(err) - } - guests := map[string][]byte{"the guest without the EQL types": plain} - if withEQL, err := EmbeddedGuest(); err == nil { - guests["the guest the program runs"] = withEQL - } - for name, wasm := range guests { - c, err := seededClient(context.Background(), wasm, [32]byte{7}) - if err == nil { - _ = c.Close() - t.Fatalf("%s took a seed in place of a client key", name) - } - if !errors.Is(err, ErrEncoding) { - t.Fatalf("%s: %v, want ErrEncoding", name, err) - } + for _, build := range []struct { + name string + load func() ([]byte, error) + absent error + }{ + {"without the EQL types", plainGuest, ErrGuestNotBuilt}, + {"with the EQL types", eqlGuest, ErrEQLGuestNotBuilt}, + } { + t.Run(build.name, func(t *testing.T) { + wasm, err := build.load() + if errors.Is(err, build.absent) { + t.Skip(err) + } + if err != nil { + t.Fatal(err) + } + c, err := seededClient(context.Background(), wasm, [32]byte{7}) + if err == nil { + _ = c.Close() + t.Fatal("a production guest took a seed in place of a client key") + } + if !errors.Is(err, ErrEncoding) { + t.Fatalf("%v, want ErrEncoding", err) + } + }) } } diff --git a/languages/golang/go.mod b/languages/golang/go.mod index 38bf2f40fd..f990caaa4c 100644 --- a/languages/golang/go.mod +++ b/languages/golang/go.mod @@ -18,7 +18,7 @@ require ( ) require ( - github.com/jackc/pgx/v5 v5.11.0 // test only: encrypt/postgres_test.go, encrypt/eql_postgres_test.go + github.com/jackc/pgx/v5 v5.11.0 // test only: encrypt/postgres_test.go, encrypt/eql_postgres_test.go, encrypt/encrypttest/internal/witheql/postgres_test.go golang.org/x/sys v0.49.0 golang.org/x/tools v0.52.0 google.golang.org/protobuf v1.36.12 diff --git a/mise.toml b/mise.toml index c64db54dd1..75d118fd9c 100644 --- a/mise.toml +++ b/mise.toml @@ -366,7 +366,7 @@ mise x --env test -- cargo nextest run """ [tasks."go:test"] -description = "Format check, vet and test the Go module (languages/golang: encrypt, auth and the internal packages) against the embedded guests; needs `wasm:guest:build` and `wasm:auth-guest:build` first" +description = "Format check, vet and test the Go module (languages/golang: encrypt, auth and the internal packages) against the embedded guests; needs `wasm:guest:build`, `wasm:guest:build:eql`, `wasm:auth-guest:build`, `wasm:guest:build:deterministic` and `wasm:guest:build:eql:deterministic` first" # The body lives in scripts/go-binding-test.sh so the macOS and Windows CI # jobs (which have Go but not mise) run exactly the same checks. One module # at languages/golang holds every Go package (ADR-0005 §4); the guest it @@ -399,7 +399,7 @@ pattern="^($(IFS='|'; echo "${TESTS[*]}"))$" # The tests skip without DATABASE_URL and without their guest builds; -v and # the grep turn either skip into a failure here, where both are provided. DATABASE_URL="$EQL_TEST_DATABASE_URL" CGO_ENABLED=0 go test -count=1 -v \ - -run "$pattern" ./encrypt ./encrypt/encrypttest \ + -run "$pattern" ./encrypt ./encrypt/encrypttest/internal/witheql \ | tee "${TMPDIR:-/tmp}/go-test-postgres.log" if grep -q -- '--- SKIP' "${TMPDIR:-/tmp}/go-test-postgres.log"; then echo "error: a PostgreSQL test skipped; build the deterministic guests first" >&2 diff --git a/scripts/go-binding-test.sh b/scripts/go-binding-test.sh index 9d6fe50b1a..64ace45820 100755 --- a/scripts/go-binding-test.sh +++ b/scripts/go-binding-test.sh @@ -10,19 +10,22 @@ # # Usage: go-binding-test.sh [...] # With no guest paths, every guest the module embeds is expected: the -# stack-encrypt guest, its build with the EQL types, and the credential guest. +# stack-encrypt guest, its build with the EQL types, the credential guest, +# and the two deterministic test builds package encrypttest embeds. Its +# tests fail, rather than skip, without them, so they are checked here first. set -euo pipefail dir=${1:?usage: go-binding-test.sh [...]} shift || true if [ $# -eq 0 ]; then - set -- encrypt/wasm/stack_encrypt_guest.wasm encrypt/eql/wasm/stack_encrypt_guest_eql.wasm auth/wasm/stack_auth_guest.wasm + set -- encrypt/wasm/stack_encrypt_guest.wasm encrypt/eql/wasm/stack_encrypt_guest_eql.wasm auth/wasm/stack_auth_guest.wasm \ + encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm encrypt/encrypttest/wasm/stack_encrypt_guest_eql_deterministic.wasm fi cd "$dir" for guest in "$@"; do if [ ! -f "$guest" ]; then - echo "guest module not built at $dir/$guest — run: mise run wasm:guest:build wasm:guest:build:eql wasm:auth-guest:build" >&2 + echo "guest module not built at $dir/$guest — run: mise run wasm:guest:build wasm:guest:build:eql wasm:auth-guest:build wasm:guest:build:deterministic wasm:guest:build:eql:deterministic" >&2 exit 1 fi done From 1b7fa300c1f1af3c9f5cadfb10a045cdae47d95a Mon Sep 17 00:00:00 2001 From: Dan Draper Date: Tue, 17 Nov 2026 23:42:19 +1100 Subject: [PATCH 3/3] test(golang): close the test gaps from the review of encrypttest.NewClient - TestTheDefaultSeedNeverChanges pins the default seed by value. The docs promise it never changes, and two clients sharing a changed seed cannot show it moved. - TestSelectBuildNeverFallsBackFromTheEQLBuild: with package eql linked, an absent EQL build is an error, never the plain build. - TestAMissingTestBuildNamesItsTask covers encrypttest's not-built error. - The release's "Build the test guests" step is run for real: it comes between building and hashing the guests, and fails when a test build overwrites a production guest. - go-binding-test.sh's default guest list is tested: a module with only the production guests is refused, naming the test builds' tasks. - TestTheClientIsClosedWhenTheTestEnds stops on a failed subtest instead of panicking on a nil client; NewClient closes a client of the wrong type before failing. - .gitignore keeps the old encrypt/testdata rules, so test builds made there before the move do not show as untracked. --- .gitignore | 4 + .../golang/encrypt/encrypttest/client.go | 3 + .../encrypttest/client_internal_test.go | 29 +++++++ .../internal/witheql/witheql_test.go | 8 +- languages/golang/encrypt/testclient_test.go | 22 ++++++ scripts/__tests__/go-binding-test.test.mjs | 36 +++++++++ .../__tests__/go-release-artifact.test.mjs | 76 +++++++++++++++++++ 7 files changed, 176 insertions(+), 2 deletions(-) create mode 100644 languages/golang/encrypt/encrypttest/client_internal_test.go diff --git a/.gitignore b/.gitignore index 820e27bf1d..45f50f01b9 100644 --- a/.gitignore +++ b/.gitignore @@ -123,3 +123,7 @@ languages/golang/auth/wasm/*.sha256 # Package encrypttest embeds them; the release commits them on the tag. languages/golang/encrypt/encrypttest/wasm/*.wasm languages/golang/encrypt/encrypttest/wasm/*.sha256 +# Where those builds went before they moved to encrypttest/wasm. A checkout +# that built them there still has them, and they must not show as untracked. +languages/golang/encrypt/testdata/*.wasm +languages/golang/encrypt/testdata/*.sha256 diff --git a/languages/golang/encrypt/encrypttest/client.go b/languages/golang/encrypt/encrypttest/client.go index e89e0c63e6..f92b31d47a 100644 --- a/languages/golang/encrypt/encrypttest/client.go +++ b/languages/golang/encrypt/encrypttest/client.go @@ -129,6 +129,9 @@ func NewClient(tb testing.TB, opts ...ClientOption) *encrypt.Client { } client, ok := built.(*encrypt.Client) if !ok { + if closer, ok := built.(interface{ Close() error }); ok { + _ = closer.Close() + } tb.Fatalf("encrypttest: the constructor returned %T, not *encrypt.Client", built) } tb.Cleanup(func() { diff --git a/languages/golang/encrypt/encrypttest/client_internal_test.go b/languages/golang/encrypt/encrypttest/client_internal_test.go new file mode 100644 index 0000000000..55e288b995 --- /dev/null +++ b/languages/golang/encrypt/encrypttest/client_internal_test.go @@ -0,0 +1,29 @@ +package encrypttest + +import ( + "encoding/hex" + "strings" + "testing" +) + +// The default seed is a promise: values an application's fixtures sealed +// under it in one release open under the next. Comparing two clients cannot +// show it changed, because both read the changed value, so it is pinned here +// by value. Changing it breaks every stored fixture: do not. +func TestTheDefaultSeedNeverChanges(t *testing.T) { + const pinned = "d691360b35d1606cd9ddb1035e658932575e269dcd8837f745584ed7b90714a8" + if got := hex.EncodeToString(defaultSeed[:]); got != pinned { + t.Fatalf("the default seed is %s, and every release has used %s", got, pinned) + } +} + +// A test build missing from the module is named, with the task that builds it. +func TestAMissingTestBuildNamesItsTask(t *testing.T) { + _, err := readTestBuild("wasm/not_a_build.wasm", "wasm:guest:build:deterministic") + if err == nil { + t.Fatal("a missing build was read") + } + if !strings.Contains(err.Error(), "mise run wasm:guest:build:deterministic") { + t.Fatalf("the error does not name the task to run: %v", err) + } +} diff --git a/languages/golang/encrypt/encrypttest/internal/witheql/witheql_test.go b/languages/golang/encrypt/encrypttest/internal/witheql/witheql_test.go index 09b94ff63f..ff0ab163bf 100644 --- a/languages/golang/encrypt/encrypttest/internal/witheql/witheql_test.go +++ b/languages/golang/encrypt/encrypttest/internal/witheql/witheql_test.go @@ -209,12 +209,16 @@ func TestAnotherSeedDoesNotOpenTheValues(t *testing.T) { func TestTheClientIsClosedWhenTheTestEnds(t *testing.T) { var client *encrypt.Client - t.Run("uses the client", func(t *testing.T) { + // A subtest that fails leaves client nil: stop here, on its failure, + // rather than on a nil client below. + if !t.Run("uses the client", func(t *testing.T) { client = encrypttest.NewClient(t) if _, err := testusers.Encrypt(t.Context(), client.DefaultKeyset(), people); err != nil { t.Fatal(err) } - }) + }) { + t.FailNow() + } _, err := testusers.Encrypt(context.Background(), client.DefaultKeyset(), people) if !errors.Is(err, encrypt.ErrState) { t.Fatalf("after the test that made it ended: %v, want ErrState", err) diff --git a/languages/golang/encrypt/testclient_test.go b/languages/golang/encrypt/testclient_test.go index 883b801f33..aae8b9968a 100644 --- a/languages/golang/encrypt/testclient_test.go +++ b/languages/golang/encrypt/testclient_test.go @@ -4,6 +4,8 @@ import ( "context" "errors" "testing" + + "github.com/cipherstash/stack/languages/golang/encrypt/internal/eqlguest" ) // The constructor package encrypttest reaches is harmless over the guests @@ -39,3 +41,23 @@ func TestAProductionGuestRefusesASeed(t *testing.T) { }) } } + +// When package eql is linked, a client runs the build with the EQL types and +// only that build. Its absence is an error, never the plain build in its +// place: every encrypt_into call would fail there. This test binary links +// eql, as the external tests' generated types name EQL types. +func TestSelectBuildNeverFallsBackFromTheEQLBuild(t *testing.T) { + if !eqlguest.Linked() { + t.Fatal("this test binary should link package eql") + } + plain := func() ([]byte, error) { return []byte("plain"), nil } + absent := func() ([]byte, error) { return nil, ErrEQLGuestNotBuilt } + wasm, err := selectBuild(plain, absent) + if !errors.Is(err, ErrEQLGuestNotBuilt) || wasm != nil { + t.Fatalf("selectBuild = %q, %v; want ErrEQLGuestNotBuilt and no build", wasm, err) + } + withEQL := func() ([]byte, error) { return []byte("eql"), nil } + if wasm, err := selectBuild(plain, withEQL); err != nil || string(wasm) != "eql" { + t.Fatalf("selectBuild = %q, %v; want the EQL build", wasm, err) + } +} diff --git a/scripts/__tests__/go-binding-test.test.mjs b/scripts/__tests__/go-binding-test.test.mjs index 75d0a92af5..328b27e79b 100644 --- a/scripts/__tests__/go-binding-test.test.mjs +++ b/scripts/__tests__/go-binding-test.test.mjs @@ -78,3 +78,39 @@ printf '%s|%s|%s\\n' "\${GOOS:-}" "\${GOARCH:-}" "$*" >> "$GO_BINDING_LOG" } } }) + +/** + * With no guest paths, the script checks for every guest the module embeds, + * the two test builds encrypttest embeds among them: its tests fail, rather + * than skip, without them. A missing build is named with the tasks to run. + */ +describe('Go binding script default guests', () => { + const PRODUCTION = [ + 'encrypt/wasm/stack_encrypt_guest.wasm', + 'encrypt/eql/wasm/stack_encrypt_guest_eql.wasm', + 'auth/wasm/stack_auth_guest.wasm', + ] + const TEST_BUILD = + 'encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm' + + it('refuses a module with the production guests and no test builds', () => { + const module = mkdtempSync(join(tmpdir(), 'go-binding-defaults-')) + try { + for (const guest of PRODUCTION) { + mkdirSync(join(module, guest, '..'), { recursive: true }) + writeFileSync(join(module, guest), 'guest') + } + const result = spawnSync( + '/bin/bash', + [join(REPO_ROOT, 'scripts/go-binding-test.sh'), module], + { encoding: 'utf8' }, + ) + expect(result.status).toBe(1) + expect(result.stderr).toContain(`${module}/${TEST_BUILD}`) + expect(result.stderr).toContain('wasm:guest:build:deterministic') + expect(result.stderr).toContain('wasm:guest:build:eql:deterministic') + } finally { + rmSync(module, { recursive: true, force: true }) + } + }) +}) diff --git a/scripts/__tests__/go-release-artifact.test.mjs b/scripts/__tests__/go-release-artifact.test.mjs index 5e7847207b..46ff97836e 100644 --- a/scripts/__tests__/go-release-artifact.test.mjs +++ b/scripts/__tests__/go-release-artifact.test.mjs @@ -324,3 +324,79 @@ describe.skipIf(!BASH_HAS_MAPFILE)( ) }, ) + +/** + * Every stack-encrypt build writes the same cargo output and differs only in + * where its mise task copies it. "Build the test guests" hashes the + * production guests before the two test builds run and checks them after, so + * a task that copied a seeded build over a production guest stops the + * release instead of being hashed and tagged as production. + */ +const BUILD_STEPS = WORKFLOW.jobs.build.steps +const TEST_BUILDS_STEP = BUILD_STEPS.find( + (step) => step.name === 'Build the test guests', +) + +/** Run the step with a `mise` that copies each test build to `target`. */ +function runTestBuilds(target) { + const bin = mkdtempSync(join(tmpdir(), 'go-release-mise-')) + try { + writeFileSync( + join(bin, 'mise'), + `#!/bin/sh\nmkdir -p "$(dirname "${target}")"\necho "seeded build of $2" > "${target}"\n`, + ) + chmodSync(join(bin, 'mise'), 0o755) + for (const guest of GUESTS) { + mkdirSync(dirname(join(repo, guest)), { recursive: true }) + writeFileSync(join(repo, guest), `guest ${guest}\n`) + } + return spawnSync('bash', ['-c', String(TEST_BUILDS_STEP.run)], { + cwd: repo, + encoding: 'utf8', + env: { + PATH: `${bin}:${SHIMS}:${process.env.PATH}`, + GUESTS: WORKFLOW.env.GUESTS, + RUNNER_TEMP: bin, + }, + }) + } finally { + rmSync(bin, { recursive: true, force: true }) + } +} + +describe('release-golang.yml build: Build the test guests', () => { + it('runs after the production guests are built and before they are hashed', () => { + const at = BUILD_STEPS.indexOf(TEST_BUILDS_STEP) + expect(at).toBeGreaterThan( + BUILD_STEPS.findIndex((step) => step.name === 'Build the guests'), + ) + expect(at).toBeLessThan( + BUILD_STEPS.findIndex((step) => step.name === 'Hash the guests'), + ) + }) + + it.skipIf(!GNU_COREUTILS)( + 'passes test builds that land where they belong', + () => { + const result = runTestBuilds( + 'languages/golang/encrypt/encrypttest/wasm/stack_encrypt_guest_deterministic.wasm', + ) + expect(result.status, result.stderr + result.stdout).toBe(0) + }, + // Spawns bash, sha256sum and a stub mise: slow on a loaded runner. + 30_000, + ) + + it.skipIf(!GNU_COREUTILS)( + 'stops the release when a test build overwrites a production guest', + () => { + const result = runTestBuilds( + 'languages/golang/encrypt/wasm/stack_encrypt_guest.wasm', + ) + expect(result.status).not.toBe(0) + expect(result.stdout + result.stderr).toContain('FAILED') + }, + // Spawns bash, sha256sum and a stub mise: slow on a loaded runner. + 30_000, + ) +})