feat: Add Calendar Proxy application with Docker support

- Implemented a FastAPI application for a calendar proxy that allows browser-only calendar links to be used by calendar clients.
- Added Dockerfile for building the application with Tailwind CSS for styling.
- Created docker-compose files for development and production environments with security hardening.
- Added .gitignore to exclude sensitive environment files.
- Included README.md with instructions for self-hosting, environment variables, and usage examples.
- Implemented health check endpoint and static file serving for a simple UI.
- Added input validation, rate limiting, and logging features.
- Integrated Redis for optional rate limiting in production.
- Included Tailwind CSS for styling the UI.
- Added example requirements.txt for Python dependencies.

Author: OidaTiftla

.github/workflows/docker-publish.yml

@@ -0,0 +1,41 @@
+name: Build and publish Docker image
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU (for multi-arch builds)
+        uses: docker/setup-qemu-action@v2
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push Docker image (multi-arch)
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64,linux/arm/v7,linux/arm/v6,linux/386
+          tags: |
+            ghcr.io/${{ github.repository_owner }}/calendar-proxy:latest
+            ghcr.io/${{ github.repository_owner }}/calendar-proxy:${{ github.sha }}
+          file: Dockerfile

.gitignore

@@ -0,0 +1 @@
+.env

Dockerfile

@@ -0,0 +1,61 @@
+# Build stage - for CSS generation only
+FROM python:3.13.7-slim AS builder
+
+# Install build dependencies for Tailwind CSS
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Tailwind CSS version (renovate: datasource=github-releases depName=tailwindlabs/tailwindcss)
+ARG TAILWIND_VERSION=v4.1.12
+
+# Install architecture-specific Tailwind CSS
+RUN case "$(uname -m)" in \
+    x86_64) \
+        curl -L https://github.com/tailwindlabs/tailwindcss/releases/download/${TAILWIND_VERSION}/tailwindcss-linux-x64 -o /usr/local/bin/tailwindcss ;; \
+    aarch64) \
+        curl -L https://github.com/tailwindlabs/tailwindcss/releases/download/${TAILWIND_VERSION}/tailwindcss-linux-arm64 -o /usr/local/bin/tailwindcss ;; \
+    *) \
+        echo "Unsupported architecture: $(uname -m)" && exit 1 ;; \
+    esac && \
+    chmod +x /usr/local/bin/tailwindcss
+
+WORKDIR /app
+
+# Build Tailwind CSS
+COPY src/index.html src/input.css ./
+RUN mkdir -p static && tailwindcss -i ./input.css --content ./index.html -o ./static/style.css --minify
+
+# Runtime stage - minimal Python environment
+FROM python:3.13.7-slim AS runtime
+
+# Create non-root user for security
+RUN groupadd --gid 1000 appuser && \
+    useradd --uid 1000 --gid appuser --shell /bin/bash --create-home appuser
+
+# Install only runtime Python dependencies (no build tools)
+COPY src/requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt && rm requirements.txt
+
+# Create app directory and set ownership
+WORKDIR /app
+RUN chown -R appuser:appuser /app
+
+# Switch to non-root user
+USER appuser
+
+# Copy application files (as non-root user)
+COPY --chown=appuser:appuser src/app.py src/index.html ./
+
+# Copy built CSS from builder stage (as non-root user)
+COPY --from=builder --chown=appuser:appuser /app/static ./static
+
+# Runtime configuration
+ENV PYTHONUNBUFFERED=1
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=5 \
+    CMD curl -f http://localhost:8000/healthz
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]

README.md

@@ -0,0 +1,150 @@
+# Calendar-Proxy
+
+A tiny proxy to make browser-only calendar links (for example Office 365 `reachcalendar.ics`) usable by calendar clients that can't authenticate or set custom User-Agent headers.
+
+## Self-hosting
+
+Run a single container (secure defaults):
+
+```bash
+docker run -d --restart=unless-stopped \
+    --name calendar-proxy \
+    -p 8000:8000 \
+    --read-only \
+    --cap-drop=ALL \
+    --security-opt=no-new-privileges:true \
+    --memory=512m \
+    --cpus=0.5 \
+    --tmpfs=/tmp:noexec,nosuid,size=100m \
+    --tmpfs=/var/tmp:noexec,nosuid,size=50m \
+    --env-file .env \
+    calendar-proxy
+```
+
+`.env` (example, keep this file private):
+
+```
+PROXY_TOKENS=longtoken123
+ALLOWED_HOSTS=example.com,calendar.example.org
+LOG_LEVEL=WARNING
+DISABLE_ACCESS_LOG=true
+```
+
+Notes:
+- Prefer `--env-file` over inline `-e` to avoid leaking secrets in process lists or shell history.
+- Container runs as non-root user (UID 1000) for enhanced security.
+- Hardened with `--read-only`, capability drops, `no-new-privileges`, resource limits, and temporary filesystems.
+- Use `REDIS_URL` when running multiple containers for shared rate-limiting.
+- For production, consider using `docker-compose.production.yml` which includes additional security measures.
+
+## Required / recommended env vars
+
+- `PROXY_TOKENS` (required): comma-separated secret tokens used in subscription URLs.
+- `ALLOWED_HOSTS` (recommended): comma-separated allowed upstream hostnames.
+- `REDIS_URL` (optional): `redis://...` for cross-process rate limiting.
+- `RATE_LIMIT_PER_MIN` (default `60`): per-token request limit per minute.
+- `UPSTREAM_USER_AGENT` (default: Safari on macOS): User-Agent header sent to upstream servers.
+- `MAX_RESPONSE_BYTES` (default: `5242880` bytes / 5MB): maximum response size to prevent memory exhaustion.
+- `CONNECT_TIMEOUT` (default: `10` seconds): timeout for establishing upstream connections.
+- `READ_TIMEOUT` (default: `20` seconds): timeout for reading upstream response data.
+- `ALLOWED_CONTENT_TYPES` (default: `text/calendar,text/plain,application/octet-stream`): comma-separated allowed upstream content types.
+- `LOG_LEVEL` (default: `INFO`): application log level (DEBUG, INFO, WARNING, ERROR).
+- `DISABLE_ACCESS_LOG` (default: `true`): set to `false` to enable logging of URLs and accesses.
+
+## Build from source
+
+```bash
+docker build -t calendar-proxy .
+```
+
+## Production deployment
+
+For production use, a hardened `docker-compose.production.yml` is provided:
+
+```bash
+# Copy and customize the production compose file
+cp docker-compose.production.yml docker-compose.yml
+
+# Create secure environment file
+echo "PROXY_TOKENS=$(openssl rand -hex 40)" > .env
+
+# Deploy with enhanced security
+docker-compose up -d
+```
+
+The production configuration includes:
+
+- **Non-root execution**: Runs as UID/GID 1000
+- **Read-only filesystem**: Prevents runtime modifications
+- **Capability restrictions**: Drops all capabilities except essential ones
+- **Resource limits**: Memory (512MB) and CPU (0.5 cores) constraints
+- **No new privileges**: Prevents privilege escalation
+- **Temporary filesystems**: Secure `/tmp` and `/var/tmp` mounts
+- **Enhanced logging**: Production-ready log levels
+
+## How the proxy works (short)
+
+- Endpoint: `GET /sub/{token}/{b64url}/{name}.ics`
+  - `token`: secret in the path.
+  - `b64url`: URL-safe base64 (no padding) of the full upstream URL.
+  - `name.ics`: final filename for clients.
+  - Optional `ua` query param: override User-Agent used to fetch upstream.
+
+Security & runtime behaviour:
+- **Container security**: Runs as non-root user, read-only filesystem, dropped capabilities, resource limits.
+- Validates `token` against `PROXY_TOKENS`.
+- Resolves `b64url` hostname and refuses private/loopback/link-local/multicast/reserved IPs (SSRF protection).
+- Enforces `ALLOWED_HOSTS` when set.
+- Validates upstream content types against `ALLOWED_CONTENT_TYPES`.
+- Per-token rate limiting (Redis if `REDIS_URL` set, otherwise in-process fallback with automatic cleanup).
+- Streams upstream response, enforces timeouts and a maximum response byte cap.
+- Strips client cookies and Authorization; forwards only safe upstream headers (e.g. `Content-Type`, `Content-Disposition`).
+- Sanitizes URLs in logs to prevent exposure of sensitive information (when `DISABLE_ACCESS_LOG=true`).
+
+## Why macOS Calendar can't directly subscribe to Microsoft Office 365 links (very short)
+
+1) Office 365 shared URLs are browser-centric
+- Shared `reachcalendar.ics` links are designed to be opened by a browser, which may provide cookies or other auth automatically; macOS Calendar does not.
+
+2) User-Agent restrictions
+- Microsoft checks User-Agent and rejects unsupported clients. Requests from macOS `CalendarAgent` often get a "Outlook is not supported on this browser" page instead of an ICS.
+
+3) No auth flow support
+- Some shared calendars require Microsoft authentication (cookies/OAuth). macOS Calendar cannot perform those interactive browser flows.
+
+Workarounds: use this proxy (fetch with a browser-like UA), import into a service that fetches server-side, or download & import manually.
+
+## Quick examples
+
+Generate a URL-safe base64 without padding (shell):
+
+```bash
+python - <<'PY'
+import base64
+u='https://example.com/cal.ics'
+print(base64.urlsafe_b64encode(u.encode()).decode().rstrip('='))
+PY
+```
+
+Or without Python (using base64 + tr):
+
+```bash
+echo -n 'https://example.com/cal.ics' | base64 -w0 | tr '+/' '-_' | tr -d '='
+```
+
+Subscription URL:
+
+```
+https://proxy.example.com/sub/<token>/<b64url>/Work.ics
+```
+
+Open `http://<host>:8000/` in a browser to use the included `index.html` UI for building links.
+
+## Endpoints
+
+- `GET /sub/{token}/{b64url}/{name}.ics` — subscription proxy endpoint.
+- `GET /healthz` — health check JSON response.
+- `GET /` — web UI for building calendar subscription URLs.
+- `GET /static/{path}` — static files (CSS, etc.) for the web UI.
+
+If you want an admin UI for token management, Redis-backed caching, or a `docker-compose.yml` with Redis, tell me which and I'll add it.

docker-compose.production.yml

@@ -0,0 +1,40 @@
+services:
+  app:
+    image: calendar-proxy:latest
+    restart: unless-stopped
+    expose:
+      - 8000  # Assuming the app is behind a reverse proxy
+    environment:
+      # Required settings
+      # - PROXY_TOKENS=test-token-123,debug-token-456  # Should be set in .env; Generate it using: openssl rand -hex 40
+      # Optional settings
+      - ALLOWED_HOSTS=outlook.office365.com,calendar.google.com
+      - LOG_LEVEL=WARNING
+      - DISABLE_ACCESS_LOG=true
+    env_file: .env
+
+    # Security hardening
+    read_only: true
+    cap_drop:
+      - ALL
+    security_opt:
+      - no-new-privileges:true
+
+    # Resource limits
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: '0.5'
+
+    # Temporary filesystems for read-only container
+    tmpfs:
+      - /tmp:noexec,nosuid,size=100m
+      - /var/tmp:noexec,nosuid,size=50m
+
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/healthz"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 5s

docker-compose.yml

@@ -0,0 +1,71 @@
+services:
+  app:
+    image: calendar-proxy:latest
+    build:
+      context: .
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    ports:
+      - 8000:8000
+
+    # For development - mount source for live reload (uncomment if needed)
+    # volumes:
+    #   - ./src:/app:ro
+
+    environment:
+      # Required settings
+      - PROXY_TOKENS=test-token-123,test-token-456
+
+      # Optional settings for testing
+      - ALLOWED_HOSTS=outlook.office365.com,calendar.google.com
+      - RATE_LIMIT_PER_MIN=60
+      - UPSTREAM_USER_AGENT=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.6 Safari/605.1.15
+      - MAX_RESPONSE_BYTES=10485760
+      - CONNECT_TIMEOUT=10
+      - READ_TIMEOUT=30
+      - ALLOWED_CONTENT_TYPES=text/calendar,text/plain,text/html,application/octet-stream
+
+      # Logging settings
+      - LOG_LEVEL=DEBUG  # Options: DEBUG, INFO, WARNING, ERROR
+      - DISABLE_ACCESS_LOG=false  # Set to 'true' to disable uvicorn access logs entirely
+
+    # Security hardening
+    read_only: true
+    cap_drop:
+      - ALL
+    security_opt:
+      - no-new-privileges:true
+
+    # Resource limits
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: '0.5'
+
+    # Temporary filesystems for read-only container
+    tmpfs:
+      - /tmp:noexec,nosuid,size=100m
+      - /var/tmp:noexec,nosuid,size=50m
+
+    # Health check
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/healthz"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 5s
+
+# Optional: Redis for rate limiting in production
+# Uncomment if you want to test with Redis
+#  redis:
+#    image: redis:7-alpine
+#    ports:
+#      - "6379:6379"
+#    command: redis-server --appendonly yes
+#    volumes:
+#      - redis_data:/data
+#    restart: unless-stopped
+
+# volumes:
+#   redis_data:

renovate.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended"
+  ],
+
+  "reviewers": [
+    "OidaTiftla"
+  ],
+
+  "packageRules": [
+    {
+      "matchUpdateTypes": ["minor", "patch"],
+      "matchCurrentVersion": "!/^0/",
+      "ignoreTests": true,
+      "automerge": true
+    }
+  ],
+
+  "timezone": "Europe/Berlin",
+  "schedule": ["before 5am"]
+}