From e8e89e5e1abfd6b36555fa190649c95eb37aeaa6 Mon Sep 17 00:00:00 2001 From: AgneCaunt <139773510+AgneCaunt@users.noreply.github.com> Date: Fri, 24 Apr 2026 15:13:13 +0300 Subject: [PATCH 1/3] Update truvera-web-wallet-integration-guide.md --- .../truvera-web-wallet-integration-guide.md | 203 +++++++++++++++++- 1 file changed, 202 insertions(+), 1 deletion(-) diff --git a/credential-wallet/truvera-web-wallet-integration-guide.md b/credential-wallet/truvera-web-wallet-integration-guide.md index 7d7d9b1..b65dcd8 100644 --- a/credential-wallet/truvera-web-wallet-integration-guide.md +++ b/credential-wallet/truvera-web-wallet-integration-guide.md @@ -1,3 +1,204 @@ # Truvera Web Wallet integration guide -_Work in progress_ +A concise reference for integrating Truvera into your application. For the full end-to-end flow, see the companion sequence diagram. + +**SDK:** [`@docknetwork/wallet-sdk-web`](https://www.npmjs.com/package/@docknetwork/wallet-sdk-web) +--- + +## Architecture + +Four components are involved in every integration: + +| Component | Role | +|---|---| +| **Customer App** | Frontend that hosts the Truvera Wallet SDK and presents consent UI to the user | +| **Customer Backend** | Your server — calls the Truvera API, holds your API key, issues and verifies credentials | +| **Truvera Wallet SDK** | Client-side SDK that manages the user's DID, stores credentials, and builds presentations | +| **Truvera API** | Truvera's hosted API — handles credential issuance, proof requests, and verification | + +--- + +## 1. Wallet Initialization + +This creates a DID that acts as the user's persistent identity handle. The SDK supports three key management methods — choose one based on your requirements. + +### Recommended: passkey (WebAuthn PRF) + +The simplest and most secure option. No mnemonic to manage. Keys are derived from the user's device authenticator (fingerprint, Face ID, PIN) via the WebAuthn PRF extension and never leave the browser. + +```ts +const wallet = await TruveraWebWallet.initialize({ + edvUrl: 'https://edv.dock.io', + edvAuthKey: '', + networkId: 'testnet', + passkey: true, +}); + +// On first enrollment only — prompt the user to save their recovery phrase +if (wallet.mnemonic) { + showRecoveryPhraseDialog(wallet.mnemonic); +} +``` + +On first use, the SDK registers a passkey, derives key material via PRF, generates and encrypts a master key, and stores it in the cloud vault. On return visits, it authenticates with a single biometric prompt. Passkeys sync automatically across devices via iCloud Keychain (Apple) or Google Password Manager (Android/Chrome). + +**Browser support:** Chrome 116+, Safari 18+, Edge 116+. + +### Alternative: mnemonic + +Use for backup/recovery flows or environments where passkeys are not supported. + +```ts +// Generate once and prompt the user to save it +const { mnemonic } = await TruveraWebWallet.generateCloudWalletMasterKey(); + +const wallet = await TruveraWebWallet.initialize({ + edvUrl: 'https://edv.dock.io', + edvAuthKey: '', + networkId: 'testnet', + mnemonic, +}); +``` + +Never store the mnemonic in localStorage, a database, or anywhere server-side. The user is the only custodian. + +### Alternative: master key + +For advanced integrations where key management is handled externally (e.g. HSM or server-side key release after authentication). + +```ts +const wallet = await TruveraWebWallet.initialize({ + edvUrl: 'https://edv.dock.io', + edvAuthKey: '', + networkId: 'testnet', + masterKey: '<32-byte-key>', +}); +``` + +--- + +After initialization, register the user's DID with your backend: + +```ts +const did = await wallet.getDID(); +// Store this DID against the user's account — it is the subject identifier for credential issuance +``` + +--- + +## 2. Credential Issuance (OID4VCI) + +Your backend creates a credential offer using data attributes from your existing systems (e.g. KYC, CRM, HR). The wallet then claims it directly from Truvera. + +**Backend — create the offer:** + +```http +POST https://api.truvera.io/openid/issuers +{ + "algorithm": "bbdt16", + "issuer": "", + "context": [""], + "subject": { + "id": "", + "fullName": "...", + "dateOfBirth": "...", + ... + } +} + +POST https://api.truvera.io/openid/credential-offers +→ { "offerUrl": "openid-credential-offer://..." } +``` + +Return the `offerUrl` to the app. + +**App — claim the credential:** + +```ts +await wallet.addCredential(offerUrl); +// Credential is now stored in the wallet +``` + +--- + +## 3. Credential Verification (OID4VP) + +Verification works in three steps: create a proof template (once), generate a proof request from it (per verification), and poll for the result after the user submits their presentation. + +### Step 1: Create a proof template (one-time setup) + +A proof template defines what credentials and attributes you want to verify — the credential type, which fields to request, and any constraints (e.g. age predicates). For most use cases you create this once and reuse it for every verification request. + +See the [Truvera API proof templates docs](https://docs.truvera.io/truvera-api/presentations/proof-templates) for the full schema and options. + +### Step 2: Generate a proof request + +Each time a user needs to verify, your backend generates a proof request from the template. This produces a short-lived request URL you pass to the app. + +**Backend:** + +```http +POST https://api.truvera.io/proof-templates/{templateId}/request +→ { "id": "...", "url": "..." } +``` + +Return the proof request URL to the app. + +### Step 3: Build and submit the presentation + +**App:** + +```ts +const credentials = await wallet.getCredentials(); + +const { submit } = await wallet.createPresentation({ + proofRequest: proofRequestUrl, + credentials: [ + { id: credential.id, attributesToReveal: ['credentialSubject.fullName'] }, + ], +}); + +await submit(); +``` + +### Step 4: Poll for the result + +**Backend:** + +```http +GET https://api.truvera.io/proof-requests/{id} +→ { "verified": true, "attributes": { ... } } +``` + +Grant or deny access based on `verified`. + +--- + +## 4. Selective Disclosure + +Only fields listed in `attributesToReveal` are shared with the verifier — including ones constrained by a ZK predicate (e.g. age >= 18). The verifier-side template decides whether each listed attribute is revealed in the clear or proven via a BBS+ predicate; + +```ts +credentials: [ + { + id: credential.id, + attributesToReveal: ['credentialSubject.age', 'credentialSubject.address'], + } +] +``` + +Use `dockbbs` (BBS+) as the algorithm when creating issuers if selective disclosure or ZK predicates are required. + +--- + +## 5. Production Checklist + +| Area | Requirement | +|---|---| +| **Key management** | Use passkey (`passkey: true`) as the default. Mnemonic and master key are for recovery or advanced cases only | +| **Mnemonic backup** | If using mnemonic, prompt the user to save it on first enrollment. Never store it server-side or in localStorage | +| **EDV auth key** | Issue per-user `edvAuthKey` values after authentication. Never share a single key across users | +| **API key security** | Keep `TRUVERA_API_KEY` server-side only. Never expose to the client | +| **Backend auth** | Scope all issuance endpoints to authenticated users. Enforce JWT verification | +| **Revocation** | Check `credentialStatus` on every presentation before granting access | +| **Per-user scoping** | Each user needs their own DID and credential store. Never share wallet state across users | From a1c47c661539229eea3926031d1391cc58e202ed Mon Sep 17 00:00:00 2001 From: AgneCaunt <139773510+AgneCaunt@users.noreply.github.com> Date: Wed, 29 Apr 2026 16:24:39 +0300 Subject: [PATCH 2/3] Update truvera-web-wallet-integration-guide.md --- credential-wallet/truvera-web-wallet-integration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/credential-wallet/truvera-web-wallet-integration-guide.md b/credential-wallet/truvera-web-wallet-integration-guide.md index b65dcd8..79c33ba 100644 --- a/credential-wallet/truvera-web-wallet-integration-guide.md +++ b/credential-wallet/truvera-web-wallet-integration-guide.md @@ -197,7 +197,7 @@ Use `dockbbs` (BBS+) as the algorithm when creating issuers if selective disclos |---|---| | **Key management** | Use passkey (`passkey: true`) as the default. Mnemonic and master key are for recovery or advanced cases only | | **Mnemonic backup** | If using mnemonic, prompt the user to save it on first enrollment. Never store it server-side or in localStorage | -| **EDV auth key** | Issue per-user `edvAuthKey` values after authentication. Never share a single key across users | +| **EDV auth key** | Contact support@dock.io to obtain your EDV auth key| | **API key security** | Keep `TRUVERA_API_KEY` server-side only. Never expose to the client | | **Backend auth** | Scope all issuance endpoints to authenticated users. Enforce JWT verification | | **Revocation** | Check `credentialStatus` on every presentation before granting access | From 349dfab0e4cd135273524946e4d5d008fc3dd55b Mon Sep 17 00:00:00 2001 From: AgneCaunt <139773510+AgneCaunt@users.noreply.github.com> Date: Wed, 29 Apr 2026 18:14:54 +0300 Subject: [PATCH 3/3] Update truvera-web-wallet-integration-guide.md --- .../truvera-web-wallet-integration-guide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/credential-wallet/truvera-web-wallet-integration-guide.md b/credential-wallet/truvera-web-wallet-integration-guide.md index 79c33ba..7db1c01 100644 --- a/credential-wallet/truvera-web-wallet-integration-guide.md +++ b/credential-wallet/truvera-web-wallet-integration-guide.md @@ -9,12 +9,12 @@ A concise reference for integrating Truvera into your application. For the full Four components are involved in every integration: -| Component | Role | +| Actor | Role | |---|---| -| **Customer App** | Frontend that hosts the Truvera Wallet SDK and presents consent UI to the user | -| **Customer Backend** | Your server — calls the Truvera API, holds your API key, issues and verifies credentials | -| **Truvera Wallet SDK** | Client-side SDK that manages the user's DID, stores credentials, and builds presentations | -| **Truvera API** | Truvera's hosted API — handles credential issuance, proof requests, and verification | +| **Holder** | The credential holder obtains credentials from an issuer, stores those credentials in a individually controlled web wallet, and uses the credentials to establish a trusted relationship with a verifier | +| **Wallet Provider** | The wallet provider is trusted by the holders to give them access to a web wallet | +| **Issuer** | The holder identity proofs with the credential issuer before receiving credentials. If the holder does not yet have a wallet, the issuer helps them set one up with the wallet provider. | +| **Verifer** | The verifier requests credentials from the holder in order to obtain trusted data that will allow the holder to complete a business process | ---