# @pagopa/io-wallet-utils Latest version **1.5.7** (published 2026-09-11) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install @pagopa/io-wallet-utils pnpm add @pagopa/io-wallet-utils yarn add @pagopa/io-wallet-utils bun add @pagopa/io-wallet-utils ``` ## Health **Score 75/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 1.5.7 | | Published | 2026-09-11 | | First published | 2025-10-17 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 3 | | Unpacked size | 89.3 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 6 | | Maintainers | pp-ps, giuseppe-nuccio-crea, diego.lagosmorales | ## Links - npm: https://www.npmjs.com/package/@pagopa/io-wallet-utils - Repository: https://github.com/pagopa/io-wallet-sdk - Homepage: https://github.com/pagopa/io-wallet-sdk/tree/main/packages/utils - Issues: https://github.com/pagopa/io-wallet-sdk/issues - npm.io page: https://npm.io/package/@pagopa/io-wallet-utils ## Dependencies (3) - [zod](https://npm.io/package/zod.md) ^4.3.6 - [@openid4vc/utils](https://npm.io/package/@openid4vc/utils.md) 0.4.3 - [@openid4vc/oauth2](https://npm.io/package/@openid4vc/oauth2.md) 0.4.3 ## Recent versions - 1.5.7 (latest) — 2026-09-11 - 1.5.4-alpha-20260731074954 (alpha) — 2026-07-31 - 1.5.6 — 2026-09-10 - 1.5.5 — 2026-09-04 - 1.5.4 — 2026-07-31 - 1.5.4-alpha-20260717125503 — 2026-07-17 - 1.5.4-alpha-20260714095946 — 2026-07-14 - 1.5.3 — 2026-06-26 - 1.5.3-alpha-20260626074041 — 2026-06-26 - 1.5.2 — 2026-06-10 - 1.5.1 — 2026-06-09 - 1.5.0 — 2026-06-05 - 1.4.2 — 2026-05-29 - 1.4.2-alpha-20260522091203 — 2026-05-22 - 1.4.1 — 2026-05-18 - … 45 more at https://npm.io/package/@pagopa/io-wallet-utils/versions ## README # IO Wallet SDK [![CI](https://github.com/pagopa/io-wallet-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/pagopa/io-wallet-sdk/actions) [![npm](https://img.shields.io/npm/v/@pagopa/io-wallet-utils?label=latest)](https://www.npmjs.com/search?q=%40pagopa%2Fio-wallet) A comprehensive TypeScript library for building applications that integrate with **Italy's national digital identity wallet**. 🇮🇹 This SDK provides all the necessary tools to handle Verifiable Credentials and secure interactions according to the official Italian specifications, which are based on **OpenID for Verifiable Credentials (OpenID4VC)** and **OAuth 2.0** standards. The project is structured as a monorepo using `pnpm` and is designed to be environment-agnostic (Node.js, Browser, React Native), allowing you to build services for Relying Parties, Issuers, and Wallets. ## Key Features - **Full IT-Wallet Compliance**: Implements the specific profiles and flows required by the official [IT Wallet specifications](https://italia.github.io/eid-wallet-it-docs/en/), supporting versions **V1.0**, **V1.3**, and **V1.4**. - **Modern & Secure**: Built with TypeScript and includes support for modern OAuth 2.0 extensions like `PAR`, `DPoP`, and `PKCE`. - **Modular Architecture**: The core logic is split into scoped packages, so you only use what you need. - **Crypto Agnostic**: Does not impose a specific cryptographic library. ## Packages This SDK is a monorepo containing the following packages: | Package | Description | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`@pagopa/io-wallet-oauth2`** | Implements core OAuth 2.0 flows and security extensions (PAR, DPoP, PKCE, JARM) required for secure interactions. | | **`@pagopa/io-wallet-oid-federation`** | Handles entity discovery and trust chain resolution within the Italian Federation, ensuring all actors are trusted and valid. | | **`@pagopa/io-wallet-oid4vci`** | Manages **Verifiable Credential Issuance** flows. Use this to build Issuer services for credentials like the `mso_mdoc` (e.g., Digital Driver's License). | | **`@pagopa/io-wallet-oid4vp`** | Manages **Verifiable Presentation** flows. Use this to build Relying Party services that request and verify user credentials from the IT-Wallet. | | **`@pagopa/io-wallet-utils`** | Shared types, configuration (`IoWalletSdkConfig`, `ItWalletSpecsVersion`), and utilities used across all packages. | ## Documentation Public SDK API documentation is published at [pagopa.github.io/io-wallet-sdk](https://pagopa.github.io/io-wallet-sdk/). ## Which packages do I need? The IT-Wallet ecosystem has three distinct actor roles. Install only the packages relevant to your use case. | Role | Description | Packages | | ---- | ----------- | -------- | | **Relying Party** (Verifier) | Requests and verifies credentials from a user's wallet | `@pagopa/io-wallet-oid4vp`, `@pagopa/io-wallet-oid-federation` | | **Credential Issuer** | Issues Verifiable Credentials to a wallet | `@pagopa/io-wallet-oid4vci`, `@pagopa/io-wallet-oid-federation` | | **Wallet Provider** | Manages wallet instance lifecycle and attestations | `@pagopa/io-wallet-oid4vci`, `@pagopa/io-wallet-oauth2`, `@pagopa/io-wallet-oid-federation` | All roles require `@pagopa/io-wallet-utils` for shared configuration types. ## Installation Install the packages for your role: ```bash # Relying Party (Verifier) pnpm add @pagopa/io-wallet-oid4vp @pagopa/io-wallet-oid-federation @pagopa/io-wallet-utils # Credential Issuer pnpm add @pagopa/io-wallet-oid4vci @pagopa/io-wallet-oid-federation @pagopa/io-wallet-utils # Wallet Provider pnpm add @pagopa/io-wallet-oid4vci @pagopa/io-wallet-oauth2 @pagopa/io-wallet-oid-federation @pagopa/io-wallet-utils ``` ## Callback Pattern This SDK is **crypto-agnostic and environment-agnostic**. Instead of bundling a specific cryptographic library or HTTP client, every function that needs to sign JWTs, hash data, or make HTTP requests accepts a `callbacks` object where you provide your own implementations. This makes the SDK compatible with Node.js, browsers, and React Native without modification. ```typescript import { createTokenDPoP } from '@pagopa/io-wallet-oauth2'; const result = await createTokenDPoP({ // Provide your own implementations for cryptographic operations callbacks: { signJwt: async (signer, { header, payload }) => { // Use any JWT library or hardware key (e.g. node-jose, jose, HSM) return { jwt: myJwtLibrary.sign(header, payload, myPrivateKey), signerJwk: myPublicJwk, }; }, hash: async (data, algorithm) => { // Use any hash implementation (e.g. SubtleCrypto, node:crypto) const digest = await crypto.subtle.digest(algorithm, data); return new Uint8Array(digest); }, generateRandom: async (byteLength) => { // Use any CSPRNG available in your environment return crypto.getRandomValues(new Uint8Array(byteLength)); }, }, signer: { method: 'jwk', publicJwk: myPublicJwk, alg: 'ES256' }, tokenRequest: { method: 'POST', url: 'https://issuer.example.com/token' }, }); ``` Each function documents exactly which callbacks it requires via TypeScript's `Pick`, so you only implement what is needed. ## Development To set up the repository for local development: 1. Clone the repository : ```bash git clone https://github.com/pagopa/io-wallet-sdk.git cd io-wallet-sdk ``` 2. Install dependencies: ```bash pnpm install ``` 3. Build all packages: ```bash pnpm run build ``` ## Version Configuration The SDK supports multiple versions of the Italian Wallet technical specifications. You must configure the version in some methods using `IoWalletSdkConfig`. | Spec Version | Status | | ------------ | ------ | | V1.0 | Supported | | V1.3 | Supported | | V1.4 | Supported | ```typescript import { IoWalletSdkConfig, ItWalletSpecsVersion } from '@pagopa/io-wallet-utils'; const config = new IoWalletSdkConfig({ itWalletSpecsVersion: ItWalletSpecsVersion.V1_4 // or V1_0, V1_3 }); ``` ## 🧭 Contribute For internal development conventions and contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md). ## License This project is licensed under the Apache License Version 2.0 (Apache-2.0). ## Credits It builds upon the foundation of the [oid4vc-ts](https://github.com/openwallet-foundation-labs/oid4vc-ts) library from the OpenWallet Foundation, extending it to meet the specific requirements of the Italian digital ecosystem. --- _Source: https://npm.io/package/@pagopa/io-wallet-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._