fix(lockfile): generate auth token from a CSPRNG and restrict lock-file permissions (#259)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Thomas Kosiewski <tk@coder.com>

Author: ThomasK33

CLAUDE.md

@@ -82,7 +82,7 @@ The `fixtures/` directory contains test Neovim configurations for verifying plug
 
 The WebSocket server implements secure authentication using:
 
-- **UUID v4 Tokens**: Generated per session with enhanced entropy
+- **128-bit Tokens**: 32-char lowercase hex from the OS CSPRNG, generated per session
 - **Header-based Auth**: Uses `x-claude-code-ide-authorization` header
 - **Lock File Discovery**: Tokens stored in `~/.claude/ide/[port].lock` for Claude CLI
 - **MCP Compliance**: Follows official Claude Code IDE authentication protocol
@@ -145,7 +145,7 @@ opts = {
 
 - ✅ **WebSocket Server**: RFC 6455 compliant with MCP message format
 - ✅ **Tool Registration**: JSON Schema-based tool definitions
-- ✅ **Authentication**: UUID v4 token-based secure handshake
+- ✅ **Authentication**: 128-bit token-based secure handshake (32-char lowercase hex from the OS CSPRNG)
 - ✅ **Message Format**: JSON-RPC 2.0 with MCP content structure
 - ✅ **Error Handling**: Comprehensive JSON-RPC error responses
 
@@ -212,7 +212,7 @@ mise run test  # Recommended for complete validation
 
 ## Authentication Testing
 
-The plugin implements authentication using UUID v4 tokens that are generated for each server session and stored in lock files. This ensures secure connections between Claude CLI and the Neovim WebSocket server.
+The plugin implements authentication using 128-bit tokens (32-char lowercase hex) from the OS CSPRNG that are generated for each server session and stored in lock files. This ensures secure connections between Claude CLI and the Neovim WebSocket server.
 
 ### Testing Authentication Features
 
@@ -340,7 +340,7 @@ Log levels for authentication events:
 ### Security Considerations
 
 - WebSocket server only accepts local connections (127.0.0.1) for security
-- Authentication tokens are UUID v4 with enhanced entropy
+- Authentication tokens are 128-bit tokens (32-char lowercase hex) from the OS CSPRNG
 - Lock files created at `~/.claude/ide/[port].lock` for Claude CLI discovery
 - All authentication events are logged for security auditing
 

PROTOCOL.md

@@ -24,7 +24,7 @@ The IDE writes a discovery file to `~/.claude/ide/[port].lock`:
   "workspaceFolders": ["/path/to/project"], // Open folders
   "ideName": "VS Code", // or "Neovim", "IntelliJ", etc.
   "transport": "ws", // WebSocket transport
-  "authToken": "550e8400-e29b-41d4-a716-446655440000" // Random UUID for authentication
+  "authToken": "a3f1c2d4e5f60718293a4b5c6d7e8f90" // 32-char lowercase hex token (128 bits) from the OS CSPRNG
 }
 ```
 
@@ -44,7 +44,7 @@ Claude reads the lock files, finds the matching port from the environment, and c
 When Claude connects to the IDE's WebSocket server, it must authenticate using the token from the lock file. The authentication happens via a custom WebSocket header:
 
 ```
-x-claude-code-ide-authorization: 550e8400-e29b-41d4-a716-446655440000
+x-claude-code-ide-authorization: a3f1c2d4e5f60718293a4b5c6d7e8f90
 ```
 
 The IDE validates this header against the `authToken` value from the lock file. If the token doesn't match, the connection is rejected.
@@ -514,7 +514,12 @@ local server = create_websocket_server("127.0.0.1", random_port)
 
 ```lua
 -- ~/.claude/ide/[port].lock
-local auth_token = generate_uuid() -- Generate random UUID
+-- Generate a 128-bit token (32-char lowercase hex) from the OS CSPRNG.
+-- Never use math.random for this; a weak token is worse than a startup error.
+local bytes = vim.loop.random(16) -- 16 secure random bytes
+local auth_token = bytes:gsub(".", function(c)
+  return string.format("%02x", string.byte(c))
+end)
 local lock_data = {
   pid = vim.fn.getpid(),
   workspaceFolders = { vim.fn.getcwd() },

lua/claudecode/lockfile.lua

@@ -19,45 +19,54 @@ end
 
 M.lock_dir = get_lock_dir()
 
--- Track if random seed has been initialized
-local random_initialized = false
-
----Generate a random UUID for authentication
----@return string uuid A randomly generated UUID string
-local function generate_auth_token()
-  -- Initialize random seed only once
-  if not random_initialized then
-    local seed = os.time() + vim.fn.getpid()
-    -- Add more entropy if available
-    if vim.loop and vim.loop.hrtime then
-      seed = seed + (vim.loop.hrtime() % 1000000)
+---Read n random bytes from a cryptographically secure source.
+---Tries libuv's OS CSPRNG first, then falls back to /dev/urandom.
+---Never falls back to math.random: a weak token is worse than a startup error.
+---@param n number The number of random bytes to read
+---@return string bytes A string of exactly n random bytes
+local function get_random_bytes(n)
+  -- Prefer libuv's uv_random (OS CSPRNG). Use vim.loop.random (available on
+  -- Neovim 0.8+) rather than vim.uv.random (only aliased on 0.10+).
+  if vim.loop and vim.loop.random then
+    local ok, bytes = pcall(vim.loop.random, n)
+    if ok and type(bytes) == "string" and #bytes == n then
+      return bytes
     end
-    math.randomseed(seed)
+  end
 
-    -- Call math.random a few times to "warm up" the generator
-    for _ = 1, 10 do
-      math.random()
+  -- Fallback: read directly from the kernel CSPRNG.
+  local file = io.open("/dev/urandom", "rb")
+  if file then
+    local bytes = file:read(n)
+    file:close()
+    if type(bytes) == "string" and #bytes == n then
+      return bytes
     end
-    random_initialized = true
   end
 
-  -- Generate UUID v4 format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
-  local template = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"
-  local uuid = template:gsub("[xy]", function(c)
-    local v = (c == "x") and math.random(0, 15) or math.random(8, 11)
-    return string.format("%x", v)
+  error("Failed to obtain " .. n .. " bytes of secure random data (no vim.loop.random or readable /dev/urandom)")
+end
+
+---Generate a cryptographically secure authentication token.
+---@return string token A 32-character lowercase hex string (128 bits of entropy)
+local function generate_auth_token()
+  local bytes = get_random_bytes(16)
+
+  -- Hex-encode the random bytes into a 32-character lowercase string.
+  local token = bytes:gsub(".", function(c)
+    return string.format("%02x", string.byte(c))
   end)
 
-  -- Validate generated UUID format
-  if not uuid:match("^[0-9a-f]+-[0-9a-f]+-[0-9a-f]+-[0-9a-f]+-[0-9a-f]+$") then
-    error("Generated invalid UUID format: " .. uuid)
+  -- Sanity-check the generated token shape.
+  if not token:match("^[0-9a-f]+$") then
+    error("Generated invalid auth token format")
   end
 
-  if #uuid ~= 36 then
-    error("Generated UUID has invalid length: " .. #uuid .. " (expected 36)")
+  if #token < 16 then
+    error("Generated auth token too short: " .. #token .. " (expected at least 16)")
   end
 
-  return uuid
+  return token
 end
 
 ---Generate a new authentication token
@@ -82,13 +91,18 @@ function M.create(port, auth_token)
   end
 
   local ok, err = pcall(function()
-    return vim.fn.mkdir(M.lock_dir, "p")
+    return vim.fn.mkdir(M.lock_dir, "p", tonumber("700", 8))
   end)
 
   if not ok then
     return false, "Failed to create lock directory: " .. (err or "unknown error")
   end
 
+  -- mkdir's mode argument only applies to newly created directories; a lock dir
+  -- left over from an earlier version may still be 0755. Tighten it to 0700.
+  -- pcall-wrapped because fs_chmod is unsupported on some non-POSIX platforms.
+  pcall(vim.loop.fs_chmod, M.lock_dir, tonumber("700", 8))
+
   local lock_path = M.lock_dir .. "/" .. port .. ".lock"
 
   local workspace_folders = M.get_workspace_folders()
@@ -130,23 +144,60 @@ function M.create(port, auth_token)
     return false, "Failed to encode lock file content: " .. (json_err or "unknown error")
   end
 
-  local file = io.open(lock_path, "w")
-  if not file then
-    return false, "Failed to create lock file: " .. lock_path
-  end
+  -- Write atomically with restrictive (0600) permissions: write to a temp file
+  -- in the same directory, then rename into place. Using "wx" (O_CREAT|O_EXCL)
+  -- refuses to follow an existing file or symlink at the temp path.
+  -- Include hrtime() so the temp path stays unique even after a crash where the
+  -- PID is reused for the same port (otherwise "wx" would fail EEXIST).
+  -- string.format keeps hrtime() (a double on LuaJIT) as a plain integer rather
+  -- than scientific notation (e.g. 1.75e+15), which would corrupt the path.
+  local tmp_path = lock_path .. ".tmp." .. vim.fn.getpid() .. "." .. string.format("%d", vim.loop.hrtime())
 
   local write_ok, write_err = pcall(function()
-    file:write(json)
-    file:close()
+    local fd = vim.loop.fs_open(tmp_path, "wx", tonumber("600", 8))
+    if not fd then
+      error("could not open temp file: " .. tmp_path)
+    end
+
+    local close_and_raise = function(message)
+      pcall(vim.loop.fs_close, fd)
+      error(message)
+    end
+
+    -- fs_write may write fewer bytes than requested (quota/disk-full/odd FS),
+    -- so loop on the returned count and an offset until all bytes are written.
+    -- Otherwise a truncated lock file could be renamed into place.
+    local pos = 0
+    while pos < #json do
+      local ok_write, written = pcall(vim.loop.fs_write, fd, json:sub(pos + 1), pos)
+      if not ok_write then
+        close_and_raise("could not write temp file: " .. tostring(written))
+      end
+      if type(written) ~= "number" or written <= 0 then
+        close_and_raise("could not write temp file: short write at offset " .. pos .. "/" .. #json)
+      end
+      pos = pos + written
+    end
+
+    -- fs_close returns (nil, err) on libuv failure without raising, so check
+    -- both the pcall status and the libuv result before renaming.
+    local ok_close, close_result = pcall(vim.loop.fs_close, fd)
+    if not ok_close or not close_result then
+      error("could not close temp file: " .. tmp_path)
+    end
   end)
 
   if not write_ok then
-    pcall(function()
-      file:close()
-    end)
+    pcall(vim.loop.fs_unlink, tmp_path)
     return false, "Failed to write lock file: " .. (write_err or "unknown error")
   end
 
+  local rename_ok, rename_err = os.rename(tmp_path, lock_path)
+  if not rename_ok then
+    pcall(vim.loop.fs_unlink, tmp_path)
+    return false, "Failed to write lock file: " .. (rename_err or "rename failed")
+  end
+
   return true, lock_path, auth_token
 end
 

lua/claudecode/server/handshake.lua

@@ -60,7 +60,7 @@ function M.validate_upgrade_request(request, expected_auth_token)
       return false, "Authentication token too short (min 10 characters)"
     end
 
-    if auth_header ~= expected_auth_token then
+    if not utils.constant_time_compare(auth_header, expected_auth_token) then
       return false, "Invalid authentication token"
     end
   end

lua/claudecode/server/utils.lua

@@ -407,14 +407,52 @@ function M.apply_mask(data, mask)
   return table.concat(result)
 end
 
+local rng_seeded = false
+
 ---Shuffle an array in place using Fisher-Yates algorithm
 ---@param tbl table The array to shuffle
 function M.shuffle_array(tbl)
-  math.randomseed(os.time())
+  -- Seed the PRNG once per process so port selection order varies across editor
+  -- starts. Seeding lazily on first use (rather than on every call, as a prior
+  -- version did with os.time()) avoids identical orderings within the same
+  -- second while still giving each process a distinct sequence.
+  if not rng_seeded then
+    math.randomseed(os.time())
+    rng_seeded = true
+  end
   for i = #tbl, 2, -1 do
     local j = math.random(i)
     tbl[i], tbl[j] = tbl[j], tbl[i]
   end
 end
 
+---Compare two strings in constant time relative to their length.
+---Returns false immediately on a length mismatch; otherwise every byte is
+---examined so total work does not depend on the matching-prefix length.
+---@param a string First string
+---@param b string Second string
+---@return boolean equal True if the strings are byte-for-byte equal
+function M.constant_time_compare(a, b)
+  if type(a) ~= "string" or type(b) ~= "string" then
+    return false
+  end
+
+  if #a ~= #b then
+    return false
+  end
+
+  -- Accumulate a value that is non-zero iff any byte differs, doing identical,
+  -- branchless work per byte (subtract + multiply + add). This keeps the timing
+  -- independent of the matching-prefix length without the bit module or the
+  -- file-local arithmetic-emulated bor/bxor, whose loop counts depend on operand
+  -- magnitude and would themselves reintroduce prefix-length timing leakage.
+  local diff = 0
+  for i = 1, #a do
+    local d = a:byte(i) - b:byte(i)
+    diff = diff + d * d
+  end
+
+  return diff == 0
+end
+
 return M