Skip to content

feat(golang): encrypttest.NewClient, an offline client for application tests - #1697

Draft
coderdan wants to merge 2 commits into
nextfrom
coderdan/go-sdk-an-applications-tests-cannot-encrypt-with
Draft

coderdan wants to merge 2 commits into
nextfrom
coderdan/go-sdk-an-applications-tests-cannot-encrypt-with

Conversation

@coderdan

@coderdan coderdan commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

A Go application can now test its encrypted read and write paths in CI with no CipherStash credentials and no network. encrypttest.NewClient(t) returns a real *encrypt.Client. It runs the same engine and the same generated code as production. Only the key source differs: each key comes from a seed, not from ZeroKMS (CipherStash's key service). EQL v4 columns in PostgreSQL accept what it writes, and its search terms match. (EQL is the SQL extension that stores and queries encrypted values.)

Before this, the only client that needed no credentials was a helper in the SDK's own _test.go files, so no application could reach it.

Changes

New API, in the existing encrypt/encrypttest package

  • NewClient(tb, ...ClientOption) *encrypt.Client. It closes the client when the test ends. It fails the test, and never skips it, when the client cannot start. It also fails outside a test binary (testing.Testing()).
  • WithSeed([32]byte). Every client with the default seed opens what another sealed, in any process, so a test that loads fixtures and a test that reads them share keys. The default seed never changes.
  • It picks the test build with the EQL types when the program links encrypt/eql, as encrypt.NewClient picks the production build.

How it reaches the engine

  • encrypt/testclient.go and encrypt/internal/testclient. encrypttest imports encrypt, so encrypt registers the constructor in an internal package on init, the same pattern as eqlguest. The constructor picks the test build with encrypt.selectBuild, the same function embeddedGuest uses for the production builds. No public function builds a client over a guest the caller chooses. The constructor already existed as deterministicClient in export_test.go and has moved.
  • The key source is stack-kms's DeterministicSource. Each key comes from the seed and the value's context. A key asked for under another context is refused with ZeroKMS's 403. So a wrong context still fails with ErrForbidden, and another keyset's value with ErrForeignKeyset.

Where the test builds live, and the release

  • The two deterministic test builds move from encrypt/testdata/ to encrypt/encrypttest/wasm/. The package embeds them from there, and the SDK's own tests read them from there. I updated every path: the mise tasks, tests-golang.yml, the conformance scripts and their tests, .gitignore, and two Go test helpers.
  • release-golang.yml adds both test builds to GUESTS. It builds them before the hash, so the tag commits them with the three production guests and verify checks them in the module zip. Before running them, it hashes the production guests, and checks those hashes again afterwards, so a test build can never be tagged as a production guest. The two test builds add about 5.8 MB (2.3 MB and 3.5 MB) to every module download.
  • go:test:postgres also runs TestEncryptTestClientInPostgres.
  • scripts/go-binding-test.sh checks for the two test builds up front, because encrypttest's tests fail without them.

Docs

  • encrypt/README.md has a new "Testing your application" section. The CHANGELOG.md entry is under Unreleased.
  • The comments that said "nothing test-only is embedded" now describe the new rule: the test builds are embedded only by encrypttest, which only _test.go files should import. These are in Cargo.toml, deterministic.rs, eql/guest.go and the wasm READMEs.
  • AGENTS.md (the Go module entry and the guest count) and SECURITY.md. SECURITY.md now says the test builds' keys are not secret by design, and that a production client loading a test build is in scope.

Verification

  • scripts/go-binding-test.sh languages/golang: gofmt, vet and the full module test suite against freshly built guests. Passed, all 15 packages, with no skips.
  • golangci-lint run ./... (2.14.0): 0 issues.
  • New tests, all passing:
    • round trip through generated code;
    • an EQL TextEq value and its query term match;
    • every keyset exists by name and by id, and KeysetName("default") is the default keyset;
    • another keyset's rows fail with ErrForeignKeyset;
    • another scope fails with ErrForbidden, and a context field mismatch with ErrContextMismatch;
    • the default seed is shared across clients, and another seed fails with ErrForbidden;
    • search terms do not depend on the seed;
    • the client is closed at cleanup;
    • the build without the EQL types is used when eql is not linked (encrypttest/internal/withouteql). The tests that link eql live in encrypttest/internal/witheql, so encrypttest's own tests keep a binary without it;
    • the production guests refuse a seed in place of a client key (TestAProductionGuestRefusesASeed).
  • TestEncryptTestClientInPostgres runs the issue's five steps: create the client, encrypt, insert into an eql_v4_text_eq column, query it with eql_v4.query_text_eq, and decrypt. It passed against a throwaway PostgreSQL 17 with the rc.5 eql-v4-install.sql (eql_v4.version() = go-0.1.0-rc.5). TestEQLTypesRoundTripAndQueryInPostgres and TestQueriesRunAgainstPostgres passed in the same run.
  • Script tests: go-release-artifact, the exchange and lifecycle conformance tests, crates-ci, go-release-version, workflow-publish-permissions, lint-no-workflow-caching and ffi-binding-step-order pass.
    • The full test:scripts run had 3 files that would not load: bench-index-expressions, check-auth-npm-changeset and migration-fixture-client. They need packages that were missing from the local node_modules I ran with, and this PR does not touch them.
    • Biome could not load its config locally. The edited script lines are path strings under 80 columns.
  • Not run locally: the release workflow itself, and the macOS and Windows CI jobs.

Related

Closes #1696

Review notes

  • Base is next, not main. v0.1.0-rc.5 was cut from next, and the EQL v4 support the issue asks for is only on next.

  • Where to look first: encrypt/encrypttest/client.go, then encrypt/testclient.go and encrypt/internal/testclient.

  • What a test cannot see:

    • every keyset exists, so a test never gets ErrNotFound for a missing keyset, or ErrForbidden for a keyset with no grant;
    • the client has no token, so it never returns ErrUnauthorized.

    NewClient's doc comment lists these.

  • Open decision: module size. The test builds add about 5.8 MB to every go get, including for programs that never import encrypttest. A nested encrypttest module would avoid that, at the cost of a second tag in the release. See the review reply.

  • Deferred: making search terms depend on the seed. DeterministicSource takes its index key from FakeDataKeySource, which uses only the keyset id. Changing that would move terms pinned by existing tests and fixtures. The doc comment says terms do not depend on the seed.

  • Import guard: Go cannot stop a non-test file importing encrypttest. The testing.Testing() check makes that fail at the first NewClient call, not silently.

…n 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.
@changeset-bot

changeset-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: bbaa732

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@coderabbitai

coderabbitai Bot commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

@github-actions

Copy link
Copy Markdown
Contributor

Mutation testing (cargo-mutants, --in-diff, stack-auth + stack-encrypt)

No mutants were generated for the changed lines.

@coderdan

Copy link
Copy Markdown
Contributor Author

Code review (/code-review high)

Nine findings, most severe first. Fixes follow on this branch; I'll reply here with what changed.

  1. WithSeed doc promises isolation that search terms don't give (encrypt/encrypttest/client.go:39). Search terms depend only on the keyset, so a query from a test with another seed still matches rows that another test wrote under the same keyset name. Decrypting those rows then fails with ErrForbidden. Tests should isolate by keyset name.
  2. go:test checks for only the production guests (scripts/go-binding-test.sh:19, mise.toml go:test description). The encrypttest tests now fail when the deterministic test builds are missing. Before this PR they skipped. The pre-check passes, the run goes red late, and nothing names the two :deterministic tasks.
  3. Build selection is copied, not shared (encrypt/encrypttest/client.go:144). testGuest repeats encrypt.embeddedGuest's rule: if eqlguest.Linked(), use the EQL build. A later change to one copy would put test and production clients on different builds.
  4. TestAProductionGuestRefusesASeed silently drops the EQL guest (encrypt/testclient_test.go:21). When the EQL production build is absent, the guest is left out of the check and the test still passes. That property is now in scope in SECURITY.md.
  5. Release: the test builds now run before the hash (.github/workflows/release-golang.yml:177). All four guest tasks build to the same cargo output. A task that copied a deterministic build over a production guest would now be hashed and tagged as production. The old order would have caught that.
  6. Each NewClient copies the embedded guest (encrypt/encrypttest/client.go:149). embed.FS.ReadFile copies the bytes on every call. A suite with hundreds of NewClient calls allocates megabytes each time.
  7. Every go get downloads the test builds (encrypt/encrypttest/wasm/README.md). This is so even for programs that never import encrypttest. A nested module for encrypttest would charge only its users.
  8. Linking eql into the encrypttest test binary changes the existing tests (encrypt/encrypttest/encrypttest_test.go:33). Contexts/AssertContexts now run only against the EQL guest and skip without it, while the NewClient tests in the same package fail. Nothing runs Contexts against the plain guest any more.
  9. The go.mod comment on the pgx dependency is out of date (go.mod:21). It lists the PostgreSQL test files that use pgx and does not include the new encrypttest one.

- 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.
@coderdan

Copy link
Copy Markdown
Contributor Author

Review fixes (bbaa73256)

  1. WithSeed doc — fixed. It no longer promises isolation. Search terms depend on the keyset alone, so tests that share a table should use separate keyset names. The NewClient doc and the README say the same.
  2. go:test pre-check — fixed. scripts/go-binding-test.sh now checks for the two test builds up front and names their mise tasks. The go:test description lists all five builds.
  3. Copied build selection — fixed. encrypt.selectBuild is now the only rule. embeddedGuest uses it for the production builds. The encrypttest constructor passes both test builds to encrypt, which picks with the same function.
  4. The EQL guest dropping out of TestAProductionGuestRefusesASeed — fixed. Each production build is now its own subtest, so a missing build shows as a skip. Locally both subtests ran and passed.
  5. Release hash order — fixed. A new "Build the test guests" step hashes the production guests, runs the two test builds, and checks the production hashes again. If a test-build task overwrote a production guest, the release stops there. All five guests are then hashed as before.
  6. ReadFile on each call — fixed. Each test build is read once, through sync.OnceValues.
  7. Test builds in every go get — not changed; your decision. I measured them on next: 2.3 MB and 3.5 MB, about 5.8 MB per module download. The PR body said 1.9 MB; that came from older builds on main and is now corrected. A nested encrypttest module would avoid the cost, but it would need its own tag in release-golang.yml, a require on the parent module at the same version, and a two-step pre-release. I would rather decide that separately than add it to this PR.
  8. eql linked into encrypttest's test binary — fixed. The NewClient tests and the PostgreSQL test moved to encrypttest/internal/witheql, beside withouteql. encrypttest's own tests are back to next's version and run against the plain guest again. go:test:postgres points at the new package.
  9. go.mod pgx comment — fixed. It now names the new PostgreSQL test.

Verification after the fixes:

  • scripts/go-binding-test.sh languages/golang: 15 packages pass, with no skips or failures.
  • golangci-lint run ./...: 0 issues.
  • 9 script test files (209 tests) pass, including go-binding-test, go-release-artifact and stack-conformance-ci.
  • TestEncryptTestClientInPostgres passes again from its new package, against a throwaway PostgreSQL 17 with the rc.5 EQL v4 bundle.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant