feat(store): encrypt playbook binding secrets at rest

binding.Binding.Secret was persisted as plaintext in the bindings.secret
column, so anyone with the SQLite file saw sender-side HMAC secrets. Seal
it with AES-256-GCM transparently inside the store: encrypt-on-write,
decrypt-on-read.

- cipher: AES-256-GCM, 12-byte random nonce, SHA-256-normalised 32-byte
  key resolved through the secret registry ([bindings].encryption_key).
- envelope 'arcie-binding:v1:<fingerprint>:<b64(nonce||ct||tag)>' so a
  future cipher/KDF change is a version bump and old rows stay readable.
- rotation via previous_encryption_keys; key identity is the material's
  SHA-256 fingerprint embedded in each row.
- legacy plaintext rows written before a key was configured stay readable;
  encryption is not retroactive.
- nil cipher (no key configured) preserves the pre-t2db.7 plaintext path.

Deferred: captured_events.body redaction upgrade (separate concern, see
docs/prds/binding-secret-encryption.md).

Refs archie-core-t2db.7
This commit is contained in:
sam committed 2026-09-02 23:54:06 +10:00
1 parent e7871450be
commit 087f161836
11 files changed
+683 -9

No files matched your search

+14
View File
@@ -274,6 +274,20 @@ gate_max_failures = 5
# rate_per_second = 1.0 # per-remote-address token bucket
# rate_burst = 5
# Playbook-binding at-rest encryption: [bindings].encryption_key resolves a
# 32-byte high-entropy key through the secret registry (engine + key) and seals
# each binding's HMAC secret in the SQLite bindings.secret column with AES-256-
# GCM (see docs/prds/binding-secret-encryption.md). When the key is absent,
# binding secrets are stored as plaintext (the pre-t2db.7 behaviour) -- enabling
# encryption does not retroactively encrypt existing rows, which stay plaintext
# until they are edited. Rotation: after changing encryption_key, retain the
# previous material in previous_encryption_keys so rows sealed under the old
# key still decrypt, then drop it once no row references it. A reload that
# changes these keys requires a daemon restart.
# [bindings]
# encryption_key = { engine = "env", key = "ARCHIE_BINDING_KEY" }
# previous_encryption_keys = [ { engine = "env", key = "ARCHIE_BINDING_KEY_OLD" } ]
# Docker sandbox execution of archie-agent is mandatory for autonomous
# workflows. Omit this section to use the default image, lifetimes, and pull
# policy; the options below show the available overrides. If Docker or
+106
View File
@@ -0,0 +1,106 @@
# Binding secret at-rest encryption -- decision
**Status:** Decided, to be implemented
**Date:** 2026-09-02
**Beads issue:** `archie-core-t2db.7` (P2), parent `archie-core-t2db`
## Problem
`binding.Binding.Secret` (the per-source HMAC shared secret) is persisted as
plaintext in the `bindings.secret TEXT` column. Anyone with read access to the
SQLite file -- the same access level as `captured_events.body` and `tasks.body`
-- sees sender-side shared secrets. A leaked database file leaks secrets even
when the filesystem ACLs were correct at rest.
## Decision
Encrypt the `secret` column at rest with **AES-256-GCM** (stdlib
`crypto/aes` + `crypto/cipher`, no new dependency), transparently inside the
store: encrypt on write, decrypt on read. The store is the data boundary; its
consumers (dispatch loop, HMAC verification) receive the plaintext secret
exactly as today, and the webui already blanks `Secret` on every response.
### Cipher parameters
- **AEAD:** AES-256-GCM, 12-byte random nonce (`crypto/rand`), tag appended.
- **Key length:** 32 bytes, derived as `SHA-256(resolved_material)`. Kept as
SHA-256 (no Argon2id) because the source is a **32-byte high-entropy** value
resolved through the secret registry, so re-deriving to 32 bytes merely
re-shapes entropy rather than defending a weak passphrase.
- **AAD:** a static domain separator, `[]byte("arcie-binding-secret")`, so a
ciphertext cannot be relocated to a different field/column and still
authenticate. AAD is intentionally **not** row-bound: binding secrets are
random HMAC keys and are never used as lookup keys, so cross-row swap is not
a meaningful attack here.
### Envelope format
```
arcie-binding:v1:<keyFingerprint>:<base64url(nonce || ciphertext || tag)>
```
- `arcie-binding` -- domain marker
- `v1` -- format version (future cipher/KDF change is a new version, old rows
stay readable)
- `<keyFingerprint>` -- `hex(SHA-256(material))[:16]`, the identity of the key
that sealed the row, enabling rotation without a one-shot rewrite
- payload -- `base64url` of `nonce ‖ GCM.Seal(plaintext, aad)`
### Key source (confirmed with maintainer)
Resolved through the existing secret registry (`internal/secret`), the
established `SecretRef` pattern already used for `forge.webhook_secret`:
```toml
[bindings]
encryption_key = { engine = "env", key = "ARCHIE_BINDING_KEY" }
# Rotation: after swapping encryption_key to a new value, retain the previous
# material so rows sealed under the old key still decrypt.
previous_encryption_keys = [ { engine = "env", key = "ARCHIE_BINDING_KEY_OLD" } ]
```
The active key encrypts new writes; `previous_encryption_keys` are retained for
decrypt-only. Key identity is intrinsic to the material (the fingerprint), so
no manual key IDs are configured.
### Rotation story
Rotate by changing `encryption_key`, moving the old material into
`previous_encryption_keys`. Rows sealed under the old key still decrypt via
their embedded fingerprint; new writes use the new active key. Once no
remaining row references an old fingerprint, remove it from the config. Losing
a fingerprint's material before all its rows are rewritten makes those rows
unreadable -- the same operational rule as any key rotation, and the reason the
old material must be retained.
## Non-goals / deferred
- **`captured_events.body` redaction upgrade** is deferred (confirmed with
maintainer). The body redaction is a separate best-effort key-name heuristic
with its own documented limits and its own capture-path surface; it is not
bundled into this store-scoped change.
- **Key re-derivation on config reload** is a startup concern: the store holds
the cipher for its lifetime, so a reload that changes `[bindings]` keys
requires a daemon restart to take effect. Documented, accepted.
## Wiring
- `internal/config`: add `BindingsConfig` (`encryption_key SecretRef`,
`previous_encryption_keys []SecretRef`) on `Config.Bindings`.
- `internal/app/archied/bootstrap.go` `openStores`: resolve both refs through
the already-built `secrets` registry, pass the material to `store.Open` via a
new option `store.WithBindingCipher(cipher)`.
- `internal/store`: add a `BindingCipher` interface (concrete AES-GCM impl in
`binding_cipher.go`), a `bindingCipher` field on `Store`, and the `Open`
option. **Nil cipher = plaintext**, so existing call sites and tests change
nothing and legacy deployments keep current behaviour until they set a key.
## Back-compat & tests
- `store.Open` gains the option variadically; all current call sites compile
unchanged.
- Existing plaintext rows are unaffected until a cipher is configured; rows
written before a cipher is installed remain plaintext and read as plaintext.
- Tests: cipher round-trip (Encrypt/Decrypt), wrong-key and tampered-ciphertext
integrity failure, envelope parse errors, and a store round-trip that asserts
the persisted column is NOT the plaintext while `GetBinding` returns it.
+40
View File
@@ -0,0 +1,40 @@
package archied
import (
"fmt"
"strings"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/secret"
"github.com/samcharles93/archie-core/internal/store"
)
// bindingCipherFromConfig resolves the binding at-rest encryption key from
// config through the secret registry and returns a store cipher. An unset
// encryption_key returns a nil cipher, keeping the legacy plaintext path (the
// store's default). See docs/prds/binding-secret-encryption.md.
func bindingCipherFromConfig(cfg config.Config, secrets *secret.Registry) (store.BindingCipher, error) {
if cfg.Bindings.EncryptionKey == (secret.SecretRef{}) {
return nil, nil
}
active, err := cfg.Bindings.EncryptionKey.Resolve(secrets)
if err != nil {
return nil, fmt.Errorf("resolve bindings encryption_key: %w", err)
}
active = strings.TrimSpace(active)
if active == "" {
return nil, fmt.Errorf("bindings encryption_key resolved empty")
}
previous := make([]string, 0, len(cfg.Bindings.PreviousEncryptionKeys))
for _, ref := range cfg.Bindings.PreviousEncryptionKeys {
v, err := ref.Resolve(secrets)
if err != nil {
return nil, fmt.Errorf("resolve bindings previous_encryption_key: %w", err)
}
if v = strings.TrimSpace(v); v != "" {
previous = append(previous, v)
}
}
return store.NewBindingCipher(active, previous)
}
+7 -1
View File
@@ -243,7 +243,13 @@ func (b *boot) openStores(ctx context.Context) error {
b.secrets = secrets
b.forgeClient, b.token = resolveForge(cfg.Forge, secrets, log)
st, err := openProductionTaskStore(ctx, taskDBPath(cfg.DBPath))
bindingCipher, err := bindingCipherFromConfig(cfg, secrets)
if err != nil {
log.Error("configure bindings cipher", "err", err)
return err
}
st, err := openProductionTaskStore(ctx, taskDBPath(cfg.DBPath), store.WithBindingCipher(bindingCipher))
if err != nil {
log.Error("open store", "err", err)
return err
+2 -2
View File
@@ -277,8 +277,8 @@ func resolveForge(cfg config.Forge, secrets *secret.Registry, log *slog.Logger)
return client, token
}
func openProductionTaskStore(ctx context.Context, path string) (store.TaskStore, error) {
return store.Open(ctx, path)
func openProductionTaskStore(ctx context.Context, path string, opts ...store.OpenOption) (store.TaskStore, error) {
return store.Open(ctx, path, opts...)
}
func taskDBPath(configuredPath string) string {
+10 -1
View File
@@ -1,6 +1,10 @@
package config
import "testing"
import (
"testing"
"github.com/samcharles93/archie-core/internal/secret"
)
// TestConfigCloneDeepCopiesReferenceFields pins that Clone returns a
// value sharing no memory with the original: mutating the clone's maps
@@ -25,6 +29,7 @@ func TestConfigCloneDeepCopiesReferenceFields(t *testing.T) {
Chat: ChatConfig{Telegram: TelegramConfig{AllowedUserIDs: []int64{1}}},
LegacyAgent: LegacyAgent{Env: []string{"HOME"}},
Extra: map[string]any{"custom": 1},
Bindings: BindingsConfig{PreviousEncryptionKeys: []secret.SecretRef{{Engine: "env", Key: "K0"}}},
}
got := orig.Clone()
@@ -41,6 +46,7 @@ func TestConfigCloneDeepCopiesReferenceFields(t *testing.T) {
got.Chat.Telegram.AllowedUserIDs[0] = 99
got.LegacyAgent.Env[0] = "changed"
got.Extra["custom"] = 2
got.Bindings.PreviousEncryptionKeys[0] = secret.SecretRef{Engine: "env", Key: "changed"}
*got.Tools.WebFetch.Enabled = false
if orig.Models["builder"] != "m" {
@@ -73,6 +79,9 @@ func TestConfigCloneDeepCopiesReferenceFields(t *testing.T) {
if orig.Extra["custom"] != 1 {
t.Error("Extra map is shared")
}
if orig.Bindings.PreviousEncryptionKeys[0].Key != "K0" {
t.Error("Bindings.PreviousEncryptionKeys is shared")
}
if !*orig.Tools.WebFetch.Enabled {
t.Error("WebFetch.Enabled pointer is shared")
}
+18
View File
@@ -473,6 +473,7 @@ type Config struct {
Containers ContainerConfig `toml:"containers" yaml:"containers"`
Chat ChatConfig `toml:"chat" yaml:"chat"`
Capture CaptureConfig `toml:"capture" yaml:"capture"`
Bindings BindingsConfig `toml:"bindings" yaml:"bindings"`
// Memory holds memory provider configuration (from config.memory.yaml).
Memory MemoryConfig `toml:"memory" yaml:"memory"`
@@ -617,6 +618,7 @@ func (c Config) Clone() Config {
c.Chat.Telegram.AllowedUserIDs = append([]int64(nil), c.Chat.Telegram.AllowedUserIDs...)
c.Chat.Telegram.UpdateCheckCommand = append([]string(nil), c.Chat.Telegram.UpdateCheckCommand...)
c.Chat.Telegram.UpdateInstallCommand = append([]string(nil), c.Chat.Telegram.UpdateInstallCommand...)
c.Bindings.PreviousEncryptionKeys = append([]secret.SecretRef(nil), c.Bindings.PreviousEncryptionKeys...)
c.Tools.MCPServers = cloneMCPServers(c.Tools.MCPServers)
c.Memory.ProviderConfig = maps.Clone(c.Memory.ProviderConfig)
if c.Tools.WebFetch.Enabled != nil {
@@ -734,6 +736,22 @@ type CaptureConfig struct {
RateBurst int `toml:"rate_burst" yaml:"rate_burst"`
}
// BindingsConfig configures the playbook-binding store (t2db). When
// EncryptionKey is unset, binding secrets are persisted as plaintext
// (legacy behaviour); when set, they are AES-256-GCM encrypted at rest
// (see docs/prds/binding-secret-encryption.md).
type BindingsConfig struct {
// EncryptionKey is the active key that seals new binding secrets.
// Resolved through the secret registry (engine + key) at startup; the
// resolved material must be 32 bytes of high-entropy randomness.
// A nil/empty ref disables encryption and keeps current behaviour.
EncryptionKey secret.SecretRef `toml:"encryption_key" yaml:"encryption_key"`
// PreviousEncryptionKeys retains older key material so rows sealed
// under a previous rotation still decrypt. Each is resolved the same
// way as EncryptionKey; entries are decrypt-only.
PreviousEncryptionKeys []secret.SecretRef `toml:"previous_encryption_keys" yaml:"previous_encryption_keys"`
}
// ContainerConfig configures Docker sandbox execution of archie-agent.
type ContainerConfig struct {
// LegacyEnabled decodes the removed containers.enabled switch so existing
+154
View File
@@ -0,0 +1,154 @@
package store
import (
"crypto/aes"
"crypto/cipher"
"crypto/rand"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"errors"
"fmt"
"strings"
)
// bindingSecretAAD is the additional-authenticated-data domain separator. It
// binds a ciphertext to the binding-secret payload context so it cannot be
// relocated to a different field/column and still authenticate. It is
// deliberately NOT row-bound: binding secrets are random HMAC keys and are
// never used as lookup keys, so cross-row relocation is not a meaningful
// attack here (see docs/prds/binding-secret-encryption.md).
var bindingSecretAAD = []byte("arcie-binding-secret")
// bindingEnvelopeMarker and bindingEnvelopeVersion identify a sealed binding
// secret and the format version. A future cipher or KDF change bumps the
// version so old rows stay readable while new writes use the new format.
const (
bindingEnvelopeMarker = "arcie-binding"
bindingEnvelopeVersion = "v1"
// bindingNonceLen is GCM's recommended 12-byte nonce.
bindingNonceLen = 12
)
// bindingKeyFingerprintLen is the number of hex characters of the
// SHA-256(material) fingerprint embedded in the envelope (8 bytes, far more
// than enough to distinguish a handful of rotation keys).
const bindingKeyFingerprintLen = 16
// BindingCipher encrypts and decrypts binding secrets at rest. The store
// calls it transparently on write and read; a nil cipher leaves secrets as
// plaintext (legacy behaviour). Implementations must be safe for concurrent
// use.
type BindingCipher interface {
// Encrypt returns the sealed envelope for a plaintext secret.
Encrypt(plaintext string) (string, error)
// Decrypt returns the plaintext secret for a sealed envelope.
Decrypt(envelope string) (string, error)
}
// bindingCipher is the AES-256-GCM BindingCipher. Keys are derived as
// SHA-256(resolved material) -- 32 bytes of high-entropy input re-shaped to a
// 256-bit key, so no passphrase-stretching KDF (Argon2id) is required. The
// active key seals new writes; previous keys are retained for decryption only
// during rotation.
type bindingCipher struct {
activeKey []byte
activeFingerprint string
keys map[string][]byte // fingerprint(hex[:16]) → 32-byte AES key
}
// NewBindingCipher builds a bindingCipher over the active key material and any
// previous (decrypt-only) material. Key identity is intrinsic to the material
// (the SHA-256 fingerprint), so rotation needs no manual key IDs. It is a pure
// constructor: it never reads the secret registry, which the composition root
// owns.
func NewBindingCipher(active string, previous []string) (*bindingCipher, error) {
if active == "" {
return nil, errors.New("store: binding cipher requires a non-empty active key")
}
fp := bindingKeyFingerprint(active)
c := &bindingCipher{
activeKey: deriveBindingKey(active),
activeFingerprint: fp,
keys: make(map[string][]byte, 1+len(previous)),
}
c.keys[fp] = c.activeKey
for _, material := range previous {
if material == "" {
continue
}
c.keys[bindingKeyFingerprint(material)] = deriveBindingKey(material)
}
return c, nil
}
// Encrypt seals plaintext with the active key and returns the versioned
// envelope: "arcie-binding:v1:<fingerprint>:<base64url(nonce‖ct‖tag)>".
func (c *bindingCipher) Encrypt(plaintext string) (string, error) {
block, err := aes.NewCipher(c.activeKey)
if err != nil {
return "", fmt.Errorf("store: binding cipher: %w", err)
}
gcm, err := cipher.NewGCM(block)
if err != nil {
return "", fmt.Errorf("store: binding cipher: %w", err)
}
nonce := make([]byte, bindingNonceLen)
if _, err := rand.Read(nonce); err != nil {
return "", fmt.Errorf("store: binding cipher: nonce: %w", err)
}
sealed := gcm.Seal(nil, nonce, []byte(plaintext), bindingSecretAAD)
payload := base64.RawURLEncoding.EncodeToString(append(nonce, sealed...))
return fmt.Sprintf("%s:%s:%s:%s", bindingEnvelopeMarker, bindingEnvelopeVersion,
c.activeFingerprint, payload), nil
}
// Decrypt parses the envelope, looks up the key by its embedded fingerprint,
// and returns the plaintext. A fingerprint not present in the keyring (an old
// key dropped from config) fails rather than returning garbage.
func (c *bindingCipher) Decrypt(envelope string) (string, error) {
parts := strings.SplitN(envelope, ":", 4)
if len(parts) != 4 || parts[0] != bindingEnvelopeMarker || parts[1] != bindingEnvelopeVersion {
return "", errors.New("store: binding cipher: unrecognised envelope")
}
key, ok := c.keys[parts[2]]
if !ok {
return "", errors.New("store: binding cipher: key not in keyring (rotated out?)")
}
raw, err := base64.RawURLEncoding.DecodeString(parts[3])
if err != nil {
return "", fmt.Errorf("store: binding cipher: decode payload: %w", err)
}
if len(raw) < bindingNonceLen {
return "", errors.New("store: binding cipher: payload too short")
}
nonce, sealed := raw[:bindingNonceLen], raw[bindingNonceLen:]
block, err := aes.NewCipher(key)
if err != nil {
return "", fmt.Errorf("store: binding cipher: %w", err)
}
gcm, err := cipher.NewGCM(block)
if err != nil {
return "", fmt.Errorf("store: binding cipher: %w", err)
}
plaintext, err := gcm.Open(nil, nonce, sealed, bindingSecretAAD)
if err != nil {
return "", fmt.Errorf("store: binding cipher: authenticate: %w", err)
}
return string(plaintext), nil
}
// deriveBindingKey reduces 32-byte high-entropy material to a 256-bit AES key.
// SHA-256 is sufficient because the input is already high-entropy; it is not a
// passphrase-stretcher.
func deriveBindingKey(material string) []byte {
sum := sha256.Sum256([]byte(material))
return sum[:]
}
// bindingKeyFingerprint returns a short stable identifier for key material,
// embedded in the envelope so a rotated row can find the key that sealed it.
func bindingKeyFingerprint(material string) string {
sum := sha256.Sum256([]byte(material))
return hex.EncodeToString(sum[:])[:bindingKeyFingerprintLen]
}
+258
View File
@@ -0,0 +1,258 @@
package store
import (
"encoding/base64"
"path/filepath"
"strings"
"testing"
)
// testBindingKey is high-entropy 32-byte-style material for cipher tests. It
// must be split across the fingerprint and key derivation consistently.
const testBindingKey = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
func TestBindingCipherRoundTrip(t *testing.T) {
c, err := NewBindingCipher(testBindingKey, nil)
if err != nil {
t.Fatalf("NewBindingCipher: %v", err)
}
plain := "sentry-hmac-secret-0123456789abcdef"
env, err := c.Encrypt(plain)
if err != nil {
t.Fatalf("Encrypt: %v", err)
}
if env == plain {
t.Fatal("Encrypt returned the plaintext")
}
if !strings.HasPrefix(env, "arcie-binding:v1:") {
t.Fatalf("envelope prefix = %q, want arcie-binding:v1:", env)
}
got, err := c.Decrypt(env)
if err != nil {
t.Fatalf("Decrypt: %v", err)
}
if got != plain {
t.Fatalf("round-trip = %q, want %q", got, plain)
}
}
func TestBindingCipherWrongKeyFails(t *testing.T) {
c, _ := NewBindingCipher(testBindingKey, nil)
env, err := c.Encrypt("secret-0123456789abcdef")
if err != nil {
t.Fatalf("Encrypt: %v", err)
}
c2, _ := NewBindingCipher("a-completely-different-key-0000000000000000", nil)
if _, err := c2.Decrypt(env); err == nil {
t.Fatal("Decrypt with the wrong key succeeded, want error")
}
}
func TestBindingCipherTamperedCiphertextFails(t *testing.T) {
c, _ := NewBindingCipher(testBindingKey, nil)
env, err := c.Encrypt("secret-0123456789abcdef")
if err != nil {
t.Fatalf("Encrypt: %v", err)
}
tampered := tamperEnvelope(t, env)
if _, err := c.Decrypt(tampered); err == nil {
t.Fatal("Decrypt of tampered envelope succeeded, want authentication error")
}
}
func TestBindingCipherUnrecognisedEnvelopeFails(t *testing.T) {
c, _ := NewBindingCipher(testBindingKey, nil)
for _, bad := range []string{"", "not-an-envelope", "arcie-binding:v2:deadbeef:AAAA"} {
if _, err := c.Decrypt(bad); err == nil {
t.Errorf("Decrypt(%q) succeeded, want error", bad)
}
}
}
func TestBindingCipherKeyNotInKeyringFails(t *testing.T) {
c, _ := NewBindingCipher("key-0-material-0000000000000000", nil)
env, err := c.Encrypt("secret-0123456789abcdef")
if err != nil {
t.Fatalf("Encrypt: %v", err)
}
// A keyring without the sealing key cannot decrypt the row.
c2, _ := NewBindingCipher(testBindingKey, nil)
if _, err := c2.Decrypt(env); err == nil {
t.Fatal("Decrypt via a keyring missing the sealing key succeeded, want error")
}
}
func TestBindingCipherRotationKeepsOldRowsReadable(t *testing.T) {
oldKey := "old-key-material-000000000000000000000000"
cOld, _ := NewBindingCipher(oldKey, nil)
env, err := cOld.Encrypt("secret-0123456789abcdef")
if err != nil {
t.Fatalf("Encrypt (old): %v", err)
}
// Rotate: active becomes a new key, old is retained for reads.
cNew, err := NewBindingCipher(testBindingKey, []string{oldKey})
if err != nil {
t.Fatalf("NewBindingCipher (rotated): %v", err)
}
got, err := cNew.Decrypt(env)
if err != nil {
t.Fatalf("Decrypt old row under rotated keyring: %v", err)
}
if got != "secret-0123456789abcdef" {
t.Fatalf("rotated decrypt = %q", got)
}
// Once the old key is dropped, the old row is unreadable.
cDropped, _ := NewBindingCipher(testBindingKey, nil)
if _, err := cDropped.Decrypt(env); err == nil {
t.Fatal("Decrypt with rotated-out keyring succeeded, want error")
}
}
func TestBindingCipherDerivesDistinctKeys(t *testing.T) {
a, _ := NewBindingCipher("material-A", nil)
b, _ := NewBindingCipher("material-B", nil)
if a.activeFingerprint == b.activeFingerprint {
t.Fatal("distinct materials produced the same fingerprint")
}
if string(a.activeKey) == string(b.activeKey) {
t.Fatal("distinct materials produced the same derived key")
}
}
func TestStoreBindingSecretEncryptedAtRest(t *testing.T) {
s := openTestWithBindingCipher(t)
b := testBinding("sentry")
id, err := s.InsertBinding(t.Context(), b)
if err != nil {
t.Fatalf("InsertBinding: %v", err)
}
// The raw column must not be the plaintext secret.
var stored string
if err := s.db.QueryRowContext(t.Context(), `SELECT secret FROM bindings WHERE id=?`, id).Scan(&stored); err != nil {
t.Fatalf("read raw secret: %v", err)
}
if stored == b.Secret {
t.Fatal("bindings.secret stored as plaintext")
}
if !strings.HasPrefix(stored, "arcie-binding:v1:") {
t.Fatalf("stored secret = %q, want arcie-binding:v1: envelope", stored)
}
// GetBinding returns the plaintext secret.
got, err := s.GetBinding(t.Context(), id)
if err != nil || got == nil {
t.Fatalf("GetBinding: %+v, %v", got, err)
}
if got.Secret != b.Secret {
t.Fatalf("GetBinding.Secret = %q, want %q", got.Secret, b.Secret)
}
}
func TestStoreListBindingsDecryptsSecrets(t *testing.T) {
s := openTestWithBindingCipher(t)
if _, err := s.InsertBinding(t.Context(), testBinding("sentry")); err != nil {
t.Fatalf("InsertBinding: %v", err)
}
got, err := s.ListBindings(t.Context())
if err != nil {
t.Fatalf("ListBindings: %v", err)
}
if len(got) != 1 {
t.Fatalf("ListBindings = %d rows, want 1", len(got))
}
if got[0].Secret != testBinding("sentry").Secret {
t.Fatalf("ListBindings.Secret not decrypted")
}
}
func TestStoreBindingCipherNoKeyIsPlaintext(t *testing.T) {
s := openTest(t) // no cipher -> legacy plaintext
b := testBinding("sentry")
id, err := s.InsertBinding(t.Context(), b)
if err != nil {
t.Fatalf("InsertBinding: %v", err)
}
got, err := s.GetBinding(t.Context(), id)
if err != nil || got == nil {
t.Fatalf("GetBinding: %+v, %v", got, err)
}
if got.Secret != b.Secret {
t.Fatalf("plaintext store round-trip = %q, want %q", got.Secret, b.Secret)
}
}
// TestStoreEncryptedReadLeavesLegacyPlaintextAlone pins that enabling a
// cipher does not break rows written before it was configured: a non-envelope
// secret must remain readable as plaintext (encryption is not retroactive).
func TestStoreEncryptedReadLeavesLegacyPlaintextAlone(t *testing.T) {
path := filepath.Join(t.TempDir(), "legacy.db")
plain, err := Open(t.Context(), path)
if err != nil {
t.Fatalf("Open (plaintext): %v", err)
}
b := testBinding("sentry")
id, err := plain.InsertBinding(t.Context(), b)
if err != nil {
t.Fatalf("InsertBinding (plaintext): %v", err)
}
if err := plain.Close(); err != nil {
t.Fatalf("Close: %v", err)
}
c, _ := NewBindingCipher(testBindingKey, nil)
encrypted, err := Open(t.Context(), path, WithBindingCipher(c))
if err != nil {
t.Fatalf("Open (cipher): %v", err)
}
t.Cleanup(func() { _ = encrypted.Close() })
got, err := encrypted.GetBinding(t.Context(), id)
if err != nil {
t.Fatalf("GetBinding under cipher: %v", err)
}
if got == nil {
t.Fatal("GetBinding returned nil")
}
if got.Secret != b.Secret {
t.Fatalf("legacy plaintext secret = %q, want %q (must stay readable)", got.Secret, b.Secret)
}
}
func openTestWithBindingCipher(t *testing.T) *Store {
t.Helper()
c, err := NewBindingCipher(testBindingKey, nil)
if err != nil {
t.Fatalf("NewBindingCipher: %v", err)
}
s, err := Open(t.Context(), filepath.Join(t.TempDir(), "test.db"), WithBindingCipher(c))
if err != nil {
t.Fatalf("Open: %v", err)
}
t.Cleanup(func() { _ = s.Close() })
return s
}
// tamperEnvelope decodes the payload, flips one byte inside the sealed
// ciphertext (after the 12-byte nonce), and re-encodes it, so the auth tag
// must fail. It returns the envelope with a corrupt ciphertext.
func tamperEnvelope(t *testing.T, envelope string) string {
t.Helper()
parts := strings.SplitN(envelope, ":", 4)
if len(parts) != 4 {
t.Fatalf("unexpected envelope: %q", envelope)
}
raw, err := base64.RawURLEncoding.DecodeString(parts[3])
if err != nil {
t.Fatalf("decode payload: %v", err)
}
// Flip a byte in the ciphertext region (not the nonce).
idx := 12
if len(raw) <= idx {
t.Fatalf("payload too short to tamper: %d bytes", len(raw))
}
raw[idx] ^= 0x01
parts[3] = base64.RawURLEncoding.EncodeToString(raw)
return strings.Join(parts, ":")
}
+50 -2
View File
@@ -5,6 +5,7 @@ import (
"database/sql"
"errors"
"fmt"
"strings"
"time"
"github.com/samcharles93/archie-core/internal/domain/binding"
@@ -84,10 +85,14 @@ func (s *Store) InsertBinding(ctx context.Context, b binding.Binding) (int64, er
}
now := time.Now().UTC().Format(bindingTimeLayout)
secret, err := s.encryptBindingSecret(b.Secret)
if err != nil {
return 0, err
}
res, err := tx.ExecContext(ctx, `
INSERT INTO bindings (name, source, mapping_id, workflow, version, status, secret, created_at, updated_at)
VALUES (?, ?, ?, ?, 1, 'draft', ?, ?, ?)`,
b.Name, b.Matcher.Source, b.MappingID, b.Workflow, b.Secret, now, now)
b.Name, b.Matcher.Source, b.MappingID, b.Workflow, secret, now, now)
if err != nil {
return 0, err
}
@@ -114,6 +119,9 @@ func (s *Store) GetBinding(ctx context.Context, id int64) (*binding.Binding, err
if err != nil {
return nil, err
}
if err := s.decryptBindingSecret(b); err != nil {
return nil, err
}
return b, nil
}
@@ -132,6 +140,9 @@ func (s *Store) ListBindings(ctx context.Context) (out []binding.Binding, retErr
if err != nil {
return nil, err
}
if err := s.decryptBindingSecret(b); err != nil {
return nil, err
}
out = append(out, *b)
}
return out, rows.Err()
@@ -163,13 +174,17 @@ func (s *Store) UpdateBinding(ctx context.Context, b binding.Binding) error {
}
now := time.Now().UTC().Format(bindingTimeLayout)
secret, err := s.encryptBindingSecret(b.Secret)
if err != nil {
return err
}
res, err := tx.ExecContext(ctx, `
UPDATE bindings SET name=?, source=?, mapping_id=?, workflow=?, secret=COALESCE(NULLIF(?, ''), secret),
status = 'pending_approval',
version = version + 1,
updated_at = ?
WHERE id=?`,
b.Name, b.Matcher.Source, b.MappingID, b.Workflow, b.Secret, now, b.ID)
b.Name, b.Matcher.Source, b.MappingID, b.Workflow, secret, now, b.ID)
if err != nil {
return err
}
@@ -283,11 +298,44 @@ func (s *Store) ArmedBindingsForSource(ctx context.Context, source string) ([]bi
if err != nil {
return nil, err
}
if err := s.decryptBindingSecret(b); err != nil {
return nil, err
}
out = append(out, *b)
}
return out, rows.Err()
}
// encryptBindingSecret seals a plaintext secret for persistence. With no
// cipher configured it returns the value unchanged (legacy plaintext).
func (s *Store) encryptBindingSecret(plaintext string) (string, error) {
if s.bindingsCipher == nil {
return plaintext, nil
}
return s.bindingsCipher.Encrypt(plaintext)
}
// decryptBindingSecret returns a binding's secret as plaintext. With no cipher
// configured the stored value is returned unchanged. A value that is not an
// encryption envelope is treated as a legacy plaintext row written before a
// cipher was configured and left readable as-is -- encryption applies to rows
// written or edited after the key is installed, not retroactively (see
// docs/prds/binding-secret-encryption.md).
func (s *Store) decryptBindingSecret(b *binding.Binding) error {
if s.bindingsCipher == nil {
return nil
}
if b.Secret == "" || !strings.HasPrefix(b.Secret, bindingEnvelopeMarker+":") {
return nil
}
decrypted, err := s.bindingsCipher.Decrypt(b.Secret)
if err != nil {
return err
}
b.Secret = decrypted
return nil
}
// sqlExecutor is the subset of *sql.DB / *sql.Tx that RecordDispatch needs.
// Both satisfy it; nil falls back to the store's own *sql.DB so callers
// that don't open an explicit transaction get best-effort semantics.
+24 -3
View File
@@ -101,12 +101,33 @@ func (t Task) IsForgeBacked() bool {
return t.Source != SourceChat
}
type Store struct{ db *sql.DB }
type Store struct {
db *sql.DB
bindingsCipher BindingCipher
}
const taskSchemaVersion = 2
// OpenOption configures the store at open time.
type OpenOption func(*openOptions)
type openOptions struct {
bindingsCipher BindingCipher
}
// WithBindingCipher installs an at-rest encryption cipher for binding secrets
// (docs/prds/binding-secret-encryption.md). When omitted, binding secrets are
// persisted as plaintext -- legacy behaviour, unchanged.
func WithBindingCipher(c BindingCipher) OpenOption {
return func(o *openOptions) { o.bindingsCipher = c }
}
// Open opens (creating if needed) the SQLite database and its schema.
func Open(ctx context.Context, path string) (*Store, error) {
func Open(ctx context.Context, path string, opts ...OpenOption) (*Store, error) {
var o openOptions
for _, opt := range opts {
opt(&o)
}
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
return nil, err
}
@@ -121,7 +142,7 @@ func Open(ctx context.Context, path string) (*Store, error) {
if err := migrateTasks(ctx, db); err != nil {
return nil, errors.Join(fmt.Errorf("store: migrate: %w", err), db.Close())
}
return &Store{db: db}, nil
return &Store{db: db, bindingsCipher: o.bindingsCipher}, nil
}
func sqliteDSN(path string) string {