add automated config drift detection

.config-audit-ignore

@@ -0,0 +1,51 @@
+# Configuration Audit Allowlist
+#
+# This file contains environment variables that are documented but not directly
+# referenced in application code. Each variable should have a comment explaining
+# why it's exempt from the unused configuration check.
+#
+# Format:
+#   # Reason for exemption
+#   VARIABLE_NAME
+#
+# Example:
+#   # Used by Docker Compose at runtime
+#   DATABASE_URL
+#
+
+# Vite environment variables are accessed through import.meta.env and may not
+# be directly referenced in source code but are used by the build process
+# VITE_STELLAR_NETWORK
+# VITE_EVENTS_API_URL
+
+# Node.js runtime environment variable
+# Used by logger and runtime detection, not always directly referenced
+NODE_ENV
+
+# Logging configuration
+# Used by Winston logger configuration
+LOG_LEVEL
+
+# ============================================================================
+# Task Bounty Contract Deployment Variables
+# These are used by deployment scripts and hardhat/truffle configuration
+# They are not referenced in smart contract source code
+# ============================================================================
+
+# Private key for contract deployment (used by deployment tools)
+PRIVATE_KEY
+
+# Ethereum RPC URLs for different networks (used by hardhat/truffle)
+MAINNET_RPC_URL
+SEPOLIA_RPC_URL
+
+# Etherscan API key for contract verification (used by hardhat-etherscan plugin)
+ETHERSCAN_API_KEY
+
+# Deployed contract addresses (documented for reference, not consumed by code)
+BOUNTY_ADDRESS
+RESOLVER_ADDRESS
+FACTORY_ADDRESS
+
+# Contract administrator address (used by deployment scripts)
+ARBITRATOR

.github/workflows/config-lint.yml

@@ -0,0 +1,84 @@
+name: Configuration Drift Detection
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+      - develop
+
+jobs:
+  config-drift:
+    name: Check for Unused Configuration Variables
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+
+      - name: Run configuration drift detection
+        id: config-check
+        run: |
+          echo "Running configuration drift detection..."
+          npm run lint:config
+        continue-on-error: true
+
+      - name: Upload results as artifact
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: config-drift-report
+          path: |
+            .config-audit-ignore
+            scripts/check-unused-config.mjs
+          retention-days: 30
+
+      - name: Comment on PR (if drift detected)
+        if: failure() && github.event_name == 'pull_request'
+        uses: actions/github-script@v6
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `## ⚠️ Configuration Drift Detected
+
+              The configuration drift detection tool found environment variables documented in \`.env.example\` files that are not referenced in the codebase.
+
+              ### Action Required
+
+              1. **Review the unreferenced variables** in the check output above
+              2. **Either:**
+                 - Remove unused variables from \`.env.example\` files
+                 - OR add them to \`.config-audit-ignore\` with a clear reason
+
+              ### How to Fix
+
+              \`\`\`bash
+              # Run locally to see details
+              npm run lint:config
+
+              # Add to allowlist if legitimately used externally
+              echo "# Reason for exemption" >> .config-audit-ignore
+              echo "VARIABLE_NAME" >> .config-audit-ignore
+              \`\`\`
+
+              📚 [Configuration Drift Detection Documentation](docs/CONFIG_DRIFT_DETECTION.md)`
+            })
+
+      - name: Fail workflow if drift detected
+        if: steps.config-check.outcome == 'failure'
+        run: |
+          echo "❌ Configuration drift detected!"
+          echo "See logs above for details or check the documentation:"
+          echo "docs/CONFIG_DRIFT_DETECTION.md"
+          exit 1

Makefile

@@ -0,0 +1,31 @@
+.PHONY: help lint-config lint-config-verbose test-lint-config
+
+help:
+	@echo "NotifyChain - Available Commands"
+	@echo ""
+	@echo "  make lint-config          - Check for unused configuration variables"
+	@echo "  make lint-config-verbose  - Check with detailed usage information"
+	@echo "  make test-lint-config     - Test the config linter with a mock unused variable"
+	@echo ""
+
+lint-config:
+	@node scripts/check-unused-config.mjs
+
+lint-config-verbose:
+	@VERBOSE=true node scripts/check-unused-config.mjs
+
+# Test the linter by temporarily adding an unused variable
+test-lint-config:
+	@echo "Testing configuration drift detection..."
+	@echo ""
+	@echo "# Test unused variable" >> listener/.env.example
+	@echo "MOCK_UNUSED_VARIABLE=test" >> listener/.env.example
+	@echo "Added MOCK_UNUSED_VARIABLE to listener/.env.example"
+	@echo ""
+	@node scripts/check-unused-config.mjs || true
+	@echo ""
+	@echo "Cleaning up test variable..."
+	@grep -v "MOCK_UNUSED_VARIABLE" listener/.env.example > listener/.env.example.tmp || true
+	@grep -v "Test unused variable" listener/.env.example.tmp > listener/.env.example || true
+	@rm -f listener/.env.example.tmp
+	@echo "Test complete!"

README.md

@@ -650,6 +650,28 @@ See [`frontend/src/components/SubscriptionForm.tsx`](frontend/src/components/Sub
 
 ---
 
+## Developer Tools
+
+### Configuration Drift Detection
+
+NotifyChain includes an automated configuration drift detection tool that identifies environment variables documented in `.env.example` files but no longer used in the codebase.
+
+**Usage:**
+```bash
+# Check for unused configuration variables
+npm run lint:config
+
+# With verbose output
+npm run lint:config:verbose
+
+# Using Make
+make lint-config
+```
+
+**Documentation:** See [CONFIG_DRIFT_DETECTION.md](docs/CONFIG_DRIFT_DETECTION.md)
+
+---
+
 ## Contributing
 
 Contributions are welcome! Please follow these steps (or start with the canonical workflow guide):
@@ -668,6 +690,11 @@ Contributions are welcome! Please follow these steps (or start with the canonica
 
 Please follow the project's coding standards and include tests where applicable.
 
+**Before committing:**
+- Run `npm run lint:config` to check for configuration drift
+- Ensure all tests pass
+- Update documentation as needed
+
 For more detailed contribution guidelines, check:
 - [`CONTRIBUTING.md`](CONTRIBUTING.md)
 - [`CONTRIBUTOR_DEVELOPMENT_WORKFLOW_GUIDE.md`](CONTRIBUTOR_DEVELOPMENT_WORKFLOW_GUIDE.md)