From da3bf25c434e0a96944d2646ee2192a12593f277 Mon Sep 17 00:00:00 2001
From: Nathan Broadbent <git@ndbroadbent.com>
Date: Mon, 26 Oct 2026 12:56:24 +1300
Subject: [PATCH 1/2] fix(cli): take turns with the security key across
 commands

Two rack-gateway commands using the security key at once (two AI agents each running a command) both failed:
the key answers one at a time, and libfido2 reported "rx error" or "unsupported option" to the other, after the
person had entered both PINs and touched the key. The person also couldn't tell which touch was for which command.

Every command now holds a lock while it uses the key: from its PIN dialog to its touch, and around the PIN check
in the script review dialog. The lock file is in the user's cache directory, which every command shares (an agent
session can have a TMPDIR of its own), and the operating system releases it when a command exits. A command that
has to wait says so. The config file lock moves onto the same filelock package.
---
 .../docs/user-guide/cli/mfa-verification.mdx  |  4 ++
 internal/cli/config_lock.go                   | 16 ++----
 internal/cli/config_lock_unix.go              | 17 -------
 internal/cli/config_lock_windows.go           | 19 -------
 internal/cli/filelock/filelock.go             | 37 ++++++++++++++
 internal/cli/filelock/filelock_test.go        | 39 +++++++++++++++
 internal/cli/filelock/filelock_unix.go        | 27 ++++++++++
 internal/cli/filelock/filelock_windows.go     | 33 ++++++++++++
 internal/cli/webauthn/key_lock.go             | 37 ++++++++++++++
 internal/cli/webauthn/key_lock_test.go        | 50 +++++++++++++++++++
 internal/cli/webauthn/pin_check.go            | 32 +++++++-----
 internal/cli/webauthn/webauthn.go             | 17 ++++++-
 12 files changed, 265 insertions(+), 63 deletions(-)
 delete mode 100644 internal/cli/config_lock_unix.go
 delete mode 100644 internal/cli/config_lock_windows.go
 create mode 100644 internal/cli/filelock/filelock.go
 create mode 100644 internal/cli/filelock/filelock_test.go
 create mode 100644 internal/cli/filelock/filelock_unix.go
 create mode 100644 internal/cli/filelock/filelock_windows.go
 create mode 100644 internal/cli/webauthn/key_lock.go
 create mode 100644 internal/cli/webauthn/key_lock_test.go

diff --git a/docs/src/content/docs/user-guide/cli/mfa-verification.mdx b/docs/src/content/docs/user-guide/cli/mfa-verification.mdx
index 538416cd..20ecadfd 100644
--- a/docs/src/content/docs/user-guide/cli/mfa-verification.mdx
+++ b/docs/src/content/docs/user-guide/cli/mfa-verification.mdx
@@ -51,6 +51,10 @@ The CLI supports multiple MFA methods:
     you don't miss one while the terminal is out of sight. On macOS, allow notifications for Script Editor if they
     don't appear. To turn them off, set `"touch_notifications": false` in `~/.config/rack-gateway/config.json`.
 
+    Commands take turns with the key. When two run at once (say, two AI agents each running a command), the second
+    prints `Waiting for another rack-gateway command to finish with the security key...` and asks for its PIN and
+    touch only once the first has its touch, so each prompt is for one command.
+
     Only security keys marked **CLI Compatible** in the web UI can be used from the CLI.
 
     <Aside type="note">
diff --git a/internal/cli/config_lock.go b/internal/cli/config_lock.go
index 6f8e0ae7..31880524 100644
--- a/internal/cli/config_lock.go
+++ b/internal/cli/config_lock.go
@@ -1,8 +1,9 @@
 package cli
 
 import (
-	"os"
 	"path/filepath"
+
+	"github.com/DocSpring/rack-gateway/internal/cli/filelock"
 )
 
 // updateConfig applies change to the latest config and saves it, holding the config lock throughout, so two
@@ -36,16 +37,5 @@ func lockConfig() (func(), error) {
 	if err := ensurePrivateDir(ConfigPath); err != nil {
 		return nil, err
 	}
-	file, err := os.OpenFile(filepath.Join(filepath.Clean(ConfigPath), "config.lock"), os.O_CREATE|os.O_RDWR, 0o600)
-	if err != nil {
-		return nil, err
-	}
-	if err := lockFile(file); err != nil {
-		_ = file.Close()
-		return nil, err
-	}
-	return func() {
-		_ = unlockFile(file)
-		_ = file.Close()
-	}, nil
+	return filelock.Lock(filepath.Join(filepath.Clean(ConfigPath), "config.lock"), nil)
 }
diff --git a/internal/cli/config_lock_unix.go b/internal/cli/config_lock_unix.go
deleted file mode 100644
index 5dd36bb2..00000000
--- a/internal/cli/config_lock_unix.go
+++ /dev/null
@@ -1,17 +0,0 @@
-//go:build !windows
-
-package cli
-
-import (
-	"os"
-
-	"golang.org/x/sys/unix"
-)
-
-func lockFile(file *os.File) error {
-	return unix.Flock(int(file.Fd()), unix.LOCK_EX)
-}
-
-func unlockFile(file *os.File) error {
-	return unix.Flock(int(file.Fd()), unix.LOCK_UN)
-}
diff --git a/internal/cli/config_lock_windows.go b/internal/cli/config_lock_windows.go
deleted file mode 100644
index 4be04cdb..00000000
--- a/internal/cli/config_lock_windows.go
+++ /dev/null
@@ -1,19 +0,0 @@
-//go:build windows
-
-package cli
-
-import (
-	"math"
-	"os"
-
-	"golang.org/x/sys/windows"
-)
-
-func lockFile(file *os.File) error {
-	return windows.LockFileEx(windows.Handle(file.Fd()), windows.LOCKFILE_EXCLUSIVE_LOCK, 0,
-		math.MaxUint32, math.MaxUint32, &windows.Overlapped{})
-}
-
-func unlockFile(file *os.File) error {
-	return windows.UnlockFileEx(windows.Handle(file.Fd()), 0, math.MaxUint32, math.MaxUint32, &windows.Overlapped{})
-}
diff --git a/internal/cli/filelock/filelock.go b/internal/cli/filelock/filelock.go
new file mode 100644
index 00000000..2ba2bb28
--- /dev/null
+++ b/internal/cli/filelock/filelock.go
@@ -0,0 +1,37 @@
+// Package filelock takes exclusive locks that several rack-gateway commands share: a lock file that one process
+// at a time holds. The operating system releases a lock when its process exits, so a command that crashes or is
+// killed never leaves one behind.
+package filelock
+
+import (
+	"os"
+	"path/filepath"
+)
+
+// Lock takes the exclusive lock on the file at path, creating it (and its directory, private to the user) when it
+// doesn't exist. When another process holds the lock, it calls waiting, then waits until it can take it. The
+// returned func releases the lock.
+func Lock(path string, waiting func()) (func(), error) {
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return nil, err
+	}
+	file, err := os.OpenFile(filepath.Clean(path), os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		return nil, err
+	}
+	locked, err := tryLockFile(file)
+	if err == nil && !locked {
+		if waiting != nil {
+			waiting()
+		}
+		err = lockFile(file)
+	}
+	if err != nil {
+		_ = file.Close()
+		return nil, err
+	}
+	return func() {
+		_ = unlockFile(file)
+		_ = file.Close()
+	}, nil
+}
diff --git a/internal/cli/filelock/filelock_test.go b/internal/cli/filelock/filelock_test.go
new file mode 100644
index 00000000..d3f07527
--- /dev/null
+++ b/internal/cli/filelock/filelock_test.go
@@ -0,0 +1,39 @@
+package filelock
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// A second Lock on the same file waits, saying so, until the first is released. (Each Lock opens the file again,
+// so two in one process conflict as two processes do.)
+func TestLockWaitsForTheHolder(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "locks", "key.lock")
+	unlockFirst, err := Lock(path, func() { t.Error("nothing holds the lock yet") })
+	require.NoError(t, err)
+
+	waiting := make(chan struct{})
+	acquired := make(chan func())
+	go func() {
+		unlock, err := Lock(path, func() { close(waiting) })
+		require.NoError(t, err)
+		acquired <- unlock
+	}()
+
+	<-waiting
+	select {
+	case <-acquired:
+		t.Fatal("the second Lock took the lock while the first held it")
+	case <-time.After(200 * time.Millisecond):
+	}
+	unlockFirst()
+	unlockSecond := <-acquired
+	unlockSecond()
+
+	unlockThird, err := Lock(path, func() { t.Error("the lock was released") })
+	require.NoError(t, err)
+	unlockThird()
+}
diff --git a/internal/cli/filelock/filelock_unix.go b/internal/cli/filelock/filelock_unix.go
new file mode 100644
index 00000000..50698042
--- /dev/null
+++ b/internal/cli/filelock/filelock_unix.go
@@ -0,0 +1,27 @@
+//go:build !windows
+
+package filelock
+
+import (
+	"errors"
+	"os"
+
+	"golang.org/x/sys/unix"
+)
+
+func lockFile(file *os.File) error {
+	return unix.Flock(int(file.Fd()), unix.LOCK_EX)
+}
+
+// tryLockFile takes the lock if no other process holds it, and reports whether it did.
+func tryLockFile(file *os.File) (bool, error) {
+	err := unix.Flock(int(file.Fd()), unix.LOCK_EX|unix.LOCK_NB)
+	if errors.Is(err, unix.EWOULDBLOCK) {
+		return false, nil
+	}
+	return err == nil, err
+}
+
+func unlockFile(file *os.File) error {
+	return unix.Flock(int(file.Fd()), unix.LOCK_UN)
+}
diff --git a/internal/cli/filelock/filelock_windows.go b/internal/cli/filelock/filelock_windows.go
new file mode 100644
index 00000000..cb5a2787
--- /dev/null
+++ b/internal/cli/filelock/filelock_windows.go
@@ -0,0 +1,33 @@
+//go:build windows
+
+package filelock
+
+import (
+	"errors"
+	"math"
+	"os"
+
+	"golang.org/x/sys/windows"
+)
+
+func lockFile(file *os.File) error {
+	return lockFileEx(file, windows.LOCKFILE_EXCLUSIVE_LOCK)
+}
+
+// tryLockFile takes the lock if no other process holds it, and reports whether it did.
+func tryLockFile(file *os.File) (bool, error) {
+	err := lockFileEx(file, windows.LOCKFILE_EXCLUSIVE_LOCK|windows.LOCKFILE_FAIL_IMMEDIATELY)
+	if errors.Is(err, windows.ERROR_LOCK_VIOLATION) {
+		return false, nil
+	}
+	return err == nil, err
+}
+
+func lockFileEx(file *os.File, flags uint32) error {
+	return windows.LockFileEx(windows.Handle(file.Fd()), flags, 0, math.MaxUint32, math.MaxUint32,
+		&windows.Overlapped{})
+}
+
+func unlockFile(file *os.File) error {
+	return windows.UnlockFileEx(windows.Handle(file.Fd()), 0, math.MaxUint32, math.MaxUint32, &windows.Overlapped{})
+}
diff --git a/internal/cli/webauthn/key_lock.go b/internal/cli/webauthn/key_lock.go
new file mode 100644
index 00000000..6df2e91b
--- /dev/null
+++ b/internal/cli/webauthn/key_lock.go
@@ -0,0 +1,37 @@
+//go:build !nofido
+
+package webauthn
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/DocSpring/rack-gateway/internal/cli/filelock"
+)
+
+// keyLockPath is the lock every rack-gateway command holds while it uses a security key. It's in the user's cache
+// directory, which every command shares (each agent session can have a TMPDIR of its own).
+var keyLockPath = func() string {
+	dir, err := os.UserCacheDir()
+	if err != nil {
+		dir = os.TempDir()
+	}
+	return filepath.Join(dir, "rack-gateway", "security-key.lock")
+}
+
+// withKeyLock runs use while holding the security key lock, waiting for any other rack-gateway command that holds
+// it. A key answers one command at a time: two commands asking for a PIN and a touch at once (two agents running
+// commands, say) both fail, with libfido2's "rx error" or "unsupported option", and the person can't tell which
+// touch is for which. A command holds the lock from its PIN dialog to its touch, so the next one asks only then.
+func withKeyLock[T any](use func() (T, error)) (T, error) {
+	unlock, err := filelock.Lock(keyLockPath(), func() {
+		fmt.Fprintln(os.Stderr, "Waiting for another rack-gateway command to finish with the security key...")
+	})
+	if err != nil {
+		var zero T
+		return zero, fmt.Errorf("failed to lock the security key for this command: %w", err)
+	}
+	defer unlock()
+	return use()
+}
diff --git a/internal/cli/webauthn/key_lock_test.go b/internal/cli/webauthn/key_lock_test.go
new file mode 100644
index 00000000..987b78d5
--- /dev/null
+++ b/internal/cli/webauthn/key_lock_test.go
@@ -0,0 +1,50 @@
+//go:build !nofido
+
+package webauthn
+
+import (
+	"errors"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/keys-pub/go-libfido2"
+	"github.com/stretchr/testify/require"
+
+	"github.com/DocSpring/rack-gateway/internal/cli/filelock"
+)
+
+// Each way a command uses the security key holds the lock, so a command waits for another that's using the key
+// rather than both failing. (No key is opened: the test replaces opening one.)
+func TestSecurityKeyUsersWaitForTheLock(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "security-key.lock")
+	lockPath, open := keyLockPath, openDevices
+	t.Cleanup(func() { keyLockPath, openDevices = lockPath, open })
+	keyLockPath = func() string { return path }
+	errNoKey := errors.New("no security key in tests")
+	openDevices = func() ([]*libfido2.Device, error) { return nil, errNoKey }
+
+	for name, use := range map[string]func() error{
+		"assertion": func() error {
+			_, _, err := GetAssertionWithCachedPIN(AssertionOptions{}, "1234")
+			return err
+		},
+		"PIN check": func() error { return CheckPIN("1234") },
+		"PIN query": func() error {
+			require.False(t, SingleKeyHasPIN())
+			return errNoKey
+		},
+	} {
+		unlock, err := filelock.Lock(path, nil)
+		require.NoError(t, err)
+		done := make(chan error, 1)
+		go func() { done <- use() }()
+		select {
+		case <-done:
+			t.Fatalf("the %s used the key while another command held the lock", name)
+		case <-time.After(200 * time.Millisecond):
+		}
+		unlock()
+		require.ErrorIs(t, <-done, errNoKey, name)
+	}
+}
diff --git a/internal/cli/webauthn/pin_check.go b/internal/cli/webauthn/pin_check.go
index db2c6a42..548db2a0 100644
--- a/internal/cli/webauthn/pin_check.go
+++ b/internal/cli/webauthn/pin_check.go
@@ -22,24 +22,32 @@ type pinKey interface {
 
 // SingleKeyHasPIN reports whether exactly one security key is connected and it has a PIN set. Its PIN can then be
 // asked for before the gateway sends a challenge: it's the key that will sign it. With several keys connected, the
-// key to use is only known from the challenge's credentials.
+// key to use is only known from the challenge's credentials. It holds the security key lock (see withKeyLock).
 func SingleKeyHasPIN() bool {
-	keys, err := openPINKeys()
-	return err == nil && onlyKeyHasPIN(keys)
+	hasPIN, err := withKeyLock(func() (bool, error) {
+		keys, err := openPINKeys()
+		return err == nil && onlyKeyHasPIN(keys), nil
+	})
+	return err == nil && hasPIN
 }
 
 // CheckPIN checks pin on the one connected security key, without a touch. A PIN the key refuses returns an error
 // wrapping ErrWrongPIN, which says how many tries are left. A key that can't check a PIN this way (it has no
-// credential management) returns nil, and the assertion checks the PIN.
+// credential management) returns nil, and the assertion checks the PIN. It holds the security key lock (see
+// withKeyLock).
 func CheckPIN(pin string) error {
-	keys, err := openPINKeys()
-	if err != nil {
-		return err
-	}
-	if len(keys) != 1 {
-		return fmt.Errorf("%d security keys are connected: connect only the one you use with rack-gateway", len(keys))
-	}
-	return verifyPIN(keys[0], pin)
+	_, err := withKeyLock(func() (struct{}, error) {
+		keys, err := openPINKeys()
+		if err != nil {
+			return struct{}{}, err
+		}
+		if len(keys) != 1 {
+			return struct{}{}, fmt.Errorf("%d security keys are connected: connect only the one you use with "+
+				"rack-gateway", len(keys))
+		}
+		return struct{}{}, verifyPIN(keys[0], pin)
+	})
+	return err
 }
 
 func openPINKeys() ([]pinKey, error) {
diff --git a/internal/cli/webauthn/webauthn.go b/internal/cli/webauthn/webauthn.go
index ca338668..ae52aa13 100644
--- a/internal/cli/webauthn/webauthn.go
+++ b/internal/cli/webauthn/webauthn.go
@@ -25,7 +25,20 @@ func GetAssertion(options AssertionOptions) (*AssertionResponse, error) {
 // GetAssertionWithCachedPIN authenticates with FIDO2 device, optionally using a cached PIN.
 // Returns the assertion response and the PIN used (for caching in subsequent calls).
 // If cachedPIN is empty, asks for the PIN when the key has one. Otherwise uses the cached PIN.
+// It holds the security key lock throughout (see withKeyLock).
 func GetAssertionWithCachedPIN(options AssertionOptions, cachedPIN string) (*AssertionResponse, string, error) {
+	var pin string
+	resp, err := withKeyLock(func() (*AssertionResponse, error) {
+		var resp *AssertionResponse
+		var err error
+		resp, pin, err = requestAssertion(options, cachedPIN)
+		return resp, err
+	})
+	return resp, pin, err
+}
+
+// requestAssertion is GetAssertionWithCachedPIN, without the lock.
+func requestAssertion(options AssertionOptions, cachedPIN string) (*AssertionResponse, string, error) {
 	allowList, err := decodeCredentialIDs(options.AllowCredentials)
 	if err != nil {
 		return nil, "", err
@@ -67,8 +80,8 @@ func openFIDODevices() ([]securityKey, error) {
 	return keys, nil
 }
 
-// openDevices opens every connected FIDO2 device that can be opened.
-func openDevices() ([]*libfido2.Device, error) {
+// openDevices opens every connected FIDO2 device that can be opened. Tests replace it.
+var openDevices = func() ([]*libfido2.Device, error) {
 	locs, err := libfido2.DeviceLocations()
 	if err != nil {
 		return nil, fmt.Errorf("failed to list FIDO2 devices: %w", err)

From 62924ea82b0ff0ef8ca4c91e946ed48c743c47dd Mon Sep 17 00:00:00 2001
From: Nathan Broadbent <git@ndbroadbent.com>
Date: Mon, 26 Oct 2026 13:08:03 +1300
Subject: [PATCH 2/2] fix(cli): refuse to use the key without a shared lock
 path, and report test goroutine failures

Without a user cache directory (no HOME), the security key lock fell back to the temporary directory, which each
agent session can have its own of, so commands would have used the key at once again. That is an error now. The
lock tests report a failure in their goroutine instead of hanging on a channel.
---
 internal/cli/filelock/filelock_test.go | 21 +++++++++++++++------
 internal/cli/webauthn/key_lock.go      | 17 +++++++++++------
 internal/cli/webauthn/key_lock_test.go |  6 ++++--
 3 files changed, 30 insertions(+), 14 deletions(-)

diff --git a/internal/cli/filelock/filelock_test.go b/internal/cli/filelock/filelock_test.go
index d3f07527..f1425f56 100644
--- a/internal/cli/filelock/filelock_test.go
+++ b/internal/cli/filelock/filelock_test.go
@@ -15,23 +15,32 @@ func TestLockWaitsForTheHolder(t *testing.T) {
 	unlockFirst, err := Lock(path, func() { t.Error("nothing holds the lock yet") })
 	require.NoError(t, err)
 
+	type result struct {
+		unlock func()
+		err    error
+	}
 	waiting := make(chan struct{})
-	acquired := make(chan func())
+	acquired := make(chan result, 1)
 	go func() {
 		unlock, err := Lock(path, func() { close(waiting) })
-		require.NoError(t, err)
-		acquired <- unlock
+		acquired <- result{unlock, err}
 	}()
 
-	<-waiting
+	select {
+	case second := <-acquired:
+		require.NoError(t, second.err)
+		t.Fatal("the second Lock took the lock while the first held it")
+	case <-waiting:
+	}
 	select {
 	case <-acquired:
 		t.Fatal("the second Lock took the lock while the first held it")
 	case <-time.After(200 * time.Millisecond):
 	}
 	unlockFirst()
-	unlockSecond := <-acquired
-	unlockSecond()
+	second := <-acquired
+	require.NoError(t, second.err)
+	second.unlock()
 
 	unlockThird, err := Lock(path, func() { t.Error("the lock was released") })
 	require.NoError(t, err)
diff --git a/internal/cli/webauthn/key_lock.go b/internal/cli/webauthn/key_lock.go
index 6df2e91b..5fe24317 100644
--- a/internal/cli/webauthn/key_lock.go
+++ b/internal/cli/webauthn/key_lock.go
@@ -11,13 +11,14 @@ import (
 )
 
 // keyLockPath is the lock every rack-gateway command holds while it uses a security key. It's in the user's cache
-// directory, which every command shares (each agent session can have a TMPDIR of its own).
-var keyLockPath = func() string {
+// directory, which every command shares. A temporary directory isn't: each agent session can have a TMPDIR of its
+// own, so commands there would use the key at once.
+var keyLockPath = func() (string, error) {
 	dir, err := os.UserCacheDir()
 	if err != nil {
-		dir = os.TempDir()
+		return "", err
 	}
-	return filepath.Join(dir, "rack-gateway", "security-key.lock")
+	return filepath.Join(dir, "rack-gateway", "security-key.lock"), nil
 }
 
 // withKeyLock runs use while holding the security key lock, waiting for any other rack-gateway command that holds
@@ -25,11 +26,15 @@ var keyLockPath = func() string {
 // commands, say) both fail, with libfido2's "rx error" or "unsupported option", and the person can't tell which
 // touch is for which. A command holds the lock from its PIN dialog to its touch, so the next one asks only then.
 func withKeyLock[T any](use func() (T, error)) (T, error) {
-	unlock, err := filelock.Lock(keyLockPath(), func() {
+	var zero T
+	path, err := keyLockPath()
+	if err != nil {
+		return zero, fmt.Errorf("failed to find where to lock the security key: %w", err)
+	}
+	unlock, err := filelock.Lock(path, func() {
 		fmt.Fprintln(os.Stderr, "Waiting for another rack-gateway command to finish with the security key...")
 	})
 	if err != nil {
-		var zero T
 		return zero, fmt.Errorf("failed to lock the security key for this command: %w", err)
 	}
 	defer unlock()
diff --git a/internal/cli/webauthn/key_lock_test.go b/internal/cli/webauthn/key_lock_test.go
index 987b78d5..47aa3eb4 100644
--- a/internal/cli/webauthn/key_lock_test.go
+++ b/internal/cli/webauthn/key_lock_test.go
@@ -20,7 +20,7 @@ func TestSecurityKeyUsersWaitForTheLock(t *testing.T) {
 	path := filepath.Join(t.TempDir(), "security-key.lock")
 	lockPath, open := keyLockPath, openDevices
 	t.Cleanup(func() { keyLockPath, openDevices = lockPath, open })
-	keyLockPath = func() string { return path }
+	keyLockPath = func() (string, error) { return path, nil }
 	errNoKey := errors.New("no security key in tests")
 	openDevices = func() ([]*libfido2.Device, error) { return nil, errNoKey }
 
@@ -31,7 +31,9 @@ func TestSecurityKeyUsersWaitForTheLock(t *testing.T) {
 		},
 		"PIN check": func() error { return CheckPIN("1234") },
 		"PIN query": func() error {
-			require.False(t, SingleKeyHasPIN())
+			if SingleKeyHasPIN() {
+				return errors.New("SingleKeyHasPIN found a PIN without a key")
+			}
 			return errNoKey
 		},
 	} {