Initial commit: add .gitignore and README

2026-02-09 21:51:45 -08:00
commit 929fe6f6b6
240 changed files with 40977 additions and 0 deletions
--- a/docs/deployment/deployment.md
+++ b/docs/deployment/deployment.md
@@ -0,0 +1,239 @@
+# Deployment Guide
+
+## Prerequisites
+
+- Node.js 18+ installed
+- PostgreSQL 14+ installed and running
+- Redis 6+ (optional, for session management)
+- SSL certificates (for mTLS, if required by receiver)
+
+## Step 1: Install Dependencies
+
+```bash
+npm install
+```
+
+## Step 2: Database Setup
+
+### Create Database
+
+```bash
+createdb dbis_core
+```
+
+### Run Schema
+
+```bash
+psql -d dbis_core -f src/database/schema.sql
+```
+
+Or using the connection string:
+
+```bash
+psql $DATABASE_URL -f src/database/schema.sql
+```
+
+### Seed Initial Operators
+
+```sql
+-- Example: Create a Maker operator
+INSERT INTO operators (operator_id, name, password_hash, role)
+VALUES (
+  'MAKER001',
+  'John Maker',
+  '$2a$10$YourHashedPasswordHere', -- Use bcrypt hash
+  'MAKER'
+);
+
+-- Example: Create a Checker operator
+INSERT INTO operators (operator_id, name, password_hash, role)
+VALUES (
+  'CHECKER001',
+  'Jane Checker',
+  '$2a$10$YourHashedPasswordHere', -- Use bcrypt hash
+  'CHECKER'
+);
+```
+
+To generate password hashes:
+
+```bash
+node -e "const bcrypt = require('bcryptjs'); bcrypt.hash('yourpassword', 10).then(console.log);"
+```
+
+## Step 3: Configuration
+
+Create a `.env` file in the project root:
+
+```env
+NODE_ENV=production
+PORT=3000
+
+# Database
+DATABASE_URL=postgresql://user:password@localhost:5432/dbis_core
+
+# Redis (optional)
+REDIS_URL=redis://localhost:6379
+
+# JWT
+JWT_SECRET=your-secure-random-secret-key-change-this
+JWT_EXPIRES_IN=8h
+
+# Receiver Configuration
+RECEIVER_IP=172.67.157.88
+RECEIVER_PORT=443
+RECEIVER_SNI=devmindgroup.com
+RECEIVER_TLS_VERSION=TLSv1.3
+
+# Client Certificates (for mTLS, if required)
+CLIENT_CERT_PATH=/path/to/client.crt
+CLIENT_KEY_PATH=/path/to/client.key
+CA_CERT_PATH=/path/to/ca.crt
+
+# Compliance
+COMPLIANCE_TIMEOUT=5000
+
+# Audit
+AUDIT_RETENTION_YEARS=7
+LOG_LEVEL=info
+```
+
+## Step 4: Build
+
+```bash
+npm run build
+```
+
+This creates the `dist/` directory with compiled JavaScript.
+
+## Step 5: Start Server
+
+### Production
+
+```bash
+npm start
+```
+
+### Development
+
+```bash
+npm run dev
+```
+
+## Step 6: Verify Deployment
+
+1. Check health endpoint:
+   ```bash
+   curl http://localhost:3000/health
+   ```
+
+2. Access terminal UI:
+   ```
+   http://localhost:3000
+   ```
+
+3. Test login:
+   ```bash
+   curl -X POST http://localhost:3000/api/auth/login \
+     -H "Content-Type: application/json" \
+     -d '{"operatorId":"MAKER001","password":"yourpassword","terminalId":"TERM-001"}'
+   ```
+
+## Docker Deployment (Optional)
+
+Create a `Dockerfile`:
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY . .
+RUN npm run build
+
+EXPOSE 3000
+
+CMD ["npm", "start"]
+```
+
+Build and run:
+
+```bash
+docker build -t dbis-core-lite .
+docker run -p 3000:3000 --env-file .env dbis-core-lite
+```
+
+## Production Considerations
+
+1. **Security**:
+   - Use strong JWT_SECRET
+   - Enable HTTPS/TLS
+   - Configure firewall rules
+   - Regular security updates
+
+2. **Monitoring**:
+   - Set up application monitoring (e.g., Prometheus, DataDog)
+   - Monitor database connections
+   - Monitor TLS connection health
+   - Set up alerting for failed payments
+
+3. **Backup**:
+   - Regular database backups
+   - Backup audit logs
+   - Test restore procedures
+
+4. **High Availability**:
+   - Run multiple instances behind load balancer
+   - Use connection pooling
+   - Configure database replication
+
+5. **Logging**:
+   - Centralized logging (e.g., ELK stack)
+   - Log rotation configured
+   - Retention policy enforced
+
+## Troubleshooting
+
+### Database Connection Issues
+
+- Verify DATABASE_URL is correct
+- Check PostgreSQL is running
+- Verify network connectivity
+- Check firewall rules
+
+### TLS Connection Issues
+
+- Verify receiver IP and port
+- Check certificate paths (if mTLS)
+- Verify SNI configuration
+- Check TLS version compatibility
+
+### Payment Processing Issues
+
+- Check compliance screening status
+- Verify ledger adapter connection
+- Review audit logs
+- Check reconciliation reports
+
+## Maintenance
+
+### Daily Tasks
+
+- Review reconciliation reports
+- Check for aging items
+- Monitor exception queue
+
+### Weekly Tasks
+
+- Review audit log integrity
+- Check system health metrics
+- Review security logs
+
+### Monthly Tasks
+
+- Archive old audit logs
+- Review operator access
+- Update compliance lists
--- a/docs/deployment/disaster-recovery.md
+++ b/docs/deployment/disaster-recovery.md
@@ -0,0 +1,152 @@
+# Disaster Recovery Procedures
+
+## Overview
+
+This document outlines procedures for disaster recovery and business continuity for the DBIS Core Lite payment system.
+
+## Recovery Objectives
+
+- **RTO (Recovery Time Objective)**: 4 hours
+- **RPO (Recovery Point Objective)**: 1 hour (data loss tolerance)
+
+## Backup Strategy
+
+### Database Backups
+
+**Full Backup:**
+- Frequency: Daily at 02:00 UTC
+- Retention: 30 days
+- Location: Secure backup storage
+- Format: Compressed SQL dump
+
+**Transaction Log Backups:**
+- Frequency: Every 15 minutes
+- Retention: 7 days
+- Used for point-in-time recovery
+
+### Audit Log Backups
+
+- Frequency: Daily
+- Retention: 10 years (compliance requirement)
+- Format: CSV export + database dump
+
+### Configuration Backups
+
+- All configuration files (env, certificates) backed up daily
+- Version controlled in secure repository
+
+## Recovery Procedures
+
+### Full System Recovery
+
+1. **Prerequisites:**
+   - Access to backup storage
+   - Database server available
+   - Application server available
+
+2. **Steps:**
+   ```bash
+   # 1. Restore database
+   gunzip < backups/dbis_core_YYYYMMDD.sql.gz | psql $DATABASE_URL
+   
+   # 2. Run migrations
+   npm run migrate
+   
+   # 3. Restore configuration
+   cp backups/.env.production .env
+   
+   # 4. Restore certificates
+   cp -r backups/certs/* ./certs/
+   
+   # 5. Start application
+   npm start
+   ```
+
+### Point-in-Time Recovery
+
+1. Restore full backup to recovery server
+2. Apply transaction logs up to desired point
+3. Verify data integrity
+4. Switch traffic to recovered system
+
+### Partial Recovery (Single Table)
+
+```sql
+-- Restore specific table
+pg_restore -t payments -d dbis_core backups/dbis_core_YYYYMMDD.dump
+```
+
+## Disaster Scenarios
+
+### Database Server Failure
+
+**Procedure:**
+1. Identify failure (health check, monitoring alerts)
+2. Activate standby database or restore from backup
+3. Update connection strings
+4. Restart application
+5. Verify operations
+
+### Application Server Failure
+
+**Procedure:**
+1. Deploy application to backup server
+2. Update load balancer configuration
+3. Verify health checks
+4. Monitor for issues
+
+### Network Partition
+
+**Procedure:**
+1. Identify affected components
+2. Route traffic around partition
+3. Monitor reconciliation for missed transactions
+4. Reconcile when connectivity restored
+
+### Data Corruption
+
+**Procedure:**
+1. Identify corrupted data
+2. Isolate affected records
+3. Restore from backup
+4. Replay transactions if needed
+5. Verify data integrity
+
+## Testing
+
+### Disaster Recovery Testing
+
+**Schedule:**
+- Full DR test: Quarterly
+- Partial DR test: Monthly
+- Backup restore test: Weekly
+
+**Test Scenarios:**
+1. Database server failure
+2. Application server failure
+3. Network partition
+4. Data corruption
+5. Complete site failure
+
+## Communication Plan
+
+During disaster:
+1. Notify technical team immediately
+2. Activate on-call engineer
+3. Update status page
+4. Communicate with stakeholders
+
+## Post-Recovery
+
+1. Document incident
+2. Review recovery time and process
+3. Update procedures if needed
+4. Conduct post-mortem
+5. Implement improvements
+
+## Contacts
+
+- **Primary On-Call**: [Contact]
+- **Secondary On-Call**: [Contact]
+- **Database Team**: [Contact]
+- **Infrastructure Team**: [Contact]
--- a/docs/deployment/package-update-guide.md
+++ b/docs/deployment/package-update-guide.md
@@ -0,0 +1,149 @@
+# Package Update Recommendations
+
+## ✅ Current Status
+- **0 security vulnerabilities** found
+- All packages are at their "wanted" versions (within semver range)
+- System is stable and secure
+
+## 📋 Update Recommendations
+
+### ⚠️ **DO NOT UPDATE** (Critical Dependencies)
+
+1. **prom-client** (13.2.0 → 15.1.3)
+   - **Reason**: Required for `express-prometheus-middleware@1.2.0` compatibility
+   - **Status**: Keep at 13.2.0 (peer dependency conflict would occur)
+
+### 🔄 **Major Version Updates** (Require Testing & Code Review)
+
+These major version updates have breaking changes and should be carefully evaluated:
+
+2. **express** (4.22.1 → 5.2.1) - **Major**
+   - Breaking changes in Express 5.x
+   - Requires thorough testing of all routes and middleware
+   - Recommendation: **Defer** until Express 5.x ecosystem is mature
+
+3. **helmet** (7.2.0 → 8.1.0) - **Major**
+   - Security middleware - needs careful testing
+   - Recommendation: **Update with testing** (security-related)
+
+4. **jest** (29.7.0 → 30.2.0) - **Major**
+   - Testing framework - breaking changes possible
+   - Recommendation: **Update in test branch first**
+
+5. **uuid** (9.0.1 → 13.0.0) - **Major**
+   - Multiple major versions jumped
+   - Recommendation: **Update carefully** (API changes likely)
+
+6. **zod** (3.25.76 → 4.2.1) - **Major**
+   - Schema validation - used extensively
+   - Recommendation: **Update with testing** (breaking changes in v4)
+
+7. **redis** (4.7.1 → 5.10.0) - **Major**
+   - Database client - critical dependency
+   - Recommendation: **Update with extensive testing**
+
+8. **joi** (17.13.3 → 18.0.2) - **Major**
+   - Validation library - used in gateway
+   - Recommendation: **Update with testing** (API may have changed)
+
+9. **dotenv** (16.6.1 → 17.2.3) - **Major**
+   - Environment variables - simple library
+   - Recommendation: **Safe to update** (likely minimal breaking changes)
+
+10. **bcryptjs** (2.4.3 → 3.0.3) - **Major**
+    - Password hashing - security critical
+    - Recommendation: **Update with testing** (verify hash compatibility)
+
+### 🔧 **Dev Dependencies** (Safer to Update)
+
+11. **@types/node** (20.19.27 → 25.0.3) - **Major**
+    - Type definitions only
+    - Recommendation: **Update gradually** (may need code changes)
+
+12. **@types/express** (4.17.25 → 5.0.6) - **Major**
+    - Type definitions for Express 5
+    - Recommendation: **Only update if Express is updated**
+
+13. **@types/jest** (29.5.14 → 30.0.0) - **Major**
+    - Type definitions only
+    - Recommendation: **Update if Jest is updated**
+
+14. **@types/uuid** (9.0.8 → 10.0.0) - **Major**
+    - Type definitions only
+    - Recommendation: **Update if uuid is updated**
+
+15. **@typescript-eslint/*** (6.21.0 → 8.50.1) - **Major**
+    - ESLint plugins - dev tooling
+    - Recommendation: **Update with config review**
+
+16. **eslint** (8.57.1 → 9.39.2) - **Major**
+    - Linting tool - dev dependency
+    - Recommendation: **Update with config migration** (ESLint 9 has flat config)
+
+17. **supertest** (6.3.4 → 7.1.4) - **Major**
+    - Testing library
+    - Recommendation: **Update with test review**
+
+18. **winston-daily-rotate-file** (4.7.1 → 5.0.0) - **Major**
+    - Logging utility
+    - Recommendation: **Update with testing**
+
+## 🎯 Recommended Update Strategy
+
+### Phase 1: Low-Risk Updates (Can do now)
+- `dotenv` → 17.2.3 (simple env var loader)
+
+### Phase 2: Medium-Risk Updates (Test first)
+- `helmet` → 8.1.0 (security middleware)
+- `winston-daily-rotate-file` → 5.0.0 (logging)
+- `bcryptjs` → 3.0.3 (with hash compatibility testing)
+
+### Phase 3: Higher-Risk Updates (Require extensive testing)
+- `zod` → 4.2.1 (validation schema changes)
+- `joi` → 18.0.2 (validation changes)
+- `redis` → 5.10.0 (client API changes)
+- `uuid` → 13.0.0 (API changes)
+
+### Phase 4: Framework Updates (Major refactoring)
+- `express` → 5.2.1 (requires route/middleware review)
+- `jest` → 30.2.0 (test framework changes)
+- ESLint ecosystem → v9 (config migration needed)
+
+## 📝 Update Process
+
+1. **Create feature branch** for each update category
+2. **Update package.json** with new version
+3. **Run `npm install`**
+4. **Fix compilation errors** (TypeScript/imports)
+5. **Run test suite** (`npm test`)
+6. **Manual testing** of affected functionality
+7. **Code review**
+8. **Merge to main**
+
+## ⚡ Quick Update Script
+
+To update specific packages safely:
+
+```bash
+# Update single package
+npm install package@latest
+
+# Update and test
+npm install package@latest && npm test
+
+# Check for breaking changes
+npm outdated package
+```
+
+## 🔒 Security Priority
+
+If security vulnerabilities are found:
+1. **Critical/High**: Update immediately (even if major version)
+2. **Medium**: Update in next maintenance window
+3. **Low**: Update in regular cycle
+
+---
+
+**Last Updated**: 2025-12-28
+**Current Status**: ✅ All packages secure, no vulnerabilities
+
--- a/docs/deployment/start-server.md
+++ b/docs/deployment/start-server.md
@@ -0,0 +1,73 @@
+# Starting the Development Server
+
+## Quick Start
+
+1. **Start the server:**
+   ```bash
+   npm run dev
+   ```
+
+2. **Wait for startup message:**
+   ```
+   DBIS Core Lite server started on port 3000
+   Terminal UI: http://localhost:3000
+   ```
+
+3. **Access the terminal:**
+   - Open browser: http://localhost:3000
+   - The IBM 800 Terminal UI will load
+
+## Troubleshooting
+
+### Connection Refused Error
+
+If you see `ERR_CONNECTION_REFUSED`:
+
+1. **Check if server is running:**
+   ```bash
+   lsof -i :3000
+   # or
+   netstat -tuln | grep 3000
+   ```
+
+2. **Check for errors in terminal:**
+   - Look for database connection errors
+   - Check configuration validation errors
+   - Verify JWT_SECRET is set (minimum 32 characters)
+
+3. **Verify database is running:**
+   ```bash
+   psql -U postgres -d dbis_core -c "SELECT 1;"
+   ```
+
+4. **Check environment variables:**
+   - Create `.env` file if needed
+   - Ensure `DATABASE_URL` is correct
+   - Ensure `JWT_SECRET` is at least 32 characters
+
+### Common Issues
+
+- **Database connection failed**: Ensure PostgreSQL is running and accessible
+- **Configuration validation failed**: Check JWT_SECRET length (min 32 chars)
+- **Port already in use**: Change PORT in .env or kill existing process
+
+## Environment Variables
+
+Create a `.env` file with:
+
+```env
+NODE_ENV=development
+PORT=3000
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/dbis_core
+JWT_SECRET=your-secret-key-must-be-at-least-32-characters-long
+```
+
+## Server Endpoints
+
+Once running:
+- **Terminal UI**: http://localhost:3000
+- **API**: http://localhost:3000/api/v1
+- **Swagger Docs**: http://localhost:3000/api-docs
+- **Health Check**: http://localhost:3000/health
+- **Metrics**: http://localhost:3000/metrics
+
--- a/docs/deployment/test-database-setup.md
+++ b/docs/deployment/test-database-setup.md
@@ -0,0 +1,84 @@
+# Test Database Setup - Quick Reference
+
+## ✅ Setup Complete
+
+The test database configuration files have been created:
+- `.env.test` - Test environment variables (create/edit with your credentials)
+- `.env.test.example` - Example configuration
+- `jest.config.js` - Jest configuration with environment loading
+- `tests/load-env.ts` - Environment loader for tests
+
+## 🚀 Quick Start
+
+### Step 1: Create Test Database
+
+```bash
+createdb dbis_core_test
+```
+
+**Or with Docker:**
+```bash
+docker run --name dbis-postgres-test \
+  -e POSTGRES_PASSWORD=postgres \
+  -e POSTGRES_USER=postgres \
+  -p 5432:5432 \
+  -d postgres:15
+
+sleep 5
+docker exec -i dbis-postgres-test psql -U postgres -c "CREATE DATABASE dbis_core_test;"
+```
+
+### Step 2: Update .env.test
+
+Edit `.env.test` with your PostgreSQL credentials:
+
+```bash
+TEST_DATABASE_URL=postgresql://USERNAME:PASSWORD@localhost:5432/dbis_core_test
+```
+
+### Step 3: Run Migrations
+
+```bash
+export TEST_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/dbis_core_test"
+DATABASE_URL=$TEST_DATABASE_URL npm run migrate
+```
+
+### Step 4: Run Tests
+
+```bash
+npm test
+```
+
+## 📝 Files Created
+
+1. **`.env.test`** - Test environment configuration (you may need to update credentials)
+2. **`jest.config.js`** - Jest configuration that loads .env.test
+3. **`tests/load-env.ts`** - Loads environment variables before tests
+4. **`scripts/setup-test-db.sh`** - Automated setup script (requires PostgreSQL running)
+5. **`scripts/quick-test-setup.sh`** - Quick reference script
+6. **`README_TEST_DATABASE.md`** - Detailed setup guide
+
+## 🔍 Verify Setup
+
+```bash
+# Check database exists
+psql -U postgres -l | grep dbis_core_test
+
+# Check tables
+psql -U postgres -d dbis_core_test -c "\dt"
+
+# Run a test
+npm test -- tests/validation/payment-validation.test.ts
+```
+
+## ⚠️ Notes
+
+- The `.env.test` file uses default PostgreSQL credentials (`postgres/postgres`)
+- Update `.env.test` if your PostgreSQL uses different credentials
+- The test database will be truncated between test runs
+- Never use your production database as the test database
+
+---
+
+**Next:** Run `npm test` to execute the full test suite!
+