A fork of wwWallet frontend

---

wwWallet

Welcome to wwWallet Frontend repository! This application is a user-friendly web wallet that empowers users to manage their digital credentials effortlessly. With a seamless interface and powerful features, users can view their credentials, obtain new ones from issuers, present credentials to verifiers, and access their presentation history.

Table of Contents

• Features
• Prerequisites
• Installation
• Pre-commit Hook
• Usage
• Changesets & Releases
• PRF Compatibility
• Tailwind CSS
• Contributing

Features

Our Web Wallet provides a range of features tailored to enhance the credential management experience:

• Credential Display: Users can easily view their stored digital credentials in a structured manner, making it simple to keep track of their qualifications.

• Issuer Interaction: Seamless integration with issuers allows users to request and receive new digital credentials directly within the wallet.

• Verifier Presentation: Users can present their credentials to verifiers using the wallet, providing a secure and efficient method of showcasing their qualifications.

• Presentation History: The wallet maintains a history of credential presentations, allowing users to review and track when and where they've shared their credentials.

Prerequisites

• Node.js
• pnpm

Installation

• Clone the repository:

• Option 1: Using HTTPS

  git clone https://github.com/your-username/wallet-frontend.git

• Option 2: Using SSH

  git clone git@github.com:your-username/wallet-frontend.git

• Navigate to the project folder:

  cd wallet-frontend

• Configure Environment Variables: The project uses environment variables to manage different configurations. A .env file is used to keep all these variables. There is a .env.template file in the repository. Copy it and rename it to .env.

  cp .env.template .env

  Now, open the .env file and fill in the variables according to your own configuration. Below is an explanation for each variable:

  Build-time variables (Vite):

  • HOST: The IP address where your app will be running (default is '0.0.0.0').
  • PORT: The port on which your app will run (default is 3000).
  • GENERATE_SOURCEMAP: Generate source maps for debugging (true or false).
  • APP_VERSION: Application version (default: $npm_package_version).

  Runtime variables (injected at container startup):

  • BASE_PATH: Base path for asset loading (default is /). Used for sub-path deployments.
  • WS_URL: The URL of the websocket service.
  • WALLET_BACKEND_URL: The URL of your backend service.
  • DID_KEY_VERSION: DID key version format (e.g., jwk_jcs-pub).
  • LOG_LEVEL: Set the log level of the browser console. Supported options: "error" | "info" | "warn" | "debug". Defaults to info.
  • WEBAUTHN_RPID: WebAuthn relying party ID (when running locally, set to localhost). This must match the config.webauthn.rp.id setting in wallet-backend-server.
  • OPENID4VCI_REDIRECT_URI: Redirect uri after authentication and token request at the authorization server in OID4VCI flow.
  • OPENID4VCI_PROOF_TYPE_PRECEDENCE: Proof type precedence for OID4VCI (e.g., "attestation,jwt").
  • OPENID4VP_SAN_DNS_CHECK: Verify at the OID4VP incoming authorization request that the SAN contained in the certificate is the same with the response_uri (true or false).
  • OPENID4VP_SAN_DNS_CHECK_SSL_CERTS: Flag to switch (true or false) the Subject Alternative Name validation of the certificates during the OpenID4VP.
  • MULTI_LANGUAGE_DISPLAY: Enable or disable multi-language support (true or false). If left empty, it will be handled as false.
  • STATIC_PUBLIC_URL: The installation's public url.
  • STATIC_NAME: The installation's public name.
  • I18N_WALLET_NAME_OVERRIDE: String to override translations of common.walletName (Optional).
  • FOLD_EVENT_HISTORY_AFTER_SECONDS: Fold history events older than this value in seconds (default: 2592000 = 30 days).
  • DISPLAY_ISSUANCE_WARNINGS: Enable or disable (true or false) the display of the issuance warnings popup.
  • OPENID4VCI_MAX_ACCEPTED_BATCH_SIZE: Configure the maximum accepted batch size during an OpenID4VCI flow.
  • OPENID4VCI_TRANSACTION_ID_POLLING_INTERVAL_IN_SECONDS: Polling interval in seconds for transaction ID.
  • OPENID4VCI_TRANSACTION_ID_LIFETIME_IN_SECONDS: Lifetime in seconds of transaction ID.
  • OHTTP_KEY_CONFIG: URL of OHTTP key config endpoint.
  • OHTTP_RELAY: URL of OHTTP relay endpoint.
  • VCT_REGISTRY_URL: URL of the Type Metadata registry for SD-JWT VC credentials.
  • OIDC_GATE_OP_URL: Base URL of the OIDC provider used by the OIDC gate feature (e.g., https://accounts.google.com). Added to the CSP connect-src directive to allow browser connections to the provider.
  • POLICY_LINKS: Links to any TOS or other policies. This should be in the format "<LABEL>::<URL>,<LABEL>::<URL>,<LABEL>::<URL>,..." Can be left blank.
  • SHOW_PWA_INSTALL_PROMPT: Hide or show the PWA installation prompt on the login screen. Defaults to false if left blank or invalid.
  • WALLET_COMPANION_INTEGRATION: Enable integration with the Wallet Companion browser extension. Defaults to false if left blank or invalid.
  • PRESERVE_PRESENTATION_HISTORY: If enabled, deleting credentials from the wallet will not remove them from the presentation history. Defaults to false if left blank or invalid.
  • SCAN_PHYSICAL_ID_ENABLED: Show the "Scan Physical ID" entry point (native wrapper apps only) on the Add Credentials page. Defaults to true; set to false for tenants that don't want this feature offered.
  • FACETEC_API_URL: URL of the facetec-api that the native wrapper apps should use for the Scan Physical ID flow. Passed to the app via startScanPhysicalId, and added to the CSP connect-src. Defaults to the app's built-in URL if unset.

  Well-known file generation:

  • WELLKNOWN_APPLE_APPIDS: Used to generate the .well-known/apple-app-site-association file, used for IOS wrappers. This should be in the format "<APP_ID>,<APP_ID>,<APP_ID>,..." Can be left blank.
  • WELLKNOWN_ANDROID_PACKAGE_NAMES_AND_FINGERPRINTS: Used to generate the .well-known/assetlinks.json file, used for Android wrappers. This should be in the format "<PKG_NAME>::<FINGERPRINT>,<PKG_NAME>::<FINGERPRINT>,<PKG_NAME>::<FINGERPRINT>,..." Can be left blank.

• Install dependencies:

  pnpm install

• Start the development server:

  pnpm start

Pre-commit Hook

We use pre-commit to enforce our .editorconfig before code is committed.

One-time setup

# install pre-commit if you don’t already have it
pip install pre-commit       # or brew install pre-commit / pipx install pre-commit

# enable the git hook in this repo
pre-commit install

# optional: clean up the repo on demand
pre-commit run --all-files

git add -A

What happens on commit

• Auto-fixers run (e.g. add final newlines).
• After the auto-fixers, the editorconfig-checker runs inside Docker to validate all staged files.
• If violations remain, fix them manually until the commit passes.

Usage

Once the development server is running, you can access the app by visiting http://localhost:3000 in your web browser. The app provides various pages and components that you can interact with. Explore the features and enjoy using the Wallet Frontend!

.gitignore strategy

This repo uses a allowlist (opt-in) .gitignore: by default nothing at the project root is tracked, and we explicitly re-include the files and directories we care about.

What this means day to day

• New top level directories will be ignored by default. Add them to the allowlist in .gitignore as required.
• Any files or sub-directories in top level directories that need to be ignored should be added to the ignorelist at the end of the .gitignore file.

Changesets & Releases

We use Changesets to track changes and manage version bumps and the CHANGELOG.md.

Adding a changeset

Whenever you make a change that should show up in the changelog (a feature, fix, or other user-facing change), add a changeset as part of your pull request:

pnpm changeset

This interactive prompt asks you to:

1. Pick the bump type (major, minor, or patch).
2. Write a short summary. This text becomes the changelog line, e.g. fix: reroute the hyperdrive coolant.

A new markdown file is created under .changeset/ and commited in a new commit (automatically).

Releasing

Warning

Releases are done by a maintainer.

1. Set up the GitHub token (once). The changelog links PR numbers and authors, which requires a token:

cp .changeset/.env.example .changeset/.env
# then edit .changeset/.env and set GITHUB_TOKEN to a token with repo read access

This file is git-ignored and only used locally.

2. Consume the changesets. This deletes the pending changeset files, bumps the version in package.json, and updates CHANGELOG.md:

pnpm run version

3. Tag the release once merged (or pushed):

pnpm run tag
git push --follow-tags

Tags follow the v${version} format.

Pre-release mode

To release beta or rc releases, you need to enter prerelease mode:

# to enter beta mode
pnpm run prerelease-mode enter beta

# to exit beta mode
pnpm run prerelease-mode exit

Instead of beta, it can be rc, or alpha or anything else.

PRF Compatibility

The wwWallet Frontend is designed to be compatible with the PRF extension to WebAuthn, ensuring a streamlined and secure registration and authentication process. Below, we present specific compatibility scenarios based on the operating system, emphasizing both WebAuthn and PRF extension compatibility.

Compatibility Description

The PRF (Pseudo Random Function) extension in WebAuthn enables the evaluation of a hash message authentication code stored on the security key during the retrieval of a credential. This mechanism is crucial for generating secret keys vital for encrypting user data. While WebAuthn supports various authentication methods, the focus of this table is the compatibility with the PRF extension.

PRF Compatibility Scenarios Support by Operating System and Latest Browser Versions

OS	Authenticator	Transport	PRF Compatibility
Linux	Linux	Internal
Linux	Android	Hybrid	✅	❌
Linux	iOS	Hybrid	❌	❌
Linux	FIDO Security Key	USB	✅	✅
Windows	Windows	Internal	❌	❌
Windows	Android	Hybrid	✅	✅
Windows	iOS	Hybrid	✅	✅
Windows	FIDO Security Key	USB	✅	✅
MacOS	MacOS	Internal	✅	✅	✅
MacOS	Android	Hybrid	✅	❌	✅
MacOS	iOS	Hybrid	✅	❌	✅
MacOS	FIDO Security Key	USB	✅	❌	❌
Android	Android	Internal	✅	❌
Android	Android	Hybrid	✅	❌
Android	iOS	Hybrid	✅	❌
Android	FIDO Security Key	USB	✅[1]	❌
Android	FIDO Security Key	NFC	❌	❌
iOS	iOS	Internal	✅	✅	✅
iOS	Android	Hybrid	✅	✅	✅
iOS	iOS	Hybrid	✅	✅	✅
iOS	FIDO Security Key	USB	❌	❌	❌
iOS	FIDO Security Key	NFC	❌	❌	❌

^[1] Note on Android with FIDO Security Keys over USB: It's essential to have Google Play Services (GPS) version 24.08.12 or later.

*Notes:

• Additional information about WebAuthn browser compatibility, can be found on Yubico's WebAuthn and PRF Developers page.
• ✅-marked scenarios have been confirmed using the latest public releases of relevant browsers, operating systems, and other dependencies at the time of testing.
• In this table, we use the term "FIDO Security Key" to refer to compatible security keys. It's important to understand that any security key should work with the hmac-secret extension, provided it supports this feature. For a detailed list of security key models that support hmac-secret, you can refer to the FIDO MDS Explorer, where hmac-secret support is listed under metadataStatement > authenticatorGetInfo > extensions.*
• Mozilla Firefox supports the PRF extension starting with version 135.0 or later except on iOS. This is because Firefox generally uses the Gecko engine, but on iOS, all browsers are required to run on WebKit.
• iOS supports PRF extension starting with the iOS 18 release.

The wwWallet is committed to delivering a secure and adaptable authentication experience with an emphasis on PRF extension compatibility.

Tailwind CSS

This project utilizes Tailwind CSS, a utility-first CSS framework that enables rapid development of custom user interfaces with minimal effort. Tailwind CSS offers a collection of utility classes that make styling components and layouts a breeze, eliminating the need for writing extensive custom CSS.

Styling with Utility Classes

To apply styles using Tailwind CSS, you can directly add utility classes to your HTML or JSX components. For example, to apply padding, margin, text color, and more:

<div class="p-4 m-2 text-blue-500">Styled with Tailwind CSS</div>

Customization

Tailwind CSS provides an extensive set of default styles, but you can also customize them to match your project's design. The tailwind.config.js file in the project's root directory allows you to customize colors, fonts, spacing, breakpoints, and more.

Learn More

Explore the Tailwind CSS documentation to learn about all the utility classes, configuration options, and techniques for building beautiful UIs efficiently.

Contributing

Want to contribute? Check out our Contribution Guidelines for more details!