Do I need to install anything?

No. The Web Wallet is a Progressive Web App served from your Aloaha tenant. It runs in the browser tab you already have open. If you want it as an app icon you can Add to Home Screen from your browser menu, but it works either way.

Which credential do I need?

For logineu.html sign-in the verifier asks for urn:aloaha:vc:email-verified (or urn:aloaha:vc:email). Import either from the wallet's 'Available attestations from your profile' panel. The email in the credential becomes your user identity for the sign-in.

Where does the wallet's private key live?

In your browser's IndexedDB as a non-extractable CryptoKey (WebCrypto). It never touches the network, and the browser will not export it even to your own JavaScript. The wallet signs the Key-Binding JWT for every presentation using this key.

What if I clear my browser data?

You lose the wallet key and every credential stored under it. Re-import them after signing in again. A recovery vault feature (encrypted zero-knowledge backup) is on the roadmap. Meanwhile treat the browser profile as the wallet.

Can I use it on my phone and my laptop?

Yes, but each browser is a separate wallet with its own key. Import the credential once per browser. Cross-device pairing (one wallet, many browsers) is planned via the recovery-vault feature.

Why does the sign-in flow ask for phone / address 'not ready'?

The wallet renders a tile per credential type your OIDC profile could support. 'Not ready' means your profile does not have that claim populated yet. Add a phone number or postal address in account.html under 'Profile', then reload the wallet and the tile will flip to 'Import'.

Does the Web Wallet talk to the EU LSP wallet?

The wallet speaks the same OpenID4VP + SD-JWT VC + HAIP protocol as the EUDI reference wallets, so a verifier that accepts one accepts the other. It is not the official EUDI Wallet Instance and does not carry a Member-State PID. For LoA-High national identity flows you still need the country wallet.

Is the wallet's response encrypted?

When the verifier requests direct_post.jwt the wallet encrypts the response as JWE using ECDH-ES + A128GCM to the verifier's ephemeral P-256 key from the request. For plain direct_post the payload is TLS-only. Both modes carry a fresh nonce and Key-Binding JWT.

How long does the sign-in session last?

After a successful presentation the verifier mints a Single-Sign-On assertion (sso_assertion) which the browser stores under codeb.oidc.sso_assertion. Downstream RPs pick it up automatically. The assertion honours the same OIDC token TTLs as password sign-in.

User guide · EU Wallet

Sign in with the Aloaha Web Wallet.

This walkthrough shows how to use the browser-based Web Wallet to sign into any Aloaha-hosted site via logineu.html — from a first-time credential import all the way to a signed session. Every step is what the code does today; nothing is aspirational.

Open the Web Wallet Open logineu.html What is the Web Wallet?

You need one credential for sign-in: an Email attestation. The wallet issues it to itself from your OIDC profile in a couple of taps. After that, every future logineu.html sign-in is two clicks — open wallet, approve.

Contents

What you need
Flow at a glance
Step 1 — Open the wallet
Step 2 — Sign into the wallet
Step 3 — Import an Email attestation
Step 4 — Go to logineu.html
Step 5 — Click ‘Open Web Wallet’
Step 6 — Approve the presentation
Step 7 — Land signed-in
Which credentials work
Troubleshooting
Under the hood

1. What you need

An Aloaha account — a username/password on the tenant you’ll be signing into. If you don’t have one, register via register.html.
A modern browser with IndexedDB and SubtleCrypto. Chrome, Edge, Firefox and Safari 14+ all qualify. Private-window modes wipe the wallet on close, which is fine for a one-off but not for daily use.
A verified email address on your profile. Open account.html and confirm the email field is populated. Verified isn’t strictly required for the plain urn:aloaha:vc:email credential, but it’s recommended.

2. Flow at a glance

Sign-in happens across two browser tabs (or two devices) that share nothing except the OpenID4VP protocol. There is no cookie handoff, no window messaging — the verifier just polls until the wallet posts a signed response.

# One-time setup (per browser) 1. Open /web-wallet.html 2. Tap Sign in → OIDC PKCE against your tenant 3. Tap Import next to Verified email address → wallet calls /vci.ashx and stores an SD-JWT VC # Every sign-in (~4 seconds) 1. Open /logineu.html 2. Tap Open Aloaha Web Wallet (new tab) 3. In the wallet tab: Approve & present 4. logineu.html detects success and redirects to /account.html

3. Step 1 — Open the wallet

Open `/web-wallet.html` in your browser.

The URL is https://<your-tenant>/web-wallet.html. For example on phone.aloaha.com that’s phone.aloaha.com/web-wallet.html. The first visit registers the service worker so the wallet shell is available offline (credentials still need network for verification).

The wallet is a hosted Progressive Web App. Nothing is installed. Optionally, Add to Home Screen from your browser menu to make it an app icon.

Tap Sign in.

The wallet uses OpenID Connect with PKCE to authenticate you against the same tenant. You’ll be redirected to login.html, sign in with your password (or a passkey if you have one), and land back inside the wallet with a bearer token.

This is what lets the wallet later ask /vci.ashx which attestations you can prove — the issuer reads your OIDC claims (email, name, phone, address, birthdate) to decide what to mint.

The wallet uses your existing sign-in for the credential-import step only. Once the credential is stored, verifiers check the wallet’s cryptographic signature on the presentation itself — not a session cookie.

5. Step 3 — Import an Email attestation

Under Available attestations from your profile, tap Import next to Verified email address.

The wallet posts your requested vct plus the wallet’s public key (cnf.jwk) to /vci.ashx?issue-in-session=1, authenticated with the bearer token from Step 2. The issuer reads the matching claims from your OIDC profile, signs a small SD-JWT Verifiable Credential (urn:aloaha:vc:email-verified) bound to your wallet key (RFC 7800 cnf.jwk), and returns it. It lands in your wallet under My credentials. The classic OpenID4VCI pre-authorized-code flow is still supported for out-of-band offers (paste an offer URL), but the in-session import is the one-tap path.

You’ll see a card:

urn:aloaha:vc:email-verified Issued by https://<your-tenant> BASE CLAIMS { "vct": "urn:aloaha:vc:email-verified", "cnf": { "jwk": { "kty": "EC", "crv": "P-256", ... your wallet public key ... } } } SELECTIVE DISCLOSURES (1) [ "<salt>", "email", "you@example.com" ]

The plain urn:aloaha:vc:email variant works too. If your profile also has phone, address, name or birthdate populated, the corresponding tiles will show Import. Either the verified or plain email credential satisfies the logineu.html request.

6. Step 4 — Go to logineu.html

Open `/logineu.html`.

Same origin, another tab. The page immediately mints an OpenID4VP session with a fresh nonce, an ephemeral P-256 encryption keypair, and displays a wallet-scannable QR code (which is for the EU reference wallet). Ignore the QR for the Web Wallet path.

7. Step 5 — Click ‘Open Aloaha Web Wallet (new tab)’

Tap the button.

The page calls /oidc.ashx?action=vp-start&query=aloaha-identity, receives a fresh openid4vp:// deep link, and opens the wallet in a new tab with that link prefilled: /web-wallet.html?openid4vp=.... Meanwhile the logineu.html tab quietly polls vp-response for the outcome.

New tab is the right choice: it preserves the presentation session’s state / nonce binding in the source tab, and the wallet works better with its own address bar for the deep-link bootstrap.

8. Step 6 — Approve the presentation

In the wallet tab, review and approve.

The wallet fetches the signed JWT Authorization Request (JAR), verifies the JAR’s ES256 signature against the certificate leaf in the x5c chain, and checks that the verifier’s client_id is bound to that certificate per HAIP §5.9.3 (either x509_hash or x509_san_dns). Full chain-to-trust-anchor validation is a roadmap item; today the check is signature + client-id binding. Then it shows you:

Who is asking (verifier client_id — your tenant domain)
Which credentials are requested (urn:aloaha:vc:email-verified or urn:aloaha:vc:email)
Which claims will be revealed (email)
Which credential the wallet will present (matches by vct)

Tap Approve & present. The wallet:

Signs a fresh Key-Binding JWT (kb+jwt) with the wallet’s non-extractable P-256 key, binding nonce, aud, and sd_hash.
Assembles the VP token = <issuer-signed SD-JWT VC> ~ <disclosure> ~ <KB-JWT>.
Encrypts the response envelope as JWE (ECDH-ES + A128GCM) if the verifier requested direct_post.jwt; otherwise posts plain application/x-www-form-urlencoded.
POSTs to the response URI baked into the JAR.

9. Step 7 — Land signed-in

Return to the logineu.html tab.

Its poll picks up a HTTP 200 with the resolved user identity. It stores the returned sso_assertion in localStorage under codeb.oidc.sso_assertion, then redirects to /account.html. Every other Aloaha admin page in the same browser now recognises you.

You can close the wallet tab as soon as it says Presentation sent. The sign-in belongs to the logineu.html tab.

10. Which credentials the sign-in accepts

The logineu.html Web-Wallet button hits vp-start?query=aloaha-identity, which builds a DCQL query for the following credential types (either one satisfies it):

vct	Requested claims	Wallet source
urn:aloaha:vc:email-verified	email	Import tile ‘Verified email address’
urn:aloaha:vc:email	email	Import tile ‘Email address’

The other urn:aloaha:vc:* credentials (name, phone-verified, postal-address, date-of-birth, age-over-18, preferred-username, tenant-membership) don’t satisfy the login query but are useful for verifier-side flows like age-verify or a KYC pre-check — hosted verifiers can request them via their own vp-start calls.

Standards-based verifiers that ask for urn:eu.europa.ec.eudi:pid:1 (Member-State PID) will not match an Aloaha-issued credential. For those you need the official EUDI Wallet with an issued PID. The Aloaha Web Wallet is honest about its ceiling: LoA-Substantial max, no Member-State PID.

11. Troubleshooting

“No attestations available from your OIDC profile” in the wallet.

Every credential tile says not ready.

Your OIDC profile has no claims populated yet. Open account.html or register.html, fill in Email, then reload the wallet.

Phone / address tiles specifically say ‘not ready’.

Add a phone number under Profile and tick Verified. For address, fill in Street + City + Country. Reload the wallet — the tile flips to Import. If the tile is still not-ready after reload, the wallet may have cached an old bearer — hit Sign out then sign back in to pick up the widened OIDC scope.

logineu.html says ‘Presentation sent’ but never redirects.

The verifier rejected the response. Open the browser console in the logineu.html tab — you’ll see the JSON error, usually one of:

invalid_kb_jwt: the wallet’s key-binding JWT failed signature or nonce match. Clear the wallet’s stored credentials and re-import.
nonce_mismatch: the session on logineu.html expired (5 min TTL). Reload the page and try again.
trust_anchor_fail: verifier config issue — contact the operator.

“Session expired — reload to start a new presentation”.

Verifier sessions live 5 minutes. If you took longer, reload logineu.html to mint a fresh one. This is a normal ceiling and matches the OpenID4VP recommendation.

Wallet opens the deep-link tab but shows ‘JAR fetch failed’.

Rare. The request_uri in the deep link points back at /oidc.ashx?action=vp-request which must resolve to your tenant. If your browser is in a captive-portal or DNS is broken, this fails. Retry once your network settles.

I’ve cleared browser data. What happens?

The wallet key and all credentials are gone. Sign into the wallet again, re-import the credential. Nothing is stored server-side against your wallet key — the verifier only knows you by the SD-JWT VC contents.

12. Under the hood

For developers who want to see what’s actually on the wire:

Step	Endpoint	Purpose
Wallet sign-in	/oidc.ashx?action=authorize (PKCE)	Bearer for /vci.ashx
List importable	/vci.ashx?available-attributes	Wallet tiles
Import credential	/vci.ashx (POST credential-offer + pre-auth code)	Signed SD-JWT VC + cnf.jwk
Start presentation	/oidc.ashx?action=vp-start&query=aloaha-identity	Fresh nonce, JAR, EPK
Fetch JAR	/oidc.ashx?action=vp-request&id=<sid>	ES256-signed request object + x5c
Post response	/oidc.ashx?action=vp-response&id=<sid>	VP token + KB-JWT + state
Poll for outcome	GET /oidc.ashx?action=vp-response&id=<sid>	Session lookup by logineu.html

Everything is standards-compliant: OpenID4VP 1.0, HAIP 1.0, SD-JWT VC (draft-ietf-oauth-sd-jwt-vc), OpenID4VCI, ISO/IEC RFC 7800 holder-binding. See the HAIP conformance notes and verifier API for the wire format.

Open the Web Wallet Try it at logineu.html Wallet explainer HAIP details