# CalSpot

A lightweight, self-hosted calendar server providing WebDAV access for calendar management and public HTTP endpoints for sharing calendars. Built with Go and SQLite.

## Features

- **WebDAV Interface**: Upload and sync `.ics` calendar files using any CalDAV-compatible client
- **Public Calendar Sharing**: Share calendars via simple HTTP URLs with security-through-obscurity
- **Authentication**: HTTP Basic Auth protection for WebDAV endpoints
- **User Management**: Interactive REPL for managing users
- **Secure Storage**: bcrypt password hashing and SQLite backend
- **Lightweight**: Single binary with no external dependencies
- **Docker Support**: Production-ready containerized deployment

## Architecture

- **Language**: Go 1.25.5
- **Database**: SQLite3 (file-based)
- **Authentication**: HTTP Basic Auth with bcrypt password hashing
- **Calendar Format**: iCalendar (`.ics`) files
- **Storage**: Single calendar per user with automatic versioning

## Quick Start

### Local Development

```bash
# Clone the repository
git clone <repository-url>
cd calspot

# Build the server
go build -o calspot main.go

# Run the server
./calspot
```

The server will start on port 8000 with an interactive REPL for user management.

### Docker Deployment

```bash
# Build the Docker image
docker build -t calspot .

# Run the container
docker run -it -p 8000:8000 -v $(pwd)/data:/home/appuser/data calspot
```

## User Management (REPL)

The server includes an interactive command-line interface for managing users:

### Commands

#### Add User
```
add [username] [password]
```
- If no username provided: generates a UUID username
- If no password provided: generates a secure 16-character password
- Displays the public calendar ID (UUID) for sharing

Example:
```
> add alice MySecurePass123
User alice created. Public ID: 01933b2c-8f5e-7890-a234-567890abcdef
```

#### Delete User
```
del <username>
```
Removes user and their associated calendar data.

#### List Users
```
list
```
Shows all registered users with their public IDs.

#### Reset Password
```
resetpassword <username> [newpassword]
```
Updates user password. Generates secure password if not provided.

## API Endpoints

### WebDAV (Authenticated)

**Endpoint**: `/webdav/`  
**Authentication**: HTTP Basic Auth  
**Methods**: `GET`, `PUT`, `DELETE`, `PROPFIND`, etc.

Upload a calendar:
```bash
curl -u username:password \
  -T calendar.ics \
  http://localhost:8000/webdav/calendar.ics
```

Download via WebDAV:
```bash
curl -u username:password \
  http://localhost:8000/webdav/calendar.ics
```

### Public Calendar Access (No Authentication)

**Endpoint**: `/<user-id>/calendar.ics`  
**Authentication**: None (security via obscure UUID)  
**Method**: `GET`

Access public calendar:
```bash
curl http://localhost:8000/01933b2c-8f5e-7890-a234-567890abcdef/calendar.ics
```

Subscribe in calendar apps:
```
http://localhost:8000/01933b2c-8f5e-7890-a234-567890abcdef/calendar.ics
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `DB_PATH` | `./data/cal.db` | Path to SQLite database file |

Example:
```bash
DB_PATH=/var/lib/calspot/calendar.db ./calspot
```

### Reverse Proxy Setup

CalSpot is designed to run behind a reverse proxy (Nginx, Caddy, Traefik) for HTTPS termination.

#### Nginx Example
```nginx
server {
    listen 443 ssl http2;
    server_name calendar.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Important for WebDAV
        proxy_set_header Depth $http_depth;
        proxy_set_header Destination $http_destination;
    }
}
```

## CalDAV Client Setup

### Thunderbird
1. Go to Calendar → New Calendar → On the Network → CalDAV
2. Location: `https://calendar.example.com/webdav/calendar.ics`
3. Username: your username
4. Password: your password

### iOS/macOS
1. Settings → Calendar → Accounts → Add Account → Other → CalDAV
2. Server: `calendar.example.com`
3. Username: your username
4. Password: your password
5. Path: `/webdav/calendar.ics`

### Android (DAVx⁵)
1. Install DAVx⁵ from F-Droid or Play Store
2. Add account → Login with URL and username
3. Base URL: `https://calendar.example.com/webdav/`
4. Username and password

## Security Considerations

### Implemented Security Features
- ✅ Bcrypt password hashing (cost factor 10)
- ✅ HTTP Basic Auth for WebDAV endpoints
- ✅ Cryptographically secure password generation
- ✅ UUID-based public calendar URLs (security through obscurity)
- ✅ File size limits (10MB per calendar)
- ✅ Input validation on usernames
- ✅ Security headers (X-Content-Type-Options, X-Frame-Options, etc.)
- ✅ Non-root container execution

### Production Recommendations
- **Always use HTTPS**: Deploy behind a reverse proxy with TLS
- **Secure public IDs**: Treat user IDs as secrets for calendar access
- **Regular backups**: Backup the SQLite database regularly
- **Monitor access**: Use reverse proxy logs to monitor unusual activity
- **Network isolation**: Run in a private network or with firewall rules

## Limitations

- **Single calendar per user**: Each user can store one `.ics` file
- **No calendar merging**: Multiple calendars must be managed at the client level
- **No collaborative features**: Designed for personal use, not team sharing
- **Flat file structure**: No folder organization support

## Technical Details

### Database Schema

```sql
CREATE TABLE users (
    id TEXT PRIMARY KEY,           -- UUIDv7 for public calendar access
    username TEXT UNIQUE,          -- Login username
    password_hash TEXT             -- bcrypt hash
);

CREATE TABLE calendars (
    user_id TEXT PRIMARY KEY,      -- Foreign key to users.id
    filename TEXT,                 -- Original filename (e.g., calendar.ics)
    content BLOB,                  -- iCalendar file content
    mod_time DATETIME              -- Last modification time
);
```

### Dependencies

- `github.com/google/uuid` - UUID generation (v1.6.0)
- `github.com/mattn/go-sqlite3` - SQLite driver (v1.14.32)
- `golang.org/x/crypto` - bcrypt hashing (v0.46.0)
- `golang.org/x/net/webdav` - WebDAV implementation (v0.48.0)

## Building from Source

```bash
# Clone repository
git clone <repository-url>
cd calspot

# Install dependencies
go mod download

# Build
go build -o calspot main.go

# Run
./calspot
```

### Build Requirements
- Go 1.25.5 or later
- GCC (for CGO/SQLite3 compilation)

## License

[Specify your license here]

## Contributing

[Contribution guidelines if applicable]

## Support

For issues, questions, or feature requests, please [open an issue](link-to-issues).