defiQUG
a2dc194a49
- Add Gitea Actions workflow; point README to gitea.d-bis.org/Sankofa_Phoenix/SMOA - Expand .gitignore for Spring H2 data, secrets, Kotlin .kotlin/, tooling - Track docs/api/generated ReDoc bundle; refresh api docs README - Android: network/auth/sync, UI shell, tests; backend credentials/integrity APIs - Docs, scripts (generate-api-docs), modules and core updates Made-with: Cursor
127 lines
7.3 KiB
Markdown
127 lines
7.3 KiB
Markdown
# 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 |
|
||
|----------|------|
|
||
| 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` |
|