formies/README.md

# Formies Backend

A production-ready Rust backend for the Formies application.

## Features

- RESTful API endpoints
- SQLite database with connection pooling
- JWT-based authentication
- Rate limiting
- Structured logging
- Error tracking with Sentry
- Health check endpoint
- CORS support
- Configuration management
- Metrics endpoint

## Prerequisites

- Rust 1.70 or later
- SQLite 3
- Make (optional, for using Makefile commands)

## Configuration

The application can be configured using environment variables or a configuration file. The following environment variables are supported:

### Required Environment Variables

- `DATABASE_URL`: SQLite database URL (default: form_data.db)
- `BIND_ADDRESS`: Server bind address (default: 127.0.0.1:8080)
- `INITIAL_ADMIN_USERNAME`: Initial admin username
- `INITIAL_ADMIN_PASSWORD`: Initial admin password

### Optional Environment Variables

- `ALLOWED_ORIGIN`: CORS allowed origin
- `RUST_LOG`: Log level (default: info)
- `SENTRY_DSN`: Sentry DSN for error tracking
- `JWT_SECRET`: JWT secret key
- `JWT_EXPIRATION`: JWT expiration time in seconds
- `CAPTCHA_ENABLED`: Enable CAPTCHA verification for public form submissions (`true` or `false`, default: `false`)
- `CAPTCHA_SECRET_KEY`: The secret key provided by your CAPTCHA service (e.g., hCaptcha, reCAPTCHA)
- `CAPTCHA_VERIFICATION_URL`: The verification endpoint URL for your CAPTCHA service (e.g., `https://hcaptcha.com/siteverify`)

## Development

1. Clone the repository
2. Install dependencies:
   ```bash
   cargo build
   ```
3. Set up environment variables:
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```
4. Run the development server:
   ```bash
   cargo run
   ```

## Production Deployment

### Docker

1. Build the Docker image:

   ```bash
   docker build -t formies-backend .
   ```

2. Run the container:
   ```bash
   docker run -d \
     --name formies-backend \
     -p 8080:8080 \
     -v $(pwd)/data:/app/data \
     -e DATABASE_URL=/app/data/form_data.db \
     -e BIND_ADDRESS=0.0.0.0:8080 \
     -e INITIAL_ADMIN_USERNAME=admin \
     -e INITIAL_ADMIN_PASSWORD=your-secure-password \
     -e ALLOWED_ORIGIN=https://your-frontend-domain.com \
     -e SENTRY_DSN=your-sentry-dsn \
     formies-backend
   ```

### Systemd Service

1. Create a systemd service file at `/etc/systemd/system/formies-backend.service`:

   ```ini
   [Unit]
   Description=Formies Backend Service
   After=network.target

   [Service]
   Type=simple
   User=formies
   WorkingDirectory=/opt/formies-backend
   ExecStart=/opt/formies-backend/formies-be
   Restart=always
   Environment=DATABASE_URL=/opt/formies-backend/data/form_data.db
   Environment=BIND_ADDRESS=0.0.0.0:8080
   Environment=INITIAL_ADMIN_USERNAME=admin
   Environment=INITIAL_ADMIN_PASSWORD=your-secure-password
   Environment=ALLOWED_ORIGIN=https://your-frontend-domain.com
   Environment=SENTRY_DSN=your-sentry-dsn

   [Install]
   WantedBy=multi-user.target
   ```

2. Enable and start the service:
   ```bash
   sudo systemctl enable formies-backend
   sudo systemctl start formies-backend
   ```

## Monitoring

### Health Check

The application exposes a health check endpoint at `/api/health`:

```bash
curl http://localhost:8080/api/health
```

### Metrics

Metrics are available at `/metrics` when enabled in the configuration.

### Logging

Logs are written to the configured log file and can be viewed using:

```bash
tail -f logs/app.log
```

## Security

- All API endpoints are rate-limited
- CORS is configured to only allow specified origins
- JWT tokens are used for authentication
- Passwords are hashed using bcrypt
- SQLite database is protected with proper file permissions

### Form Submission Security

The public form submission endpoint (`/api/forms/{form_id}/submissions`) includes several security measures:

- **Global Rate Limiting:** The overall number of requests to the API is limited.
- **Per-Form, Per-IP Rate Limiting:** Limits the number of submissions one IP address can make to a specific form within a time window (e.g., 5 submissions per minute). Configurable in code.
- **CAPTCHA Verification:** If enabled via environment variables (`CAPTCHA_ENABLED=true`), requires a valid CAPTCHA token (e.g., from hCaptcha, reCAPTCHA, Turnstile) to be sent in the `captcha_token` field of the submission payload. The backend verifies this token with the configured provider.
- **Payload Size Limit:** The maximum size of the submission payload is limited (e.g., 1MB) to prevent DoS attacks. Configurable in code.
- **Input Validation:** Submission data is validated against the specific form's field definitions (type, required, length, pattern, etc.).
- **Notification Throttling:** Limits the rate at which notifications (Email, Ntfy) are sent per form to prevent spamming channels (e.g., max 1 per minute). Configurable in code.

## License

MIT