lixen/chess
SHA256
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.5.0 user support with auth added, tests and doc updated

Browse Source
This commit is contained in:
Lixen Wraith
2025-11-05 02:56:41 -05:00
parent 59486bfe32
commit a3f4db96fa
25 changed files with 2409 additions and 1172 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
doc/development.md
View File

@ -4,13 +4,14 @@
- Go 1.24+
- Stockfish in PATH
- SQLite3
- Git
- curl, jq (for testing)
## Building
```bash
git clone https://git.lixen.com/lixen/chess
#git clone https://git.lixen.com/lixen/chess # Mirror
git clone https://github.com/lixenwraith/chess
cd chess
go build ./cmd/chessd
```
@ -23,65 +24,141 @@ go build ./cmd/chessd
- `-serve`: Enable embedded web UI server
- `-web-host`: Web UI server host (default: localhost)
- `-web-port`: Web UI server port (default: 9090)
- `-dev`: Development mode with relaxed rate limits
- `-storage-path`: SQLite database file path (enables persistence)
- `-dev`: Development mode with relaxed rate limits and fixed JWT secret
- `-storage-path`: SQLite database file path (enables persistence and authentication)
- `-pid`: PID file path for process tracking
- `-pid-lock`: Enable exclusive locking (requires -pid)
### Modes
```bash
# In-memory only
# In-memory only (no persistence or auth)
./chessd
# With persistence
# With persistence and authentication
./chessd -storage-path ./db/chess.db
# Singleton enforcement (requires same PID file path across instances)
./chessd -pid /var/run/chessd.pid -pid-lock
# Development with all features
./chessd -dev -storage-path chess.db -pid /tmp/chessd.pid
./chessd -dev -storage-path chess.db -pid /tmp/chessd.pid -serve
# Initialize database with user tables
./chessd db init -path chess.db
```
## Database Management
### CLI Commands
### Schema Initialization
```bash
# Initialize database schema
# Create all tables (users, games, moves)
./chessd db init -path chess.db
```
# Query games
./chessd db query -path chess.db [-gameId ID] [-playerId ID]
### User Management CLI
```bash
# Add user with password
./chessd db user add -path chess.db -username alice -password SecurePass123
# Delete database
# Add user with email
./chessd db user add -path chess.db -username bob -email bob@example.com -password BobPass456
# Interactive password input
./chessd db user add -path chess.db -username charlie -interactive
# List all users
./chessd db user list -path chess.db
# Update password
./chessd db user set-password -path chess.db -username alice -password NewPass789
# Update email
./chessd db user set-email -path chess.db -username alice -email newemail@example.com
# Update username
./chessd db user set-username -path chess.db -current alice -new alice2
# Import with existing Argon2 hash
./chessd db user set-hash -path chess.db -username alice -hash '$argon2id$v=19$m=65536,t=3,p=2$...'
# Delete user
./chessd db user delete -path chess.db -username alice
```
### Game Query CLI
```bash
# Query all games
./chessd db query -path chess.db -gameId "*"
# Query games for specific user
./chessd db query -path chess.db -playerId "550e8400-e29b-41d4-a716-446655440000"
# Query specific game
./chessd db query -path chess.db -gameId "a1b2c3d4-e5f6-7890-1234-567890abcdef"
# Delete database (destructive)
./chessd db delete -path chess.db
```
Query parameters accept `*` for all records (default if omitted) or specific IDs for filtering.
## Authentication Configuration
### JWT Secret Management
- **Production**: Cryptographically secure 32-byte secret generated on startup
- **Development** (`-dev`): Fixed secret for testing consistency
- **Sessions**: Valid for 7 days, renewed on each login
### Password Requirements
- Minimum 8 characters
- At least one letter and one number
- Argon2id hashing with secure defaults
### User Account Features
- Case-insensitive username and email matching
- Optional email addresses
- Last login tracking
- Unique constraint enforcement with transaction isolation
## Project Structure
```
chess/
├── cmd/chessd/
│ ├── main.go # Entry point
│ ├── main.go # Entry point with auth initialization
│ ├── pid.go # PID file management
│ └── cli/ # Database CLI
│ └── cli/ # Database and user CLI
├── internal/
│ ├── board/ # FEN/ASCII operations
│ ├── core/ # Shared types
│ ├── core/ # Shared types and API models
│ ├── engine/ # Stockfish UCI wrapper
│ ├── game/ # Game state
│ ├── http/ # Fiber handlers
│ ├── processor/ # Command processing
│ ├── service/ # State management
│ ├── game/ # Game state with player associations
│ ├── http/ # Fiber handlers and auth endpoints
│ │ ├── handler.go # Game endpoints
│ │ ├── auth.go # Authentication endpoints
│ │ └── middleware.go # JWT validation
│ ├── processor/ # Command processing with user context
│ ├── service/ # State and user management
│ │ ├── service.go # Core service
│ │ ├── game.go # Game operations
│ │ └── user.go # User and auth operations
│ └── storage/ # SQLite persistence
│ ├── storage.go # Async writer for games
│ ├── game.go # Game persistence
│ ├── user.go # User persistence (synchronous)
│ └── schema.go # Database schema
└── test/ # Test scripts
```
## Testing
See [test documentation](../test/README.md) for details.
See [test documentation](../test/README.md) for comprehensive test suites covering API, authentication, and database operations.
### Quick Test Commands
```bash
# API functionality tests
./test/test-api.sh
# User authentication and database tests
./test/test-db.sh
# Run test server with sample users
./test/test-db-server.sh
```
## Configuration
@ -92,15 +169,30 @@ See [test documentation](../test/README.md) for details.
- Min search time: 100ms (internal/processor/processor.go)
- Write queue: 1000 operations (internal/storage/storage.go)
- DB connections: 25 max, 5 idle (internal/storage/storage.go)
- JWT expiration: 7 days (internal/service/user.go)
### Authentication Configuration
- Password minimum: 8 characters with letter and number
- Username format: 1-40 characters, alphanumeric and underscore
- Email validation: Standard RFC 5322 format
- Hash algorithm: Argon2id (memory-hard, side-channel resistant)
### Storage Configuration
- WAL mode enabled in development for concurrency
- Foreign key constraints enforced
- Async write pattern with 2-second drain on shutdown
- Async write pattern for games with 2-second drain on shutdown
- Synchronous writes for user operations (data consistency)
- Degradation to memory-only on write failures
- Case-insensitive collation for usernames and emails
### Rate Limiting Configuration
- General endpoints: 10 req/s (20 in dev mode)
- User registration: 5 req/min
- User login: 10 req/min
- Rate limit key: IP address from X-Forwarded-For or connection
### PID Management
- Singleton enforcement requires same PID file path - all instances must use the same -pid value
- Singleton enforcement requires same PID file path
- Stale PID detection via signal 0 checking
- Exclusive file locking with LOCK_EX|LOCK_NB
- Automatic cleanup on graceful shutdown
@ -111,10 +203,35 @@ See [test documentation](../test/README.md) for details.
- Search time: 100-10000ms
- UCI moves: 4-5 characters ([a-h][1-8][a-h][1-8][qrbn]?)
- Undo count: 1-300
- Username: 1-40 characters, [a-zA-Z0-9_]
- Password: 8-128 characters, requires letter and number
## Security Considerations
### Authentication Security
- Passwords hashed with Argon2id before storage
- JWT tokens signed with HS256
- Constant-time password comparison
- Case-insensitive matching prevents user enumeration
- Rate limiting on auth endpoints prevents brute force
### Input Validation
- All user inputs validated and sanitized
- SQL injection prevented via parameterized queries
- UCI command injection blocked via character validation
- FEN strings validated against strict regex pattern
### Session Management
- JWT tokens expire after 7 days
- No token refresh mechanism (re-login required)
- Tokens include minimal claims (user ID, username, email)
- Secret rotates on server restart (except dev mode)
## Limitations
- No persistence (memory only)
- Hardcoded Stockfish path
- Fixed worker pool size
- No game history beyond current session
- JWT tokens don't support refresh (must re-login after expiry)
- User deletion doesn't cascade to games (games remain with player IDs)
- No password recovery mechanism
- No email verification for registration
- Fixed worker pool size for engine calculations
- No real-time game updates (polling required)