feat: implement WebSocket authentication system with UUID tokens

[ThomasK33]

Summary

This PR implements a comprehensive WebSocket authentication system for claudecode.nvim:

• UUID Token Generation: Server generates UUID v4 tokens with enhanced entropy for each session
• Lock File Integration: Authentication tokens stored in ~/.claude/ide/[port].lock for Claude CLI discovery
• Header-based Validation: WebSocket handshake validates x-claude-code-ide-authorization header
• Security Controls: Token format validation, length limits, and comprehensive error handling
• Enhanced Logging: Detailed authentication event logging for debugging and security auditing

Technical Implementation

• Server Authentication: Modified server startup to generate and validate auth tokens throughout the connection lifecycle
• Handshake Security: Updated WebSocket handshake to reject connections with missing/invalid tokens
• Protocol Compliance: Follows official Claude Code IDE authentication protocol specifications
• Test Coverage: Added comprehensive test suite including unit tests for handshake validation and integration tests for end-to-end auth flows

Security Features

• Authentication tokens are 36-character UUIDs with proper format validation
• Token length limits (10-500 characters) prevent potential abuse
• Enhanced entropy sources for secure token generation
• All authentication events logged for security auditing

This implementation ensures secure connections between Claude CLI and the Neovim WebSocket server while maintaining compatibility with the official Claude Code protocol.

[Copilot]

Pull Request Overview

This PR implements a secure WebSocket authentication system for claudecode.nvim by introducing UUID v4 token generation, integrating authentication tokens into lock files, and validating WebSocket upgrade requests via an authentication header. Key changes include:

• Generating and validating UUID v4 tokens for each session with enhanced entropy.
• Storing and retrieving authentication tokens via lock files for Claude CLI discovery.
• Updating handshake, TCP server, and client logic along with extensive tests and documentation updates.

Reviewed Changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/unit/server_spec.lua	Added integration tests to verify server auth token state and operations.
tests/unit/server/handshake_spec.lua	Expanded tests for handshake validation including auth header cases.
tests/unit/init_spec.lua	Updated tests to reflect new lockfile auth token generation.
tests/lockfile_test.lua	Extended lockfile tests for auth token generation, reading, and error cases.
tests/integration/mcp_tools_spec.lua	Integrated tests covering full authentication flow across the server lifecycle.
scripts/lib_ws_persistent.sh	Updated ws_connect to pass the optional auth token.
scripts/lib_claude.sh	Added function integration to retrieve auth tokens from lock files.
lua/claudecode/server/tcp.lua	Propagated auth token to TCP server creation for connection validation.
lua/claudecode/server/init.lua	Stored, logged, and cleared auth tokens and integrated token in server start/stop.
lua/claudecode/server/handshake.lua	Enhanced handshake processing to validate expected auth tokens.
lua/claudecode/server/client.lua	Improved handshake logging and auth validation during client connection.
lua/claudecode/lockfile.lua	Added auth token generation, validation, and propagation with lock files.
lua/claudecode/init.lua	Bootstrapped auth token generation and ensured lockfile auth token consistency.
PROTOCOL.md and CLAUDE.md	Updated documentation to describe the authentication protocol and testing.