feat: add test suites and improve documentation

Node.js reference app:
- Add Jest configuration with coverage thresholds
- Add comprehensive health check tests with mocked dependencies
- Add configuration tests
- Add application entry point tests

TypeScript API-first reference app:
- Add Jest configuration for TypeScript with ts-jest
- Add comprehensive health check tests
- Add configuration and entry point tests
- Add supertest and @types/supertest dependencies

Documentation:
- Document AppRole secret_id renewal process with commands
- Add automated renewal instructions (crontab)
- Add renewal timeline table

Configuration:
- Fix .env.example network IPs to match 4-tier architecture
- Organize IPs by network segment (vault/data/app/observability)

Author: NormB

.env.example

@@ -26,26 +26,37 @@ VAULT_TOKEN=
 # Or leave empty and it will be read from ~/.config/vault/root-token
 
 # ===========================================================================
-# Docker Network IP Addresses (172.20.0.0/16)
+# Docker Network IP Addresses (4-Tier Segmentation)
 # ===========================================================================
-# Static IP addresses for services in the dev-services network
+# Static IP addresses for services across 4 network segments:
+#   - vault-network:        172.20.1.0/24 (secrets management)
+#   - data-network:         172.20.2.0/24 (databases, redis, rabbitmq)
+#   - app-network:          172.20.3.0/24 (forgejo, reference APIs)
+#   - observability-network: 172.20.4.0/24 (prometheus, grafana, loki)
+#
 # Change these if you need custom IP assignments or have conflicts
 #
-# Default assignments:
-POSTGRES_IP=172.20.0.10
-PGBOUNCER_IP=172.20.0.11
-MYSQL_IP=172.20.0.12
-REDIS_1_IP=172.20.0.13
-RABBITMQ_IP=172.20.0.14
-MONGODB_IP=172.20.0.15
-REDIS_2_IP=172.20.0.16
-REDIS_3_IP=172.20.0.17
-FORGEJO_IP=172.20.0.20
-VAULT_IP=172.20.0.21
-REFERENCE_API_IP=172.20.0.100
-PROMETHEUS_IP=172.20.0.101
-GRAFANA_IP=172.20.0.102
-LOKI_IP=172.20.0.103
+# Vault Network (172.20.1.x):
+VAULT_IP=172.20.1.5
+
+# Data Network (172.20.2.x):
+POSTGRES_IP=172.20.2.10
+PGBOUNCER_IP=172.20.2.11
+MYSQL_IP=172.20.2.12
+REDIS_1_IP=172.20.2.13
+RABBITMQ_IP=172.20.2.14
+MONGODB_IP=172.20.2.15
+REDIS_2_IP=172.20.2.16
+REDIS_3_IP=172.20.2.17
+
+# App Network (172.20.3.x):
+FORGEJO_IP=172.20.3.20
+REFERENCE_API_IP=172.20.3.100
+
+# Observability Network (172.20.4.x):
+PROMETHEUS_IP=172.20.4.10
+GRAFANA_IP=172.20.4.20
+LOKI_IP=172.20.4.30
 
 # ===========================================================================
 # TLS Configuration (Enabled by Default)

docs/VAULT.md

@@ -303,6 +303,57 @@ vault write -f -field=secret_id auth/approle/role/reference-api/secret-id > ~/.c
 - AppRole implementation: `reference-apps/fastapi/app/services/vault.py`
 - Docker configuration: `docker-compose.yml` (line 879)
 
+#### AppRole Secret ID Renewal
+
+**⚠️ IMPORTANT:** AppRole secret_ids have a **30-day TTL**. Services will fail to authenticate after expiry.
+
+**Check Secret ID Expiry:**
+```bash
+export VAULT_ADDR=http://localhost:8200
+export VAULT_TOKEN=$(cat ~/.config/vault/root-token)
+
+# Check remaining TTL for a service (e.g., reference-api)
+vault write auth/approle/role/reference-api/secret-id-accessor/lookup \
+  secret_id_accessor=$(cat ~/.config/vault/approles/reference-api/secret-id-accessor 2>/dev/null)
+```
+
+**Renew Secret IDs (Before Expiry):**
+```bash
+# Renew all AppRole secret_ids
+./scripts/vault-approle-bootstrap.sh --renew-secrets
+
+# Or renew for a specific service
+SERVICE=reference-api
+vault write -f -field=secret_id auth/approle/role/${SERVICE}/secret-id \
+  > ~/.config/vault/approles/${SERVICE}/secret-id
+
+# Save the accessor for future lookups
+vault write -f -field=secret_id_accessor auth/approle/role/${SERVICE}/secret-id \
+  > ~/.config/vault/approles/${SERVICE}/secret-id-accessor
+
+# Restart the service to pick up new credentials
+docker compose restart ${SERVICE}
+```
+
+**Automated Renewal (Recommended for Production):**
+
+Add to crontab to renew secret_ids weekly:
+```bash
+# Edit crontab
+crontab -e
+
+# Add this line (runs every Sunday at 3 AM)
+0 3 * * 0 cd /path/to/devstack-core && ./scripts/vault-approle-bootstrap.sh --renew-secrets >> /var/log/vault-approle-renewal.log 2>&1
+```
+
+**Renewal Timeline:**
+| Event | TTL Remaining | Action |
+|-------|---------------|--------|
+| Created | 30 days | Normal operation |
+| Week 3 | 7-14 days | Consider renewal |
+| Week 4 | < 7 days | **Renew immediately** |
+| Expired | 0 days | Service authentication fails |
+
 ### SSL/TLS Certificate Management
 
 **TLS Implementation: Pre-Generated Certificates with Vault-Based Configuration**

reference-apps/nodejs/jest.config.js

@@ -1,7 +1,25 @@
+/**
+ * Jest Configuration
+ */
+
 module.exports = {
   testEnvironment: 'node',
-  coverageDirectory: 'coverage',
-  collectCoverageFrom: ['src/**/*.js'],
   testMatch: ['**/tests/**/*.test.js'],
+  collectCoverageFrom: [
+    'src/**/*.js',
+    '!src/index.js'  // Exclude main entry point from coverage
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  coverageThreshold: {
+    global: {
+      branches: 50,
+      functions: 50,
+      lines: 50,
+      statements: 50
+    }
+  },
+  setupFilesAfterEnv: ['./tests/setup.js'],
+  testTimeout: 10000,
   verbose: true
 };

reference-apps/nodejs/tests/config.test.js

@@ -0,0 +1,92 @@
+/**
+ * Configuration Tests
+ *
+ * Tests for configuration loading and validation.
+ */
+
+describe('Configuration', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...originalEnv };
+  });
+
+  afterAll(() => {
+    process.env = originalEnv;
+  });
+
+  it('should load default configuration', () => {
+    const config = require('../src/config');
+
+    expect(config.http.port).toBe(8003);
+    expect(config.http.host).toBe('0.0.0.0');
+    expect(config.vault.address).toBe('http://vault:8200');
+    expect(config.postgres.host).toBe('postgres');
+    expect(config.mysql.host).toBe('mysql');
+    expect(config.mongodb.host).toBe('mongodb');
+    expect(config.redis.host).toBe('redis-1');
+    expect(config.rabbitmq.host).toBe('rabbitmq');
+  });
+
+  it('should load custom port from environment', () => {
+    process.env.HTTP_PORT = '9000';
+    jest.resetModules();
+    const config = require('../src/config');
+
+    expect(config.http.port).toBe(9000);
+  });
+
+  it('should load custom Vault address from environment', () => {
+    process.env.VAULT_ADDR = 'http://custom-vault:8200';
+    jest.resetModules();
+    const config = require('../src/config');
+
+    expect(config.vault.address).toBe('http://custom-vault:8200');
+  });
+
+  it('should have correct Redis cluster nodes', () => {
+    const config = require('../src/config');
+
+    expect(config.redis.nodes).toHaveLength(3);
+    expect(config.redis.nodes[0]).toEqual({ host: 'redis-1', port: 6379 });
+    expect(config.redis.nodes[1]).toEqual({ host: 'redis-2', port: 6379 });
+    expect(config.redis.nodes[2]).toEqual({ host: 'redis-3', port: 6379 });
+  });
+
+  it('should have correct application metadata', () => {
+    const config = require('../src/config');
+
+    expect(config.app.name).toBe('DevStack Core Node.js Reference API');
+    expect(config.app.language).toBe('Node.js');
+    expect(config.app.framework).toBe('Express');
+    expect(config.app.version).toBeDefined();
+  });
+
+  it('should enable debug in development', () => {
+    process.env.NODE_ENV = 'development';
+    jest.resetModules();
+    const config = require('../src/config');
+
+    expect(config.debug).toBe(true);
+  });
+
+  it('should respect DEBUG environment variable', () => {
+    process.env.NODE_ENV = 'production';
+    process.env.DEBUG = 'true';
+    jest.resetModules();
+    const config = require('../src/config');
+
+    expect(config.debug).toBe(true);
+  });
+
+  it('should parse HTTPS configuration', () => {
+    process.env.HTTPS_PORT = '8446';
+    process.env.NODEJS_API_ENABLE_TLS = 'true';
+    jest.resetModules();
+    const config = require('../src/config');
+
+    expect(config.https.port).toBe(8446);
+    expect(config.https.enabled).toBe(true);
+  });
+});