# Identity templates: SMOA ↔ Complete Credential alignment

This document aligns **SMOA** credential templates (mobile presentation, barcode formats, sync payloads) with the **Complete Credential** umbrella program (`complete-credential` repo), in particular:

- Shared OpenAPI draft: `submodules/cc-shared-schemas/openapi/v1/openapi.yaml` — `CredentialRef.domain`
- Master plan credential domains (PIV, travel-adjacent, payment, NFC, mobile)

SMOA code lives in this repository; Complete Credential is an external reference layout. **Keep the string constants in sync** with:

- Android: `modules/credentials/.../SmoaCredentialTemplateIds.kt`
- Backend: `backend/.../SmoaCredentialType.kt` (same literal values)

---

## 1. Complete Credential `CredentialRef.domain`

From `cc-shared-schemas` (draft v0.1):

| `domain` value | Meaning (program) |
|----------------|-------------------|
| `payment` | Payment / financial instrument workflows |
| `piv_pki` | PIV-class, PKI-backed, high-assurance identity |
| `nfc_access` | Physical access, badge, NFC-adjacent credentials |
| `mobile` | Derived / mobile wallet–style credentials |

---

## 2. SMOA `credentialType` (canonical)

Use these values in **backend** `CredentialSyncRequest.credentialType`, **database** `credentials.credential_type`, and **mobile** when serializing sync payloads.

| `credentialType` | Maps to CC `domain` | SMOA implementation |
|------------------|---------------------|----------------------|
| `piv_pki` | `piv_pki` | PIV / smart card presentation; no single barcode class—use secure element / card APIs. Pair with org PKI metadata in `payload`. |
| `payment` | `payment` | Payment tokens / instruments (future wire-up to issuance services). |
| `nfc_access` | `nfc_access` | Access cards, mission badges; often QR/PDF417 from directory or access system. |
| `mobile` | `mobile` | Derived credentials, mobile-issued wallet artifacts. |
| `icao9303_mrtd` | *(travel-adjacent issuance — CC Phase / national programs)* | **ICAO Doc 9303** MRTD: `com.smoa.core.barcode.formats.ICAO9303Credential` |
| `aamva_dlid` | *(state ID — often under organizational / civil ID)* | **AAMVA** DL/ID PDF417: `com.smoa.core.barcode.formats.AAMVACredential` |
| `mil_std_129` | *(defense ID — organizational / sovereign)* | **MIL-STD-129**: `com.smoa.core.barcode.formats.MILSTD129Credential` |
| `agency_badge` | Often co-issued with `nfc_access` | Agency photo ID / badge; generic card UI when format is org-specific. |

### 2.1 Legacy aliases (older API / docs)

Prefer canonical types above for new integrations.

| Legacy | Prefer |
|--------|--------|
| `id` | `agency_badge` or `piv_pki` (context-dependent) |
| `badge` | `nfc_access` or `agency_badge` |
| `license` | `aamva_dlid` |
| `permit` | `agency_badge` or domain-specific extension in `payload` |
| `other` | Explicit new `credentialType` after design review |

---

## 3. Optional `payload` keys for cross-system identity

When syncing, `payload` (JSON object) may include:

| Key | Type | Description |
|-----|------|-------------|
| `completeCredentialDomain` | string | Echo CC `CredentialRef.domain`: `payment` \| `piv_pki` \| `nfc_access` \| `mobile` |
| `issuingAuthority` | object | **Preferred** for tenant / jurisdiction / ministry / agency (see `docs/schemas/credential-authority.schema.json`): `tenantId`, `jurisdiction`, `government`, `credentialRegistryRef`, etc. |
| `credentialId` | string | External issuance id (if different from sync `credentialId`) |
| `subjectId` | string (uuid) | Aligns with CC `SubjectRef.subjectId` when known |

Do **not** rely on a duplicate top-level `tenantId` alone; nest under `issuingAuthority` for consistency with JSON Schema.

Format-specific fields should match the Kotlin models (e.g. ICAO field names as JSON keys) when embedding structured data for rendering or barcode regeneration.

---

## 4. Barcode / format mapping (SMOA modules)

| `credentialType` | Kotlin model | Module / usage |
|------------------|--------------|----------------|
| `icao9303_mrtd` | `ICAO9303Credential` | `core/barcode`, `modules/credentials` |
| `aamva_dlid` | `AAMVACredential` | `core/barcode`, `modules/credentials` |
| `mil_std_129` | `MILSTD129Credential` | `core/barcode`, `modules/credentials` |
| `piv_pki` | *(no default barcode)* | PIV is typically X.509 / card APDU, not MRZ in-app |
| `nfc_access`, `agency_badge` | *(varies)* | Often backend-supplied bitmap or QR payload in `payload` |

---

## 5. Operational checklist

1. **Issuance systems** in Complete Credential should set `CredentialRef.domain` consistently; SMOA sync should set `credentialType` and optionally `completeCredentialDomain` to the same logical row in §2.
2. **Travel documents** use `icao9303_mrtd` and MRZ/check digit rules already implemented in `ICAO9303Credential`.
3. **PIV** uses `piv_pki`; do not conflate with `icao9303_mrtd` unless the credential is literally an eMRTD with ICAO structure.
4. When CC publishes expanded enums or template packs under `platform/entity-packs/`, update this file and the two Kotlin `SmoaCredential*` files in the same commit.

---

## 6. JSON Schema (issuance pipeline validation)

Payload shapes for **`icao9303_mrtd`**, **`aamva_dlid`**, and **`mil_std_129`** are defined under `docs/schemas/`:

| File | Purpose |
|------|---------|
| `credential-authority.schema.json` | Reusable **issuing authority** and **jurisdiction** (multi-government: tenant, country, subdivision, ministry, agency, service branch, localized names). |
| `credential-payload-icao9303_mrtd.schema.json` | MRZ-oriented travel document fields (YYMMDD). |
| `credential-payload-aamva_dlid.schema.json` | AAMVA-style DL/ID (YYYYMMDD). |
| `credential-payload-mil_std_129.schema.json` | Military ID-style card (YYYYMMDD). |
| `credential-payload-piv_pki.schema.json` | PIV/PKI optional payload. |
| `credential-payload-payment.schema.json` | Payment token refs. |
| `credential-payload-nfc_access.schema.json` | Access / badge metadata. |
| `credential-payload-mobile.schema.json` | Mobile / derived wallet refs. |
| `credential-payload-agency_badge.schema.json` | Agency photo ID / badge. |
| `credential-payload-document.schema.json` | **`oneOf`** union over all payload schemas (select by `credentialType` on the request body). |

Resolve **`$ref`** from the schema directory (same folder as the referring file). Schemas describe **`CredentialSyncRequest.payload` only** — the top-level **`credentialType`** field is on the sync JSON body alongside `credentialId`, `holderId`, etc.; do not duplicate `credentialType` inside `payload`. Use **`issuingAuthority`** in `payload` when syncing across ministries, agencies, or coalition programs.

The **`credential-payload-document.schema.json`** `oneOf` union is ambiguous without a discriminator on `payload`; issuance pipelines should select the schema file that matches **`request.credentialType`** after validating that string against `SmoaCredentialType.CANONICAL`.

---

## 7. Related paths

| Artifact | Path |
|----------|------|
| **Complete Credential — integration runbook + ADR-0010** | Umbrella repo: `docs/integrations/smoa.md`, `adr/0010-smoa-mobile-integration-boundary.md` (when cloned as e.g. `../complete-credential/`) |
| Client config example (FQDN / endpoints) | `backend/docs/examples/smoa-client-config.example.json` |
| LXC / hosting | `backend/docs/LXC-PROXMOX-CONTAINERS.md` |
| Backend credential entity | `backend/.../CredentialEntity.kt` |
| Sync DTO | `backend/.../CredentialSyncRequest` in `SyncRequest.kt` |
| OpenAPI (SMOA API) | `docs/api/api-specification.yaml` |

### 7.1 Contract drift check (with Complete Credential clone)

From the **complete-credential** repository root (submodules initialized):

```bash
SMOA_REPO=/path/to/smoa ./tools/verify/verify-smoa-cc-domain-alignment.sh
```

This asserts the shared `CredentialRef.domain` line in `cc-shared-schemas` and that `SmoaCredentialType.kt` still contains literals `payment`, `piv_pki`, `nfc_access`, `mobile`.