From 2da98c3dd4304f072ba0758a9978c84c79f1670f Mon Sep 17 00:00:00 2001
From: sscodeai <sscodeai@users.noreply.github.com>
Date: Wed, 21 Oct 2026 21:20:43 +0900
Subject: [PATCH 1/6] fix(mask): mask by key name, not only by value shape

KeyNameIsSensitive existed but nothing called it, so a sensitive key holding
a passphrase without digits (DB_PASSWORD=correcthorsebatterystaple) was
returned verbatim by get/list, the MCP get tool and the MCP resource.

MaskKey applies the key-name rule first and falls back to the value
heuristics. store.List, the MCP get handler, the CLI get/set/vault commands,
the Vault KV listing and the leak-scan report now use it.
---
 cmd/keysmith/main.go          | 10 +++++-----
 internal/leakscan/leakscan.go |  2 +-
 internal/mask/mask.go         | 20 ++++++++++++++++++++
 internal/mask/mask_test.go    | 23 +++++++++++++++++++++++
 internal/mcp/server.go        |  2 +-
 internal/store/store.go       |  2 +-
 internal/store/store_test.go  | 14 ++++++++++++++
 internal/vault/client.go      | 16 +++-------------
 8 files changed, 68 insertions(+), 21 deletions(-)

diff --git a/cmd/keysmith/main.go b/cmd/keysmith/main.go
index d320cd1..eb70f72 100644
--- a/cmd/keysmith/main.go
+++ b/cmd/keysmith/main.go
@@ -157,7 +157,7 @@ func runCLI(storeDir, vaultAddr string, args []string) error {
 		if unsafe {
 			fmt.Println(val)
 		} else {
-			fmt.Println(mask.Mask(val))
+			fmt.Println(mask.MaskKey(key, val))
 		}
 		return nil
 
@@ -179,7 +179,7 @@ func runCLI(storeDir, vaultAddr string, args []string) error {
 		if err := st.Set(key, value); err != nil {
 			return err
 		}
-		fmt.Printf("stored %s (masked: %s)\n", key, mask.Mask(value))
+		fmt.Printf("stored %s (masked: %s)\n", key, mask.MaskKey(key, value))
 		return nil
 
 	case "rotate":
@@ -246,7 +246,7 @@ func runCLI(storeDir, vaultAddr string, args []string) error {
 		if containsFlag(rest, "--unsafe") {
 			fmt.Println(val)
 		} else {
-			fmt.Println(mask.Mask(val))
+			fmt.Println(mask.MaskKey(rest[0], val))
 		}
 		return nil
 
@@ -271,7 +271,7 @@ func runCLI(storeDir, vaultAddr string, args []string) error {
 		if err := vc.SetKV(context.Background(), rest[0], value); err != nil {
 			return err
 		}
-		fmt.Printf("stored %s in vault (masked: %s)\n", rest[0], mask.Mask(value))
+		fmt.Printf("stored %s in vault (masked: %s)\n", rest[0], mask.MaskKey(rest[0], value))
 		return nil
 
 	case "vault-kv-list":
@@ -302,7 +302,7 @@ func runCLI(storeDir, vaultAddr string, args []string) error {
 			return err
 		}
 		fmt.Printf("username: %s\n", creds.Username)
-		fmt.Printf("password: %s (masked)\n", mask.Mask(creds.Password))
+		fmt.Printf("password: %s (masked)\n", mask.MaskKey("DB_PASSWORD", creds.Password))
 		fmt.Printf("lease_id: %s\n", creds.LeaseID)
 		fmt.Printf("ttl: %ds (auto-expires — leaked cred is harmless)\n", creds.LeaseTTL)
 		fmt.Printf("renewable: %v\n", creds.Renewable)
diff --git a/internal/leakscan/leakscan.go b/internal/leakscan/leakscan.go
index ee43eaa..d1a3145 100644
--- a/internal/leakscan/leakscan.go
+++ b/internal/leakscan/leakscan.go
@@ -80,7 +80,7 @@ func ScanGitHistory(repoDir string, st *store.Store, autoRotate bool) ([]ScanRes
 				if autoRotate && !rotated {
 					if _, err := st.Rotate(key, 32); err == nil {
 						res.Rotated = true
-						res.NewMasked = mask.Mask(mustGet(st, key))
+						res.NewMasked = mask.MaskKey(key, mustGet(st, key))
 						rotated = true
 					}
 				}
diff --git a/internal/mask/mask.go b/internal/mask/mask.go
index ce34d93..ba07cde 100644
--- a/internal/mask/mask.go
+++ b/internal/mask/mask.go
@@ -125,6 +125,26 @@ func Mask(value string) string {
 	return maskPlain(value)
 }
 
+// MaskKey masks a stored value with the key name taken into account.
+//
+// A key name that marks a credential (DB_PASSWORD, GITHUB_TOKEN, ...) forces
+// masking even when the value itself does not match a value heuristic: a
+// passphrase without digits, a DSN, or a short password is still a secret, and
+// value-only heuristics cannot recognise every one. The key name is the one
+// signal the caller always has, so it is applied first.
+func MaskKey(key, value string) string {
+	if value == "" {
+		return ""
+	}
+	if !KeyNameIsSensitive(key) {
+		return Mask(value)
+	}
+	if urlSchemeRe.MatchString(value) {
+		return MaskURL(value)
+	}
+	return maskPlain(value)
+}
+
 // MaskURL masks a URL-shaped value per segment: userinfo password always
 // masked, random-looking runs in path/query masked, scheme/user/host/port stay
 // clear.
diff --git a/internal/mask/mask_test.go b/internal/mask/mask_test.go
index 4d97449..145825d 100644
--- a/internal/mask/mask_test.go
+++ b/internal/mask/mask_test.go
@@ -69,6 +69,29 @@ func TestMask(t *testing.T) {
 	}
 }
 
+func TestMaskKeyUsesTheKeyName(t *testing.T) {
+	cases := []struct {
+		key, val, want string
+	}{
+		// A sensitive key name forces masking even though the value has no
+		// digit and no credential prefix.
+		{"DB_PASSWORD", "correcthorsebatterystaple", "co******le"},
+		{"DB_PASSWORD", "hunter2", "hu******r2"},
+		{"GITHUB_TOKEN", "short", "sh******rt"},
+		// URL values keep their scheme/host but lose the password.
+		{"DB_PASSWORD", "postgres://app:s3cret@db.internal/app", "postgres://app:s3******et@db.internal/app"},
+		// A non-sensitive key keeps plain configuration readable.
+		{"DEBUG", "correcthorsebatterystaple", "correcthorsebatterystaple"},
+		// A URL value is still segment-masked by the value heuristics.
+		{"DATABASE_URL", "postgres://app:s3cret@db.internal/app", "postgres://app:s3******et@db.internal/app"},
+	}
+	for _, c := range cases {
+		if got := MaskKey(c.key, c.val); got != c.want {
+			t.Errorf("MaskKey(%q, %q) = %q, want %q", c.key, c.val, got, c.want)
+		}
+	}
+}
+
 func TestMaskURL(t *testing.T) {
 	cases := []struct {
 		val  string
diff --git a/internal/mcp/server.go b/internal/mcp/server.go
index 4d1fb3f..0213d87 100644
--- a/internal/mcp/server.go
+++ b/internal/mcp/server.go
@@ -117,7 +117,7 @@ func NewServer(st *store.Store, version string) (*Server, error) {
 			}
 			return nil, nil, fmt.Errorf("get %q: %w", args.Key, err)
 		}
-		return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: mask.Mask(v)}}}, nil, nil
+		return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: mask.MaskKey(args.Key, v)}}}, nil, nil
 	})
 
 	// put: set a secret. Value is read from a temp file path arg, so the
diff --git a/internal/store/store.go b/internal/store/store.go
index 4b0a8c1..60dfb9c 100644
--- a/internal/store/store.go
+++ b/internal/store/store.go
@@ -219,7 +219,7 @@ func (s *Store) List() (map[string]string, error) {
 	}
 	out := make(map[string]string, len(m))
 	for k, v := range m {
-		out[k] = mask.Mask(v)
+		out[k] = mask.MaskKey(k, v)
 	}
 	return out, nil
 }
diff --git a/internal/store/store_test.go b/internal/store/store_test.go
index e7933d6..85c1c15 100644
--- a/internal/store/store_test.go
+++ b/internal/store/store_test.go
@@ -86,6 +86,20 @@ func TestListIsMasked(t *testing.T) {
 	}
 }
 
+func TestListMasksSensitiveKeyNames(t *testing.T) {
+	s := newTestStore(t)
+	if err := s.Set("DB_PASSWORD", "correcthorsebatterystaple"); err != nil {
+		t.Fatalf("Set: %v", err)
+	}
+	items, err := s.List()
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if v := items["DB_PASSWORD"]; v == "correcthorsebatterystaple" {
+		t.Errorf("List leaked a passphrase for a sensitive key name: %q", v)
+	}
+}
+
 func TestDelete(t *testing.T) {
 	s := newTestStore(t)
 	if err := s.Set("TMP", "secret1"); err != nil {
diff --git a/internal/vault/client.go b/internal/vault/client.go
index 389e704..903b998 100644
--- a/internal/vault/client.go
+++ b/internal/vault/client.go
@@ -17,6 +17,8 @@ import (
 	"net/http"
 	"strings"
 	"time"
+
+	"github.com/sscodeai/keysmith/internal/mask"
 )
 
 // Client is a minimal Vault HTTP API client. It deliberately implements only
@@ -116,7 +118,7 @@ func (c *Client) ListKV(ctx context.Context) (map[string]string, error) {
 		if err != nil {
 			continue
 		}
-		result[k] = maskValue(v)
+		result[k] = mask.MaskKey(k, v)
 	}
 	return result, nil
 }
@@ -194,15 +196,3 @@ func (c *Client) doJSON(ctx context.Context, method, path string, body []byte, o
 	}
 	return nil
 }
-
-// maskValue is a tiny inline masker for Vault values (reuses mask pkg when
-// wired, but kept standalone to avoid import cycle).
-func maskValue(v string) string {
-	if v == "" {
-		return ""
-	}
-	if len(v) <= 4 {
-		return v[:1] + "***"
-	}
-	return v[:2] + "******" + v[len(v)-2:]
-}

From 8dc8d0f1d37e517257cd18922a86cefcce46e84d Mon Sep 17 00:00:00 2001
From: sscodeai <sscodeai@users.noreply.github.com>
Date: Wed, 21 Oct 2026 21:22:59 +0900
Subject: [PATCH 2/6] fix(mcp): confine put value_file to the store inbox

put read any path the agent supplied and unlinked it afterwards, which made
the tool an arbitrary-file read (store a file, then read it back with get when
the value does not look secret) and an arbitrary-file delete.

Value files now have to resolve inside <store>/inbox: symlink escapes,
relative escapes and absolute paths elsewhere are refused. The inbox is
created 0700, `keysmith inbox` prints it, and the tool description tells the
agent where to write. e2e_test.py asserts the refusal and that the outside
file survives.
---
 AGENTS.ja.md                |  4 +-
 AGENTS.md                   |  8 +++-
 README.ja.md                |  9 +++--
 README.md                   | 14 +++++--
 cmd/keysmith/main.go        | 10 +++++
 e2e_test.py                 | 29 +++++++++++---
 internal/mcp/server.go      | 76 +++++++++++++++++++++++++++--------
 internal/mcp/server_test.go | 80 +++++++++++++++++++++++++++++++++++++
 internal/store/store.go     |  4 ++
 skill/SKILL.ja.md           |  2 +-
 skill/SKILL.md              |  7 ++--
 11 files changed, 206 insertions(+), 37 deletions(-)
 create mode 100644 internal/mcp/server_test.go

diff --git a/AGENTS.ja.md b/AGENTS.ja.md
index d41a5c3..bc606b2 100644
--- a/AGENTS.ja.md
+++ b/AGENTS.ja.md
@@ -15,8 +15,8 @@
 
 1. `secrets.enc` は平文の key material を決して含んではいけません。age で暗号化します。
 2. `key.txt` は `0600`、store dir は `0700` でなければなりません。
-3. すべての MCP tool result と resource はマスク済みでなければなりません。tool result に平文を出してはいけません。
-4. `put` は `value_file` パスを受け取り、それを読み、読み取り後に削除しなければなりません。
+3. すべての MCP tool result と resource はマスク済みでなければなりません。tool result に平文を出してはいけません。`mask.MaskKey` を使い、機密キー名 (DB_PASSWORD, GITHUB_TOKEN...) の場合は値がヒューリスティックに一致しなくてもマスクしてください。
+4. `put` は **`<store>/inbox` 内** の `value_file` パスを受け取り、それを読み、読み取り後に削除しなければなりません。inbox の外のパス (外を指す symlink を含む) は拒否します。引数はエージェントが制御するためです。
 5. マスキング規則は `internal/mask` にあります。entropy/prefix/URL segmentation のテストを green に保ってください。
 6. **redemption は fail-closed です** (`internal/redeem`、docs/THREAT-MODEL.md)。未知のセッション、期限切れセッション、そのセッションで発行されていないキー名、値の欠落または空値、不正な予約プレフィックス、`argv` 内のトークン、audit log の書き込み失敗。いずれの場合もコマンドを起動しません。トークンをそのまま転送するフォールバックも、平文を転送するフォールバックも存在せず、エラーメッセージに値を含めてはいけません。
 7. redemption は `argv` に値を置かず、値も引数リスト全体もログに残しません (`<store>/audit.log` はキー名のみを記録します)。
diff --git a/AGENTS.md b/AGENTS.md
index 9e85a45..76f0b53 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -20,8 +20,12 @@ agents that develop it.
 1. `secrets.enc` must never contain plaintext key material (age-encrypted).
 2. `key.txt` must be `0600`, store dir `0700`.
 3. Every MCP tool result and resource must be masked — no plaintext in
-   tool results, ever.
-4. `put` must accept a `value_file` path, read it, and delete it after.
+   tool results, ever. Use `mask.MaskKey`, so a sensitive key name
+   (DB_PASSWORD, GITHUB_TOKEN, ...) masks the value even when the value itself
+   does not match a heuristic.
+4. `put` must accept a `value_file` path **inside `<store>/inbox`**, read it,
+   and delete it after. Paths outside the inbox (including symlinks that
+   resolve outside) are refused: the argument is agent-controlled.
 5. Masking rules live in `internal/mask` — keep the entropy/prefix/URL
    segmentation tests green.
 6. **Redemption fails closed** (`internal/redeem`, docs/THREAT-MODEL.md). On any
diff --git a/README.ja.md b/README.ja.md
index 90e2ed1..47b21ad 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -20,7 +20,7 @@ Keysmith は、**多層セキュリティモデル**でこれを解決します
 |---|---|---|
 | 暗号化された保存 | 保存時に age (X25519) で暗号化 | ディスク上の平文。コンテキストに漏れても blob は暗号文なので無害 |
 | マスク済みビュー | resources/tools が `sk******ij` 形式で返す | 認証情報がエージェントのコンテキストに入ること |
-| ハンドル渡し | `put` は transcript ではなく一時ファイル引数から値を読む | ツール呼び出し transcript 内の平文 |
+| ハンドル渡し | `put` は transcript ではなくストアの inbox にあるファイルから値を読む | ツール呼び出し transcript 内の平文 |
 | 自己修復ローテーション | `scan --rotate` が漏えいを検出し、漏れた値を無効化 | 古い漏えい済み認証情報が使われ続けること |
 | 短 TTL (Vault) | 動的 DB 認証情報は 1 時間で期限切れ | 漏えいした認証情報の価値が残ること |
 | Redemption | `keysmith run` がトークンをローカルで差し替え、子プロセスの環境変数へ渡す | 認証情報を「使う」必要があるエージェントが平文を出力してしまうこと。`argv`、transcript、ログ内の平文 |
@@ -95,6 +95,7 @@ keysmith set API_KEY < value.txt     # stdin から値を読み、shell history
 keysmith rotate API_KEY 32           # 強力な新しいシークレットを生成して保存
 keysmith delete API_KEY              # キーを削除
 keysmith scan [--rotate] [repo-dir]  # git 履歴から漏えいしたシークレットをスキャン
+keysmith inbox                       # MCP の put が値ファイルを受け取るディレクトリ
 keysmith token API_KEY               # セッションに紐づくプレースホルダートークンを発行
 keysmith token API_KEY --allow-host api.example.test --allow-path /v1/
                                      # ...宛先に結合する（下記参照）
@@ -134,7 +135,7 @@ keysmith -vault http://127.0.0.1:8200 vault-db-creds app-role       # 短 TTL 
 |---|---|---|
 | `list` | すべてのキーとマスク済み値 | 値は平文にならない |
 | `get` | 1 つのキーのマスク済み値 | 値は平文にならない |
-| `put` | シークレットを保存 | 値は `value_file` 引数から読み、一時ファイルは自動削除 |
+| `put` | シークレットを保存 | `value_file` はストアの inbox 内のみ受け付け、読み取り後に削除 |
 | `rotate` | 強力なランダムシークレットを生成して保存 | マスク済み値のみを返す |
 | `delete` | キーを削除 | - |
 
@@ -192,9 +193,9 @@ flowchart TB
 
 - **保存時**: 常に age (X25519) で暗号化され、armor 形式です。平文ファイルはディスク上に存在しません。atomic write (temp + rename) と `0600` 権限を使います。
 - **コンテキスト内**: マスク済み値のみです。マスキングは先頭/末尾 2 文字を残し (`sk******ij`)、認証情報を識別できるが露出しない形にします。
-- **Transcript 内**: `put` は平文を引数として受け取りません。一時ファイルパスを読み、読み取り後にファイルを削除します。
+- **Transcript 内**: `put` は平文を引数として受け取りません。ファイルパスを読み、ストアの inbox (`keysmith inbox`) 内のパスのみ受け付け、読み取り後にファイルを削除します。inbox の外は拒否されるため、任意ファイルの読み取りや削除には使えません。
 - **使用時**: `keysmith run` はセッションに紐づくトークンをローカルで解決し、値を子プロセスの環境変数へ渡します。値は `argv`、audit log、モデルへのリクエストに到達しません。失敗時はコマンド起動前に中止し、平文フォールバックもトークンのそのまま転送も行いません。結合済みトークンは `--target` も満たす必要があり、宣言された宛先は audit 行に記録されます。
-- **マスキング規則**: キー名マーカー (SECRET/TOKEN/PASSWORD/API_KEY/DSN...)、既知の値プレフィックス (sk-, ghp_, glpat-, xoxb-, JWT...)、高エントロピーな英数字列 (英字と数字が混在する 20 文字以上、Shannon entropy 3.5 以上) を使います。URL 形状の値はセグメントごとにマスクされます。userinfo のパスワードは常にマスクされ、高エントロピーな path/query はマスクされ、host/port は残ります。timeout や retry などの純数字値はマスクされません。
+- **マスキング規則**: キー名マーカー (SECRET/TOKEN/PASSWORD/API_KEY/DSN...)、既知の値プレフィックス (sk-, ghp_, glpat-, xoxb-, JWT...)、高エントロピーな英数字列 (英字と数字が混在する 20 文字以上、Shannon entropy 3.5 以上) を使います。キー名が認証情報を示す場合は、値がヒューリスティックに一致しなくても必ずマスクします (数字を含まないパスフレーズもシークレットです)。機密でないキー (DEBUG, PORT) の設定値はそのまま読めます。URL 形状の値はセグメントごとにマスクされます。userinfo のパスワードは常にマスクされ、高エントロピーな path/query はマスクされ、host/port は残ります。timeout や retry などの純数字値はマスクされません。
 
 ## 開発
 
diff --git a/README.md b/README.md
index e1eabe8..92bfa32 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@ Keysmith fixes this with a **layered security model**:
 |---|---|---|
 | Encrypted residency | age (X25519) encrypted store at rest | Plaintext on disk; even a leaked context is harmless (blobs are ciphertext) |
 | Masked views | resources/tools return `sk******ij` form | Credentials entering agent context |
-| Handle-passing | `put` reads value from a temp file arg, not the transcript | Plaintext in tool-call transcripts |
+| Handle-passing | `put` reads the value from a file in the store inbox, not from the transcript | Plaintext in tool-call transcripts |
 | Self-healing rotation | `scan --rotate` detects leaks, kills the leaked value | Stale leaked credentials keep working |
 | Short-TTL (Vault) | dynamic DB creds expire in 1h | Leaked credentials become worthless |
 | Redemption | `keysmith run` substitutes a token locally, into the child's environment | An agent that must *use* a credential being tempted to print it; plaintext in `argv`, transcripts, or logs |
@@ -106,6 +106,7 @@ keysmith set API_KEY < value.txt     # value from stdin, no shell-history leak
 keysmith rotate API_KEY 32           # generate + store new strong secret
 keysmith delete API_KEY               # remove a key
 keysmith scan [--rotate] [repo-dir]  # scan git history for leaked secrets
+keysmith inbox                       # directory the MCP put tool accepts files from
 keysmith token API_KEY               # issue a session-bound placeholder token
 keysmith token API_KEY --allow-host api.example.test --allow-path /v1/
                                      # ...bound to a destination (see below)
@@ -157,7 +158,7 @@ keysmith -vault http://127.0.0.1:8200 vault-db-creds app-role       # dynamic sh
 |---|---|---|
 | `list` | All keys with masked values | Values never plaintext |
 | `get` | Single key, masked value | Values never plaintext |
-| `put` | Store a secret | Value read from `value_file` arg, temp file auto-removed |
+| `put` | Store a secret | Reads `value_file` from the store inbox only, then deletes it |
 | `rotate` | Generate + store a new strong random secret | Returns masked value only |
 | `delete` | Remove a key | — |
 
@@ -220,10 +221,12 @@ itself, transports decide how agents connect.
 
 - **At rest**: always age-encrypted (X25519), armor format. A plaintext file
   never exists on disk. Atomic writes (temp + rename), `0600` perms.
+- **In transcripts**: `put` never takes the plaintext as an argument — it
+  reads a file path, and only inside the store inbox (`keysmith inbox`); the
+  file is deleted after it is read. A path outside the inbox is refused, so the
+  tool cannot be used as an arbitrary-file read or unlink.
 - **In context**: masked values only. Masking keeps first/last 2 chars
   (`sk******ij`) so credentials are distinguishable without being revealed.
-- **In transcripts**: `put` never takes the plaintext as an argument — it
-  reads a temp file path and deletes the file after.
 - **At use time**: `keysmith run` redeems a session-bound token locally and
   places the value in the child's environment. Values never reach `argv`, the
   audit log, or a model request; every failure aborts before the command starts
@@ -233,6 +236,9 @@ itself, transports decide how agents connect.
 - **Masking rules**: key-name markers (SECRET/TOKEN/PASSWORD/API_KEY/DSN...),
   known value prefixes (sk-, ghp_, glpat-, xoxb-, JWT...), and high-entropy
   alphanumeric runs (≥20 chars mixing letters+digits, Shannon entropy ≥3.5).
+  A sensitive key name forces masking even when the value does not match a
+  value heuristic — a passphrase without digits is still a secret. Plain
+  configuration under a non-sensitive key (DEBUG, PORT) stays readable.
   URL-shaped values are masked per-segment: userinfo password always masked,
   high-entropy path/query runs masked, host/port stay clear. Pure-numeric
   values (timeouts, retries) are never masked.
diff --git a/cmd/keysmith/main.go b/cmd/keysmith/main.go
index eb70f72..93373e0 100644
--- a/cmd/keysmith/main.go
+++ b/cmd/keysmith/main.go
@@ -230,6 +230,15 @@ func runCLI(storeDir, vaultAddr string, args []string) error {
 		fmt.Print(leakscan.Format(results))
 		return nil
 
+	case "inbox":
+		// keysmith inbox — print the directory `put` accepts value files from.
+		dir := filepath.Join(storeDir, mcp.InboxDirName)
+		if err := os.MkdirAll(dir, 0o700); err != nil {
+			return err
+		}
+		fmt.Println(dir)
+		return nil
+
 	case "vault-kv-get":
 		// keysmith vault-kv-get KEY  (masked by default, --unsafe for plaintext)
 		if len(rest) < 1 {
@@ -380,6 +389,7 @@ USAGE:
   keysmith rotate KEY [len]   # generate + store new strong secret
   keysmith delete KEY         # remove a key
   keysmith scan [--rotate] [repo-dir]  # scan git history for leaked secrets
+  keysmith inbox              # print the directory MCP put accepts value files from
   keysmith token NAME [--ttl 1h] [--allow-host H] [--allow-path P] [--allow-header HN]
                                        # issue a session-bound placeholder token
   keysmith run [--session SID] [--target URL] --env KEY='<template>' -- cmd args...
diff --git a/e2e_test.py b/e2e_test.py
index ea3c328..9444ae4 100644
--- a/e2e_test.py
+++ b/e2e_test.py
@@ -4,6 +4,7 @@
 import os
 import subprocess
 import sys
+import tempfile
 import time
 
 # Binary path: env override, else relative to this script (repo/bin/keysmith)
@@ -47,16 +48,34 @@ def main():
     names = [t["name"] for t in r["result"]["tools"]]
     print("tools/list:", names)
 
-    # 4. tools/call put (value via temp file — plaintext never in transcript)
-    with open("/tmp/smcp-e2e-val.txt", "w") as f:
+    # 4. tools/call put — value via a file inside the inbox, so the plaintext
+    # never appears in the transcript. Paths outside the inbox must be refused:
+    # the argument is agent-controlled, so an unrestricted path would let it
+    # read and delete arbitrary files.
+    inbox = os.path.join(STORE, "inbox")
+    os.makedirs(inbox, mode=0o700, exist_ok=True)
+    valfile = os.path.join(inbox, "e2e-value.txt")
+
+    outside = os.path.join(tempfile.gettempdir(), "smcp-e2e-outside.txt")
+    with open(outside, "w") as f:
+        f.write("sk-outside-e2e-1234567890")
+    send(proc, {"jsonrpc": "2.0", "id": 30, "method": "tools/call",
+                "params": {"name": "put", "arguments": {"key": "OUTSIDE", "value_file": outside}}})
+    r = recv(proc)
+    refused = bool((r.get("result") or {}).get("isError")) or "error" in r
+    print("put outside inbox refused:", refused)
+    print("  outside file kept:", os.path.exists(outside))
+    os.remove(outside)
+
+    with open(valfile, "w") as f:
         f.write("sk-super-secret-e2e-1234567890")
     send(proc, {"jsonrpc": "2.0", "id": 3, "method": "tools/call",
-                "params": {"name": "put", "arguments": {"key": "API_KEY", "value_file": "/tmp/smcp-e2e-val.txt"}}})
+                "params": {"name": "put", "arguments": {"key": "API_KEY", "value_file": valfile}}})
     r = recv(proc)
     print("put:", "OK" if r and "result" in r else f"FAIL {r}")
     print("  result:", r["result"]["content"][0]["text"])
-    # temp file should be gone
-    print("  temp file removed:", not os.path.exists("/tmp/smcp-e2e-val.txt"))
+    # value file should be gone
+    print("  value file removed:", not os.path.exists(valfile))
 
     # 5. tools/call list (masked)
     send(proc, {"jsonrpc": "2.0", "id": 4, "method": "tools/call",
diff --git a/internal/mcp/server.go b/internal/mcp/server.go
index 0213d87..b343316 100644
--- a/internal/mcp/server.go
+++ b/internal/mcp/server.go
@@ -26,16 +26,30 @@ import (
 // Server wraps a secret store as an MCP server.
 type Server struct {
 	store *store.Store
+	inbox string
 	mcp   *mcp.Server
 }
 
+// InboxDirName is the directory, next to the encrypted store, where `put` reads
+// value files from. Agents are told about it (`keysmith inbox`); anything
+// outside it is refused by readValueFile.
+const InboxDirName = "inbox"
+
 // NewServer creates an MCP server backed by the given store. version is what
 // clients see as serverInfo.version; an empty value is reported as "dev".
+//
+// The inbox directory is created with 0700 because `put` will only read (and
+// then delete) value files inside it: the tool argument is agent-controlled, so
+// an unrestricted path would be an arbitrary-file read and unlink primitive.
 func NewServer(st *store.Store, version string) (*Server, error) {
 	if version == "" {
 		version = "dev"
 	}
-	s := &Server{store: st}
+	inbox := filepath.Join(st.Dir(), InboxDirName)
+	if err := os.MkdirAll(inbox, 0o700); err != nil {
+		return nil, fmt.Errorf("create inbox: %w", err)
+	}
+	s := &Server{store: st, inbox: inbox}
 	srv := mcp.NewServer(&mcp.Implementation{
 		Name:    "keysmith",
 		Version: version,
@@ -124,16 +138,18 @@ func NewServer(st *store.Store, version string) (*Server, error) {
 	// plaintext never appears in the tool call transcript.
 	type putArgs struct {
 		Key       string `json:"key" jsonschema:"the secret key name"`
-		ValueFile string `json:"value_file" jsonschema:"path to a file containing the value (keeps plaintext out of the transcript)"`
+		ValueFile string `json:"value_file" jsonschema:"path to a file inside the keysmith inbox containing the value (keeps plaintext out of the transcript)"`
 	}
 	mcp.AddTool(srv, &mcp.Tool{
-		Name:        "put",
-		Description: "Store a secret. Pass value_file (a path to a file containing the value) to avoid putting plaintext in the transcript.",
+		Name: "put",
+		Description: "Store a secret. Write the value to a file inside the keysmith inbox " +
+			"(run `keysmith inbox` for the path), then pass that path as value_file: paths " +
+			"outside the inbox are refused, and the file is deleted after it is read.",
 	}, func(ctx context.Context, req *mcp.CallToolRequest, args putArgs) (*mcp.CallToolResult, any, error) {
 		if args.Key == "" {
 			return nil, nil, errors.New("key is required")
 		}
-		val, err := readValueFile(args.ValueFile)
+		val, err := readValueFile(s.inbox, args.ValueFile)
 		if err != nil {
 			return nil, nil, err
 		}
@@ -200,22 +216,50 @@ func (s *Server) Handler() *mcp.Server {
 	return s.mcp
 }
 
-// readValueFile reads a secret value from a file (single line, trailing newline
-// stripped). The file is removed after reading to avoid leaving plaintext.
-func readValueFile(path string) (string, error) {
-	if path == "" {
-		return "", errors.New("value_file is required (write the value to a temp file first)")
+// readValueFile reads a secret value from a file inside inbox (single line,
+// trailing newline stripped) and removes it after reading, so plaintext does
+// not linger. Paths outside the inbox are refused: the MCP caller chooses this
+// path, and reading + unlinking an arbitrary file would be a destructive
+// primitive (for example value_file: "~/.ssh/id_ed25519").
+func readValueFile(inbox, path string) (string, error) {
+	inside, err := resolveInside(inbox, path)
+	if err != nil {
+		return "", err
 	}
-	b, err := os.ReadFile(path)
+	b, err := os.ReadFile(inside)
 	if err != nil {
 		return "", fmt.Errorf("read value file: %w", err)
 	}
 	val := strings.TrimSuffix(string(b), "\n")
 	val = strings.TrimSuffix(val, "\r")
-	// Best-effort cleanup: remove the temp file so plaintext doesn't linger.
-	abs, aerr := filepath.Abs(path)
-	if aerr == nil {
-		_ = os.Remove(abs)
-	}
+	// Remove the file now that the value is in memory.
+	_ = os.Remove(inside)
 	return val, nil
 }
+
+// resolveInside returns path if it resolves, after following symlinks, to a
+// regular file inside dir. Anything else — a relative escape, an absolute path
+// elsewhere, or a symlink pointing out of dir — is refused.
+func resolveInside(dir, path string) (string, error) {
+	if strings.TrimSpace(path) == "" {
+		return "", fmt.Errorf("value_file is required: write the value to %s and pass that path", dir)
+	}
+	root, err := filepath.EvalSymlinks(dir)
+	if err != nil {
+		return "", fmt.Errorf("resolve inbox: %w", err)
+	}
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return "", fmt.Errorf("resolve value file: %w", err)
+	}
+	resolved, err := filepath.EvalSymlinks(abs)
+	if err != nil {
+		return "", fmt.Errorf("read value file: %w", err)
+	}
+	rel, err := filepath.Rel(root, resolved)
+	if err != nil || rel == "." || rel == ".." ||
+		filepath.IsAbs(rel) || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) {
+		return "", fmt.Errorf("value_file must be inside the keysmith inbox (%s); run `keysmith inbox` for the path", dir)
+	}
+	return resolved, nil
+}
diff --git a/internal/mcp/server_test.go b/internal/mcp/server_test.go
new file mode 100644
index 0000000..7598cba
--- /dev/null
+++ b/internal/mcp/server_test.go
@@ -0,0 +1,80 @@
+package mcp
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The value_file argument is agent-controlled. These cases are the access
+// control for it: only files inside the inbox may be read (and then removed).
+func TestResolveInside(t *testing.T) {
+	root := t.TempDir()
+	inbox := filepath.Join(root, "inbox")
+	if err := os.MkdirAll(inbox, 0o700); err != nil {
+		t.Fatalf("mkdir inbox: %v", err)
+	}
+	outsideDir := filepath.Join(root, "outside")
+	if err := os.MkdirAll(outsideDir, 0o700); err != nil {
+		t.Fatalf("mkdir outside: %v", err)
+	}
+	outsideFile := filepath.Join(outsideDir, "secret.txt")
+	if err := os.WriteFile(outsideFile, []byte("not-for-mcp"), 0o600); err != nil {
+		t.Fatalf("write outside: %v", err)
+	}
+	insideFile := filepath.Join(inbox, "value.txt")
+	if err := os.WriteFile(insideFile, []byte("ok"), 0o600); err != nil {
+		t.Fatalf("write inside: %v", err)
+	}
+	link := filepath.Join(inbox, "escape.txt")
+	if err := os.Symlink(outsideFile, link); err != nil {
+		t.Fatalf("symlink: %v", err)
+	}
+
+	t.Run("accepts a file inside the inbox", func(t *testing.T) {
+		got, err := resolveInside(inbox, insideFile)
+		if err != nil {
+			t.Fatalf("resolveInside: %v", err)
+		}
+		if !strings.HasSuffix(got, "value.txt") {
+			t.Errorf("resolved to %q, want the inbox file", got)
+		}
+	})
+
+	refused := []struct {
+		name string
+		path string
+	}{
+		{"absolute path outside", outsideFile},
+		{"relative escape", filepath.Join(inbox, "..", "outside", "secret.txt")},
+		{"symlink pointing outside", link},
+		{"the inbox directory itself", inbox},
+		{"empty path", "   "},
+	}
+	for _, c := range refused {
+		t.Run("refuses "+c.name, func(t *testing.T) {
+			if _, err := resolveInside(inbox, c.path); err == nil {
+				t.Fatalf("resolveInside(%q) = nil error, want refusal", c.path)
+			}
+		})
+	}
+}
+
+func TestReadValueFileRemovesTheFileAfterReading(t *testing.T) {
+	inbox := t.TempDir()
+	path := filepath.Join(inbox, "value.txt")
+	if err := os.WriteFile(path, []byte("sk-test-1234567890\n"), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	got, err := readValueFile(inbox, path)
+	if err != nil {
+		t.Fatalf("readValueFile: %v", err)
+	}
+	if got != "sk-test-1234567890" {
+		t.Errorf("got %q, want the trimmed value", got)
+	}
+	if _, err := os.Stat(path); !os.IsNotExist(err) {
+		t.Errorf("value file still exists after read: %v", err)
+	}
+}
diff --git a/internal/store/store.go b/internal/store/store.go
index 60dfb9c..194a8cf 100644
--- a/internal/store/store.go
+++ b/internal/store/store.go
@@ -51,6 +51,10 @@ func New(dir string) (*Store, error) {
 // KeyPath returns the path to the secret key file.
 func (s *Store) KeyPath() string { return filepath.Join(s.dir, "key.txt") }
 
+// Dir returns the store directory. Callers that need to place files next to the
+// store (for example the MCP inbox) resolve them against this path.
+func (s *Store) Dir() string { return s.dir }
+
 // DataPath returns the path to the encrypted secrets file.
 func (s *Store) DataPath() string { return filepath.Join(s.dir, "secrets.enc") }
 
diff --git a/skill/SKILL.ja.md b/skill/SKILL.ja.md
index ffde71c..73ffd50 100644
--- a/skill/SKILL.ja.md
+++ b/skill/SKILL.ja.md
@@ -26,7 +26,7 @@ version: 1.1.0
 
 - **`list`** — すべてのキーをマスク済み値付きで確認します。まずこれで状況を把握します。
 - **`get <key>`** — 1 つのマスク済み値を読みます。
-- **`put <key> <value_file>`** — 新しい値を保存します。先に値を一時ファイルへ書き込み (`echo -n "$VAL" > /tmp/x`)、そのパスを `value_file` として渡します。サーバーは読み取り後にファイルを削除します。値を引数として渡してはいけません。
+- **`put <key> <value_file>`** — 新しい値を保存します。先に値を keysmith の inbox (`keysmith inbox`、通常は `<store>/inbox`) 内のファイルへ書き込み、そのパスを `value_file` として渡します。サーバーは読み取り後にファイルを削除します。inbox の外のパスは拒否されます。値を引数として渡してはいけません。
 - **`rotate <key> [length]`** — 強力なランダム値を生成して保存します。返るのはマスク済み値です。
 - **`delete <key>`** — 削除します。
 
diff --git a/skill/SKILL.md b/skill/SKILL.md
index cc09494..c232d06 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -29,9 +29,10 @@ Prefer them because they work, not because they are enforced.
 ## Tool usage (via MCP)
 - **`list`** — see all keys with masked values. Use first to orient.
 - **`get <key>`** — read one masked value.
-- **`put <key> <value_file>`** — store a new value. Write the value to a
-  temp file first (`echo -n "$VAL" > /tmp/x`), pass the PATH as `value_file`,
-  and the server deletes the file after. Never pass the value as an argument.
+- **`put <key> <value_file>`** — store a new value. Write the value to a file
+  inside the keysmith inbox (`keysmith inbox`, normally `<store>/inbox`), pass
+  that PATH as `value_file`, and the server deletes it after. Paths outside the
+  inbox are refused. Never pass the value as an argument.
 - **`rotate <key> [length]`** — generate a new strong random value and store
   it. Returns masked.
 - **`delete <key>`** — remove.

From 867011d2eabaeace468a92121dd0ce539b99b377 Mon Sep 17 00:00:00 2001
From: sscodeai <sscodeai@users.noreply.github.com>
Date: Wed, 21 Oct 2026 21:23:57 +0900
Subject: [PATCH 3/6] fix(store): serialize writers so concurrent sets cannot
 drop keys

Set/Delete/Rotate did a read-modify-write of the whole map with no lock. The
MCP server and the CLI share the store, so an agent writing while a human runs
`keysmith set` silently lost one of the writes: 20 concurrent `set` calls
stored only 12 keys.

Writers now take an exclusive flock on <store>/store.lock (unix; a no-op
single-process fallback elsewhere), including key initialization, so two
processes cannot generate competing identities. Temp files use a unique name
per write, and randomSecret uses rejection sampling instead of a biased
modulo, since the bias was easy to remove while touching the file.
---
 go.mod                       |  2 +-
 go.sum                       |  6 ---
 internal/store/lock_other.go | 25 ++++++++++
 internal/store/lock_unix.go  | 36 ++++++++++++++
 internal/store/store.go      | 93 ++++++++++++++++++++++++++++++------
 internal/store/store_test.go | 49 +++++++++++++++++++
 6 files changed, 190 insertions(+), 21 deletions(-)
 create mode 100644 internal/store/lock_other.go
 create mode 100644 internal/store/lock_unix.go

diff --git a/go.mod b/go.mod
index cb75d6f..64ecc85 100644
--- a/go.mod
+++ b/go.mod
@@ -5,6 +5,7 @@ go 1.25.13
 require (
 	filippo.io/age v1.2.1
 	github.com/modelcontextprotocol/go-sdk v1.7.0
+	golang.org/x/sys v0.41.0
 )
 
 require (
@@ -15,6 +16,5 @@ require (
 	golang.org/x/crypto v0.45.0 // indirect
 	golang.org/x/oauth2 v0.35.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.41.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
 )
diff --git a/go.sum b/go.sum
index 30173cb..90ecbba 100644
--- a/go.sum
+++ b/go.sum
@@ -1,9 +1,7 @@
 c2sp.org/CCTV/age v0.0.0-20240306222714-3ec4d716e805 h1:u2qwJeEvnypw+OCPUHmoZE3IqwfuN5kgDfo5MLzpNM0=
 c2sp.org/CCTV/age v0.0.0-20240306222714-3ec4d716e805/go.mod h1:FomMrUJ2Lxt5jCLmZkG3FHa72zUprnhd3v/Z18Snm4w=
-cloud.google.com/go/compute/metadata v0.3.0/go.mod h1:zFmK7XCadkQkj6TtorcaGlCW1hT1fIilQDwofLpJ20k=
 filippo.io/age v1.2.1 h1:X0TZjehAZylOIj4DubWYU1vWQxv9bJpo+Uu2/LGhi1o=
 filippo.io/age v1.2.1/go.mod h1:JL9ew2lTN+Pyft4RiNGguFfOpewKwSHm5ayKD/A4004=
-filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
 github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
 github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
@@ -12,7 +10,6 @@ github.com/google/jsonschema-go v0.4.3 h1:/DBOLZTfDow7pe2GmaJNhltueGTtDKICi8V8p+
 github.com/google/jsonschema-go v0.4.3/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/modelcontextprotocol/go-sdk v1.7.0 h1:yqjY2dsbKAC0LSuWZVBMrHgiG8ukXv6NRo0JiALay44=
 github.com/modelcontextprotocol/go-sdk v1.7.0/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts=
-github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99yedzYV+kq4uf4=
 github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
 github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
 github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
@@ -21,15 +18,12 @@ github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zI
 github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 golang.org/x/crypto v0.45.0 h1:jMBrvKuj23MTlT0bQEOBcAE0mjg8mK9RXFhRH6nyF3Q=
 golang.org/x/crypto v0.45.0/go.mod h1:XTGrrkGJve7CYK7J8PEww4aY7gM3qMCElcJQ8n8JdX4=
-golang.org/x/net v0.47.0/go.mod h1:/jNxtkgq5yWUGYkaZGqo27cfGZ1c5Nen03aYrrKpVRU=
 golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
 golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
 golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
 golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
 golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
-golang.org/x/term v0.37.0/go.mod h1:5pB4lxRNYYVZuTLmy8oR2BH8dflOR+IbTYFD8fi3254=
-golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
diff --git a/internal/store/lock_other.go b/internal/store/lock_other.go
new file mode 100644
index 0000000..c92fd30
--- /dev/null
+++ b/internal/store/lock_other.go
@@ -0,0 +1,25 @@
+//go:build !unix
+
+package store
+
+import "os"
+
+// fileLock is a best-effort lock on platforms without flock. Writers are
+// serialized only within one process; concurrent writers from different
+// processes are not protected, so run a single writer on these platforms.
+type fileLock struct {
+	f *os.File
+}
+
+func lockFile(path string) (*fileLock, error) {
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		return nil, err
+	}
+	return &fileLock{f: f}, nil
+}
+
+// Unlock closes the descriptor.
+func (l *fileLock) Unlock() {
+	_ = l.f.Close()
+}
diff --git a/internal/store/lock_unix.go b/internal/store/lock_unix.go
new file mode 100644
index 0000000..1c020f4
--- /dev/null
+++ b/internal/store/lock_unix.go
@@ -0,0 +1,36 @@
+//go:build unix
+
+package store
+
+import (
+	"os"
+
+	"golang.org/x/sys/unix"
+)
+
+// fileLock serializes writers across processes that share a store directory
+// (the MCP server and the CLI, for example). Reads do not take it: the data
+// file is replaced by rename, so a reader always sees a complete blob.
+type fileLock struct {
+	f *os.File
+}
+
+// lockFile opens (creating if needed) path and takes an exclusive advisory
+// lock, blocking until it is available.
+func lockFile(path string) (*fileLock, error) {
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		return nil, err
+	}
+	if err := unix.Flock(int(f.Fd()), unix.LOCK_EX); err != nil {
+		_ = f.Close()
+		return nil, err
+	}
+	return &fileLock{f: f}, nil
+}
+
+// Unlock releases the lock and closes the descriptor.
+func (l *fileLock) Unlock() {
+	_ = unix.Flock(int(l.f.Fd()), unix.LOCK_UN)
+	_ = l.f.Close()
+}
diff --git a/internal/store/store.go b/internal/store/store.go
index 194a8cf..8cfab8f 100644
--- a/internal/store/store.go
+++ b/internal/store/store.go
@@ -42,12 +42,32 @@ func New(dir string) (*Store, error) {
 		return nil, fmt.Errorf("mkdir %s: %w", dir, err)
 	}
 	s := &Store{dir: dir}
+	// Two processes may initialize the same directory at once (for example an
+	// MCP server and an interactive `keysmith set`). Serialize key creation so
+	// they cannot write two different identities over each other.
+	unlock, err := s.lock()
+	if err != nil {
+		return nil, err
+	}
+	defer unlock()
 	if err := s.ensureKey(); err != nil {
 		return nil, err
 	}
 	return s, nil
 }
 
+// lockPath is the writer lock file next to the encrypted store.
+func (s *Store) lockPath() string { return filepath.Join(s.dir, "store.lock") }
+
+// lock takes the exclusive writer lock. The returned function releases it.
+func (s *Store) lock() (func(), error) {
+	l, err := lockFile(s.lockPath())
+	if err != nil {
+		return nil, fmt.Errorf("lock store: %w", err)
+	}
+	return l.Unlock, nil
+}
+
 // KeyPath returns the path to the secret key file.
 func (s *Store) KeyPath() string { return filepath.Join(s.dir, "key.txt") }
 
@@ -175,13 +195,25 @@ func (s *Store) writeEncrypted(m map[string]string) error {
 	if err := aw.Close(); err != nil {
 		return fmt.Errorf("armor close: %w", err)
 	}
-	// Atomic write: temp file in same dir, then rename.
-	tmp := s.DataPath() + ".tmp"
-	if err := os.WriteFile(tmp, buf.Bytes(), 0o600); err != nil {
+	// Atomic write: temp file in the same directory, then rename. The name is
+	// unique per write so two writers can never share (and truncate) a temp
+	// file, even if one of them ignores the lock.
+	f, err := os.CreateTemp(s.dir, "secrets.enc.tmp-*")
+	if err != nil {
+		return fmt.Errorf("write temp: %w", err)
+	}
+	tmp := f.Name()
+	if _, err := f.Write(buf.Bytes()); err != nil {
+		_ = f.Close()
+		_ = os.Remove(tmp)
+		return fmt.Errorf("write temp: %w", err)
+	}
+	if err := f.Close(); err != nil {
+		_ = os.Remove(tmp)
 		return fmt.Errorf("write temp: %w", err)
 	}
 	if err := os.Rename(tmp, s.DataPath()); err != nil {
-		os.Remove(tmp)
+		_ = os.Remove(tmp)
 		return fmt.Errorf("rename temp: %w", err)
 	}
 	return nil
@@ -192,6 +224,16 @@ func (s *Store) Set(key, value string) error {
 	if key == "" || strings.ContainsAny(key, " \t\n=") {
 		return fmt.Errorf("invalid key %q", key)
 	}
+	unlock, err := s.lock()
+	if err != nil {
+		return err
+	}
+	defer unlock()
+	return s.setLocked(key, value)
+}
+
+// setLocked performs Set's read-modify-write. The caller must hold the lock.
+func (s *Store) setLocked(key, value string) error {
 	m, err := s.readDecrypted()
 	if err != nil {
 		return err
@@ -230,6 +272,11 @@ func (s *Store) List() (map[string]string, error) {
 
 // Delete removes a key. Returns ErrNotFound if absent.
 func (s *Store) Delete(key string) error {
+	unlock, err := s.lock()
+	if err != nil {
+		return err
+	}
+	defer unlock()
 	m, err := s.readDecrypted()
 	if err != nil {
 		return err
@@ -252,10 +299,15 @@ func (s *Store) Rotate(key string, length int) (string, error) {
 	if err != nil {
 		return "", err
 	}
-	if err := s.Set(key, val); err != nil {
+	unlock, err := s.lock()
+	if err != nil {
+		return "", err
+	}
+	defer unlock()
+	if err := s.setLocked(key, val); err != nil {
 		return "", err
 	}
-	return mask.Mask(val), nil
+	return mask.MaskKey(key, val), nil
 }
 
 // CreatedAt returns the file mtime of the data file (approximate store age).
@@ -283,13 +335,26 @@ func (s *Store) SortedKeys() ([]string, error) {
 
 func randomSecret(n int) (string, error) {
 	const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
-	b := make([]byte, n)
-	rb := make([]byte, n)
-	if _, err := rand.Read(rb); err != nil {
-		return "", err
-	}
-	for i := range b {
-		b[i] = alphabet[int(rb[i])%len(alphabet)]
+	// Rejection sampling: 256 is not a multiple of len(alphabet), so taking a
+	// modulus of every byte would bias the first 8 letters. Bytes above the
+	// largest multiple are discarded instead.
+	const limit = 256 - 256%len(alphabet)
+	out := make([]byte, n)
+	buf := make([]byte, n)
+	for i := 0; i < n; {
+		if _, err := rand.Read(buf); err != nil {
+			return "", err
+		}
+		for _, b := range buf {
+			if int(b) >= limit {
+				continue
+			}
+			out[i] = alphabet[int(b)%len(alphabet)]
+			i++
+			if i == n {
+				break
+			}
+		}
 	}
-	return string(b), nil
+	return string(out), nil
 }
diff --git a/internal/store/store_test.go b/internal/store/store_test.go
index 85c1c15..fba002c 100644
--- a/internal/store/store_test.go
+++ b/internal/store/store_test.go
@@ -2,9 +2,11 @@ package store
 
 import (
 	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
 	"testing"
 )
 
@@ -100,6 +102,53 @@ func TestListMasksSensitiveKeyNames(t *testing.T) {
 	}
 }
 
+func TestConcurrentSetKeepsEveryKey(t *testing.T) {
+	s := newTestStore(t)
+	const n = 16
+	var wg sync.WaitGroup
+	errs := make(chan error, n)
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			if err := s.Set(fmt.Sprintf("K%02d", i), fmt.Sprintf("value-%02d-abcdefghij", i)); err != nil {
+				errs <- err
+			}
+		}(i)
+	}
+	wg.Wait()
+	close(errs)
+	for err := range errs {
+		t.Fatalf("Set: %v", err)
+	}
+	keys, err := s.SortedKeys()
+	if err != nil {
+		t.Fatalf("SortedKeys: %v", err)
+	}
+	if len(keys) != n {
+		t.Fatalf("stored %d keys, want %d — a write was lost", len(keys), n)
+	}
+}
+
+func TestRandomSecretUsesTheWholeAlphabet(t *testing.T) {
+	seen := map[rune]bool{}
+	for i := 0; i < 40; i++ {
+		v, err := randomSecret(64)
+		if err != nil {
+			t.Fatalf("randomSecret: %v", err)
+		}
+		if len(v) != 64 {
+			t.Fatalf("length = %d, want 64", len(v))
+		}
+		for _, r := range v {
+			seen[r] = true
+		}
+	}
+	if len(seen) != 62 {
+		t.Errorf("saw %d distinct characters, want 62", len(seen))
+	}
+}
+
 func TestDelete(t *testing.T) {
 	s := newTestStore(t)
 	if err := s.Set("TMP", "secret1"); err != nil {

From 51269b0ba2d351921dd37041f21baa05cb0eae7f Mon Sep 17 00:00:00 2001
From: sscodeai <sscodeai@users.noreply.github.com>
Date: Wed, 21 Oct 2026 21:24:37 +0900
Subject: [PATCH 4/6] fix(redeem): refuse target paths that normalise outside
 the binding

--allow-path matched the parsed path with a string prefix, but url.Parse
keeps dot segments, so a token bound to /services/ was redeemed for
https://hooks.slack.com/services/../../admin. Encoded separators (%2f,
%5c) and the '..;' path-parameter form were accepted the same way.

ParseTarget now refuses '.'/'..' segments, encoded slashes, backslashes and
dot segments hidden behind path parameters. '.well-known' still parses.
---
 docs/REDEEM.md                 |  5 ++++-
 internal/redeem/policy.go      | 33 +++++++++++++++++++++++++++++++++
 internal/redeem/policy_test.go | 19 ++++++++++++++-----
 3 files changed, 51 insertions(+), 6 deletions(-)

diff --git a/docs/REDEEM.md b/docs/REDEEM.md
index b2a20df..72ce394 100644
--- a/docs/REDEEM.md
+++ b/docs/REDEEM.md
@@ -101,7 +101,9 @@ Rules:
 `keysmith run --target URL` declares the destination. The URL must be `https`, or
 `http` only for a loopback host (`localhost`, `127.0.0.0/8`, `::1`); a query
 string or fragment is rejected rather than ignored, because that is where a
-hidden destination would sit.
+hidden destination would sit. The path is also rejected when it contains `.` or
+`..` segments, encoded slashes (`%2f`) or backslashes, so a path prefix cannot
+be escaped by a form the destination normalises after the check.
 
 - A name with a binding **requires** `--target`, and every binding must pass.
 - A name without a binding is still redeemed anywhere, but `run` prints a warning
@@ -124,6 +126,7 @@ fallback that forwards a literal token, and no fallback that sends the value.
 | A bound token used without `--target` | refuse |
 | Target host or path not allowed by the binding | refuse |
 | Target that is not https (except loopback http), or that carries a query string | refuse |
+| Target path containing `.`/`..` segments, an encoded slash or a backslash | refuse |
 | A bound header name missing from the command text | refuse |
 | Audit record cannot be written | refuse — after the binding check, before the child |
 | Any resolution error in one `--env` while another resolved fine | refuse — nothing is exported and nothing runs |
diff --git a/internal/redeem/policy.go b/internal/redeem/policy.go
index eb52dcd..8835906 100644
--- a/internal/redeem/policy.go
+++ b/internal/redeem/policy.go
@@ -73,6 +73,9 @@ func ParseTarget(raw string) (*Target, error) {
 	if u.RawQuery != "" || u.Fragment != "" {
 		return nil, errors.New("target must not carry a query string or fragment")
 	}
+	if err := checkTargetPath(u); err != nil {
+		return nil, err
+	}
 	path := u.Path
 	if path == "" {
 		path = "/"
@@ -96,6 +99,36 @@ func isLoopback(host string) bool {
 	return false
 }
 
+// checkTargetPath refuses a path that the prefix check would read differently
+// from the server that receives it. url.Parse leaves ".." segments in Path, so
+// a binding on /services/ would otherwise accept /services/../../admin, which
+// the destination resolves outside the allowed prefix.
+func checkTargetPath(u *url.URL) error {
+	escaped := u.EscapedPath()
+	lower := strings.ToLower(escaped)
+	if strings.Contains(lower, "%2f") || strings.Contains(lower, "%5c") {
+		return errors.New("target path must not contain encoded slashes")
+	}
+	decoded, err := url.PathUnescape(escaped)
+	if err != nil {
+		return errors.New("target path is not valid percent-encoding")
+	}
+	if strings.Contains(decoded, `\`) {
+		return errors.New("target path must not contain a backslash")
+	}
+	for _, seg := range strings.Split(decoded, "/") {
+		// Strip path parameters ("..;x") before comparing: some servers treat
+		// the semicolon form as the same traversal.
+		if i := strings.Index(seg, ";"); i >= 0 {
+			seg = seg[:i]
+		}
+		if seg == "." || seg == ".." {
+			return errors.New("target path must not contain '.' or '..' segments")
+		}
+	}
+	return nil
+}
+
 // hostAllowed reports whether host matches one of the allowed entries. An entry
 // beginning with "." matches that domain and its subdomains, and never a
 // look-alike such as "evil-example.test".
diff --git a/internal/redeem/policy_test.go b/internal/redeem/policy_test.go
index e18c639..b7d9eaa 100644
--- a/internal/redeem/policy_test.go
+++ b/internal/redeem/policy_test.go
@@ -9,11 +9,12 @@ import (
 
 func TestParseTargetAcceptsExpectedURLs(t *testing.T) {
 	ok := map[string]Target{
-		"https://api.example.test/v1/me": {Host: "api.example.test", Path: "/v1/me", Secure: true},
-		"https://API.Example.Test":       {Host: "api.example.test", Path: "/", Secure: true},
-		"http://127.0.0.1:8080/v1/x":     {Host: "127.0.0.1", Port: "8080", Path: "/v1/x"},
-		"http://localhost:11434/api":     {Host: "localhost", Port: "11434", Path: "/api"},
-		"http://[::1]:9000/ping":         {Host: "::1", Port: "9000", Path: "/ping"},
+		"https://api.example.test/v1/me":                            {Host: "api.example.test", Path: "/v1/me", Secure: true},
+		"https://API.Example.Test":                                  {Host: "api.example.test", Path: "/", Secure: true},
+		"http://127.0.0.1:8080/v1/x":                                {Host: "127.0.0.1", Port: "8080", Path: "/v1/x"},
+		"http://localhost:11434/api":                                {Host: "localhost", Port: "11434", Path: "/api"},
+		"http://[::1]:9000/ping":                                    {Host: "::1", Port: "9000", Path: "/ping"},
+		"https://api.example.test/.well-known/openid-configuration": {Host: "api.example.test", Path: "/.well-known/openid-configuration", Secure: true},
 	}
 	for raw, want := range ok {
 		got, err := ParseTarget(raw)
@@ -34,6 +35,14 @@ func TestParseTargetRefusesUnsafeURLs(t *testing.T) {
 		"http://api.example.test/x",       // plain http to a remote host
 		"https://api.example.test/v1?k=v", // query string (a place to hide a destination)
 		"https://api.example.test/v1#frag",
+		// A path prefix on /services/ must not be escapable by segments the
+		// destination will resolve elsewhere.
+		"https://hooks.slack.com/services/../admin",
+		"https://hooks.slack.com/services/..;/admin",
+		"https://hooks.slack.com/services/%2e%2e/admin",
+		"https://hooks.slack.com/services%2f..%2fadmin",
+		"https://hooks.slack.com/a/./b",
+		"https://hooks.slack.com/a%5cb",
 	}
 	for _, raw := range bad {
 		if _, err := ParseTarget(raw); err == nil {

From 6a7f0e7df98a0566f17570073a43b6676f0dac9a Mon Sep 17 00:00:00 2001
From: sscodeai <sscodeai@users.noreply.github.com>
Date: Wed, 21 Oct 2026 21:26:52 +0900
Subject: [PATCH 5/6] fix(scan): stop printing the leaked value in the report

`keysmith scan` printed the matched line verbatim, so the secret it was
warning about landed in the terminal, the CI log, and any issue the report
was pasted into.

Lines are now redacted: the key name and diff marker stay, the value is
masked with mask.Redact, which always masks instead of consulting the
heuristics. The test that asserted the value appears now asserts it does not.
---
 internal/leakscan/leakscan.go      | 18 ++++++++++++++++--
 internal/leakscan/leakscan_test.go | 16 +++++++++++++++-
 internal/mask/mask.go              | 10 ++++++++++
 internal/mask/mask_test.go         |  8 ++++++++
 4 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/internal/leakscan/leakscan.go b/internal/leakscan/leakscan.go
index d1a3145..63c3c9d 100644
--- a/internal/leakscan/leakscan.go
+++ b/internal/leakscan/leakscan.go
@@ -76,7 +76,7 @@ func ScanGitHistory(repoDir string, st *store.Store, autoRotate bool) ([]ScanRes
 		rotated := false
 		for val, key := range values {
 			if strings.Contains(trimmed, val) {
-				res := ScanResult{Key: key, Pattern: "exact-value", Location: line, Rotated: rotated}
+				res := ScanResult{Key: key, Pattern: "exact-value", Location: redactLine(line), Rotated: rotated}
 				if autoRotate && !rotated {
 					if _, err := st.Rotate(key, 32); err == nil {
 						res.Rotated = true
@@ -90,7 +90,7 @@ func ScanGitHistory(repoDir string, st *store.Store, autoRotate bool) ([]ScanRes
 
 		// 2) Pattern match (known secret shapes).
 		if isSecretPattern(trimmed) {
-			results = append(results, ScanResult{Pattern: "pattern", Location: line})
+			results = append(results, ScanResult{Pattern: "pattern", Location: redactLine(line)})
 		}
 	}
 
@@ -139,6 +139,20 @@ func isSecretPattern(line string) bool {
 	return false
 }
 
+// redactLine keeps the shape of a matched line (key name, diff marker) but
+// masks the value. A scan report is read in terminals, CI logs and issues, so
+// printing the leaked secret there would repeat the leak.
+func redactLine(line string) string {
+	trimmed := strings.TrimSpace(line)
+	if i := strings.IndexAny(trimmed, "=:"); i >= 0 {
+		rest := strings.TrimSpace(trimmed[i+1:])
+		if rest != "" {
+			return trimmed[:i+1] + " " + mask.Redact(rest)
+		}
+	}
+	return mask.Redact(trimmed)
+}
+
 func mustGet(st *store.Store, key string) string {
 	v, err := st.Get(key)
 	if err != nil {
diff --git a/internal/leakscan/leakscan_test.go b/internal/leakscan/leakscan_test.go
index 628a57c..0cda964 100644
--- a/internal/leakscan/leakscan_test.go
+++ b/internal/leakscan/leakscan_test.go
@@ -51,11 +51,25 @@ func TestScanDetectsLeakedSecret(t *testing.T) {
 	found := false
 	for _, r := range results {
 		if strings.Contains(r.Location, "sk-REALLEAKED") {
+			t.Errorf("report repeats the leaked value: %q", r.Location)
+		}
+		if strings.Contains(r.Location, "API_KEY") {
 			found = true
 		}
 	}
 	if !found {
-		t.Errorf("did not find the leaked value in results: %+v", results)
+		t.Errorf("did not report the leaking line: %+v", results)
+	}
+}
+
+func TestFormatDoesNotPrintTheValue(t *testing.T) {
+	results := []ScanResult{{Pattern: "pattern", Location: redactLine("+API_KEY=sk-REAL1234567890")}}
+	out := Format(results)
+	if strings.Contains(out, "REAL1234567890") {
+		t.Errorf("Format repeats the leaked value: %q", out)
+	}
+	if !strings.Contains(out, "API_KEY") {
+		t.Errorf("Format lost the key context: %q", out)
 	}
 }
 
diff --git a/internal/mask/mask.go b/internal/mask/mask.go
index ba07cde..fe1c71b 100644
--- a/internal/mask/mask.go
+++ b/internal/mask/mask.go
@@ -139,6 +139,16 @@ func MaskKey(key, value string) string {
 	if !KeyNameIsSensitive(key) {
 		return Mask(value)
 	}
+	return Redact(value)
+}
+
+// Redact always masks a value, regardless of heuristics. Use it where the
+// caller already knows the text is sensitive — a line matched by the leak
+// scanner, for example — because the value heuristics can miss a passphrase.
+func Redact(value string) string {
+	if value == "" {
+		return ""
+	}
 	if urlSchemeRe.MatchString(value) {
 		return MaskURL(value)
 	}
diff --git a/internal/mask/mask_test.go b/internal/mask/mask_test.go
index 145825d..6b2ad43 100644
--- a/internal/mask/mask_test.go
+++ b/internal/mask/mask_test.go
@@ -92,6 +92,14 @@ func TestMaskKeyUsesTheKeyName(t *testing.T) {
 	}
 }
 
+func TestRedactAlwaysMasks(t *testing.T) {
+	for _, v := range []string{"correcthorsebatterystaple", "hunter2", "postgres://u:pass@h/db"} {
+		if got := Redact(v); got == v {
+			t.Errorf("Redact(%q) returned the original value", v)
+		}
+	}
+}
+
 func TestMaskURL(t *testing.T) {
 	cases := []struct {
 		val  string

From 48fcaff3bfccf28f6358a925c319f91eb136d3b0 Mon Sep 17 00:00:00 2001
From: sscodeai <sscodeai@users.noreply.github.com>
Date: Wed, 21 Oct 2026 21:26:57 +0900
Subject: [PATCH 6/6] fix(http): require a bearer token off loopback

The HTTP/SSE and Streamable transports had no authentication at all, while
the tools include delete and rotate. Binding `-http :8080` (every interface),
as the README showed, exposed them to the LAN.

A non-loopback bind now requires `-http-token`; when set, every request must
carry `Authorization: Bearer <token>` (constant-time comparison) or gets 401.
The README examples bind 127.0.0.1 and document the flag.
---
 CHANGELOG.md              | 18 +++++++++++++
 README.ja.md              | 10 +++++--
 README.md                 | 12 +++++++--
 cmd/keysmith/main.go      | 57 +++++++++++++++++++++++++++++++++++++--
 cmd/keysmith/main_test.go | 57 +++++++++++++++++++++++++++++++++++++++
 5 files changed, 148 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ffe7c59..2ed5f0b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,24 @@ All notable changes to this project are documented here. The format follows
   merging now have unit tests; CI runs `gofmt`, `go vet`, `go test`,
   `e2e_test.py`, `verify_redeem.py` and the doc-parity check on every push.
 
+### Fixed
+- Masking now uses the key name: `DB_PASSWORD=correcthorsebatterystaple` is
+  masked by `get`, `list`, the MCP `get` tool and the MCP resource, instead of
+  being returned verbatim. `KeyNameIsSensitive` had no callers before.
+- `put` only accepts a `value_file` inside `<store>/inbox`; an agent-supplied
+  path outside it was an arbitrary-file read and unlink. `keysmith inbox`
+  prints the directory, and symlink escapes are refused.
+- Store writes take an exclusive lock (`<store>/store.lock`), so the MCP server
+  and the CLI can no longer lose each other's updates (20 concurrent `set`
+  calls used to store 12 keys).
+- `--target` paths containing `.`/`..` segments, encoded slashes or
+  backslashes are refused, closing a `--allow-path` prefix escape such as
+  `/services/../../admin`.
+- An HTTP listener on a non-loopback address requires `-http-token`; requests
+  without a matching `Authorization: Bearer` get 401.
+- `keysmith scan` no longer prints the leaked value itself in its report.
+- `randomSecret` uses rejection sampling instead of a biased modulo.
+
 ## 0.4.0 — 2026-09-14
 
 ### Added
diff --git a/README.ja.md b/README.ja.md
index 47b21ad..800e1e2 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -47,17 +47,23 @@ KEYSMITH_STORE=/path/to/store keysmith
 リモートエージェント向けに HTTP/SSE で提供します。
 
 ```sh
-keysmith -store ~/.keysmith -http :8080
+keysmith -store ~/.keysmith -http 127.0.0.1:8080
 # endpoint: http://localhost:8080/sse
 ```
 
 MCP 2025 Streamable HTTP で提供します。単一 POST エンドポイントのステートレス方式です。
 
 ```sh
-keysmith -store ~/.keysmith -http :8080 -streamable
+keysmith -store ~/.keysmith -http 127.0.0.1:8080 -streamable
 # endpoint: http://localhost:8080/mcp
 ```
 
+HTTP リスナー自体には認証がないため、keysmith は `-http-token` なしで非ループバックアドレスにバインドしません。トークンを指定した場合、すべてのリクエストに `Authorization: Bearer <token>` が必要です。
+
+```sh
+keysmith -store ~/.keysmith -http 192.168.1.10:8080 -http-token "$(openssl rand -hex 16)" -streamable
+```
+
 HashiCorp Vault をバックエンドとして使用します。短 TTL の動的シークレットに対応します。
 
 ```sh
diff --git a/README.md b/README.md
index 92bfa32..1413e13 100644
--- a/README.md
+++ b/README.md
@@ -58,17 +58,25 @@ KEYSMITH_STORE=/path/to/store keysmith
 Serve over HTTP/SSE for remote agents:
 
 ```sh
-keysmith -store ~/.keysmith -http :8080
+keysmith -store ~/.keysmith -http 127.0.0.1:8080
 # endpoint: http://localhost:8080/sse
 ```
 
 Serve MCP 2025 Streamable HTTP (single POST endpoint, stateless):
 
 ```sh
-keysmith -store ~/.keysmith -http :8080 -streamable
+keysmith -store ~/.keysmith -http 127.0.0.1:8080 -streamable
 # endpoint: http://localhost:8080/mcp
 ```
 
+An HTTP listener has no authentication of its own, so keysmith refuses to bind
+a non-loopback address unless `-http-token` is set. With a token, every request
+must carry `Authorization: Bearer <token>`:
+
+```sh
+keysmith -store ~/.keysmith -http 192.168.1.10:8080 -http-token "$(openssl rand -hex 16)" -streamable
+```
+
 Use HashiCorp Vault as the backend (dynamic short-TTL secrets):
 
 ```sh
diff --git a/cmd/keysmith/main.go b/cmd/keysmith/main.go
index 93373e0..c063e80 100644
--- a/cmd/keysmith/main.go
+++ b/cmd/keysmith/main.go
@@ -20,11 +20,13 @@ package main
 
 import (
 	"context"
+	"crypto/subtle"
 	"errors"
 	"flag"
 	"fmt"
 	"io"
 	"log"
+	"net"
 	"net/http"
 	"os"
 	"os/exec"
@@ -46,6 +48,7 @@ var version = "0.5.0"
 func main() {
 	storeDir := flag.String("store", defaultStoreDir(), "directory holding age-encrypted secrets (key.txt + secrets.enc)")
 	httpAddr := flag.String("http", "", "serve MCP over HTTP/SSE on this address (e.g. :8080) instead of stdio")
+	httpToken := flag.String("http-token", "", "require this bearer token on every HTTP request (required when -http binds a non-loopback address)")
 	streamable := flag.Bool("streamable", false, "with -http: use Streamable HTTP (MCP 2025) instead of SSE")
 	vaultAddr := flag.String("vault", "", "HashiCorp Vault address (e.g. http://127.0.0.1:8200) — use Vault as backend")
 	showVer := flag.Bool("version", false, "print version and exit")
@@ -60,7 +63,7 @@ func main() {
 
 	// No subcommand → MCP server mode (stdio or HTTP/SSE).
 	if len(args) == 0 {
-		runMCPServer(*storeDir, *httpAddr, *vaultAddr, *streamable)
+		runMCPServer(*storeDir, *httpAddr, *vaultAddr, *httpToken, *streamable)
 		return
 	}
 
@@ -70,7 +73,7 @@ func main() {
 	}
 }
 
-func runMCPServer(storeDir, httpAddr, vaultAddr string, streamable bool) {
+func runMCPServer(storeDir, httpAddr, vaultAddr, httpToken string, streamable bool) {
 	st, err := store.New(storeDir)
 	if err != nil {
 		log.Fatalf("store init: %v", err)
@@ -84,6 +87,9 @@ func runMCPServer(storeDir, httpAddr, vaultAddr string, streamable bool) {
 	// Default = SSE transport (GET /sse + POST endpoint).
 	// With -streamable = MCP 2025 Streamable HTTP (single POST endpoint, JSON).
 	if httpAddr != "" {
+		if err := checkHTTPBinding(httpAddr, httpToken); err != nil {
+			log.Fatalf("http: %v", err)
+		}
 		var handler http.Handler
 		if streamable {
 			handler = sdk.NewStreamableHTTPHandler(func(*http.Request) *sdk.Server { return srv.Handler() },
@@ -95,6 +101,10 @@ func runMCPServer(storeDir, httpAddr, vaultAddr string, streamable bool) {
 			log.Printf("keysmith serving MCP over SSE on %s", httpAddr)
 			log.Printf("  endpoint: http://localhost%s/sse", httpAddr)
 		}
+		if httpToken != "" {
+			handler = requireBearer(handler, httpToken)
+			log.Printf("  authentication: Authorization: Bearer <token> is required")
+		}
 		if err := http.ListenAndServe(httpAddr, handler); err != nil {
 			log.Fatalf("http server: %v", err)
 		}
@@ -398,6 +408,8 @@ USAGE:
 
 FLAGS:
   -store DIR   store directory (default ~/.keysmith or $KEYSMITH_STORE)
+  -http ADDR   serve MCP over HTTP (SSE) instead of stdio
+  -http-token  require Authorization: Bearer <token> on every HTTP request
 
 SECURITY:
   - set reads the value from stdin — never pass secrets as arguments
@@ -408,6 +420,8 @@ SECURITY:
   - redemption fails closed: any error aborts the command, with no fallback
   - --allow-host/--allow-path/--allow-header bind a token to a destination;
     run --target must match, or the command is not started
+  - a non-loopback -http bind requires -http-token; unauthenticated requests
+    are answered with 401 instead of reaching the store
   - secrets are stored age-encrypted at rest (key.txt 0600, secrets.enc armor)
 `
 }
@@ -717,6 +731,45 @@ func mergeEnv(base, overrides []string) []string {
 	return append(out, overrides...)
 }
 
+// checkHTTPBinding refuses to expose the MCP server on a non-loopback address
+// without a bearer token. There is no other authentication and the tools are
+// destructive (delete, rotate) as well as data-bearing, so an unauthenticated
+// LAN listener is not a safe default.
+func checkHTTPBinding(addr, token string) error {
+	if isLoopbackListen(addr) || token != "" {
+		return nil
+	}
+	return fmt.Errorf("refusing to serve MCP on non-loopback %q without -http-token: "+
+		"bind 127.0.0.1, or pass -http-token and send Authorization: Bearer <token>", addr)
+}
+
+// isLoopbackListen reports whether addr binds only a loopback interface. An
+// empty host (":8080") binds every interface and is not loopback.
+func isLoopbackListen(addr string) bool {
+	host, _, err := net.SplitHostPort(addr)
+	if err != nil {
+		return false
+	}
+	if strings.EqualFold(host, "localhost") {
+		return true
+	}
+	ip := net.ParseIP(host)
+	return ip != nil && ip.IsLoopback()
+}
+
+// requireBearer wraps an MCP handler with a constant-time bearer check.
+func requireBearer(next http.Handler, token string) http.Handler {
+	want := []byte("Bearer " + token)
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if subtle.ConstantTimeCompare([]byte(r.Header.Get("Authorization")), want) != 1 {
+			w.Header().Set("WWW-Authenticate", `Bearer realm="keysmith"`)
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
 func validEnvName(s string) bool {
 	if s == "" {
 		return false
diff --git a/cmd/keysmith/main_test.go b/cmd/keysmith/main_test.go
index 9035155..10b5876 100644
--- a/cmd/keysmith/main_test.go
+++ b/cmd/keysmith/main_test.go
@@ -1,12 +1,69 @@
 package main
 
 import (
+	"net/http"
+	"net/http/httptest"
 	"strings"
 	"testing"
 )
 
 const token = "[[keysmith:v1:DEMO_KEY:8f3a2b1c]]"
 
+func TestCheckHTTPBindingRequiresAuthOffLoopback(t *testing.T) {
+	cases := []struct {
+		addr, token string
+		wantErr     bool
+	}{
+		{"127.0.0.1:8080", "", false},
+		{"[::1]:8080", "", false},
+		{"localhost:8080", "", false},
+		{":8080", "", true},
+		{"0.0.0.0:8080", "", true},
+		{"192.168.1.10:8080", "", true},
+		{"192.168.1.10:8080", "s3cret", false},
+	}
+	for _, c := range cases {
+		err := checkHTTPBinding(c.addr, c.token)
+		if (err != nil) != c.wantErr {
+			t.Errorf("checkHTTPBinding(%q, %q) = %v, wantErr %v", c.addr, c.token, err, c.wantErr)
+		}
+	}
+}
+
+func TestRequireBearer(t *testing.T) {
+	ok := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNoContent)
+	})
+	srv := httptest.NewServer(requireBearer(ok, "s3cret"))
+	defer srv.Close()
+
+	do := func(header string) int {
+		req, err := http.NewRequest(http.MethodGet, srv.URL, nil)
+		if err != nil {
+			t.Fatalf("request: %v", err)
+		}
+		if header != "" {
+			req.Header.Set("Authorization", header)
+		}
+		resp, err := http.DefaultClient.Do(req)
+		if err != nil {
+			t.Fatalf("do: %v", err)
+		}
+		defer resp.Body.Close()
+		return resp.StatusCode
+	}
+
+	if got := do(""); got != http.StatusUnauthorized {
+		t.Errorf("no header: status %d, want 401", got)
+	}
+	if got := do("Bearer wrong"); got != http.StatusUnauthorized {
+		t.Errorf("wrong token: status %d, want 401", got)
+	}
+	if got := do("Bearer s3cret"); got != http.StatusNoContent {
+		t.Errorf("correct token: status %d, want 204", got)
+	}
+}
+
 func TestParseRunArgsSplitsOptionsAndCommand(t *testing.T) {
 	opts, err := parseRunArgs(
 		[]string{"--session", "8f3a2b1c", "--target", "https://api.example.test/v1/me",