feat(stack-kms-aws): AWS KMS key vendor backend (CIP-5307)

.github/workflows/tests-crates.yml

@@ -21,6 +21,7 @@ on:
       - packages/stack-profile/**
       - packages/stack-kms/**
       - packages/stack-kms-vendor/**
+      - packages/stack-kms-aws/**
       - packages/stack-encrypt/**
       - conformance/stack-encrypt/**
       - packages/stack-encrypt-derive/**
@@ -46,6 +47,7 @@ on:
       - packages/stack-profile/**
       - packages/stack-kms/**
       - packages/stack-kms-vendor/**
+      - packages/stack-kms-aws/**
       - packages/stack-encrypt/**
       - conformance/stack-encrypt/**
       - packages/stack-encrypt-derive/**
@@ -153,15 +155,45 @@ jobs:
       # with no `version`, or a crate that uses API its dependency's packaged
       # source does not have yet. stack-profile and stack-auth are in the list
       # because stack-kms and stack-encrypt depend on them: without them, cargo
-      # resolves the published versions, which lag the tree. stack-kms-vendor
-      # is publishable but staged in release-plz.toml (its
-      # first version is published by hand); packaging it here keeps it
+      # resolves the published versions, which lag the tree. stack-kms-vendor and stack-kms-aws
+      # are publishable but staged in release-plz.toml (their
+      # first version is published by hand); packaging them here keeps them
       # publishable meanwhile. No token.
       # `--allow-dirty` tolerates files earlier steps leave in the tree. Once a
       # version is on crates.io, cargo warns rather than fails on a dry run of
       # it.
       - name: Verify the stack-* crates package cleanly for crates.io
-        run: cargo publish --locked --dry-run --allow-dirty -p stack-profile -p stack-auth -p stack-kms -p stack-encrypt-derive -p stack-encrypt -p stack-kms-vendor
+        run: cargo publish --locked --dry-run --allow-dirty -p stack-profile -p stack-auth -p stack-kms -p stack-encrypt-derive -p stack-encrypt -p stack-kms-vendor -p stack-kms-aws
+
+  # stack-kms-aws against a real AWS KMS API: LocalStack, as a service
+  # (ADR-0014). The `rust` job runs the same test binary, where it skips
+  # itself for want of an endpoint; this job sets the endpoint, and the mise
+  # task refuses to run without one, so a skip cannot read as a pass here.
+  localstack:
+    name: stack-kms-aws against LocalStack
+    runs-on: blacksmith-16vcpu-ubuntu-2204
+    timeout-minutes: 30
+    env:
+      MISE_ENV: test
+      STACK_KMS_AWS_LOCALSTACK_ENDPOINT: http://localhost:4566
+    services:
+      localstack:
+        # Pinned by digest. 4.4 is a community release that needs no auth
+        # token.
+        image: localstack/localstack:4.4@sha256:b52c16663c70b7234f217cb993a339b46686e30a1a5d9279cb5feeb2202f837c
+        ports:
+          - 4566:4566
+        env:
+          SERVICES: kms
+        options: >-
+          --health-cmd "curl -fs http://localhost:4566/_localstack/health"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 30
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
 
       - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4
         with:
@@ -174,6 +206,8 @@ jobs:
 
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
 
+      - name: stack-kms-aws against LocalStack
+        run: mise run test:localstack:stack-kms-aws
 
       - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4
         with:

.github/workflows/udeps.yml

@@ -15,6 +15,7 @@ on:
       - packages/stack-profile/**
       - packages/stack-kms/**
       - packages/stack-kms-vendor/**
+      - packages/stack-kms-aws/**
       - packages/stack-encrypt/**
       - packages/stack-encrypt-derive/**
       - packages/stack-guest-abi/**
@@ -35,6 +36,7 @@ on:
       - packages/stack-profile/**
       - packages/stack-kms/**
       - packages/stack-kms-vendor/**
+      - packages/stack-kms-aws/**
       - packages/stack-encrypt/**
       - packages/stack-encrypt-derive/**
       - packages/stack-guest-abi/**

AGENTS.md

@@ -91,7 +91,7 @@ Every npm package except EQL lives under `languages/typescript/`: packages in `l
   `cipherstash/encrypt-query-language` repository. Old upstream issue and PR
   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".
-- `packages/stack-kms-vendor`: The key vendor seam (ADR-0013 and ADR-0014 in `packages/stack-encrypt/docs/adr/`). `stack-kms-vendor` is the vendor seam (`KeyVendorBackend`), keyset records, the derived data key mode, the static key backend and the `VendorTransport` HTTP seam (feature `http`: the native reqwest transport). Its `test-support` feature holds the test code every vendor crate shares: the contract suite (`contract`), `FakeVendor`, and the recorded-fixture harness (`replay`: fixture types, `Replay`, `Recording`); a vendor crate's `tests/common/mod.rs` holds only its own emulator, keys and constants. It is a root workspace member, publishable in the `stack-kms-vendor` version group, and staged in `release-plz.toml` (`release = false`) until its first version is published by hand. The `stack-kms-vendor` crate docs hold the capability matrix of every key backend (key lifetime, vendor calls, what the vendor sees and can refuse, credentials, rotation, known limits); change it with the code it describes. TypeScript (`@cipherstash/stack`) cannot use a key vendor backend yet.
+- `packages/stack-kms-vendor`, `packages/stack-kms-aws`: The key vendor backends (ADR-0013 and ADR-0014 in `packages/stack-encrypt/docs/adr/`). `stack-kms-vendor` is the vendor seam (`KeyVendorBackend`), keyset records, the derived data key mode, the static key backend and the `VendorTransport` HTTP seam (feature `http`: the native reqwest transport). Its `test-support` feature holds the test code every vendor crate shares: the contract suite (`contract`), `FakeVendor`, and the recorded-fixture harness (`replay`: fixture types, `Replay`, `Recording`); a vendor crate's `tests/common/mod.rs` holds only its own emulator, keys and constants. `stack-kms-aws` is the AWS KMS backend: a hand-written JSON client with SigV4 signing in-crate and the AWS credential providers; its LocalStack test runs in `tests-crates.yml`'s `localstack` job. All two are root workspace members, publishable in the `stack-kms-vendor` version group, and staged in `release-plz.toml` (`release = false`) until their first version is published by hand. The `stack-kms-vendor` crate docs hold the capability matrix of every key backend (key lifetime, vendor calls, what the vendor sees and can refuse, credentials, rotation, known limits); change it with the code it describes. TypeScript (`@cipherstash/stack`) cannot use a key vendor backend yet.
 - `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 <branch>`): 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.
 - `e2e/*`: Cross-package end-to-end tests (package managers, supply chain, Prisma example README)
@@ -716,7 +716,7 @@ term. `cts-common` and `zerokms-protocol` take caret
 requirements, because the published `stack-auth` inherits them, and an
 exact pin would stop the suite sharing one `cts-common` with it.
 
-- **Three Cargo workspaces, not one.** The root workspace (the seven stack-*
+- **Three Cargo workspaces, not one.** The root workspace (the eight stack-*
   crates and the three node binding crates), protect-ffi's and EQL's. The root
   `Cargo.toml` excludes the other two, and they pin their own vitaminc. The
   three fuzz crates, the two Go guests and the EQL v4 block ORE timing
@@ -758,7 +758,7 @@ exact pin would stop the suite sharing one `cts-common` with it.
   `MISE_ENV=test` cargo tools — and the live tests), `crap-crates.yml`,
   `mutants.yml`, `fuzz.yml`, `miri.yml` and `udeps.yml`.
   `scripts/__tests__/crates-ci.test.mjs` fails when a mise task in the root
-  `mise.toml` or the six crate `tasks.toml` files loses its last CI caller.
+  `mise.toml` or the seven crate `tasks.toml` files loses its last CI caller.
 - **Auth refresh cancellation soak:** `tests-auth-refresh.yml` runs a short,
   seeded, virtual-time soak on every PR and the long run on auth changes and
   Version Packages PRs. `release-plz.yml` also requires the long run before

Cargo.toml

@@ -10,6 +10,7 @@ members = [
   "packages/stack-profile",
   "packages/stack-kms",
   "packages/stack-kms-vendor",
+  "packages/stack-kms-aws",
   "packages/stack-encrypt",
   "packages/stack-encrypt-derive",
   "packages/stack-guest-abi",

SECURITY.md

@@ -38,9 +38,9 @@ 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.
 
-One more Rust crate, **`stack-kms-vendor`**
-(`packages/stack-kms-vendor`), is prepared for
-crates.io but not yet published. It is in scope on the same terms, and
+Two more Rust crates, **`stack-kms-vendor`** and **`stack-kms-aws`**
+(`packages/stack-kms-vendor`, `packages/stack-kms-aws`), are prepared for
+crates.io but not yet published. They are in scope on the same terms, and
 under the same licence as the stack-* crates below.
 
 The five stack-* crates are licensed under the PolyForm Internal Use License

biome.json

@@ -15,6 +15,7 @@
       "!packages/stack-encrypt/tests/fixtures/value_kinds.json",
       "!packages/stack-encrypt/tests/fixtures/stored_rows_v1.json",
       "!packages/stack-encrypt/tests/fixtures/json_tree_vectors.json",
+      "!packages/stack-kms-*/tests/fixtures",
       "!packages/eql/tests/encryption/fixtures/ste_vec_selectors.json",
       "!packages/eql/tests/encryption/fixtures/v4_terms.json",
       "!packages/eql/tests/encryption/fixtures/v4_rows.json",

mise.toml

@@ -11,6 +11,7 @@ includes = [
   "packages/stack-auth/tasks.toml",
   "packages/stack-kms/tasks.toml",
   "packages/stack-kms-vendor/tasks.toml",
+  "packages/stack-kms-aws/tasks.toml",
   "packages/stack-profile/tasks.toml",
   "packages/stack-encrypt/tasks.toml",
   "packages/stack-guest-abi/tasks.toml",
@@ -125,6 +126,9 @@ check stack-encrypt --no-default-features
 # must add nothing here either.
 check stack-kms-vendor
 check stack-kms-vendor --features http
+# The AWS KMS key vendor backend, default features on: its native transport
+# and workload identity credential sources are gated off on wasm32.
+check stack-kms-aws
 # The Go binding's credential guest (ADR-0005) compiles stack-profile for
 # WASI: the hostname and the process id are native-only there.
 check stack-profile

packages/stack-kms-aws/Cargo.toml

@@ -0,0 +1,46 @@
+[package]
+name = "stack-kms-aws"
+description = "The AWS KMS key vendor backend for Stack Encrypt: a hand-written AWS KMS client with SigV4 signing, for native Rust and the WASI guest"
+version = "0.1.0"
+edition.workspace = true
+authors.workspace = true
+repository.workspace = true
+homepage.workspace = true
+keywords.workspace = true
+categories.workspace = true
+license-file = "LICENSE"
+# Publishable, in the `stack-kms-vendor` version group with the vendor seam it
+# implements. release-plz.toml keeps `release = false` until the first version
+# is on crates.io (published by hand; see stack-kms-vendor's Cargo.toml).
+
+[features]
+default = ["http"]
+# `AwsKms::from_env`: the native transport (`HttpVendorTransport`) and the
+# default credential chain over it. Native only; on wasm32 it adds nothing.
+http = ["stack-kms-vendor/http"]
+
+[dependencies]
+stack-kms = { path = "../stack-kms", version = "0.2.0", default-features = false }
+stack-kms-vendor = { path = "../stack-kms-vendor", version = "0.1.0" }
+
+vitaminc = { workspace = true, features = ["protected"] }
+base64ct = { version = "1.7", features = ["alloc"] }
+hmac = "0.13"
+sha2 = "0.11"
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+url = { workspace = true }
+web-time = { workspace = true }
+zeroize = { workspace = true }
+
+[dev-dependencies]
+stack-kms-vendor = { path = "../stack-kms-vendor", features = ["test-support", "http"] }
+stack-encrypt = { path = "../stack-encrypt", default-features = false }
+aes-gcm = { version = "0.10.3", features = ["zeroize"] }
+tokio = { workspace = true, features = ["rt", "macros", "time"] }
+uuid = { workspace = true }
+vitaminc = { workspace = true, features = ["protected", "random"] }
+
+[package.metadata.docs.rs]
+all-features = true