feat: Add configurable local-only middleware for consistency with other services

- Added DISABLE_LOCAL_ONLY config option to allow external access when needed
- Made localOnlyMiddleware conditional based on config.disableLocalOnly
- Updated .env.example with new configuration option
- Maintains secure-by-default behavior (localhost only unless explicitly disabled)
- Consistent with school district service architecture

Author: Wal33D

.env.example

@@ -9,4 +9,10 @@ GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
 
 # Server Configuration (optional)
 PORT=3715
-NODE_ENV=development
+NODE_ENV=development
+
+# Access Control
+# Set to true to disable local-only restriction and allow external access
+# WARNING: Only set to true if you have other security measures in place!
+# DEFAULT: false (only localhost can access the API)
+DISABLE_LOCAL_ONLY=false

README.md

@@ -6,7 +6,16 @@ High-performance address validation and geocoding service using USPS and Google
 
 Provides address standardization and geocoding for the CandyComp platform. Combines USPS official address validation with Google Maps geocoding for accurate property location data. Built with TypeScript and Express, featuring token caching and optimized for real estate applications.
 
-## Quick Start
+## Features
+
+- **USPS Integration** - Official USPS Web Tools API for address standardization
+- **Google Maps Geocoding** - Forward and reverse geocoding
+- **Token Management** - Automatic USPS OAuth token refresh
+- **IP Restriction** - Security through IP whitelisting
+- **Response Caching** - In-memory caching for duplicate requests
+- **TypeScript** - Full type safety with zero errors/warnings
+
+## Installation
 
 ```bash
 # Install dependencies
@@ -16,34 +25,34 @@ npm install
 cp .env.example .env
 # Edit .env with your API credentials
 
+# Build TypeScript
+npm run build
+
 # Run development server
 npm run dev
 
 # Run production
 npm start
 ```
 
-## Configuration
-
-Required environment variables:
-
-| Variable              | Description                  | Example          |
-| --------------------- | ---------------------------- | ---------------- |
-| `PORT`                | Service port                 | `3715`           |
-| `USPS_CLIENT_ID`      | USPS Web Tools Client ID     | `your-client-id` |
-| `USPS_CLIENT_SECRET`  | USPS Web Tools Client Secret | `your-secret`    |
-| `GOOGLE_MAPS_API_KEY` | Google Maps API key          | `AIza...`        |
-| `ALLOWED_IPS`         | Comma-separated allowed IPs  | `::1,127.0.0.1`  |
+## Environment Variables
 
-## API Reference
+| Variable            | Description                  | Example        |
+| ------------------- | ---------------------------- | -------------- |
+| PORT                | Service port                 | 3715           |
+| USPS_CLIENT_ID      | USPS Web Tools Client ID     | your-client-id |
+| USPS_CLIENT_SECRET  | USPS Web Tools Client Secret | your-secret    |
+| GOOGLE_MAPS_API_KEY | Google Maps API key          | AIza...        |
+| ALLOWED_IPS         | Comma-separated allowed IPs  | ::1,127.0.0.1  |
+| NODE_ENV            | Environment mode             | production     |
 
-### Endpoints
+## API Endpoints
 
-#### `POST /validate`
+### `POST /validate`
 
 Validate and standardize an address
 
-**Request Body:**
+**Request:**
 
 ```json
 {
@@ -72,11 +81,11 @@ Validate and standardize an address
 }
 ```
 
-#### `POST /geocode`
+### `POST /geocode`
 
 Forward geocode an address
 
-**Request Body:**
+**Request:**
 
 ```json
 {
@@ -95,11 +104,11 @@ Forward geocode an address
 }
 ```
 
-#### `POST /reverse-geocode`
+### `POST /reverse-geocode`
 
 Get address from coordinates
 
-**Request Body:**
+**Request:**
 
 ```json
 {
@@ -120,7 +129,7 @@ Get address from coordinates
 }
 ```
 
-#### `GET /health`
+### `GET /health`
 
 Health check endpoint
 
@@ -135,9 +144,14 @@ npm run type-check
 
 # Linting
 npm run lint
+npm run lint:fix
 
 # Format code
 npm run format
+npm run format:check
+
+# Clean build
+npm run clean
 ```
 
 ## Testing
@@ -155,15 +169,6 @@ npm run test:watch
 
 ## Architecture
 
-### Key Features
-
-- **USPS Integration**: Official USPS Web Tools API for address standardization
-- **Google Maps API**: Geocoding and reverse geocoding
-- **Token Management**: Automatic USPS OAuth token refresh
-- **IP Restriction**: Security through IP whitelisting
-- **Error Handling**: Comprehensive error handling with fallbacks
-- **Response Caching**: In-memory caching for duplicate requests
-
 ### Service Flow
 
 1. Receive address validation request
@@ -172,19 +177,85 @@ npm run test:watch
 4. Geocode through Google Maps
 5. Return standardized address with coordinates
 
-## Deployment
+### Key Components
+
+- **USPS Client** - Handles OAuth token management and API calls
+- **Google Maps Client** - Geocoding and reverse geocoding
+- **Cache Manager** - In-memory caching for performance
+- **IP Middleware** - Security through IP whitelisting
+- **Error Handler** - Comprehensive error handling with fallbacks
 
-Runs as a local service on port 3715:
+## Production Deployment
+
+### Using PM2
 
 ```bash
-# Start service
-npm start
+# Build for production
+npm run build
 
-# Using PM2
+# Start with PM2
 pm2 start ecosystem.config.js
-pm2 logs address-validation-service
+
+# Monitor
+pm2 monit
+
+# View logs
+pm2 logs service-address-validation
+
+# Restart
+pm2 restart service-address-validation
 ```
 
+### Manual Start
+
+```bash
+npm start
+```
+
+## GitHub Actions Deployment
+
+The repository includes a GitHub Actions workflow that automatically builds and deploys the service when you push to the `main` branch.
+
+### Required GitHub Secrets
+
+Configure these secrets in your GitHub repository settings:
+
+#### SSH Connection
+
+- `LINODE_HOST` - Server IP or hostname
+- `LINODE_USERNAME` - SSH username (e.g., `puppeteer-user`)
+- `LINODE_PASSWORD` - SSH password for authentication
+
+#### Application Environment
+
+- `USPS_CLIENT_ID` - USPS Web Tools Client ID
+- `USPS_CLIENT_SECRET` - USPS Web Tools Client Secret
+- `GOOGLE_MAPS_API_KEY` - Google Maps API key
+- `ALLOWED_IPS` - Comma-separated allowed IPs
+- `NODE_ENV` - Environment setting (e.g., `production`)
+
+### Deployment Process
+
+1. Builds TypeScript project
+2. Copies built files to server
+3. Creates `.env` file from GitHub secrets
+4. Installs production dependencies
+5. Restarts PM2 process
+
+## Performance
+
+- **Caching** - In-memory cache for duplicate requests
+- **Token Reuse** - USPS OAuth tokens cached until expiry
+- **Connection Pooling** - Optimized HTTP connections
+- **Async Processing** - Non-blocking operations
+
+## Security
+
+- **IP Whitelisting** - Only configured IPs can access
+- **Input Validation** - All inputs validated before processing
+- **Error Sanitization** - Sensitive data removed from error responses
+- **Rate Limiting** - Built-in request throttling
+
 ## License
 
 © 2024 Waleed Judah. All rights reserved.

src/config/index.ts

@@ -11,6 +11,7 @@ interface Config {
   // Server
   port: number;
   nodeEnv: string;
+  disableLocalOnly: boolean;
 
   // USPS API
   usps: {
@@ -63,6 +64,7 @@ function validateConfig(): Config {
   return {
     port: parseInt(process.env['PORT'] || '3715', 10),
     nodeEnv: process.env['NODE_ENV'] || 'development',
+    disableLocalOnly: process.env['DISABLE_LOCAL_ONLY'] === 'true',
 
     usps: {
       tokenUrl: process.env['USPS_TOKEN_URL']!,

src/server.ts

@@ -870,8 +870,10 @@ if (config.nodeEnv === 'production' || process.env['ENABLE_SECURITY'] === 'true'
   app.use(...securityMiddleware());
 }
 
-// Local only middleware
-app.use(localOnlyMiddleware);
+// Apply local-only middleware for actual API endpoints (unless disabled)
+if (!config.disableLocalOnly) {
+  app.use(localOnlyMiddleware);
+}
 
 // Cache stats endpoint
 app.get('/cache/stats', (_req: Request, res: Response) => {