# Security Practices — Kordant Android

> **Last updated:** 2026-06-01  
> **Package:** `com.kordant.android`  
> **Purpose:** Document security practices for Play Store Data Safety form and user transparency

---

## 1. Encryption in Transit

### TLS Configuration

All network communication between the Kordant Android app and backend servers is encrypted using **TLS 1.2 or higher**.

**Implementation:**
- `network_security_config.xml` enforces `cleartextTrafficPermitted="false"` for all domains
- Debug builds allow cleartext for local development via `<debug-overrides>`
- API base URL uses HTTPS (`https://api.kordant.com`)

### Certificate Pinning

The Android app implements **SHA-256 certificate pinning** for production and staging domains:

| Domain | Pin 1 (Primary) | Pin 2 (Backup) |
|--------|----------------|----------------|
| `api.kordant.com` | Primary SHA-256 hash | Backup SHA-256 hash |
| `staging.api.kordant.com` | Staging SHA-256 hash | Staging backup SHA-256 hash |

**File:** `res/xml/network_security_config.xml`

**Rotation:** Pins include a backup for graceful certificate rotation. Update pins before certificate expiry. Expiration set to 2027-06-01.

### TLS Enforcement Points

| Component | Enforcement |
|-----------|------------|
| OkHttpClient | HTTPS URLs only (BuildConfig.API_BASE_URL) |
| AUTH interceptor | All auth requests via HTTPS |
| API service | Retrofit base URL uses HTTPS |
| Image loading | Coil via OkHttp with TLS |

---

## 2. Encryption at Rest

### EncryptedSharedPreferences

All sensitive data is stored in **EncryptedSharedPreferences** using:

| Property | Value |
|----------|-------|
| **Key encryption** | AES256-SIV (deterministic, allows key lookup) |
| **Value encryption** | AES256-GCM (authenticated encryption) |
| **Master key** | Android Keystore (`MasterKey.Builder` with `KeyScheme.AES256_GCM`) |
| **Library** | `androidx.security:security-crypto` |

### Data Stored Encrypted

| Data | Key | File |
|------|-----|------|
| Access token | `access_token` | `SecureStorageManager.kt` |
| Refresh token | `refresh_token` | `SecureStorageManager.kt` |
| User profile (PII) | `user_profile_json` | `SecureStorageManager.kt` |
| FCM device token | `fcm_device_token` | `SecureStorageManager.kt` |
| Biometric preference | `biometric_enabled` | `SecureStorageManager.kt` |

### Non-Sensitive Data (Unencrypted)

User preferences that do not contain PII are stored in Android's standard **Preferences DataStore**:

- Theme selection (system/light/dark)
- Language/locale
- Notification preferences (alerts/marketing/system toggles)
- Onboarding completion status
- App version for migration tracking
- Background sync toggle
- Last sync timestamp

### Spam Database (Hashed)

Phone numbers in the local SQLite spam database are **SHA-256 hashed** before storage.

| Field | Storage |
|-------|---------|
| `number_hash` | SHA-256 hash of normalized phone number |
| `pattern` | Wildcard pattern (e.g., `+1-800-*`) |
| `action` | `block`, `flag`, `allow` |
| `category` | `scam`, `telemarketer`, `robocall`, `spam` |
| `spam_score` | 0-100 confidence score |

Raw phone numbers are **never written to disk** in the spam database.

---

## 3. Secure Deletion

### Overwrite-Then-Remove

The app implements **secure deletion** for sensitive keys to mitigate forensic recovery:

```
secureOverwriteAndRemove(key) {
    for (i in 0 until 3) {
        overwrite with random data → apply()
    }
    remove(key) → apply()
}
```

### Deletion Methods

| Method | What It Clears | Use Case |
|--------|---------------|----------|
| `clearAllAuthData()` | Access token, refresh token, user profile | Logout |
| `clearAllData()` | All encrypted preferences including biometric | Account deletion (GDPR) |
| `clearAll()` (DataStore) | All user preferences | Reset to defaults |
| `clearAll()` (CacheManager) | API response cache | Logout / cache clear |
| `clearAll()` (SpamDatabase) | Spam numbers + call logs | Full resync / account deletion |

---

## 4. Root Detection & Anti-Tampering

### Detection Methods

| Check | Detection Target |
|-------|-----------------|
| SU binary paths | `/system/bin/su`, `/system/xbin/su`, `/data/local/su`, etc. |
| Busybox paths | `/system/xbin/busybox`, `/data/local/bin/busybox` |
| Dangerous props | `ro.debuggable=1`, `ro.secure=0` |
| Build tags | `test-keys`, `dev-keys` |
| Magisk indicators | `/sbin/.magisk`, `/data/adb/magisk`, Magisk packages |
| Root management packages | Magisk, SuperSU, KingRoot, LuckyPatcher, etc. |
| SU command execution | `su -c id` — checks if uid=0 |
| App signature verification | SHA-256 hash of signing certificate |
| Debugger detection | `android.os.Debug.isDebuggerConnected()` |
| ADB over network | `service.adb.tcp.port` system property |
| Emulator detection | Known properties, model, manufacturer, fingerprint |
| Installer source verification | Play Store, Amazon App Store, Samsung Galaxy Store |

### Response to Detection

| Detection | Behavior |
|-----------|----------|
| Root detected | Features degraded; reported to backend and Crashlytics |
| Tampering detected | Biometric and payment features disabled |
| Emulator detected | Features may be restricted |
| Untrusted install | Warning logged, security restrictions applied |

---

## 5. Log Sanitization

All network logs are sanitized before writing to prevent PII exposure:

| Pattern | Redacted To |
|---------|-------------|
| `Bearer <token>` | `Bearer [REDACTED]` |
| `\b\d{10,15}\b` (phone numbers) | `[PHONE_REDACTED]` |
| Email addresses | `[EMAIL_REDACTED]` |
| Refresh tokens in bodies | `"refreshToken":"[REDACTED]"` |
| Access tokens in bodies | `"accessToken":"[REDACTED]"` |
| ID tokens in bodies | `"idToken":"[REDACTED]"` |
| Passwords in bodies | `"password":"[REDACTED]"` |

**Implementation:** `NetworkModule.kt` → `provideLoggingInterceptor()`

**Log levels:**
- **Debug builds:** Full headers + sanitized bodies
- **Release builds:** Headers only (no body logging)

---

## 6. Token Refresh Security

### Automatic Silent Refresh

| Property | Value |
|----------|-------|
| **Trigger** | HTTP 401 Unauthorized |
| **Mechanism** | `AuthInterceptor.intercept()` → `refreshAccessToken()` |
| **Concurrency** | Synchronized via `refreshLock` to prevent race conditions |
| **Fallback** | Clears tokens on refresh failure → user re-authenticates |

### Token Storage

| Token | Storage | Encryption |
|-------|---------|------------|
| Access token | EncryptedSharedPreferences | AES256-GCM |
| Refresh token | EncryptedSharedPreferences | AES256-GCM |

---

## 7. Network Security

### OkHttp Configuration

| Property | Value |
|----------|-------|
| Connect timeout | 30 seconds |
| Read timeout | 30 seconds |
| Write timeout | 30 seconds |
| TLS enforcement | Platform default (TLS 1.2+) |
| Certificate pinning | SHA-256 pins for api.kordant.com |

### Retrofit API Configuration

| Property | Value |
|----------|-------|
| Base URL | `https://api.kordant.com/` (production) |
| Converter | Kotlinx Serialization JSON |
| Headers | `X-Request-ID`, `X-Client-Version`, `X-Client-Platform` |

---

## 8. Biometric Authentication

| Property | Value |
|----------|-------|
| **Library** | `androidx.biometric:biometric` |
| **Storage** | Preference flag in EncryptedSharedPreferences |
| **Root check** | Biometric disabled on rooted/tampered devices |
| **Fallback** | Device credentials (PIN/pattern/password) |

---

## 9. Data Collection Compliance

### Data Minimization

The app collects only the data necessary for its core functionality:

| Feature | Minimum Data Required |
|---------|----------------------|
| Authentication | Email, password (or Google account ID), name |
| Call Screening | Incoming phone number (temporary, hashed for storage) |
| VoicePrint | Voice recording samples |
| DarkWatch | Watchlist items (email, phone, name to monitor) |
| Analytics | Device info, app version (no personal identifiers) |
| Crash reporting | Crash stack trace, device model, OS version |

### User Consent

| Data Type | Consent Mechanism |
|-----------|------------------|
| Account creation | Explicit signup form |
| Google Sign-In | OAuth consent screen |
| Voice recordings | `RECORD_AUDIO` permission + in-app rationale |
| Call screening | `READ_PHONE_STATE` permission + in-app rationale |
| Notifications | `POST_NOTIFICATIONS` (Android 13+) + in-app toggles |
| Crash reporting | Crashlytics opt-out (configured in manifest) |
| Marketing communications | Explicit opt-in via notification settings |

---

## 10. Independent Security Review

**Status:** ⚠️ Pending

An independent third-party security audit is planned before the production launch.
The audit will cover:
- Penetration testing of the mobile application
- API security assessment
- Cryptographic implementation review
- Privacy compliance review

---

## 11. Compliance Standards

| Standard | Status | Notes |
|----------|--------|-------|
| **GDPR** | ✅ Compliant | Data deletion, portability, consent, breach notification |
| **CCPA** | ✅ Compliant | Right to know, delete, opt-out, non-discrimination |
| **COPPA** | ✅ Compliant | No children under 13 data collection |
| **Play Store Data Safety** | ✅ Complete | All data types accurately declared |
| **Android Target API 36** | ✅ Compliant | No deprecated API usage |
| **TLS 1.2/1.3** | ✅ Enforced | Cleartext traffic blocked |
| **OWASP MASVS** | ⚠️ Partial | Security audit planned for full certification |