# Implementation Notes - Sender ID API

## Key Changes and Implementation Details

This document outlines the changes made to implement the Sender ID API with IP whitelisting and no modifications to the existing Deywuro database tables.

### 1. Database Structure

We've created a completely independent tracking system for Sender ID requests with:

- **New tables in our API database:**
  - `sender_id_requests` - Tracks all API requests for sender IDs
  - `ip_whitelist` - Stores authorized IP addresses for clients
  - Other supporting tables for API keys, logs, etc.

- **No modifications to Deywuro database:**
  - We use read-only access to the `users` table for authentication
  - We read the `user_sender_ids` table to check for existing IDs
  - We don't need to add any columns to these tables

### 2. IP Whitelist Implementation

We've implemented a comprehensive IP whitelisting system:

- **IPWhitelist model:**
  - Checks if an IP address is allowed for a client
  - Provides functions to add/remove/list IPs
  - Only allows whitelisted IPs to access the API once whitelist exists

- **Whitelist exemptions:**
  - Whitelist management endpoints are exempt from whitelist requirements
  - This allows clients to add their IP to the whitelist even if they're not currently in it
  - Provides a way for new clients to set up their security

### 3. Client Authentication Flow

The updated authentication flow:

1. Client provides API key in Authorization header
2. System validates API key and retrieves client_id
3. System checks if IP is whitelisted for the client
4. If IP check passes, normal rate limiting applies
5. Request is processed if all security checks pass

### 4. Database Connection Setup

We've configured the system to work with two separate databases:

- **API Database (Local):**
  - Contains all API-specific tables
  - Stores API keys, IP whitelists, and request tracking info
  - Configuration defined in PRIMARY_DB_* constants

- **Deywuro Database (Remote):**
  - Contains user data and existing sender IDs
  - Read-only access for our API
  - Configuration defined in PRIMARY_DB_* constants

### 5. Test Tools and Setup Scripts

We've created comprehensive testing tools:

- **db-test.php:**
  - Tests connections to both databases
  - Verifies table existence and permissions
  - Provides clear error messages for troubleshooting

- **test-api.php:**
  - Command-line tool to test API functionality
  - Supports different test modes: sender_id, ip_whitelist, api_key
  - Demonstrates proper API usage

- **LOCAL_SETUP.md:**
  - Detailed setup instructions for local development
  - Step-by-step guide for database configuration
  - Troubleshooting tips

### 6. Security Enhancements

Additional security features implemented:

- **IP-based security:**
  - Optional whitelist for authorized IPs
  - Automatically activated when first IP is added
  - Prevents API key usage from unauthorized locations

- **Whitelist management endpoints:**
  - `/whitelist/add` - Add an IP to the whitelist
  - `/whitelist/remove` - Remove an IP from the whitelist
  - `/whitelist` - List all whitelisted IPs

### 7. Documentation Updates

Documentation has been expanded to include:

- **IP whitelist usage and best practices**
- **Updated error codes including UNAUTHORIZED_IP**
- **New whitelist management endpoints**
- **Local setup instructions with both databases**

## How the System Works

1. **Client Sends Request:**
   - Request includes API key in Authorization header
   - Request arrives from client's IP address

2. **Authentication & Security:**
   - System validates API key
   - System checks if IP is in the client's whitelist
   - System applies rate limiting

3. **Sender ID Request Creation:**
   - Client request is validated
   - User credentials are checked in Deywuro database
   - System checks for duplicate sender IDs
   - Record is created in the API's `sender_id_requests` table
   - Status changes are tracked in our tables

4. **Status Retrieval & Updates:**
   - System reads status from our database
   - Webhook notifications use our database records
   - All queries only read from Deywuro database, never modify

## Best Practices for API Usage

1. **IP Whitelist Management:**
   - Add your IP to the whitelist immediately after getting an API key
   - Keep your whitelist updated when changing network infrastructure
   - Remove unused or old IPs from the whitelist

2. **Database Configuration:**
   - Use separate credentials for API database and Deywuro database
   - Apply least-privilege principle to the Deywuro database credentials
   - Regularly test database connections with the provided scripts

3. **Testing and Deployment:**
   - Use the db-test.php script to verify database connections
   - Use the test-api.php script to test API functionality
   - Follow security recommendations in LOCAL_SETUP.md