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,88 @@
+name: CI
+
+# Every commit is covered exactly once: a branch commit by its pull_request run,
+# a main commit by its push run.
+#
+# `push: ["**"]` alongside `pull_request` ran BOTH on every push to a PR branch.
+# The concurrency group below collapsed that pair, but collapsing means one of
+# the two is cancelled -- and GitHub attaches a cancelled check run to the head
+# commit, where it is not a success. So the PR reported `mergeable_state:
+# unstable` on every push even with CI fully green, which is indistinguishable
+# at a glance from a real failure. Not generating the duplicate beats cancelling
+# it.
+#
+# The trade-off: a branch with no pull request open gets no CI. That is the
+# intended shape -- the checks exist to gate the merge, and opening the PR is
+# what starts them.
+on:
+  push:
+    branches: ["main"]
+  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
+
+# Supersede a branch's own earlier run when a new commit lands on it: pushing
+# three times in a minute should not leave three runs competing for runners to
+# report on commits nobody is waiting for any more.
+#
+# This cancels only runs for SUPERSEDED commits, never the current head's --
+# the `on:` block above is what guarantees one run per commit, so there is no
+# same-SHA pair left to collapse. A cancelled check run lands on the old commit,
+# which is why this no longer costs the head commit its green state.
+#
+# The branch name alone is not unique across repositories: 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 keeps forks apart. head_ref is the source branch on a
+# pull_request and empty on a push; ref_name is the branch without the
+# refs/heads/ prefix (github.ref would keep it).
+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