Initial commit

2025-12-26 10:48:33 -08:00
commit 97f75e144f
270 changed files with 35886 additions and 0 deletions
--- a/docs/integrations/as4-gateway-integration.md
+++ b/docs/integrations/as4-gateway-integration.md
@@ -0,0 +1,298 @@
+# AS4 Gateway Integration Documentation
+
+**Version:** 1.0  
+**Last Updated:** 2024-12-20  
+**Status:** Draft - In Progress
+
+---
+
+## Integration Overview
+
+### Purpose
+SMOA integrates with AS4 (Applicability Statement 4) gateway for secure, reliable inter-agency messaging per OASIS AS4 Profile 1.0.
+
+### Integration Type
+- **Protocol:** AS4 (ebMS 3.0 profile)
+- **Message Format:** SOAP with WS-Security
+- **Transport:** HTTPS/TLS
+- **Authentication:** Certificate-based mutual authentication
+
+### Integration Status
+- **Status:** Framework Complete
+- **Implementation:** Partial (full implementation pending Apache CXF integration)
+- **Testing:** Framework testing complete
+
+---
+
+## Integration Architecture
+
+### AS4 Message Flow
+
+```
+SMOA Application
+    ↓
+AS4 Service Layer (core:as4)
+    ↓
+AS4 Message Construction
+    ↓
+WS-Security Headers
+    ↓
+SOAP Envelope
+    ↓
+HTTPS/TLS Transport
+    ↓
+AS4 Gateway
+    ↓
+Partner System
+```
+
+### Components
+
+#### AS4 Service Layer
+- **Location:** `core/as4/src/main/java/com/smoa/core/as4/`
+- **Components:**
+  - AS4MessageBuilder
+  - AS4SecurityHandler
+  - AS4ReliabilityHandler
+  - AS4Service
+
+#### Message Models
+- **AS4Message:** Complete AS4 message structure
+- **AS4Party:** Sender/receiver party information
+- **AS4Security:** WS-Security headers
+- **AS4Reliability:** WS-ReliableMessaging headers
+
+---
+
+## Configuration
+
+### AS4 Gateway Configuration
+
+#### Endpoint Configuration
+```kotlin
+// AS4 gateway endpoint
+as4GatewayEndpoint = "https://as4-gateway.example.com/as4"
+as4GatewayCertificate = "gateway-cert.pem"
+```
+
+#### Party Configuration
+```kotlin
+// SMOA party information
+smoaPartyId = "SMOA-001"
+smoaPartyName = "Secure Mobile Operations Application"
+smoaCertificate = "smoa-cert.pem"
+```
+
+#### Security Configuration
+```kotlin
+// Security settings
+signatureAlgorithm = "RSA-SHA256"
+encryptionAlgorithm = "AES-256-GCM"
+certificateValidation = true
+mutualTLS = true
+```
+
+### Partner Configuration
+
+#### Partner Agreements (CPA)
+- **CPA Management:** Collaboration Protocol Agreement management
+- **Partner Registration:** Partner registration procedures
+- **Certificate Exchange:** Certificate exchange procedures
+- **Policy Configuration:** Policy configuration per partner
+
+---
+
+## Message Formats
+
+### AS4 Message Structure
+
+#### Message Envelope
+```xml
+<soap:Envelope>
+  <soap:Header>
+    <eb:Messaging>
+      <eb:UserMessage>
+        <eb:MessageInfo>
+          <eb:MessageId>uuid:...</eb:MessageId>
+          <eb:Timestamp>2024-12-20T12:00:00Z</eb:Timestamp>
+        </eb:MessageInfo>
+        <eb:PartyInfo>
+          <eb:From>...</eb:From>
+          <eb:To>...</eb:To>
+        </eb:PartyInfo>
+        <eb:CollaborationInfo>...</eb:CollaborationInfo>
+        <eb:PayloadInfo>...</eb:PayloadInfo>
+      </eb:UserMessage>
+    </eb:Messaging>
+    <wsse:Security>...</wsse:Security>
+    <wsrm:Sequence>...</wsrm:Sequence>
+  </soap:Header>
+  <soap:Body>...</soap:Body>
+</soap:Envelope>
+```
+
+### WS-Security Headers
+
+#### XML Digital Signature
+- **Algorithm:** RSA-SHA256
+- **Canonicalization:** Exclusive XML Canonicalization
+- **Signature Location:** SOAP header
+- **Certificate:** X.509 certificate
+
+#### XML Encryption
+- **Algorithm:** AES-256-GCM
+- **Key Transport:** RSA-OAEP
+- **Encryption Scope:** Message body
+- **Certificate:** Recipient certificate
+
+### Message Payload
+
+#### Payload Format
+- **Content Type:** Application-specific (XML, JSON, binary)
+- **Compression:** Optional compression
+- **Size Limits:** Per AS4 specification
+
+---
+
+## Message Operations
+
+### Sending Messages
+
+#### Send Message Procedure
+1. **Construct Message:** Build AS4 message
+2. **Add Security:** Add WS-Security headers
+3. **Add Reliability:** Add WS-ReliableMessaging headers
+4. **Sign Message:** Sign message with XMLDSig
+5. **Encrypt Message:** Encrypt message (if required)
+6. **Send Message:** Send via HTTPS
+7. **Wait for Receipt:** Wait for AS4 receipt
+8. **Verify Receipt:** Verify receipt signature
+
+#### Message Sending Code
+```kotlin
+val message = AS4MessageBuilder()
+    .setMessageId(UUID.randomUUID().toString())
+    .setFrom(smoaParty)
+    .setTo(partnerParty)
+    .setPayload(payload)
+    .build()
+
+val signedMessage = as4SecurityHandler.sign(message, smoaCertificate)
+val encryptedMessage = as4SecurityHandler.encrypt(signedMessage, partnerCertificate)
+
+val receipt = as4Service.sendMessage(encryptedMessage)
+```
+
+### Receiving Messages
+
+#### Receive Message Procedure
+1. **Receive Message:** Receive AS4 message
+2. **Verify Signature:** Verify XMLDSig signature
+3. **Decrypt Message:** Decrypt message (if encrypted)
+4. **Process Message:** Process message payload
+5. **Generate Receipt:** Generate AS4 receipt
+6. **Sign Receipt:** Sign receipt
+7. **Send Receipt:** Send receipt to sender
+
+### Message Receipts
+
+#### Receipt Generation
+- **Receipt Type:** AS4 non-repudiation receipt
+- **Receipt Content:** Message ID, timestamp, status
+- **Receipt Signature:** Digital signature on receipt
+- **Receipt Delivery:** Reliable delivery of receipt
+
+### Error Handling
+
+#### Error Signal Messages
+- **Error Types:** Processing errors, security errors, reliability errors
+- **Error Format:** AS4 error signal format
+- **Error Handling:** Error signal processing and response
+
+---
+
+## Security
+
+### Authentication
+- **Mutual TLS:** Certificate-based mutual authentication
+- **Certificate Validation:** Full certificate chain validation
+- **Revocation Checking:** OCSP/CRL checking
+
+### Message Security
+- **Digital Signatures:** XMLDSig on all messages
+- **Message Encryption:** XMLEnc for sensitive messages
+- **Non-Repudiation:** Receipt-based non-repudiation
+
+### Key Management
+- **Certificate Storage:** Secure certificate storage
+- **Certificate Rotation:** Certificate rotation procedures
+- **Key Exchange:** Secure key exchange procedures
+
+---
+
+## Reliability
+
+### WS-ReliableMessaging
+- **Message Ordering:** Guaranteed message ordering
+- **Duplicate Detection:** Automatic duplicate detection
+- **Acknowledgments:** Message acknowledgments
+- **Retry Logic:** Automatic retry on failure
+
+### Pull Protocol
+- **Pull Support:** AS4 pull protocol support
+- **Polling:** Message polling procedures
+- **Message Retrieval:** Secure message retrieval
+
+---
+
+## Testing
+
+### Integration Testing
+- **Test Environment:** AS4 test gateway
+- **Test Messages:** Test message scenarios
+- **Test Certificates:** Test certificates
+- **Test Procedures:** Integration test procedures
+
+### Test Scenarios
+- **Message Sending:** Test message sending
+- **Message Receiving:** Test message receiving
+- **Error Handling:** Test error scenarios
+- **Reliability:** Test reliable messaging
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### Message Sending Failures
+- **Issue:** Messages not sending
+- **Diagnosis:** Check network, certificates, configuration
+- **Resolution:** Verify connectivity, certificates, configuration
+
+#### Signature Verification Failures
+- **Issue:** Signature verification fails
+- **Diagnosis:** Check certificates, signature format
+- **Resolution:** Verify certificates, check signature format
+
+#### Receipt Not Received
+- **Issue:** Receipt not received
+- **Diagnosis:** Check message delivery, receipt generation
+- **Resolution:** Verify message delivery, check receipt generation
+
+---
+
+## References
+
+- [OASIS AS4 Profile 1.0](https://docs.oasis-open.org/ebxml-msg/ebms/v3.0/profiles/AS4-profile/v1.0/)
+- [WS-Security Specification](https://docs.oasis-open.org/wss/v1.1/)
+- [WS-ReliableMessaging Specification](https://docs.oasis-open.org/ws-rx/wsrm/200702)
+- [Architecture Documentation](../architecture/ARCHITECTURE.md)
+
+---
+
+**Document Owner:** Integration Developer  
+**Last Updated:** 2024-12-20  
+**Status:** Draft - In Progress  
+**Next Review:** 2024-12-27
+
--- a/docs/integrations/ncic-integration.md
+++ b/docs/integrations/ncic-integration.md
@@ -0,0 +1,335 @@
+# NCIC/III Integration Documentation
+
+**Version:** 1.0  
+**Last Updated:** 2024-12-20  
+**Status:** Draft - In Progress  
+**Classification:** Law Enforcement Use Only
+
+---
+
+## Integration Overview
+
+### Purpose
+SMOA integrates with NCIC (National Crime Information Center) and III (Interstate Identification Index) for law enforcement database queries.
+
+### Integration Type
+- **Protocol:** NCIC 2000 or N-DEx format
+- **Transport:** Secure VPN or dedicated line
+- **Authentication:** ORI/UCN-based authentication
+- **Authorization:** CJIS Security Policy compliance required
+
+### Integration Status
+- **Status:** Framework Complete
+- **Implementation:** Partial (pending CJIS approval and API access)
+- **Testing:** Framework testing complete
+
+---
+
+## Integration Architecture
+
+### NCIC Query Flow
+
+```
+SMOA Application
+    ↓
+NCIC Service Layer (modules:ncic)
+    ↓
+Query Construction
+    ↓
+ORI/UCN Generation
+    ↓
+Secure VPN/Dedicated Line
+    ↓
+NCIC/III Gateway
+    ↓
+NCIC/III Database
+    ↓
+Response Processing
+    ↓
+SMOA Application
+```
+
+### Components
+
+#### NCIC Service Layer
+- **Location:** `modules/ncic/src/main/java/com/smoa/modules/ncic/`
+- **Components:**
+  - NCICService
+  - NCICQueryBuilder
+  - ORI/UCN Manager
+  - ResponseProcessor
+
+---
+
+## Configuration
+
+### NCIC Gateway Configuration
+
+#### Endpoint Configuration
+```kotlin
+// NCIC gateway endpoint
+ncicGatewayEndpoint = "https://ncic-gateway.example.com/ncic"
+ncicGatewayCertificate = "ncic-cert.pem"
+```
+
+#### ORI Configuration
+```kotlin
+// Originating Agency Identifier
+ori = "XX12345" // Assigned by FBI
+oriName = "Agency Name"
+oriType = "LE" // Law Enforcement
+```
+
+#### UCN Configuration
+```kotlin
+// Unique Control Number generation
+ucnPrefix = "XX12345"
+ucnSequence = autoIncrement
+ucnFormat = "XX12345-YYYYMMDD-HHMMSS-####"
+```
+
+### CJIS Compliance Configuration
+
+#### Security Requirements
+- **Background Checks:** All operators must pass background checks
+- **Two-Factor Authentication:** Required for all operators
+- **Encryption:** All queries/responses encrypted
+- **Access Logging:** Complete access logging
+- **Audit Trail:** Comprehensive audit trail
+
+---
+
+## Query Operations
+
+### Query Types
+
+#### Person Query
+- **Query Type:** PERSON
+- **Search Criteria:** Name, DOB, SSN, etc.
+- **Response:** Person records, warrants, etc.
+
+#### Vehicle Query
+- **Query Type:** VEHICLE
+- **Search Criteria:** VIN, license plate, etc.
+- **Response:** Vehicle records, stolen vehicles, etc.
+
+#### Article Query
+- **Query Type:** ARTICLE
+- **Search Criteria:** Serial number, description, etc.
+- **Response:** Article records, stolen articles, etc.
+
+#### Other Query Types
+- **BOAT:** Boat queries
+- **GUN:** Gun queries
+- **LICENSE_PLATE:** License plate queries
+
+### Query Construction
+
+#### Query Format
+```kotlin
+val query = NCICQuery(
+    queryId = UUID.randomUUID().toString(),
+    ori = "XX12345",
+    ucn = generateUCN(),
+    queryType = NCICQueryType.PERSON,
+    searchCriteria = mapOf(
+        "firstName" to "John",
+        "lastName" to "Doe",
+        "dateOfBirth" to "1980-01-01"
+    ),
+    timestamp = Instant.now(),
+    operatorId = currentUser.id
+)
+```
+
+### Query Execution
+
+#### Execute Query Procedure
+1. **Validate Query:** Validate query parameters
+2. **Generate UCN:** Generate Unique Control Number
+3. **Construct Query:** Build NCIC query message
+4. **Encrypt Query:** Encrypt query for transmission
+5. **Send Query:** Send via secure connection
+6. **Receive Response:** Receive and decrypt response
+7. **Process Response:** Process response data
+8. **Log Query:** Log query for audit
+
+---
+
+## Response Processing
+
+### Response Types
+
+#### Hit Response
+- **Status:** HIT
+- **Content:** Matching records
+- **Action:** Process records, display to user
+
+#### No Hit Response
+- **Status:** NO_HIT
+- **Content:** No matching records
+- **Action:** Log response, inform user
+
+#### Error Response
+- **Status:** ERROR
+- **Content:** Error message
+- **Action:** Log error, inform user, retry if appropriate
+
+#### Restricted Response
+- **Status:** RESTRICTED
+- **Content:** Access restricted
+- **Action:** Log restriction, inform user
+
+### Response Processing Code
+```kotlin
+val response = ncicService.executeQuery(query)
+
+when (response.responseCode) {
+    NCICResponseCode.HIT -> {
+        // Process records
+        response.records?.forEach { record ->
+            processRecord(record)
+        }
+    }
+    NCICResponseCode.NO_HIT -> {
+        // No records found
+        logNoHit(query)
+    }
+    NCICResponseCode.ERROR -> {
+        // Handle error
+        handleError(response.message)
+    }
+    NCICResponseCode.RESTRICTED -> {
+        // Handle restriction
+        handleRestriction(response.message)
+    }
+}
+```
+
+---
+
+## ORI/UCN Management
+
+### ORI Management
+
+#### ORI Assignment
+- **Assignment:** ORI assigned by FBI
+- **Registration:** Register ORI with NCIC
+- **Validation:** Validate ORI before use
+- **Storage:** Secure ORI storage
+
+### UCN Generation
+
+#### UCN Format
+- **Format:** ORI-Date-Time-Sequence
+- **Uniqueness:** Guaranteed unique per query
+- **Validation:** UCN validation before use
+- **Storage:** UCN storage for audit
+
+#### UCN Generation Code
+```kotlin
+fun generateUCN(): String {
+    val date = LocalDate.now().format(DateTimeFormatter.BASIC_ISO_DATE)
+    val time = LocalTime.now().format(DateTimeFormatter.ofPattern("HHmmss"))
+    val sequence = ucnSequence.incrementAndGet()
+    return "$ori-$date-$time-$sequence"
+}
+```
+
+---
+
+## Security
+
+### Authentication
+- **ORI-Based:** ORI-based authentication
+- **Certificate-Based:** Certificate authentication
+- **Two-Factor:** Two-factor authentication required
+
+### Encryption
+- **Query Encryption:** All queries encrypted
+- **Response Encryption:** All responses encrypted
+- **TLS:** TLS 1.2+ for transport
+
+### Access Control
+- **Operator Authorization:** Only authorized operators
+- **Query Authorization:** Query type authorization
+- **Data Access:** Data access restrictions
+
+### Audit Logging
+- **Query Logging:** All queries logged
+- **Response Logging:** All responses logged
+- **Access Logging:** All access logged
+- **Audit Trail:** Complete audit trail
+
+---
+
+## Compliance
+
+### CJIS Security Policy
+
+#### Compliance Requirements
+- **Background Checks:** All operators
+- **Two-Factor Authentication:** Required
+- **Encryption:** All data encrypted
+- **Access Logging:** Complete logging
+- **Audit Trail:** Comprehensive audit
+
+#### Compliance Verification
+- **Regular Audits:** Regular compliance audits
+- **Policy Updates:** Policy update procedures
+- **Training:** CJIS training requirements
+- **Certification:** CJIS certification
+
+---
+
+## Testing
+
+### Test Environment
+- **Test Gateway:** NCIC test gateway
+- **Test ORI:** Test ORI assignment
+- **Test Queries:** Test query scenarios
+- **Test Procedures:** Integration test procedures
+
+### Test Scenarios
+- **Person Query:** Test person queries
+- **Vehicle Query:** Test vehicle queries
+- **Error Handling:** Test error scenarios
+- **Security:** Test security controls
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### Query Failures
+- **Issue:** Queries not executing
+- **Diagnosis:** Check network, ORI, certificates
+- **Resolution:** Verify connectivity, ORI, certificates
+
+#### Authentication Failures
+- **Issue:** Authentication fails
+- **Diagnosis:** Check ORI, certificates, credentials
+- **Resolution:** Verify ORI, certificates, credentials
+
+#### Response Processing Failures
+- **Issue:** Responses not processing
+- **Diagnosis:** Check response format, processing logic
+- **Resolution:** Verify response format, fix processing
+
+---
+
+## References
+
+- [CJIS Security Policy](https://www.fbi.gov/services/cjis/cjis-security-policy-resource-center)
+- [NCIC Documentation](https://www.fbi.gov/services/cjis/ncic)
+- [Architecture Documentation](../architecture/ARCHITECTURE.md)
+
+---
+
+**Document Owner:** Integration Developer  
+**Last Updated:** 2024-12-20  
+**Status:** Draft - In Progress  
+**Classification:** Law Enforcement Use Only  
+**Next Review:** 2024-12-27
+