README
¶
CipherStash Stack for Go
This module provides searchable field encryption for Go structs. stashgen
turns stash tags into typed encryption, decryption and query methods. The
encrypt package runs the Rust encryption engine in an embedded WASI guest
with wazero; applications do not need cgo.
Start with the SDK guide for installation, credentials, generation and PostgreSQL storage. The stashgen reference explains tags, supported field types and generated methods. The typed JSON document example walks through an EQL v4 table, queries and partial reads. The credential guide covers profile, access key and federation strategies. See the Go changelog for release and compatibility notes.
Using a released module
Use Go 1.26.10 or later (or 1.27.3 or later on the 1.27 line). Add the
generator to your application module, declare a struct with stash
tags, then generate and commit its *_stash.go file:
go get -tool github.com/cipherstash/stack/languages/golang/cmd/stashgen
go generate ./...
Use a tagged Go module version. Release tags include the embedded WASI guests;
a checkout or an untagged commit does not. The SDK guide
explains how to build them locally. Searchable encrypt_into fields require
EQL v4 in PostgreSQL; the EQL v4 SQL bundle is attached to the matching Go
release. Go and TypeScript currently use different EQL versions, so follow
the EQL column guide when choosing a schema.
Working in this repository
From the repository root, install the toolchain pinned by mise.toml and
build the guests before running Go tests:
mise run wasm:guest:build
mise run wasm:guest:build:eql
mise run wasm:guest:build:deterministic
mise run wasm:guest:build:eql:deterministic
mise run wasm:auth-guest:build
mise run go:test
The .wasm files are build outputs and are not committed on development
branches. mise run go:test:postgres also runs the PostgreSQL suite against
the EQL v4 bundle built from this tree; it needs the database named by
EQL_TEST_DATABASE_URL. See mise.toml and AGENTS.md
for the build and release details.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package auth is the Go binding of the developer profile: the directory `stash auth login` writes (~/.cipherstash, or CS_CONFIG_PATH), read through the stack-profile crate running unmodified inside a WASI guest under wazero (CGO_ENABLED=0), so the on-disk layout is never re-derived by hand in Go.
|
Package auth is the Go binding of the developer profile: the directory `stash auth login` writes (~/.cipherstash, or CS_CONFIG_PATH), read through the stack-profile crate running unmodified inside a WASI guest under wazero (CGO_ENABLED=0), so the on-disk layout is never re-derived by hand in Go. |
|
cmd
|
|
|
stashgen
command
Command stashgen writes the encrypted type and its functions for a struct with stash tags.
|
Command stashgen writes the encrypted type and its functions for a struct with stash tags. |
|
Package encrypt is the Stack Encrypt Go SDK: searchable, field-level encryption under per-value ZeroKMS data keys, running the stack-encrypt Rust engine unmodified inside a WASI guest under wazero (CGO_ENABLED=0).
|
Package encrypt is the Stack Encrypt Go SDK: searchable, field-level encryption under per-value ZeroKMS data keys, running the stack-encrypt Rust engine unmodified inside a WASI guest under wazero (CGO_ENABLED=0). |
|
eql
Package eql holds the EQL types a program stores: one Go type per EQL type, each holding the EQL value as the JSON bytes PostgreSQL stores in the type's domain, and the query types that match them.
|
Package eql holds the EQL types a program stores: one Go type per EQL type, each holding the EQL value as the JSON bytes PostgreSQL stores in the type's domain, and the query types that match them. |
|
example
command
Command example encrypts a batch of users against real ZeroKMS, using the credentials `stash auth login` leaves in the developer profile (or the CS_* environment variables, which win), and reads them back.
|
Command example encrypts a batch of users against real ZeroKMS, using the credentials `stash auth login` leaves in the developer profile (or the CS_* environment variables, which win), and reads them back. |
|
example/json
command
Command json demonstrates a typed encrypted JSON document in PostgreSQL.
|
Command json demonstrates a typed encrypted JSON document in PostgreSQL. |
|
gensupport
Package gensupport holds what only code written by stashgen calls.
|
Package gensupport holds what only code written by stashgen calls. |
|
internal/eqlguest
Package eqlguest is where package eql hands the guest build with the EQL types to package encrypt.
|
Package eqlguest is where package eql hands the guest build with the EQL types to package encrypt. |
|
internal/genmember
command
Command genmember writes testpolicy's generated file from a policy: the stashgen.Generate path, over testmember.Member, with the declaration testusers.User carries as tags.
|
Command genmember writes testpolicy's generated file from a policy: the stashgen.Generate path, over testmember.Member, with the declaration testusers.User carries as tags. |
|
internal/testmember
Package testmember holds a struct the encrypt tests encrypt through the two generator paths that take a type the program does not own: the `-for` flag (testusers declares the tags for Member in a struct of its own) and stashgen.Generate from a policy (genmember writes testpolicy).
|
Package testmember holds a struct the encrypt tests encrypt through the two generator paths that take a type the program does not own: the `-for` flag (testusers declares the tags for Member in a struct of its own) and stashgen.Generate from a policy (genmember writes testpolicy). |
|
internal/testpolicy
Package testpolicy holds the file stashgen.Generate writes for testmember.Member from a policy (see internal/genmember): the generated Encrypt, Decrypt and Fields over *testmember.Member, with the declaration testusers.User carries as tags.
|
Package testpolicy holds the file stashgen.Generate writes for testmember.Member from a policy (see internal/genmember): the generated Encrypt, Decrypt and Fields over *testmember.Member, with the declaration testusers.User carries as tags. |
|
internal/testusers
Package testusers holds the tagged structs the encrypt tests encrypt through the generated API: a record in separate columns, an opaque struct, and a probe struct with one field of each scalar type for the term ordering tests.
|
Package testusers holds the tagged structs the encrypt tests encrypt through the generated API: a record in separate columns, an opaque struct, and a probe struct with one field of each scalar type for the term ordering tests. |
|
policy
Package policy decides how a type that cannot carry stash tags is encrypted, from what its schema says about each field.
|
Package policy decides how a type that cannot carry stash tags is encrypted, from what its schema says about each field. |
|
policy/protosource
Package protosource reads the facts about a protobuf message's fields: each field's name, its Go name, its kind, and its options as annotations.
|
Package protosource reads the facts about a protobuf message's fields: each field's name, its Go name, its kind, and its options as annotations. |
|
policy/protosource/internal/testpb
Package testpb is protoc-gen-go output for the protosource tests: the two messages of docs/plans/2026-10-04-plan-builder/proto, where classification.data_categories is a repeated string field option.
|
Package testpb is protoc-gen-go output for the protosource tests: the two messages of docs/plans/2026-10-04-plan-builder/proto, where classification.data_categories is a repeated string field option. |
|
internal
|
|
|
guest
Package guest is what the Go packages over the WASI guests share and neither should own: the locked, non-dumpable memory a guest instance runs in; the status table every guest reports through, the errors it decodes to and the Diagnostic behind each; and the opaque client key one package reads and the other consumes.
|
Package guest is what the Go packages over the WASI guests share and neither should own: the locked, non-dumpable memory a guest instance runs in; the status table every guest reports through, the errors it decodes to and the Diagnostic behind each; and the opaque client key one package reads and the other consumes. |
|
guesttest
Package guesttest holds what the tests of the guest packages share: a hand-assembled probe module that exercises the memory allocator without a guest, the lock-limit machinery those tests need, and the skip rules for hosts that cannot run them.
|
Package guesttest holds what the tests of the guest packages share: a hand-assembled probe module that exercises the memory allocator without a guest, the lock-limit machinery those tests need, and the skip rules for hosts that cannot run them. |
|
record
Package record is the data form of a declaration as the engine reads it: the plan object the guest's se_encrypt_record, se_decrypt_record and se_plan_check parse, and the per-field outputs they return.
|
Package record is the data form of a declaration as the engine reads it: the plan object the guest's se_encrypt_record, se_decrypt_record and se_plan_check parse, and the per-field outputs they return. |
|
Package stashgen is the Stack Encrypt code generator for Go, as a library.
|
Package stashgen is the Stack Encrypt code generator for Go, as a library. |
|
enginetest
Package enginetest is a static stand-in for the Rust engine in the generator's tests.
|
Package enginetest is a static stand-in for the Rust engine in the generator's tests. |
Click to show internal directories.
Click to hide internal directories.