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, backend/docs/BACKEND-GAPS-AND-ROADMAP.md, docs/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, 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, docs/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; 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, 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.

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.

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 Implemented table as appropriate.