feat: add auth checks to spec/validator and JWT_SECRET to infrastructure scripts

Add JWT_SECRET and CORS_ORIGINS to spec optional env vars, Authentication
section, and compatibility checklist. Validator now warns (not fails) when
JWT_SECRET or JWT library is missing. Infrastructure scripts generate,
rotate, and inject JWT_SECRET alongside existing DB/S3 credentials.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: baijum

docs/spec.md

@@ -85,6 +85,8 @@ Applications must support configuration via environment variables.
 | `S3_BUCKET` | Storage bucket name |
 | `S3_ACCESS_KEY` | Storage access key |
 | `S3_SECRET_KEY` | Storage secret key |
+| `JWT_SECRET` | Secret key for JWT token signing |
+| `CORS_ORIGINS` | Comma-separated allowed CORS origins |
 | `EMAIL_API_KEY` | Transactional email API key |
 | `EMAIL_FROM` | Sender email address |
 
@@ -177,6 +179,16 @@ Applications should follow basic security practices:
 - Validate input data
 - Enforce authentication where required
 
+## Authentication
+
+Applications that require user authentication should use:
+
+- **JWT tokens** (HS256) for session management
+- **bcrypt** for password hashing
+- **HTTPBearer** scheme for token transport
+
+The app-template provides this infrastructure out of the box. See the [app-template README](https://github.com/towlion/app-template#authentication) for usage.
+
 ## Compatibility Checklist
 
 To remain compatible with the Towlion platform, applications must:
@@ -195,6 +207,7 @@ To remain compatible with the Towlion platform, applications must:
 - [ ] `app/main.py` uses FastAPI
 - [ ] Python dependencies (`requirements.txt` or `pyproject.toml`) include `fastapi` and `uvicorn`
 - [ ] No hardcoded secrets in source code
+- [ ] `deploy/env.template` contains `JWT_SECRET` (if using authentication)
 
 **Runtime:**
 - [ ] Expose HTTP service on port 8000

infrastructure/create-app-credentials.sh

@@ -45,6 +45,7 @@ info "Database: $APP_DB, User: $APP_USER"
 # Generate passwords
 DB_PASSWORD=$(openssl rand -base64 24)
 S3_PASSWORD=$(openssl rand -base64 24)
+JWT_SECRET=$(openssl rand -base64 32)
 
 # PostgreSQL user creation (idempotent)
 info "Checking PostgreSQL user..."
@@ -127,6 +128,7 @@ DB_USER=${APP_USER}
 DB_PASSWORD=${DB_PASSWORD}
 S3_ACCESS_KEY=${MINIO_USER}
 S3_SECRET_KEY=${S3_PASSWORD}
+JWT_SECRET=${JWT_SECRET}
 EOF
 
 # Set permissions
@@ -143,6 +145,7 @@ info "PostgreSQL User:  ${APP_USER}"
 info "PostgreSQL DB:    ${APP_DB}"
 info "MinIO User:       ${MINIO_USER}"
 info "MinIO Bucket:     ${APP_NAME}-uploads"
+info "JWT Secret:       (generated)"
 info "Credentials File: ${CREDENTIALS_FILE}"
 echo ""
 info "✓ All credentials provisioned successfully"

infrastructure/deploy-blue-green.sh

@@ -125,6 +125,11 @@ if [ -f "$CREDENTIALS_FILE" ]; then
       && sed -i "s|^S3_BUCKET=.*|S3_BUCKET=${APP_NAME}-uploads|" deploy/.env \
       || echo "S3_BUCKET=${APP_NAME}-uploads" >> deploy/.env
   fi
+  if [ -n "${JWT_SECRET:-}" ]; then
+    grep -q "^JWT_SECRET=" deploy/.env \
+      && sed -i "s|^JWT_SECRET=.*|JWT_SECRET=${JWT_SECRET}|" deploy/.env \
+      || echo "JWT_SECRET=${JWT_SECRET}" >> deploy/.env
+  fi
   info "deploy/.env updated with per-app credentials"
 else
   warn "Per-app credentials not found at $CREDENTIALS_FILE"

infrastructure/rotate-credentials.sh

@@ -31,7 +31,8 @@ usage() {
   echo "  --type       Type of credentials to rotate (default: all)"
   echo "               db  — PostgreSQL password only"
   echo "               s3  — MinIO password only"
-  echo "               all — Both PostgreSQL and MinIO"
+  echo "               jwt — JWT secret only"
+  echo "               all — PostgreSQL, MinIO, and JWT"
   echo ""
   echo "Examples:"
   echo "  $0 todo-app"
@@ -55,8 +56,8 @@ while [ $# -gt 0 ]; do
     --type)
       shift
       ROTATE_TYPE="${1:-all}"
-      if [[ ! "$ROTATE_TYPE" =~ ^(db|s3|all)$ ]]; then
-        error "Invalid type: $ROTATE_TYPE (must be db, s3, or all)"
+      if [[ ! "$ROTATE_TYPE" =~ ^(db|s3|jwt|all)$ ]]; then
+        error "Invalid type: $ROTATE_TYPE (must be db, s3, jwt, or all)"
         usage
       fi
       ;;
@@ -174,6 +175,29 @@ if [[ "$ROTATE_TYPE" == "s3" || "$ROTATE_TYPE" == "all" ]]; then
   S3_SECRET_KEY="$NEW_S3_PASSWORD"
 fi
 
+# Rotate JWT secret
+if [[ "$ROTATE_TYPE" == "jwt" || "$ROTATE_TYPE" == "all" ]]; then
+  info "--- Rotating JWT secret ---"
+
+  NEW_JWT_SECRET=$(openssl rand -base64 32)
+
+  # Update credentials file
+  grep -q '^JWT_SECRET=' "$CREDENTIALS_FILE" \
+    && sed -i "s|^JWT_SECRET=.*|JWT_SECRET=${NEW_JWT_SECRET}|" "$CREDENTIALS_FILE" \
+    || echo "JWT_SECRET=${NEW_JWT_SECRET}" >> "$CREDENTIALS_FILE"
+  info "Credentials file updated: $CREDENTIALS_FILE"
+
+  # Update app deploy/.env
+  if [ -f "$APP_ENV_FILE" ]; then
+    grep -q '^JWT_SECRET=' "$APP_ENV_FILE" \
+      && sed -i "s|^JWT_SECRET=.*|JWT_SECRET=${NEW_JWT_SECRET}|" "$APP_ENV_FILE" \
+      || echo "JWT_SECRET=${NEW_JWT_SECRET}" >> "$APP_ENV_FILE"
+    info "App .env updated: $APP_ENV_FILE"
+  else
+    warn "App .env not found at $APP_ENV_FILE — manual update needed"
+  fi
+fi
+
 # Restart the app container to pick up new credentials
 info "--- Restarting app container ---"
 cd "/opt/apps/${APP_NAME}"

tests/fixtures/valid-app/deploy/env.template

@@ -1,3 +1,4 @@
 APP_DOMAIN=example.com
 DATABASE_URL=postgresql://user:pass@postgres:5432/app_db
 REDIS_URL=redis://redis:6379/0
+JWT_SECRET=test-secret

tests/fixtures/valid-app/requirements.txt

@@ -1,3 +1,4 @@
 fastapi>=0.100.0
 uvicorn>=0.23.0
 alembic>=1.12.0
+pyjwt>=2.8

tests/test_validator.py

@@ -92,6 +92,14 @@ def test_valid_app_has_dependencies(self):
         assert has_result(v, Result.PASS, "fastapi")
         assert has_result(v, Result.PASS, "uvicorn")
 
+    def test_valid_app_env_has_jwt_secret(self):
+        v = run_validator(VALID_APP, tier=2)
+        assert has_result(v, Result.PASS, "JWT_SECRET")
+
+    def test_missing_jwt_secret_warns(self):
+        v = run_validator(INVALID_APP, tier=2)
+        assert has_result(v, Result.WARN, "JWT_SECRET")
+
 
 class TestStrictMode:
     def test_strict_mode_treats_warnings_as_errors(self):

validator/validate.py

@@ -177,6 +177,11 @@ def _check_env_template(self):
             else:
                 self._record(Result.FAIL, f"env.template contains {var}", "not found")
 
+        if "JWT_SECRET" in content:
+            self._record(Result.PASS, "env.template contains JWT_SECRET")
+        else:
+            self._record(Result.WARN, "env.template contains JWT_SECRET", "not found (needed if using authentication)")
+
     def _check_caddyfile(self):
         content = self._read("deploy", "Caddyfile")
         if content is None:
@@ -239,6 +244,11 @@ def _check_dependencies(self):
         else:
             self._record(Result.WARN, f"{deps_file} contains alembic", "not found (only needed if using database migrations)")
 
+        if "pyjwt" in content_lower or "python-jose" in content_lower:
+            self._record(Result.PASS, f"{deps_file} contains JWT library")
+        else:
+            self._record(Result.WARN, f"{deps_file} contains JWT library", "not found (needed if using authentication)")
+
     def _check_secrets(self):
         secret_patterns = [
             (r'(?i)password\s*=\s*["\'][^"\']+["\']', "hardcoded password"),