smoa/docs/reference/OUTSTANDING-PRODUCTION-AND-COMPLIANCE-WORK.md

# Outstanding production and compliance work (“not completed in-repo”)

**Purpose:** This document expands everything that was explicitly **out of scope** for in-repository implementation—typically because it depends on **agency approval**, **infrastructure you operate**, **formal certification**, or **long-running QA**—into actionable work packages with prerequisites, deliverables, and acceptance criteria.

**Audience:** Security officers, backend/platform owners, mobile leads, and integration engineers planning a production rollout.

**Related audits:** [`GAPS-AND-INCONSISTENCIES.md`](./GAPS-AND-INCONSISTENCIES.md), [`backend/docs/BACKEND-GAPS-AND-ROADMAP.md`](../../backend/docs/BACKEND-GAPS-AND-ROADMAP.md), [`docs/security/TENANT-THREAT-MODEL.md`](../security/TENANT-THREAT-MODEL.md).

---

## Executive summary

| Workstream | Why it is “not done here” | Primary owner |
|------------|---------------------------|----------------|
| Strong tenant isolation | Requires policy + DB architecture + often IdP | Platform / security / DBA |
| AAMVA / ICAO barcode production readiness | Jurisdiction-specific test vectors and legal use | Compliance + mobile + issuing authority |
| OpenAPI golden CI | CI images, Testcontainers, golden file governance | DevOps + backend |
| CJIS / live NCIC–III | CJIS Security Policy, contracts, accredited networks | Agency + integration |
| ATF / NFA eForms (live) | Federal credentials and APIs | Agency + legal |
| WebRTC (production) | TURN/signaling ops and scale | Infrastructure + mobile |
| Enterprise security (full) | IdP-specific, device program, backend verification | Security + mobile + backend |
| E2E / release QA | Tooling and environments | QA + DevOps |
| Formal assessments | External process | Authorizing official |

---

## 1. Strong multi-tenant isolation

### Current state (repository)

- Optional **API key** on `/api/v1/*` when `SMOA_API_KEY` is set; key does **not** encode tenant or unit membership.
- **`X-Unit`** and `smoa.tenant.require-unit` can force clients to send a unit header; this is **not** proof of membership and is **not** row-level isolation.
- PostgreSQL (when used in prod) has **no RLS** policies in this codebase; queries rely on application-layer filters where implemented.

**References:** [`docs/security/TENANT-THREAT-MODEL.md`](../security/TENANT-THREAT-MODEL.md), [`backend/docs/BACKEND-GAPS-AND-ROADMAP.md`](../../backend/docs/BACKEND-GAPS-AND-ROADMAP.md) §9.

### Goal

Ensure that **compromise of one tenant’s credential** (or one device’s API access) cannot read or mutate another tenant’s data at scale—aligned with your **threat model** and **data classification**.

### Prerequisites

- Defined **tenant model** (org id, unit hierarchy, holder scope).
- Identity story: **mTLS**, **JWT** with `tenant_id` / `sub` / scopes, or **OAuth2 client credentials** per tenant/device class.
- PostgreSQL (or equivalent) as system of record with migration path from dev H2.

### Deliverables

1. **Authentication:** Replace or supplement shared API key with per-tenant or per-device credentials where policy requires it.
2. **Authorization policy:** Map principal → **allowed units** (and optional holder IDs); centralize in a service or Spring `SecurityContext` claims.
3. **Enforcement:** Audit **every** sync/pull/delete handler; reject cross-tenant IDs; add integration tests that prove isolation.
4. **Database:** Implement **PostgreSQL RLS** *or* **schema-per-tenant** *or* strict **tenant_id** column + mandatory predicate on every query (with query review).
5. **Observability:** Correlate `X-Request-Id`, principal, tenant, and `sync_audit_log` for incident response.

### Acceptance criteria

- Penetration test or internal red-team scenario: valid token for **Tenant A** cannot read/write **Tenant B** data (including ID enumeration and bulk export).
- Documented **key rotation** and **breach response** for compromised client credentials.
- RLS/policy review signed off by DBA + security.

---

## 2. AAMVA / ICAO (and related) barcode production compliance

### Current state (repository)

- Kotlin encoders/decoders and PDF417 pipeline exist under **`core/barcode`** (e.g. AAMVA DL/ID, ICAO 9303 MRTD, MIL-STD-129).
- README and compliance sections describe **standards alignment**; they do **not** constitute jurisdiction acceptance.

**References:** [`docs/reference/IDENTITY-TEMPLATE-ALIGNMENT.md`](./IDENTITY-TEMPLATE-ALIGNMENT.md), [`docs/schemas/`](../schemas/), barcode modules under `core/barcode/`.

### Goal

Barcode generation and parsing are **correct and permitted** for each **deploying jurisdiction** and **credential issuer** (motor vehicle agency, passport office, defense ID program, etc.).

### Prerequisites

- Identify **which credential types** are in scope for each deployment.
- Obtain **official test vectors**, **spec versions**, and **errata** from issuing authorities (AAMVA circulars, ICAO Doc 9303 parts, national supplements).

### Deliverables

1. **Per-format test suite:** Golden vectors from authorities; negative tests for malformed inputs.
2. **Jurisdiction matrix:** Which fields are mandatory/optional per state/country/program.
3. **Legal / policy:** Data minimization, display rules, and retention for barcode contents.
4. **Field QA:** Visual/scan QA on target devices (foldable phones, scanners) at required DPI/lighting.
5. **Change control:** Process when AAMVA/ICAO updates specs.

### Acceptance criteria

- Sign-off from **issuing authority** or **program security** where required.
- Regression suite runs in CI for barcode modules; failures block release for in-scope formats.

---

## 3. Automated OpenAPI golden-file CI

### Current state (repository)

- Springdoc exposes **`GET /v3/api-docs`** as the live contract.
- Static **`docs/api/api-specification.yaml`** is maintained for humans and can **drift**.
- Manual process documented in [`docs/development/OPENAPI-SYNCHRONIZATION.md`](../development/OPENAPI-SYNCHRONIZATION.md); scripts such as `scripts/export-openapi-local.sh` assist locally.

### Goal

CI fails when the **running backend contract** changes without updating the **committed golden artifact** (or an approved migration).

### Prerequisites

- CI runner with Docker or JVM support for **Testcontainers** (or a lightweight boot of the Spring app).
- Decision: golden file is **JSON** from `/v3/api-docs`, **normalized YAML**, or **both**.

### Deliverables

1. **CI job** (e.g. Gitea Actions) that:
   - Starts backend with **test profile** (H2 in-memory is acceptable).
   - Fetches `/v3/api-docs`.
   - **Normalizes** JSON (sort keys, stable ordering) to avoid noise.
   - **Diffs** against `docs/api/generated/openapi-golden.json` (or agreed path).
2. **Update workflow:** When API intentionally changes, developer updates golden file in the same PR with rationale in commit/PR description.
3. **Optional:** Diff against `docs/api/api-specification.yaml` if you keep YAML as second source—define which wins.

### Acceptance criteria

- Intentional controller change without golden update → **red CI**.
- Documented **escape hatch** for emergency hotfix (e.g. label + follow-up ticket) if policy allows.

---

## 4. CJIS and live NCIC / III integration

### Current state (repository)

- **NCIC module** validates ORI/UCN patterns, runs **simulated** queries, and logs audit events.
- README mentions **CJIS Security Policy** as a compliance target; the app does **not** connect to FBI CJIS systems.

### Goal

Lawful, accredited use of **NCIC** and related **III** capabilities per **CJIS Security Policy** and agency agreements.

### Prerequisites

- **CJIS compliance** program: networking, personnel screening, workstation security, encryption, auditing, agreements.
- **ORI** and **connectivity** to approved CJIS channels (e.g. state CJIS systems, VPN, MFA).
- Contracted **API or message interface** (often not public; varies by state/federal partner).

### Deliverables

1. **Security controls** mapped to CJIS policy areas (identification, encryption, media protection, incident response).
2. **Replace simulation** in `NCICService` with real transport (HTTPS client certs, VPN-only endpoints, or middleware).
3. **Audit and retention** meeting CJIS logging requirements; **no PII** in mobile logs beyond policy.
4. **Training and SOPs** for operators (hit/no-hit handling, privacy, civil rights).

### Acceptance criteria

- **CJIS audit** or state-equivalent authorization to operate (ATO) as required.
- Legal review for **query justification** and **use of criminal justice information** on mobile devices.

---

## 5. ATF eForms / eTrace and live NFA workflows

### Current state (repository)

- **ATF module** validates Form 4473 fields and **simulates** submission; Forms 1 and 4 are documented stubs.
- Production use requires **federal systems** and **approved credentials** not present in the repo.

### Goal

Legally compliant firearms transaction and NFA workflows where your organization is authorized to use **ATF electronic systems**.

### Prerequisites

- **FFL** status and **API / eForms** enrollment as applicable.
- **OAuth or certificate** credentials issued by ATF or intermediary.
- Legal review of **data stored on device** vs **ATF systems of record**.

### Deliverables

1. Replace simulation with **real API clients** (timeouts, retries, idempotency).
2. **Secure storage** of any client secrets (HSM, MDM, backend proxy pattern).
3. **Error taxonomy** aligned with ATF responses; operator messaging that avoids leaking sensitive data.

### Acceptance criteria

- Sign-off from **compliance/legal** and **ATF program** contacts.
- Test environment validation before production keys.

---

## 6. WebRTC, TURN, and signaling (production)

### Current state (repository)

- Meetings/communications modules include **stubs or framework** code; **WebRTCManager** notes production peer connections are not fully wired.
- Documentation for **Coturn** and signaling URLs exists.

**References:** [`docs/infrastructure/TURN-SIGNALING.md`](../infrastructure/TURN-SIGNALING.md), `modules/communications/`, `modules/meetings/`.

### Goal

Reliable **NAT traversal**, **media path**, and **signaling** at expected scale and security posture.

### Deliverables

1. Deploy **TURN** (e.g. Coturn) with **TLS**, **time-limited credentials** (HMAC), monitoring.
2. Deploy **signaling** service (WebSocket or long-poll); configure `SMOA_SIGNALING_URLS` / build-time props.
3. Complete Android **PeerConnection** integration, codecs, and **screen share** policy if required.
4. Load and **failure testing**; logging without storing raw media.

### Acceptance criteria

- SLO for call setup time and drop rate in pilot environment.
- Security review for **ICE**, **DTLS-SRTP**, and **metadata** leakage.

---

## 7. Enterprise security (full operationalization)

### Current state (repository)

- **TLS pinning**, **OIDC placeholders**, **session lock**, **Play Integrity hook**, **Knox probe**, **BiometricSecretsVault** scaffolding are documented and partially implemented.

**Reference:** [`docs/development/SECURITY-ENTERPRISE.md`](../development/SECURITY-ENTERPRISE.md).

### Goal

Each control is **configured**, **tested**, and **operationally owned** for your IdP and device fleet.

### Work items

| Item | What “done” looks like |
|------|-------------------------|
| **TLS pinning** | Pins for all API hosts; rotation runbook; optional `RemoteEndpointStore` pins from hosted config (see doc). |
| **OIDC / AppAuth** | End-to-end code exchange; refresh; logout; token revocation policy. |
| **Play Integrity** | `cloudProjectNumber` set; **backend** verifies tokens with Google API; abuse signals integrated. |
| **Knox / MDM** | Knox SDK or UEM policies enforced (not just classpath detection). |
| **BiometricSecretsVault** | Full `CryptoObject` path bound to refresh or high-value keys per your IdP design. |
| **Classification marking** | `smoa.classification.buildMarking` aligned with organizational data labeling; content-level markings if required. |

### Acceptance criteria

- **Security architecture review** with traceability from threat model to controls.
- **Operational runbooks** for rotation, incident, and user lockout.

---

## 8. End-to-end and pre-release testing

### Current state (repository)

- **Unit and integration tests** run via `./gradlew smoaVerify` (backend + Android unit + debug assemble).
- E2E is **planned**, not implemented as an automated suite.

**Reference:** [`docs/testing/E2E-PLAN.md`](../testing/E2E-PLAN.md).

### Goal

Repeatable **user-journey** validation before release (sync, auth, meetings, browser policy, etc.).

### Deliverables

1. Choose stack: **Maestro**, **Appium**, or **Espresso + MockWebServer** (per E2E-PLAN).
2. **Seed data** and **test backend** (container or dedicated env).
3. **Nightly** or **pre-release** pipeline; keep **smoaVerify** on every push.

### Acceptance criteria

- Critical paths (e.g. sign-in, directory pull, credential display) automated with **flake budget** and ownership.

---

## 9. iOS and additional clients

### Current state (repository)

- **Android** is the primary implementation; **iOS** documentation exists under `docs/ios/` as guidance/samples.

### Goal (if in program scope)

Feature parity and **shared contract** compliance for an iOS app or SDK.

### Deliverables

- Contract tests against same **OpenAPI**; shared **credential type** constants; platform-specific secure storage.

---

## 10. Formal assessments and authorization

### Examples (deployment-dependent)

- **CJIS** Security Policy compliance assessment.
- **FedRAMP**, **StateRAMP**, **HIPAA**, **SOC 2**, or **department-specific ATO** packages.
- **Country export** and **crypto** regulations for international deployments.

### Deliverables

- System security plan (SSP), control narratives, evidence from CI and ops.
- POA&M for gaps discovered during assessment.

---

## 11. Suggested sequencing (non-binding)

1. **Tenant isolation + auth model** (blocks safe multi-org production).
2. **OpenAPI golden CI** (cheap win; prevents silent contract drift).
3. **E2E smoke** on top 3 flows.
4. **Barcode / issuance QA** for each in-scope credential type.
5. **Agency integrations** (CJIS, ATF) as approvals arrive.
6. **WebRTC** when meetings are production-critical.
7. **Formal ATO** package in parallel with engineering hardening.

---

## Document control

| Version | Date | Notes |
|---------|------|--------|
| 1.0 | 2026-03-23 | Initial consolidation of “not done here” items from gaps, threat model, backend roadmap, OpenAPI, E2E, security enterprise, infrastructure docs. |

When a workstream is completed, update this file and trim or move the section to [`GAPS-AND-INCONSISTENCIES.md`](./GAPS-AND-INCONSISTENCIES.md) **Implemented** table as appropriate.