docs: key vendor backend capability matrix, and refuse an unsafe rewrap (CIP-5313)

.changeset/auth-keyset-records.md

@@ -0,0 +1,7 @@
+---
+'@cipherstash/auth': minor
+---
+
+Add `keysetCreate` and `keysetRewrap` (Node only). They create and rewrap keyset records for the key vendor backends (AWS KMS, Google Cloud KMS, Azure Key Vault, HashiCorp Vault Transit and the static key backend), through the same Rust vendor clients that the Rust and Go SDKs use. Each vendor's credentials come from its environment chain. Both return a `Result`; a failure is a `KeysetFailure`. `stash keyset create` and `stash keyset rewrap` call them. ZeroKMS users do not need them. `keysetRewrap` does not re-key stored values, so a record in the wrapped key mode may move only to a new version of its own vendor key; a move to another key fails with `REWRAP_REFUSED` before any vendor call. A record in the derived key mode may move to any key.
+
+For Google Cloud KMS, set `GOOGLE_OAUTH_ACCESS_TOKEN` (for example from `gcloud auth print-access-token`) or run on Google Cloud. Service account key files are not read, so that the binary has no RSA signing code.

.changeset/stash-key-vendor-rewrap-docs.md

@@ -0,0 +1,13 @@
+---
+'stash': patch
+---
+
+`stash keyset rewrap` now refuses to move a `wrapped`-mode record to another
+vendor key, with the code `rewrap_refused`, before any vendor call. Each stored
+value keeps its data key wrapped under the vendor key that sealed it, so such a
+move would leave the stored values unable to open. A `wrapped` record may still
+move to a new version of its own key (after a rotation), and a `derived` record
+may move to any key. The command help, the note it prints, the README and the
+`stash-cli` skill state the rule. The `stash-zerokms` skill now says that key
+vendor backends exist for the Rust crates and the Go SDK, that TypeScript does
+not support them yet, and that `stash keyset` creates their keyset records.

.changeset/stash-keyset-commands.md

@@ -0,0 +1,12 @@
+---
+'stash': minor
+---
+
+Add `stash keyset create` and `stash keyset rewrap`, for keysets held by a key vendor backend (AWS KMS, Google Cloud KMS, Azure Key Vault, HashiCorp Vault Transit, or the static key backend). ZeroKMS users never need them.
+
+- `stash keyset create --backend <aws|gcp|azure|vault|static> --vendor-key <ref> --mode <wrapped|derived> [--name <name>]` makes a keyset record and prints it as `CS_KEYSET_RECORD` (or `CS_KEYSET_RECORD_<NAME>`). The record is not secret. Pass its value to `encrypt.WithKeysetRecords` (Go) or `KeysetRecord::parse` (Rust).
+- `stash keyset rewrap <record | --in file> [--vendor-key <ref>]` wraps a record's key again, after a key rotation in the vendor or to move to another vendor key. The keyset id does not change, and stored data is not re-keyed, so a `wrapped` record may move only to a new version of its own vendor key; a move to another key is refused. A `derived` record may move to any key.
+- Credentials come from each vendor's environment chain, never from a flag. A static key is named by its environment variable (`--key-env`); without one, a new key is generated and printed as `CS_STATIC_KEY`.
+- `--out <file>` writes the block with mode 0600 (`--force` to overwrite), and `--json` emits one NDJSON event.
+
+The `stash-cli` skill documents both commands.

.github/workflows/integration-azure-key-vault.yml

@@ -0,0 +1,116 @@
+name: Integration — stack-kms-azure (Azure Key Vault)
+
+# stack-kms-azure against real Azure Key Vault and, optionally, Managed HSM
+# (tests/live.rs). Microsoft publishes no Key Vault emulator, so unlike the
+# LocalStack and Vault jobs in tests-crates.yml this needs a real key and real
+# credentials. Every other stack-kms-azure test runs in tests-crates.yml,
+# against fixtures and an in-process emulator.
+#
+# OPT-IN. The job runs only when the repository variable
+# STACK_KMS_AZURE_LIVE_KEY is set, so the workflow is inert until someone sets
+# up the Azure side. To turn it on:
+#
+#   1. Create an RSA key (2048 bits or more) in a Key Vault, for this test
+#      only. Optionally, create an oct-HSM AES-256 key in a Managed HSM too
+#      (a Managed HSM is billed by the hour, so this part is optional).
+#   2. Create an app registration (service principal) with a client secret.
+#      Give it the role "Key Vault Crypto Service Encryption User" on the key
+#      and nothing else ("Managed HSM Crypto Service Encryption User" on the
+#      HSM key, if there is one).
+#   3. Set the repository variable STACK_KMS_AZURE_LIVE_KEY to the key
+#      identifier (https://<vault>.vault.azure.net/keys/<name>), and, for the
+#      HSM, STACK_KMS_AZURE_LIVE_HSM_KEY
+#      (https://<hsm>.managedhsm.azure.net/keys/<name>). Set the repository
+#      secrets STACK_KMS_AZURE_TENANT_ID, STACK_KMS_AZURE_CLIENT_ID and
+#      STACK_KMS_AZURE_CLIENT_SECRET.
+#
+# Once the variable is set, a missing or empty secret FAILS the job (the
+# pre-flight below): a credentialed job that skips for want of a secret reads
+# exactly like one that passes.
+#
+# Fork PRs have no secrets, so the job skips them; every other event runs.
+# Enforced by scripts/__tests__/workflow-dispatch-job-conditions.test.mjs.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - packages/stack-kms-azure/**
+      - packages/stack-kms-vendor/**
+      - packages/stack-kms/**
+      - Cargo.lock
+      - .github/workflows/integration-azure-key-vault.yml
+  pull_request:
+    # Repeated verbatim: GitHub Actions does not support YAML anchors/aliases.
+    paths:
+      - packages/stack-kms-azure/**
+      - packages/stack-kms-vendor/**
+      - packages/stack-kms/**
+      - Cargo.lock
+      - .github/workflows/integration-azure-key-vault.yml
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  live:
+    name: stack-kms-azure against Azure Key Vault
+    runs-on: blacksmith-16vcpu-ubuntu-2204
+    timeout-minutes: 30
+    if: >-
+      vars.STACK_KMS_AZURE_LIVE_KEY != ''
+      && (github.event_name != 'pull_request'
+      || github.event.pull_request.head.repo.full_name == github.repository)
+    env:
+      MISE_ENV: test
+      STACK_KMS_AZURE_LIVE_KEY: ${{ vars.STACK_KMS_AZURE_LIVE_KEY }}
+      STACK_KMS_AZURE_LIVE_HSM_KEY: ${{ vars.STACK_KMS_AZURE_LIVE_HSM_KEY }}
+    steps:
+      # Fast pre-flight: fail in seconds if a secret was rotated or cleared,
+      # before the toolchain install and the compile.
+      - name: Require the Azure service principal
+        env:
+          TENANT_ID: ${{ secrets.STACK_KMS_AZURE_TENANT_ID }}
+          CLIENT_ID: ${{ secrets.STACK_KMS_AZURE_CLIENT_ID }}
+          CLIENT_SECRET: ${{ secrets.STACK_KMS_AZURE_CLIENT_SECRET }}
+        run: |
+          missing=0
+          for name in TENANT_ID CLIENT_ID CLIENT_SECRET; do
+            if [ -z "${!name}" ]; then
+              echo "::error::STACK_KMS_AZURE_LIVE_KEY is set but the secret STACK_KMS_AZURE_${name} is empty"
+              missing=1
+            fi
+          done
+          exit "$missing"
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+
+      - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4
+        with:
+          version: 2026.4.0
+          install: true
+          working_directory: .
+          cache: true
+          # Must name runs-on's image; see scripts/__tests__/workflow-mise-cache-image.test.mjs
+          cache_key_prefix: mise-v1-ubuntu-2204
+
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+
+      # The secrets reach only this step's environment.
+      - name: stack-kms-azure against Azure Key Vault
+        env:
+          AZURE_TENANT_ID: ${{ secrets.STACK_KMS_AZURE_TENANT_ID }}
+          AZURE_CLIENT_ID: ${{ secrets.STACK_KMS_AZURE_CLIENT_ID }}
+          AZURE_CLIENT_SECRET: ${{ secrets.STACK_KMS_AZURE_CLIENT_SECRET }}
+        run: mise run test:live:stack-kms-azure

.github/workflows/integration-drizzle.yml

@@ -67,6 +67,17 @@ on:
       # require-auth-npm-changeset.yml.
       - 'packages/stack-auth/Cargo.toml'
       - 'packages/stack-auth/src/**'
+      # The key vendor crates the auth binding compiles in (stash keyset).
+      - 'packages/stack-kms-vendor/Cargo.toml'
+      - 'packages/stack-kms-vendor/src/**'
+      - 'packages/stack-kms-aws/Cargo.toml'
+      - 'packages/stack-kms-aws/src/**'
+      - 'packages/stack-kms-vault/Cargo.toml'
+      - 'packages/stack-kms-vault/src/**'
+      - 'packages/stack-kms-gcp/Cargo.toml'
+      - 'packages/stack-kms-gcp/src/**'
+      - 'packages/stack-kms-azure/Cargo.toml'
+      - 'packages/stack-kms-azure/src/**'
       - 'languages/typescript/packages/auth/**'
       - 'languages/typescript/packages/stack-auth-wasm/**'
       # The Rust that produces every EQL payload these suites round-trip.
@@ -175,6 +186,17 @@ on:
       # require-auth-npm-changeset.yml.
       - 'packages/stack-auth/Cargo.toml'
       - 'packages/stack-auth/src/**'
+      # The key vendor crates the auth binding compiles in (stash keyset).
+      - 'packages/stack-kms-vendor/Cargo.toml'
+      - 'packages/stack-kms-vendor/src/**'
+      - 'packages/stack-kms-aws/Cargo.toml'
+      - 'packages/stack-kms-aws/src/**'
+      - 'packages/stack-kms-vault/Cargo.toml'
+      - 'packages/stack-kms-vault/src/**'
+      - 'packages/stack-kms-gcp/Cargo.toml'
+      - 'packages/stack-kms-gcp/src/**'
+      - 'packages/stack-kms-azure/Cargo.toml'
+      - 'packages/stack-kms-azure/src/**'
       - 'languages/typescript/packages/auth/**'
       - 'languages/typescript/packages/stack-auth-wasm/**'
       # The Rust that produces every EQL payload these suites round-trip.

.github/workflows/integration-gcp-kms.yml

@@ -0,0 +1,111 @@
+name: Integration — stack-kms-gcp (Google Cloud KMS)
+
+# stack-kms-gcp against real Google Cloud KMS (tests/live.rs). Google
+# publishes no Cloud KMS emulator, so unlike the LocalStack and Vault jobs in
+# tests-crates.yml this needs a real crypto key and real credentials. Every
+# other stack-kms-gcp test runs in tests-crates.yml, against fixtures and an
+# in-process emulator.
+#
+# OPT-IN. The job runs only when the repository variable
+# STACK_KMS_GCP_LIVE_KEY is set, so the workflow is inert until someone sets
+# up the Google Cloud side. To turn it on:
+#
+#   1. Create a symmetric ENCRYPT_DECRYPT crypto key for this test only.
+#   2. Create a service account with roles/cloudkms.cryptoKeyEncrypterDecrypter
+#      on that key and nothing else, and make a JSON key for it.
+#   3. Set the repository variable STACK_KMS_GCP_LIVE_KEY to the crypto key
+#      name (projects/<p>/locations/<l>/keyRings/<r>/cryptoKeys/<k>), and the
+#      repository secret STACK_KMS_GCP_SERVICE_ACCOUNT_KEY to the JSON key.
+#
+# Once the variable is set, a missing or empty secret FAILS the job (the
+# pre-flight below): a credentialed job that skips for want of a secret reads
+# exactly like one that passes.
+#
+# Fork PRs have no secrets, so the job skips them; every other event runs.
+# Enforced by scripts/__tests__/workflow-dispatch-job-conditions.test.mjs.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - packages/stack-kms-gcp/**
+      - packages/stack-kms-vendor/**
+      - packages/stack-kms/**
+      - Cargo.lock
+      - .github/workflows/integration-gcp-kms.yml
+  pull_request:
+    # Repeated verbatim: GitHub Actions does not support YAML anchors/aliases.
+    paths:
+      - packages/stack-kms-gcp/**
+      - packages/stack-kms-vendor/**
+      - packages/stack-kms/**
+      - Cargo.lock
+      - .github/workflows/integration-gcp-kms.yml
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  live:
+    name: stack-kms-gcp against Cloud KMS
+    runs-on: blacksmith-16vcpu-ubuntu-2204
+    timeout-minutes: 30
+    if: >-
+      vars.STACK_KMS_GCP_LIVE_KEY != ''
+      && (github.event_name != 'pull_request'
+      || github.event.pull_request.head.repo.full_name == github.repository)
+    env:
+      MISE_ENV: test
+      STACK_KMS_GCP_LIVE_KEY: ${{ vars.STACK_KMS_GCP_LIVE_KEY }}
+    steps:
+      # Fast pre-flight: fail in seconds if the secret was rotated or
+      # cleared, before the toolchain install and the compile.
+      - name: Require the Cloud KMS service account key
+        env:
+          SERVICE_ACCOUNT_KEY: ${{ secrets.STACK_KMS_GCP_SERVICE_ACCOUNT_KEY }}
+        run: |
+          if [ -z "$SERVICE_ACCOUNT_KEY" ]; then
+            echo "::error::STACK_KMS_GCP_LIVE_KEY is set but the secret STACK_KMS_GCP_SERVICE_ACCOUNT_KEY is empty"
+            exit 1
+          fi
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+
+      - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4
+        with:
+          version: 2026.4.0
+          install: true
+          working_directory: .
+          cache: true
+          # Must name runs-on's image; see scripts/__tests__/workflow-mise-cache-image.test.mjs
+          cache_key_prefix: mise-v1-ubuntu-2204
+
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+
+      # The key goes to a file only this user can read, outside the
+      # checkout, and is removed after the test.
+      - name: Write the service account key
+        env:
+          SERVICE_ACCOUNT_KEY: ${{ secrets.STACK_KMS_GCP_SERVICE_ACCOUNT_KEY }}
+        run: |
+          umask 077
+          printf '%s' "$SERVICE_ACCOUNT_KEY" > "$RUNNER_TEMP/stack-kms-gcp-live.json"
+          echo "GOOGLE_APPLICATION_CREDENTIALS=$RUNNER_TEMP/stack-kms-gcp-live.json" >> "$GITHUB_ENV"
+
+      - name: stack-kms-gcp against Cloud KMS
+        run: mise run test:live:stack-kms-gcp
+
+      - name: Remove the service account key
+        if: always()
+        run: rm -f "$RUNNER_TEMP/stack-kms-gcp-live.json"

.github/workflows/integration-protect-ffi.yml

@@ -106,6 +106,17 @@ on:
       # require-auth-npm-changeset.yml.
       - 'packages/stack-auth/Cargo.toml'
       - 'packages/stack-auth/src/**'
+      # The key vendor crates the auth binding compiles in (stash keyset).
+      - 'packages/stack-kms-vendor/Cargo.toml'
+      - 'packages/stack-kms-vendor/src/**'
+      - 'packages/stack-kms-aws/Cargo.toml'
+      - 'packages/stack-kms-aws/src/**'
+      - 'packages/stack-kms-vault/Cargo.toml'
+      - 'packages/stack-kms-vault/src/**'
+      - 'packages/stack-kms-gcp/Cargo.toml'
+      - 'packages/stack-kms-gcp/src/**'
+      - 'packages/stack-kms-azure/Cargo.toml'
+      - 'packages/stack-kms-azure/src/**'
       - 'languages/typescript/packages/auth/**'
       - 'languages/typescript/packages/stack-auth-wasm/**'
       - '.github/actions/require-cs-secrets/**'
@@ -155,6 +166,17 @@ on:
       # require-auth-npm-changeset.yml.
       - 'packages/stack-auth/Cargo.toml'
       - 'packages/stack-auth/src/**'
+      # The key vendor crates the auth binding compiles in (stash keyset).
+      - 'packages/stack-kms-vendor/Cargo.toml'
+      - 'packages/stack-kms-vendor/src/**'
+      - 'packages/stack-kms-aws/Cargo.toml'
+      - 'packages/stack-kms-aws/src/**'
+      - 'packages/stack-kms-vault/Cargo.toml'
+      - 'packages/stack-kms-vault/src/**'
+      - 'packages/stack-kms-gcp/Cargo.toml'
+      - 'packages/stack-kms-gcp/src/**'
+      - 'packages/stack-kms-azure/Cargo.toml'
+      - 'packages/stack-kms-azure/src/**'
       - 'languages/typescript/packages/auth/**'
       - 'languages/typescript/packages/stack-auth-wasm/**'
       - '.github/actions/require-cs-secrets/**'

.github/workflows/integration-supabase.yml

@@ -60,6 +60,17 @@ on:
       # require-auth-npm-changeset.yml.
       - 'packages/stack-auth/Cargo.toml'
       - 'packages/stack-auth/src/**'
+      # The key vendor crates the auth binding compiles in (stash keyset).
+      - 'packages/stack-kms-vendor/Cargo.toml'
+      - 'packages/stack-kms-vendor/src/**'
+      - 'packages/stack-kms-aws/Cargo.toml'
+      - 'packages/stack-kms-aws/src/**'
+      - 'packages/stack-kms-vault/Cargo.toml'
+      - 'packages/stack-kms-vault/src/**'
+      - 'packages/stack-kms-gcp/Cargo.toml'
+      - 'packages/stack-kms-gcp/src/**'
+      - 'packages/stack-kms-azure/Cargo.toml'
+      - 'packages/stack-kms-azure/src/**'
       - 'languages/typescript/packages/auth/**'
       - 'languages/typescript/packages/stack-auth-wasm/**'
       # The Rust that produces every EQL payload these suites round-trip.
@@ -154,6 +165,17 @@ on:
       # require-auth-npm-changeset.yml.
       - 'packages/stack-auth/Cargo.toml'
       - 'packages/stack-auth/src/**'
+      # The key vendor crates the auth binding compiles in (stash keyset).
+      - 'packages/stack-kms-vendor/Cargo.toml'
+      - 'packages/stack-kms-vendor/src/**'
+      - 'packages/stack-kms-aws/Cargo.toml'
+      - 'packages/stack-kms-aws/src/**'
+      - 'packages/stack-kms-vault/Cargo.toml'
+      - 'packages/stack-kms-vault/src/**'
+      - 'packages/stack-kms-gcp/Cargo.toml'
+      - 'packages/stack-kms-gcp/src/**'
+      - 'packages/stack-kms-azure/Cargo.toml'
+      - 'packages/stack-kms-azure/src/**'
       - 'languages/typescript/packages/auth/**'
       - 'languages/typescript/packages/stack-auth-wasm/**'
       # The Rust that produces every EQL payload these suites round-trip.