The holder wallet

From the white paper: section 4.2 describes a non-custodial wallet that keeps keys and credentials on the person's device, shares proofs only with consent and recovers without a custodian; this page explains what the app on a person's phone actually does.

A non-custodial app with no accounts. The wallet holders use today is a launched mobile application for iOS and Android, the one Civitas inherited with the platform it operates Live. Every private key and every credential is kept on the holder's device: the recovery phrase and the key that encrypts the wallet sit in the phone's secure storage (the iOS Keychain, or on Android a store encrypted under an Android Keystore key, hardware-backed on handsets that support it), and the other keys and the credentials sit in a wallet encrypted with that key. There is no server-side credential store and no user account: no email and no login password. The app registers one device identity with the platform and uses it to detect when an installation has been cloned or restored; what an institution records about its own clients sits in that institution's tenant, on infrastructure Civitas hosts today (see the privacy page). Access is protected by a mandatory passcode, with fingerprint or face unlock as an opt-in addition.

What the credential engine does today. A 24-word recovery phrase is generated at setup. It derives the key that encrypts the wallet and unlocks the encrypted backup; the other keys are random and are restored from that backup. Credentials use the AnonCreds scheme over a Hyperledger Indy ledger Live, and the wallet exercises the scheme fully: selective disclosure, so the holder presents only the attributes a verifier requests; zero-knowledge predicates, so a condition such as "over 18" is proven without revealing the birth date; and end-to-end revocation, with the wallet producing a proof of non-revocation at presentation time. Predicate conditions are validated on the device before anything is sent: the wallet renders each requirement in plain language and will not let the holder proceed until the conditions are satisfied. Exchange with issuers and verifiers runs over the platform's own encrypted exchange protocol, with a fresh pairwise identifier for each relationship that is never published to any registry. Replacing that substrate with OID4VCI and OID4VP is the largest piece of the standards migration Research: no OpenID exchange code is in service.

Consent per presentation. No credential leaves the device automatically or silently. Each presentation requires the holder to proceed through a consent step in the wallet interface, and that action is logged on the device. The disclosure parameters themselves, which attributes a verifier may ask for, are set by the institutional verifier; within them, the holder has the final say.

Offline behavior. Credentials live on the device and stay available to the holder without a network connection. The registry check on the platform reads a signed snapshot and needs no access to the Stellar network; checking the credential itself on the rail in service still reads the Hyperledger Indy ledger. A presentation made while the holder is fully offline, over a QR code or a local link, is not built Research: it arrives with the OpenID exchange protocols above.

Navigation to a missing credential. When a verifier asks for a credential the holder does not have, the wallet searches its local service catalog for an interaction that issues the required credential type, offers the matching issuers, opens the issuing interaction, and returns the holder to the request that was blocked Live. The catalog itself is governed: registry status drives which services appear in the wallet, and every public service listing computes its visibility the same way, so a suspended issuer disappears with no separate step In build: the trust registry runs on the Stellar test network. The engine that plans a whole goal path, rather than resolving the next missing credential, is not built Research: no shipped code.

Document verification at onboarding. For a person whose only anchor is a paper document, wallet onboarding integrates a commercial document-verification provider: a document scan In build: the provider account runs in sandbox mode and no live check has been made; the current integration does not yet cover the refugee identity card issued in Kenya, a second provider for Kenya is being integrated, and coverage in other countries is unconfirmed. The single-vendor exposure and the per-country gating check are on the risk register.

Recovery. Losing the phone is survivable without any custodian if the holder has turned on the encrypted backup, which is off by default in the app in service; the decided change to offer it after the first credential and on each new one is not built yet. The 24-word phrase unlocks that backup, and the backup restores both the keys and the credentials; the phrase alone restores an empty wallet. A restored wallet resumes its existing relationships, and the credentials it holds remain valid and re-presentable. A biometric route that would re-derive a key from the holder's own fingerprint, storing neither the biometric nor the key, is a research track Research: no code, and error rates on the target handsets are unmeasured.

The build and the redesign. The launched app came with the platform Civitas operates and carries several white-label build configurations. One of them is the Civitas build In build: the configuration exists and no version has been released in a public app store. A redesign of the wallet for low-literacy users and low-cost handsets, part of the same funded work as the standards migration, is specified and has no screens built Research: first releases are targeted for early 2027.

Status, 2026-09-11: the wallet runs as a launched iOS and Android app with on-device keys, per-presentation consent and live missing-credential navigation; the Civitas white-label build has no store release, and the low-literacy redesign has no screens built.