2. Glossary & Terminology¶
| Term | Definition |
|---|---|
| KYC | Know Your Customer — identity verification against government or third-party records |
| Nafath | Saudi national identity platform used for government-level KYC |
| mTLS | Mutual TLS — both client and server present certificates during TLS handshake, providing mutual authentication. Used by all devices (personal scanner, pos, gate, kiosk) to authenticate to the Identity Platform. |
| PKI | Public Key Infrastructure — the set of certificates, keys, and trust relationships that bind a public key to an identity. The platform operates two unrelated PKIs: the server TLS PKI (admin-uploaded HTTPS cert) and the platform CA PKI (private, signs device certs). |
| Platform CA | The platform's own private Certificate Authority. Signs all device client certificates issued during pairing. The CA cert is self-signed and stored (along with its private key) in the platform_secrets DB table; it is never presented in any TLS handshake. Distinct from the server TLS cert. See §9.2.1. |
| CSR | Certificate Signing Request — a PKCS#10-encoded blob containing a public key and a self-signature over its own contents (proof-of-possession of the matching private key). The scanner generates a CSR during pairing; the platform CA signs it to produce the device's client cert. |
| SAN URI | Subject Alternative Name (URI form) — an X.509 cert extension carrying a URI as an identity attribute. Device certs use urn:link:tenant:{tenant_id}:device:{device_id} as the canonical identity at request time; the mTLS middleware parses this URI on every request to derive device_id and tenant_id. |
| StrongBox | Android's hardware-isolated secure element for storing cryptographic keys. Personal scanners generate their pairing keypair inside StrongBox; the private key is non-exportable and never crosses into app or OS memory. See §21.5 for the Android implementation reference. |
| Hexagonal Architecture | Ports & adapters architecture — the domain core defines abstract interfaces (ports), and external integrations are implemented as adapters |
| Port | An interface defining a capability (e.g., KYCProvider, PalmVerifier) |
| Adapter | A concrete implementation of a port (e.g., NafathAdapter, LinkHFVerificationAdapter) |
| PalmVerifier | Port for palm biometric vendor integration |
| KYCProvider | Port for KYC provider integration |
| X-Telcom BioWave Pass | The sole palm-vein verification vendor (X-Telcom Palm Vein SDK / BioWave Pass) — IR+RGB, large-scale 1:N, self-hostable. Integrated behind the PalmVerifier port (§8.3). |
| Large model | The BioWave palm model in which all /KZ/* matching is server-to-server (device → Identity Platform → verification server) and the platform applies palm_match_policy (§8.4). The MVP-documented topology. See §8.13. |
| Small model | The BioWave palm model in which the device client SDK matches at the verification server directly and reports the outcome to the platform over mTLS; the platform records it without re-applying palm_match_policy. Deployment-wide; migratable small→large (§8.13–8.14). |
| Verify (1:1) | Compare a palm scan against a specific user's enrolled template — confirms "this person is user X" |
| Identify (1:N) | Search a palm scan against all enrolled templates in a tenant — answers "who is this person?" |
| DSR | Data Subject Rights — GDPR/PDPL rights including data export and deletion |
| Envoy | API gateway that validates user session JWTs via JWKS without calling Identity Platform |
| JWKS | JSON Web Key Set — public keys endpoint (/.well-known/jwks.json) used by Envoy for JWT validation |
| RBAC | Role-Based Access Control — authorization model where permissions are assigned to roles, and roles are assigned to users |
| Tenant Isolation | The guarantee that data belonging to one tenant cannot be accessed by another tenant |
| Platform Admin | Link operations team member with cross-tenant management privileges |
| Tenant Admin | Integrator administrator with full management privileges within a single tenant |
| Tenant Operator | Support staff with read-only access within a single tenant |
| Console User | A person who accesses the Web Console — Platform Admin, Tenant Admin, or Tenant Operator |
| Device Class | The kind of Identity-managed device: personal_scanner, pos, gate, or kiosk. Determines the interaction pattern (challenge-poll vs device-initiated) and binding. See §9.1. |
| Device-Initiated | A flow that starts when a user scans their palm at a pos/gate device (no pre-created challenge). The device calls Identity directly over mTLS; Identity identifies and brokers a product decision back in-band. See §10. |
| Linked Service | A product backend (e.g. Wallet, Access) registered per tenant that Identity calls synchronously during a device-initiated transaction. See §10. |
| Broker | The platform component that, after identifying a palm, calls the bound linked service's authorize endpoint and relays its allow/deny decision to the device. See §10. |
| Identity Assertion | A short-lived JWT the platform signs (and the product verifies via the platform JWKS) to authenticate a broker authorize call and bind it to a specific user / device / request. See §10. |
Disambiguation — overloaded terms. A few words carry more than one meaning in this domain; this PRD uses them as follows: - "Linked Service" (§10) is a product backend the broker calls. It is unrelated to account auto-linking (§6.11) and the
identity_linked/user.identity_linkedevent (§16), which mean merging auth methods onto one user. - "Enroll" means palm enrollment — capturing a template at a physical device (§8, §13). Account creation is "signup" (§13), a separate lifecycle. - "Verify (1:1)" (§8.3) is a palm match against a claimed user. It is distinct from mobile/email verification (require_mobile_verified/require_email_verified, §4.5), which are auth gates. - "Identify (1:N)" (§8.3) is a palm search with no claim, run internally by the broker (§10).