scan-receipts/docs/SECURITY_DEPLOYMENT.md

Security & Deployment — Directory Listing & Sensitive Paths

This document explains why the app can never serve directory listings, which paths are blocked where, and how to deploy the standalone build behind nginx. It is the production hardening companion to nginx.conf.example at the repo root and to the in-app middleware policy in src/lib/http/sensitivePaths.ts.

---

1. Why the app never lists directories (by design)

The production image runs the Next.js standalone server (node server.js, see Dockerfile, stage "Production Runner"). The standalone server:

• serves only the files that were copied into the image: public/ and the compiled .next/ build output — nothing else from the repository (no src/, no root config files, no .env);
• never generates directory listings: a request to a directory path (e.g. /demo/ or /showcase/) is answered with 404/403 by Next's file router — there is no directory-index mechanism at all, unlike Apache (Options Indexes) or nginx (autoindex on);
• only responds with content when the exact URL maps to an existing file under public/ or a compiled route.

So "disable directory listing" is already the default behaviour of the stack — there is no autoindex/Options Indexes directive anywhere in this repository, and nginx.conf.example additionally sets autoindex off; for the reverse proxy (defense in depth, see §3).

2. What the app-layer middleware blocks

src/middleware.ts runs the Edge-runtime hook blockSensitivePath() (defined in src/lib/http/sensitivePaths.ts) on every request before any other processing, including before the CORS hook and before static-file serving. Blocked paths get a plain 404 ({"error":"Not found"}) — deliberately not a redirect, so an attacker cannot distinguish "blocked" from "does not exist".

The blocking policy (all case-insensitive):

Rule	Example paths blocked
Any path segment starting with a dot (dotfiles / dot-directories)	/.env, /.env.local, /.git/config, /.dockerignore, /.npmrc, /.next/…, /.next-corrupt-20260815-2345/…, /api/.env
Path-traversal segments . / ..	/%2e%2e/… (normalized), /foo/../bar
Non-web-facing directories	/node_modules/…, /drizzle/…, /scripts/…
Project / build / config filenames	/docker-compose.yml, /Dockerfile, /build_err.txt, /package.json, /package-lock.json, /tsconfig.json, /next.config.ts, /drizzle.config.ts, … at any depth
Sensitive file extensions	*.md, *.pem, *.key, *.crt, *.log at any depth
Percent-encoded traversal artefacts	/%2eenv, /%252eenv, /%5c… (encoded dot/backslash/double-encoding)

The middleware additionally blocks nothing legitimate: public/ assets (/showcase/*.png|jpg, /app-icon.jpg, icons, favicon) and the demo/ image folder match none of the patterns. The middleware matcher in src/middleware.ts excludes _next/static, _next/image, the favicon/icon files and demo/ entirely, so those are served untouched.

Note: /.env* is covered by the dotfile rule, and the .env extension rule (env.*) in the nginx config catches non-dot files like foo.env.

3. Deploying behind nginx (production)

The standalone server listens on 127.0.0.1:3000 inside the container (the Dockerfile sets PORT=3000 / HOSTNAME="0.0.0.0"). Put nginx in front of it:

1. Copy nginx.conf.example to /etc/nginx/conf.d/receipt-scanner.conf and replace the placeholders (example.com, certificate paths).
2. Obtain TLS certificates (e.g. Let's Encrypt) — the config enforces HTTPS with HSTS and refuses to serve anything over plain HTTP.
3. nginx -t && systemctl reload nginx (or docker exec nginx nginx -s reload).
4. Point the app's NEXT_PUBLIC_APP_URL at the public https:// URL.

What the proxy enforces before any request reaches the app:

• autoindex off; — directory listing is explicitly disabled;
• location ~ /\. { deny all; } — any URI containing a / + . segment (dotfiles, dot-directories) is rejected with 403 at the proxy; the single carve-out is location ^~ /.well-known/acme-challenge/ so Let's Encrypt HTTP-01 challenges keep working (^~ beats the regex location);
• location ~* \.(md|pem|key|crt|log|env.*)$ { deny all; } — sensitive file extensions rejected with 403, at any depth;
• explicit deny all locations for the known sensitive root files (docker-compose.yml, Dockerfile, tsconfig.json, next.config.ts, …);
• security headers: HSTS, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy;
• gzip for text assets;
• everything else is proxied to http://127.0.0.1:3000 with the original Host, client IP and X-Forwarded-Proto headers so the app's own HSTS and CORS logic sees the true scheme.

4. Keeping secrets out of public/ (and out of the image)

public/ is the only directory the web server ever serves directly. Rules:

• Never put .env, .env.*, keys, certificates, logs, or documentation into public/ — files there are downloadable by URL by design.
• .env*, node_modules, .next, build_err.txt, tests and drizzle are already excluded from the Docker image via .dockerignore; secrets are injected at runtime through the container's environment, not baked in.
• Treat any file you add to the repo root as potentially web-reachable by URL (.env, .git, *.md, configs, ...) — the middleware and nginx config above block those paths, but the first line of defense is not having them in public/ and not shipping them in the image at all.

5. Verification

• scripts/verify_sensitive_paths.mjs — run node --import ./scripts/register-next-server-resolve.mjs scripts/verify_sensitive_paths.mjs (plain Node, uses native TypeScript type-stripping; the small resolve hook maps next/server → next/server.js, which only plain Node needs) or npx tsx scripts/verify_sensitive_paths.mjs. It asserts the pure policy and the middleware wrapper against the blocked / allowed path battery in the file. The output ends with N checks, 0 failure(s) and exit code 0.
• npx tsc --noEmit — type-checks the new module and its wiring (clean).
• Repo scan for autoindex / Options Indexes (excluding node_modules, .next*, .git, .agents): the only hits are nginx.conf.example (autoindex off;) and this document — no web-server config in the repo enables directory listing.
• Get-ChildItem public -Recurse -Force — public/ contains only demo images, showcase images and icons; no .env, no .git, no markdown, no keys/certs/logs.