v1.2.0 — Hardening & Performance (roadmap phases 0–5)

.env.example

@@ -0,0 +1,85 @@
+# Copy to .env and adjust. Every value below is the built-in default, so an
+# unset variable behaves exactly like the line shown.
+#
+#   cp .env.example .env
+#
+# .env is gitignored. Never commit real secrets.
+
+# --- Required in production --------------------------------------------------
+
+# Flask/CSRF signing key. The built-in development default is publicly known, so
+# the app REFUSES TO START with it when APP_ENV=production.
+#   python -c "import secrets; print(secrets.token_hex(32))"
+SECRET_KEY=dev-secret-key-change-in-production
+
+# The single canonical production signal. Setting it to "production" enables the
+# SECRET_KEY fail-fast, the Secure session cookie, and the rate-limit topology
+# guard. No other spelling is accepted -- two names would let a deployment
+# satisfy one gate and silently miss another.
+# APP_ENV=production
+
+# --- Deployment topology (see README "Deployment topology and rate limiting") --
+
+# Worker count. Single source of truth: gunicorn reads it natively and every
+# documented start command passes --workers "$WEB_CONCURRENCY". Required under
+# APP_ENV=production.
+WEB_CONCURRENCY=1
+
+# Replica count. Invisible from inside the process, so it is declared here and
+# must mirror render.yaml's numInstances. Required under APP_ENV=production.
+APP_REPLICAS=1
+
+# Rate-limit counter storage. memory:// counters are process-local, so the
+# effective limit is multiplied by workers x replicas. Anything above 1x1
+# requires a shared backend (and requirements-redis.txt installed).
+RATELIMIT_STORAGE_URI=memory://
+
+# Trust X-Forwarded-* from exactly one proxy hop. Enable ONLY when the app sits
+# behind a proxy you control; otherwise clients can forge their rate-limit bucket.
+TRUST_PROXY=0
+
+# --- Limits ------------------------------------------------------------------
+
+MAX_UPLOAD_SIZE=10485760
+PREVIEW_ROW_LIMIT=25
+FLATTEN_MAX_DEPTH=10
+
+# XLSX-only export budget, in cells (rows x columns). Derived from the
+# measurement in docs/export-budget-v1.2.md. CSV/TSV are streamed and uncapped.
+# 0 disables the guard.
+MAX_EXPORT_CELLS=250000
+
+# --- API fetch ---------------------------------------------------------------
+
+API_FETCH_TIMEOUT=30
+API_FETCH_MAX_RESPONSE=10485760
+
+# Ports the API-fetch feature may connect to. Empty disables the check.
+API_ALLOWED_PORTS=80,443,8443
+
+# DNS admission control. API_DNS_TIMEOUT bounds how long a REQUEST waits, not how
+# long the lookup runs -- getaddrinfo exposes no timeout and cannot be cancelled.
+# API_DNS_MAX_WORKERS bounds concurrency, which is the actual starvation fix.
+API_DNS_TIMEOUT=3
+API_DNS_MAX_WORKERS=4
+API_DNS_ADMISSION_TIMEOUT=1
+
+# --- Rate limits -------------------------------------------------------------
+
+RATE_LIMIT_DEFAULT=120/minute
+RATE_LIMIT_PROCESS=30/minute
+RATE_LIMIT_EXPORT=60/minute
+
+# --- Misc --------------------------------------------------------------------
+
+# Cache lifetime for static assets. Safe because asset URLs carry ?v=APP_VERSION.
+STATIC_MAX_AGE=86400
+
+# Responses below this size are not worth compressing.
+GZIP_MIN_SIZE=1024
+
+# Set to 0 to omit the version from /health.
+HEALTH_REVEAL_VERSION=1
+
+# Flask debug mode. Never enable in production.
+FLASK_DEBUG=0

.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+# Nothing here touches the GitHub API beyond checkout, so the token needs no
+# write scope; an explicit block also stops it inheriting wider repo defaults.
+permissions:
+  contents: read
+
+# A branch push and its pull_request event overlap constantly. Superseded runs
+# only tie up runners and delay the checks that matter.
+#
+# github.ref alone does NOT dedupe them: a push is refs/heads/<branch> while the
+# pull_request event is refs/pull/<n>/merge, so both ran on every push to a PR
+# branch. The pair only collapses if both sides render the same bare branch
+# name: head_ref is the source branch on a pull_request and empty on a push,
+# and ref_name is the branch name without the refs/heads/ prefix (github.ref
+# would keep it and miss the match).
+#
+# The branch name alone is not unique across repositories, though: two pull
+# requests opened from different forks on a branch both named `feature` would
+# share a group, and cancel-in-progress would have them kill each other's
+# checks. Keying on the source repo as well keeps forks apart, and still
+# collapses the push/pull_request pair for a same-repo branch, where
+# head.repo.full_name and github.repository are the same string.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.head.repo.full_name || github.repository }}-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Nothing after this step talks to GitHub, so leaving the token in
+          # .git/config only widens what a compromised dependency can reach.
+          persist-credentials: false
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Format check
+        run: ruff format --check .
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Tests
+        run: python -m pytest tests/ -v
+
+      - name: Client-side export assertions (F1)
+        run: node tests/js/test_export_sanitize.mjs
+
+      - name: Client-side render/cap assertions (P4/P5/P13)
+        run: node tests/js/test_render_caps.mjs
+
+      - name: Client-side feature assertions (Phase 4)
+        run: node tests/js/test_features.mjs
+
+      - name: Audit runtime dependencies
+        run: pip-audit -r requirements.txt

.gitignore

@@ -19,6 +19,9 @@ ENV/
 .DS_Store
 Thumbs.db
 
+# Node (test assertions only; no build step)
+node_modules/
+
 # Project specific
 *.log
 .env