feat(golang)!: the Go SDK: stash tags, stashgen and generated Encrypt/Decrypt

.github/dependabot.yml

@@ -211,8 +211,8 @@ updates:
       - /packages/stack-auth/fuzz
       - /packages/stack-kms/fuzz
       - /packages/stack-encrypt/fuzz
-      - /languages/golang/stackencrypt/guest
-      - /languages/golang/stackauth/guest
+      - /languages/golang/encrypt/guest
+      - /languages/golang/auth/guest
     # Monthly, matching the other two cargo entries.
     schedule:
       interval: monthly

.github/workflows/tests-golang.yml

@@ -8,8 +8,10 @@ name: Tests (Go)
 #   wasi-check  the stack crates build for wasm32-wasip1 with no JS-host or
 #               native-HTTP dependencies, the no-http shape passes its tests
 #               and docs, both guests pass lint and tests and are built with
-#               their import surfaces checked, their sha256 is recorded, and
-#               `go:test` runs against them.
+#               their import surfaces checked (the stack-encrypt guest twice:
+#               the real build and the deterministic-kms test build), their
+#               sha256 is recorded, `go:test` runs against them, and
+#               `go generate` leaves the tree unchanged.
 #   go-lint     golangci-lint, Linux only.
 #   go-binding-cross
 #               the same Go tests on macOS and Windows, against the guests
@@ -122,8 +124,8 @@ jobs:
         with:
           workspaces: |
             .
-            languages/golang/stackencrypt/guest
-            languages/golang/stackauth/guest
+            languages/golang/encrypt/guest
+            languages/golang/auth/guest
 
       # The HTTP-free core compiles for wasm32-wasip1 with no JS-host backend
       # and no native HTTP/TLS stack in its graph: the invariant the wazero
@@ -146,6 +148,14 @@ 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.
+      - name: stack-encrypt guest deterministic test build
+        run: mise run wasm:guest:build:deterministic
+
       - name: Credential guest lint and tests
         run: mise run wasm:auth-guest:test
 
@@ -157,7 +167,7 @@ jobs:
       # same bytes rather than a stale or rebuilt guest.
       - name: Record the guests' checksums
         run: |
-          for guest in stackencrypt/wasm/stack_encrypt_guest.wasm stackauth/wasm/stack_auth_guest.wasm; do
+          for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/testdata/stack_encrypt_guest_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
 
@@ -166,25 +176,45 @@ jobs:
         with:
           name: wasm-guests
           path: |
-            languages/golang/stackencrypt/wasm/stack_encrypt_guest.wasm
-            languages/golang/stackencrypt/wasm/stack_encrypt_guest.wasm.sha256
-            languages/golang/stackauth/wasm/stack_auth_guest.wasm
-            languages/golang/stackauth/wasm/stack_auth_guest.wasm.sha256
+            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/auth/wasm/stack_auth_guest.wasm
+            languages/golang/auth/wasm/stack_auth_guest.wasm.sha256
           if-no-files-found: error
           retention-days: 1
 
       # Format, vet and hermetic tests on amd64 and 386. The guest's memory
       # lock is best effort, so its test skips where RLIMIT_MEMLOCK refuses
-      # it; CI raises the limit and sets STACKENCRYPT_TESTS_REQUIRE_LOCK so
+      # it; CI raises the limit and sets STACK_ENCRYPT_TESTS_REQUIRE_LOCK so
       # the skip is an error here.
       - name: Go binding
         env:
-          STACKENCRYPT_TESTS_REQUIRE_LOCK: "1"
+          STACK_ENCRYPT_TESTS_REQUIRE_LOCK: "1"
         run: |
           ulimit -l "$(ulimit -H -l)"
           echo "RLIMIT_MEMLOCK: $(ulimit -l) KiB"
           mise run go:test
 
+      # What is encrypted is fixed before the program ships: every generated
+      # file is committed, and this fails when `go generate` would change
+      # one. It runs the real stashgen against the guest just built, so it
+      # also proves the generator and the engine agree on the module's own
+      # examples. `git diff` sees only tracked files, so the status check
+      # catches a generated file that was never committed.
+      - name: Generated code is committed
+        working-directory: languages/golang
+        run: |
+          CGO_ENABLED=0 go generate ./...
+          git diff --exit-code -- .
+          untracked="$(git status --porcelain -- .)"
+          if [ -n "$untracked" ]; then
+            echo "::error::go generate wrote files that are not committed:"
+            echo "$untracked"
+            exit 1
+          fi
+
   # Linux only: macOS and Windows would report the same findings. Needs no
   # guests: the packages embed a directory and compile without them.
   go-lint:
@@ -260,7 +290,7 @@ jobs:
       - name: The guests are the ones Linux built and checked
         run: |
           cd languages/golang
-          for guest in stackencrypt/wasm/stack_encrypt_guest.wasm stackauth/wasm/stack_auth_guest.wasm; do
+          for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/testdata/stack_encrypt_guest_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
@@ -326,7 +356,7 @@ jobs:
       - name: The guests are the ones the wasi-check job built and checked
         run: |
           cd languages/golang
-          for guest in stackencrypt/wasm/stack_encrypt_guest.wasm stackauth/wasm/stack_auth_guest.wasm; do
+          for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/testdata/stack_encrypt_guest_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
@@ -340,7 +370,7 @@ jobs:
       # call `liveClient`, and not all of them are named `TestLive*`.
       - name: Go live tests
         working-directory: languages/golang
-        run: CGO_ENABLED=0 go test -v ./stackencrypt/...
+        run: CGO_ENABLED=0 go test -v ./encrypt/...
 
       - name: stack-encrypt examples
         run: |

.gitignore

@@ -108,7 +108,11 @@ mutants.out/
 
 # The Go module's embedded WASI guests: build outputs of `mise run
 # wasm:guest:build` and `mise run wasm:auth-guest:build`.
-languages/golang/stackencrypt/wasm/*.wasm
-languages/golang/stackauth/wasm/*.wasm
-languages/golang/stackencrypt/wasm/*.sha256
-languages/golang/stackauth/wasm/*.sha256
+languages/golang/encrypt/wasm/*.wasm
+languages/golang/auth/wasm/*.wasm
+languages/golang/encrypt/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

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 (`stackencrypt`, `stackauth`, `internal`), a wazero host with no cgo. Its two WASI guests (`*/guest`) are detached Cargo workspaces built by `mise run wasm:guest:build` and `mise run wasm:auth-guest:build`; the `.wasm` files they embed are gitignored. There is no Go release process yet.
+- `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. Generated `*_stash.go` files are committed and CI fails when `go generate ./...` changes one. There is no Go release process yet.
 - `e2e/*`: Cross-package end-to-end tests (package managers, supply chain, Prisma example README)
 - `languages/typescript/examples/*`: Working apps (basic, prisma, supabase-worker)
 - `docs/plans/*`: Internal design plans. User-facing documentation lives at https://cipherstash.com/docs (not in this repo).

Cargo.toml

@@ -27,8 +27,8 @@ exclude = [
   "packages/stack-encrypt/fuzz",
   # WASI guests for the Go module, built through `wasm:guest:build` and
   # `wasm:auth-guest:build`.
-  "languages/golang/stackencrypt/guest",
-  "languages/golang/stackauth/guest",
+  "languages/golang/encrypt/guest",
+  "languages/golang/auth/guest",
 ]
 
 [workspace.package]

SECURITY.md

@@ -33,7 +33,7 @@ It also carries the source of five Rust crates published to crates.io,
 `packages/stack-profile`) and **`stack-kms`**, **`stack-encrypt`** and
 **`stack-encrypt-derive`** (`packages/stack-kms`, `packages/stack-encrypt`,
 `packages/stack-encrypt-derive`), and of the **Go module** at
-`languages/golang` (`stackencrypt` and `stackauth`, over WASI guests built
+`languages/golang` (`encrypt` and `auth`, over WASI guests built
 from the stack-* crates), which has no release yet. All of these are in scope
 for security reports on the same terms as the npm packages above.
 

docs/plans/2026-10-04-plan-builder.md

@@ -16,6 +16,13 @@ the builder itself, #1071), with a second round of decisions: decrypt is
 spelled `open`, the two starts and the three context sources, the typed
 verb and the picker, the derive narrowed before it emits the plan, and EQL
 types assembled per language with no registry.
+Amended 2026-10-07 (#1094): where this document says the typed parts "have
+no data form" and lists `context_field` among them ("Consolidation", and
+item 3 under "Why the first draft was dropped"), it is wrong about
+`context_field`. That verb is not typed, and the data grammar now spells it
+as a plan-level `"context_field"` key; the Go SDK spells it as the
+`context_field` tag word. The typed parts that have no data form are
+`encrypt_into`, the picker and the one-value start.
 **Date:** 2026-10-04
 **Issue:** #1046
 **Builds on:** #1050 (one context per column; `Label`, `Describe`), #971 (EQL v3

languages/golang/.gitattributes

@@ -0,0 +1,10 @@
+# stashgen's golden test expectations. Marked `linguist-generated` so GitHub
+# collapses them in pull-request and commit diffs by default and excludes them
+# from repository language statistics. This is a GitHub display hint only:
+# nothing about Git, CI, or the build changes.
+#
+# The generated *_stash.go files are deliberately NOT marked. They are the
+# committed record of which fields are encrypted, with which indexes and under
+# which context, so a change to them must stay expanded for the reviewer to
+# read (docs/sdk-design-principles.md, Go principle 10).
+*.golden linguist-generated

languages/golang/stackauth/README.md → languages/golang/auth/README.md

@@ -1,9 +1,9 @@
-# stackauth
+# auth
 
 The Go binding of the developer profile — the directory `stash auth login`
 writes — read through the `stack-profile` Rust crate running inside a WASI
 guest under [wazero], with `CGO_ENABLED=0`. It is the credential half of
-the Go SDK: it hands a [`stackencrypt`](../stackencrypt) client its client
+the Go SDK: it hands an [`encrypt`](../encrypt) client its client
 key and its bearer token without either package re-deriving the profile's
 layout, and without either importing the other.
 
@@ -16,30 +16,30 @@ cross-process refresh lock for device sessions.
 
 ## Use
 
-Most applications never call this package directly: a `stackencrypt`
+Most applications never call this package directly: an `encrypt`
 client built with `NewClient(ctx)` and no options resolves its credentials with
-`stackencrypt.AutoCredentials`, which reads the environment first and then
+`encrypt.AutoCredentials`, which reads the environment first and then
 the profile, through this package. Use it directly to take the profile
 apart yourself:
 
 ```go
 import (
     "context"
 
-    "github.com/cipherstash/stack/languages/golang/stackauth"
-    "github.com/cipherstash/stack/languages/golang/stackencrypt"
+    "github.com/cipherstash/stack/languages/golang/auth"
+    "github.com/cipherstash/stack/languages/golang/encrypt"
 )
 
 func run(ctx context.Context) error {
-    profile, err := stackauth.Resolve(ctx) // CS_CONFIG_PATH, else ~/.cipherstash
+    profile, err := auth.Resolve(ctx) // CS_CONFIG_PATH, else ~/.cipherstash
     if err != nil {
         return err
     }
     defer profile.Close()
 
     workspace, err := profile.CurrentWorkspaceStore(ctx)
     if err != nil {
-        return err // stackauth.ErrNoCurrentWorkspace: run `stash auth login`
+        return err // auth.ErrNoCurrentWorkspace: run `stash auth login`
     }
     clientID, clientKey, err := workspace.SecretKey(ctx)
     if err != nil {
@@ -50,9 +50,9 @@ func run(ctx context.Context) error {
         return err
     }
     defer source.Close()
-    client, err := stackencrypt.NewClient(ctx,
+    client, err := encrypt.NewClient(ctx,
         // The key is consumed and wiped by NewClient.
-        stackencrypt.WithCredentials(stackencrypt.NewCredentials(clientID, clientKey, source)),
+        encrypt.WithCredentials(encrypt.NewCredentials(clientID, clientKey, source)),
     )
     if err != nil {
         return err
@@ -63,32 +63,32 @@ func run(ctx context.Context) error {
 }
 ```
 
-`stackauth.ClientKey` and `stackencrypt.ClientKey` are one type, so the
+`auth.ClientKey` and `encrypt.ClientKey` are one type, so the
 key goes straight from the profile into the credentials. The profile and
 the strategy are the caller's: the client asks the strategy for a token on
 every request but never closes it, so both stay open until the client is
 closed (the deferred calls above run in that order).
 
-A stackencrypt client takes its token only from a strategy, never a raw
+An encrypt client takes its token only from a strategy, never a raw
 string: a raw token cannot be refreshed when it expires, and would bypass
 the cross-process lock a device-session refresh holds with the `stash` CLI
 (the IdP revokes a whole refresh-token chain when one is used twice).
 `workspace.Token(ctx)` still reads the stored token, for inspection.
 
 With no profile directory at all (CI, a container, a server authenticating
-by federation), `stackauth.OpenWithoutProfile(ctx)` runs the guest with
+by federation), `auth.OpenWithoutProfile(ctx)` runs the guest with
 nothing mounted: the access-key and OIDC strategies work, and every profile
 read is `ErrNoProfile`.
 
 `profile.AccessKey(ctx, crn, key)`, `profile.OIDC(ctx, crn, provider)`, and
-`profile.Auto(ctx)` also return strategies that `stackencrypt.NewCredentials`
+`profile.Auto(ctx)` also return strategies that `encrypt.NewCredentials`
 takes. `Auto` checks `CS_CLIENT_ACCESS_KEY` and
 `CS_WORKSPACE_CRN` first, then the current workspace's stored device session.
 The OIDC provider is a one-method `Token(context.Context) (string, error)`
 interface, called on every token fetch for the JWT of the user the call is
 for; each distinct JWT is exchanged once while its CTS token lasts. Use
-`stackauth.OAuth2TokenSource(source)` to adapt a
-`golang.org/x/oauth2.TokenSource`. `WithAuthBaseURL(url)` overrides service
+`auth.OAuth2TokenSource(source)` to adapt a
+`golang.org/x/oauth2.TokenSource`. `WithBaseURL(url)` overrides service
 discovery for local tests or a custom CTS host; `WithCacheCapacity(n)` sets
 how many users' CTS tokens an OIDC strategy keeps (1024 unless set), sized to
 the users it serves within a CTS token's lifetime.
@@ -107,7 +107,7 @@ session refresh call, on the path `ProfileStore.LockPath` names. A fresh
 token is read without the lock; on refresh the guest re-reads
 auth.json after acquisition and saves refreshed tokens before release.
 
-The crypto guest behind `stackencrypt` is not widened by this package
+The crypto guest behind `encrypt` is not widened by this package
 existing: it still has no filesystem and no environment.
 
 ## Build

languages/golang/stackauth/clientkey.go → languages/golang/auth/clientkey.go

@@ -1,12 +1,12 @@
-package stackauth
+package auth
 
 import "github.com/cipherstash/stack/languages/golang/internal/guest"
 
 // ClientKey is the ZeroKMS client key as [ProfileStore.SecretKey] reads it
 // out of secretkey.json: opaque (it prints a redaction under every verb and
 // hands its bytes to no caller) and wiped once consumed. It is the same
-// type as stackencrypt.ClientKey, by identity, so a key read here goes
-// straight into stackencrypt.NewCredentials. This package does not import
-// stackencrypt: a binary that only wants the profile does not carry the
-// crypto guest. (stackencrypt imports this one, for AutoCredentials.)
+// type as encrypt.ClientKey, by identity, so a key read here goes
+// straight into encrypt.NewCredentials. This package does not import
+// encrypt: a binary that only wants the profile does not carry the
+// crypto guest. (encrypt imports this one, for AutoCredentials.)
 type ClientKey = guest.ClientKey