Production ready

.env.example

@@ -1,9 +1,15 @@
 # Environment Configuration Example for LyttlenGinx Application
+#
+# This file is intentionally safe to commit.
+# Do not place live secrets in this file or commit your local `.env` / `.env.*` overrides.
+# For production, inject sensitive values through Docker Swarm secrets or an external secret store.
 
 # ===============================================
 # DATABASE CONFIGURATION (REQUIRED)
 # ===============================================
-DATABASE_URL="postgresql://user:password@localhost:5432/lyttlenginx?connection_limit=20&pool_timeout=10&connect_timeout=10"
+DATABASE_URL="postgresql://lyttlenginx:<db-password>@localhost:5432/lyttlenginx?connect_timeout=360&pool_timeout=360&pool_size=1&schema=public&sslmode=no-verify"
+# If you provide `pool_size`, the runtime will mirror it into Prisma's
+# `connection_limit` setting automatically.
 
 # ===============================================
 # ADMIN CONFIGURATION (REQUIRED FOR PRODUCTION)
@@ -13,19 +19,94 @@ DATABASE_URL="postgresql://user:password@localhost:5432/lyttlenginx?connection_l
 ADMIN_EMAIL="admin@example.com"
 
 # ===============================================
-# SECURITY (REQUIRED - CHANGE THESE IN PRODUCTION!)
+# SECURITY (REQUIRED - INJECT THESE AT RUNTIME)
 # ===============================================
-# Generate secure random strings for production:
-# - Use: openssl rand -base64 32
-# API_KEY supports multiple comma-separated keys
-API_KEY="your-secure-api-key-change-this"
+# Generate strong secrets at deploy time, for example:
+#   openssl rand -base64 32
+# API_KEY supports multiple comma-separated keys.
+# Keep the real value in a Swarm secret or external secret manager.
+# API keys remain available as a temporary compatibility bridge, but bearer
+# tokens should be the default client credential format going forward.
+API_KEY="<inject-runtime-secret>"
+
+# JWT / bearer-token foundation.
+# AUTH_JWT_SECRET enables locally signed HS256 access tokens (including
+# `/auth/token` exchange from a legacy API key). For external identity providers,
+# prefer AUTH_JWT_PUBLIC_KEY plus the expected issuer/audience below.
+AUTH_JWT_SECRET="<inject-runtime-secret>"
+# AUTH_JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
+AUTH_JWT_ISSUER="lyttle-nginx"
+AUTH_JWT_AUDIENCE="lyttle-nginx-admin"
+AUTH_JWT_ALLOWED_ALGS="HS256,RS256"
+AUTH_ACCESS_TOKEN_TTL_SECONDS="900"
+
+# Temporary default identity mapping for legacy API keys during the bearer-token migration.
+# Supported RBAC roles are: viewer, operator, security-admin, platform-admin.
+AUTH_DEFAULT_ADMIN_ROLES="platform-admin"
+AUTH_DEFAULT_ADMIN_SCOPES="admin:full"
+
+# Certificate private-key encryption at rest.
+# The current build uses a local application-layer envelope-encryption provider by default.
+# Generate a strong secret, for example: openssl rand -base64 32
+# Change PRIVATE_KEY_ENCRYPTION_KEY_VERSION when you intentionally rotate the master key.
+PRIVATE_KEY_ENCRYPTION_PROVIDER="local"
+PRIVATE_KEY_ENCRYPTION_MASTER_KEY="<inject-runtime-secret>"
+PRIVATE_KEY_ENCRYPTION_KEY_VERSION="v1"
+
+# Backup encryption and integrity protection.
+# This key encrypts downloaded backup artifacts and signs their manifests.
+# Generate a strong secret, for example: openssl rand -base64 32
+BACKUP_ENCRYPTION_KEY="<inject-runtime-secret>"
+BACKUP_ENCRYPTION_KEY_VERSION="v1"
 
 # ===============================================
 # APPLICATION SETTINGS
 # ===============================================
 NODE_ENV="production"
 PORT="3000"
 
+# Restrict `nginx_custom_code` root/alias directives to approved static-content
+# prefixes. The application validates fragments against this allowlist before any
+# staged config activation occurs.
+NGINX_CUSTOM_CODE_ALLOWED_PATH_PREFIXES="/var/www,/srv/www,/etc/nginx/custom,/usr/share/nginx/html,/etc/nginx/html"
+
+# ===============================================
+# CLUSTER CONTROL-PLANE SETTINGS
+# ===============================================
+# Configure the host/address and port that peer nodes should use for inter-node
+# control-plane traffic. Do not rely on public-IP autodiscovery.
+#
+# Single-node/local example:
+#   CLUSTER_CONTROL_ADDRESS="app"
+#   CLUSTER_CONTROL_PORT="3000"
+#
+# Swarm global-mode example with host-published admin port:
+#   CLUSTER_CONTROL_ADDRESS="node-a.internal"
+#   CLUSTER_CONTROL_PORT="3003"
+#
+# You may alternatively provide CLUSTER_CONTROL_URL="http://node-a.internal:3003"
+# instead of the address/port pair.
+CLUSTER_CONTROL_ADDRESS="node-a.internal"
+CLUSTER_CONTROL_PORT="3003"
+CLUSTER_CONTROL_PROTOCOL="http"
+
+# Leader coordination lease tuning.
+# Keep the TTL comfortably larger than the renew interval so transient delays do
+# not cause avoidable leader loss.
+CLUSTER_LEASE_TTL_SECONDS="30"
+CLUSTER_LEASE_RENEW_INTERVAL_MS="10000"
+
+# Health/readiness freshness thresholds for local config apply and certificate sync.
+HEALTH_CONFIG_APPLY_MAX_AGE_MS="900000"
+HEALTH_CERTIFICATE_SYNC_MAX_AGE_MS="900000"
+
+# Metrics/alerting freshness thresholds used by /metrics and the recommended
+# Prometheus alerts documented in docs/runbooks/monitoring-alerts.md.
+METRICS_CLUSTER_OPERATION_STALE_MAX_AGE_MS="900000"
+METRICS_CLUSTER_OPERATION_FAILURE_WINDOW_MS="3600000"
+METRICS_CERTIFICATE_ORDER_STALE_MAX_AGE_MS="1800000"
+METRICS_BACKUP_MAX_AGE_MS="86400000"
+
 # ===============================================
 # CERTIFICATE MANAGEMENT SETTINGS
 # ===============================================
@@ -39,6 +120,28 @@ ALERT_THRESHOLD_DAYS="14"
 # Set to "true" to avoid rate limits during testing
 # LETSENCRYPT_STAGING="false"
 
+# ACME challenge strategy selection.
+# - auto   : production default; currently resolves to the built-in shared HTTP-01 flow
+# - http-01: force the built-in shared HTTP-01 flow explicitly
+# Wildcard orders are intentionally rejected because the hardened ACME flow must
+# not require DNS TXT changes.
+ACME_CHALLENGE_STRATEGY="auto"
+
+# Optional explicit ACME directory URL override.
+# Leave unset for the default Let's Encrypt production/staging selection.
+# ACME_DIRECTORY_URL="https://acme-v02.api.letsencrypt.org/directory"
+
+# ACME account key persistence. The application creates this key on first use and
+# reuses it for later orders instead of relying on external shell scripts.
+ACME_ACCOUNT_PRIVATE_KEY_PATH="/app/state/acme/account.pem"
+
+# Built-in HTTP-01 configuration.
+ACME_HTTP01_PROVIDER="database-http-01"
+ACME_HTTP01_PROPAGATION_SECONDS="5"
+ACME_HTTP01_VERIFICATION_TIMEOUT_MS="30000"
+ACME_HTTP01_POLL_INTERVAL_MS="2000"
+
+
 # ===============================================
 # EMAIL/SMTP CONFIGURATION (OPTIONAL - RECOMMENDED)
 # ===============================================
@@ -48,24 +151,30 @@ SMTP_HOST=""
 SMTP_PORT="587"
 SMTP_SECURE="false"
 SMTP_USER=""
-SMTP_PASS=""
+SMTP_PASS="<inject-runtime-secret-or-leave-empty>"
 ALERT_EMAIL=""
 ALERT_FROM_EMAIL=""
 
 # ===============================================
 # ALERT WEBHOOKS (OPTIONAL - RECOMMENDED)
 # ===============================================
 # Slack webhook URL for alerts
-SLACK_WEBHOOK_URL=""
+SLACK_WEBHOOK_URL="<inject-runtime-secret-or-leave-empty>"
 
 # Discord webhook URL for alerts
-DISCORD_WEBHOOK_URL=""
+DISCORD_WEBHOOK_URL="<inject-runtime-secret-or-leave-empty>"
 
 # ===============================================
 # RATE LIMITING (OPTIONAL)
 # ===============================================
 RATE_LIMIT_TTL="60"
 RATE_LIMIT_MAX="100"
 
-
-
+# ===============================================
+# SECRET-HANDLING NOTES
+# ===============================================
+# - `.env.example` is the only env file intended to be tracked in git.
+# - Keep real `.env`, `.env.production`, `.env.local`, and similar files out of version control.
+# - Prefer Docker Swarm secrets, Vault, AWS Secrets Manager, GCP Secret Manager, or equivalent.
+# - Until the application gains first-class *_FILE secret ingestion, inject runtime values from
+#   your deployment system rather than committing them to the repository.

.github/workflows/main.yml

@@ -1,16 +1,184 @@
-name: MAIN Workflow
+name: CI and Release Gates
 
 on:
+  pull_request:
+    branches:
+      - main
   push:
     branches:
       - main
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  NODE_VERSION: 24.16.0
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+  COVERAGE_MIN_LINES: '70'
+  COVERAGE_MIN_BRANCHES: '67'
+  COVERAGE_MIN_FUNCTIONS: '76'
+
+permissions:
+  contents: read
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6.4.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run CI lint gate
+        run: npm run lint:ci
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6.4.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npm run prisma:generate
+
+      - name: Run TypeScript typecheck
+        run: npm run typecheck
+
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6.4.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npm run prisma:generate
+
+      - name: Run tests with coverage gate
+        run: npm run test:coverage:ci
+
   build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6.4.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npm run prisma:generate
+
+      - name: Build application
+        run: npm run build
+
+  dependency-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6.4.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run production dependency audit
+        run: npm run audit:prod
+
+  container-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6.0.3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build container image for scanning
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          load: true
+          pull: true
+          tags: lyttle-nginx:ci-${{ github.sha }}
+
+      - name: Scan container image with Trivy
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          image-ref: lyttle-nginx:ci-${{ github.sha }}
+          format: table
+          exit-code: '1'
+          ignore-unfixed: true
+          vuln-type: os,library
+          severity: HIGH,CRITICAL
+
+  publish-image:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs:
+      - lint
+      - typecheck
+      - tests
+      - build
+      - dependency-audit
+      - container-scan
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6.0.3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Prepare container metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/lyttlenginx
+          tags: |
+            type=raw,value=main
+            type=sha,prefix=sha-
 
       - name: Login to GitHub Container Registry
         uses: docker/login-action@v3
@@ -19,8 +187,12 @@ jobs:
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Build API Docker image
-        run: docker build -t ghcr.io/lyttle-development/lyttlenginx:main -f Dockerfile .
-
-      - name: Push API Docker image to GitHub Container Registry
-        run: docker push ghcr.io/lyttle-development/lyttlenginx:main
+      - name: Build and push API Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          pull: true
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}