# @animo-id/pex 中文文档

规范地址：https://npmcn.com/package/%40animo-id/pex/

版本：6\.1\.1
npm 元数据更新时间：2025-06-24T11:23:21.981Z
中文译文更新时间：2026-11-06T04:49:03.968Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40animo-id/pex
原文对照：https://npmcn.com/package/%40animo-id/pex/?lang=original
项目主页：https://github.com/Sphereon-Opensource/pex#readme
源码仓库：https://github.com/Sphereon-Opensource/pex

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.9 MB，408 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：12 个
- 首次发布：2024-11-23T18:16:25.550Z
- 最新版本发布：2025-06-24T11:23:21.740Z
- 近 30 天下载量：45505（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 0 个）

## 中文简介

V1 和 v2 的 Typescription 执行

## 安装

```sh
npm install @animo-id/pex
```

也可以使用：`pnpm add @animo-id/pex`、`yarn add @animo-id/pex`、`bun add @animo-id/pex`

## README

> \[尖叫声\] 这是Sphereon公司临时推出的PEX原始库. [https://github.com/Sphereon-开放源代码/pex](https://github.com/Sphereon-Opensource/pex)

#   
[![Sphereon](https://sphereon.com/content/themes/sphereon/assets/img/logo.svg)](https://www.sphereon.com/)  
演示文稿交换 v1和 v2  
类型脚本库  

[![CI](https://github.com/Sphereon-Opensource/pex/actions/workflows/main.yml/badge.svg)](https://github.com/Sphereon-Opensource/pex/actions/workflows/main.yml) [![codecov](https://codecov.io/gh/Sphereon-Opensource/pex/branch/develop/graph/badge.svg?token=9P1JGUYA35)](https://codecov.io/gh/Sphereon-Opensource/pex) [![NPM Version](https://img.shields.io/npm/v/@sphereon/pex.svg)](https://npm.im/@sphereon/pex)

## 背景情况

演示文稿交换所( PEX) 库执行此功能 说明 [DIF 演示文稿交换规格](https://identity.foundation/presentation-exchange/) 两者 第1版和第2版.

Sphereon 的 PEX 库对验证系统和持有人(例如钱包)都有用,可用于客户端 浏览器和移动应用程序以及服务器侧面技术如REST API(例如由NodeJS所建). 这个 允许任何人在其现有的钱包、代理和/或验证器中添加DIF演示文稿逻辑,而不制作 任何关于密码学、其产品中使用的证书说明等技术的进一步假设.

介绍交流一般如下; 验证人创建演示文稿定义 持证人的全权证书。 全权证书的列报定义发送给持有人,持有人返回a 可核实 提交材料中将全权证书与 作为回应的定义. 提交材料介绍可核查的列报与列报之间的关系 定义. 它可以是可验证演示文稿的一部分,也可以是外部的,比如OpenID4VC规格. 现在核查员将通过检查签名和其他文件来核查可核查的演示文稿 附带证明以及确保提交数据符合规格要求.

演示文稿交易所将确保核查人使用的模型,由持有人解释。 这么说吧 确保使用持有者证书的正确部分来创建演示文稿。 PEX 图书馆 包含全部 解释模型的逻辑,从而消除了核查者和持有者调整其具体 模特们.

PEX中使用的Typescript数据对象(模型)由Sphereon的DIF PEX OpenAPI Spec组件生成. 代码 联 合 国 组件可见于 [PEX- OpenAPI github 仓库](https://github.com/Sphereon-Opensource/pex-openapi)这个 通过配置maven,允许以许多编程语言和框架一致生成对象 插件 .

警告:请注意,这个库不支持最新的V2规格! 将增加支助部分 本库的V3主要版本

### PEX 库支持以下行动:

-   创建演示文稿定义/请求
-   验证符合规格v1和v2的演示文稿定义
-   创建演示文稿
-   使用回调函数创建可验证演示文稿
-   在收到陈述(提交材料)时予以验证
-   投入评价:核查符合列报定义的列报呈件
-   公用事业:建造和使用符合 页:1 [DIF 演示文稿交换 v 2. 0.0 规格](https://identity.foundation/presentation-exchange/)。 。 。 .
-   支助 页:1 [DIF 演示文稿交换 v 1. 0.0 规格](https://identity.foundation/presentation-exchange/spec/v1.0.0/)。 。 。 .

应在单独的库/模块中实施国家存储、签名支持或证书管理 使用此库。 通过保持这些分开,PEX图书馆将留下 平台的不可知性,并倾向于依赖性.

## PEX 用户

库可直接从npmjs通过:

```shell
# install via yarn
  yarn add @sphereon/pex

# install via npm
  npm install @sphereon/pex
```

DIF演示文稿交易所的核心功能可概述如下:

-   核证人/代理人:
    
    -   [评价](https://npmcn.com/package/%40animo-id/pex/#readme-verifier-input-evaluation)
    -   [公用事业](https://npmcn.com/package/%40animo-id/pex/#readme-utilities)
-   持有者/钱包:
    
    -   [证书查询](https://npmcn.com/package/%40animo-id/pex/#readme-holder-credential-query)
    -   [不可验证的演示文稿创建](https://npmcn.com/package/%40animo-id/pex/#readme-holder-presentation-creation-non-verifiable)
    -   [可验证的演示文稿创建](https://npmcn.com/package/%40animo-id/pex/#readme-holder-verifiable-presentation-with-callback)
    -   [公用事业](https://npmcn.com/package/%40animo-id/pex/#readme-utilities)

### 验证器: 创建演示文稿定义对象 :

[列报方式](https://identity.foundation/presentation-exchange/#presentation-definition) 是对象 说明验证人所要求的证据。 这些帮助验证者决定如何或是否与Holder互动. 定义由各种投入组成,这些投入描述它们所需要的证明的形式和细节,以及 可选的一组选择规则,允许持单人灵活处理不同类型证据可能满足 输入要求. PEX 库支持两个版本的 `presentation_definition` 对象。 详细内容可以找到 内 `@spehereon/pex-models` 下面您可以通过演示文稿 定义对象找到一些查询提示 :

-   使用 `constraint` 字段 :
    -   您可以使用约束字段创建您的查询 :

```js
constraints: {
  fields: [
    {
      path: ['$.credentialSubject.role'],
      filter: {
        type: 'string',
        const: 'admin',
      },
    },
  ];
}
```

-   ,例如查询字段 `@` 您可以使用下列语法:
    -   您可以使用以下语法, PEX 将更改它来修正查询本身 :

```js
path: ['$.@context', '$.vc.@context'];
```

为了查询数组,我们现在不支持 [json-schema (日语)](http://json-schema.org/draft-07/schema#) 完全地说, 但我们确实支持以下语法:

-   使用 `[*]` 例如:

```json
{
  "fields": [
    {
      "path": ["$.type.[*]"],
      "filter": {
        "type": "string",
        "pattern": "AlumniCredential"
      }
    }
  ]
}
```

-   使用 `.*` 例如:

```json
{
  "fields": [
    {
      "path": ["$.type.*"],
      "filter": {
        "type": "string",
        "pattern": "AlumniCredential"
      }
    }
  ]
}
```

-   使用 `type: array` 财务报告和审定财务报表 `contains` 关键词 PEX 目前不完全支持这个语法, 但是如果你不依赖 我们 `versionDiscovery` 函数和调用 PEX (PEXv1 或 PEXv2) 的特定版本, 您可以使用此功能 语法也.

```json
{
  "fields": [
    {
      "path": ["$.type"],
      "filter": {
        "type": "array",
        "contains": {
          "enum": ["https://example.com/type"]
        }
      }
    }
  ]
}
```

### 验证:投入评价

投入评价是核查人确定可核查的演示文稿和 持证人的呈文 匹配请求中要求的演示文稿定义。 显然,持有者/Wallet也可以使用这种方法: 在与核查人联系之前,核实其提交是否有效.

```typescript
import { PEX } from '@sphereon/pex';

const pex: PEX = new PEX();

// Example of Presentation Definition V1 (notice the required schema for V1)
const presentationDefinitionV1 = {
  "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
  "input_descriptors": [
    {
      "id": "wa_driver_license",
      "name": "Washington State Business License",
      "purpose": "We can only allow licensed Washington State business representatives into the WA Business Conference",
      "schema": [{
        "uri": "https://licenses.example.com/business-license.json"
      }]
    }
  ]
};

// Example of Presentation Definition V2
const presentationDefinitionV2 = {
  "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
  "input_descriptors": [
    {
      "id": "wa_driver_license",
      "name": "Washington State Business License",
      "purpose": "We can only allow licensed Washington State business representatives into the WA Business Conference"
    }
  ]
};

const verifiablePresentation = {
  '@context': [
    "https://www.w3.org/2018/credentials/v1",
    "https://identity.foundation/presentation-exchange/submission/v1"
  ],
  type: [
    "VerifiablePresentation",
    "PresentationSubmission"
  ],
  presentation_submission: { ... },
  verifiableCredential: [...],
  proof: { ... }
}

// We are using the PEX class, to automatically detect the definition version. PEXv1 and PEXv2 are also available to use fixed PEX versions
const { value, warnings, errors } = pex.evaluatePresentation(presentationDefinitionV2, verifiablePresentation);
```

### 持有者:证书查询

证书查询允许持有者过滤其一组证书,以匹配给定的演示文稿定义. 此过滤出任何传入的非匹配证书 。 请注意,多重全权证书可以是: 满足定义.

```typescript
import { PEX } from '@sphereon/pex';
import { IVerifiableCredential } from "./SSI.types";

const pex: PEX = new PEX();

// Definition from verifier request
const presentationDefinition = {
  ...
};
// Finding out which version presentationDefinition is this:
// The result is either 'v1', 'v2' or an error
// You only have to do this if you want to apply some custom logic. The PEX class uses feature detection on the definition to determine whether it is v1 or v2 internally
const result = PEX.definitionVersionDiscovery(pdSchema);

// Example for loading credentials from your secure storage
const credentials: IVerifiableCredential[] = await secureStore.getCredentials();

// Find matching credentials
const srMatches = pex.selectFrom(presentationDefinition, credentials, { holderDIDs: [holderDID] });

// An example that selects the first 'count' credentials from
// the matches. in a real scenario, the user has to select which
// credentials to use. PEX did the first filtering,
// but there still could be multiple credentials satisfying a presentation definition
const selectedCredentials = srMatches.map(
  ({ matches, count }) => matches.slice(0, count)
).flat();

```

### 持有者:演示文稿创建(不可验证)

创建没有证据的演示文稿(对于证明, 见 [以下可核实格式](https://npmcn.com/package/%40animo-id/pex/#readme-holder-verifiable-presentation-with-callback)你必须通过在 演示文稿定义,所选的可验证的证书和一个可选的持有人(ID). 结果是可验证的 演示,没有证据,所以实际上是一个演示. 本报告还载有秘书处提交的列报数据 修证能用.

由你们在演示文稿上签名,并添加证据,使之成为真正可以验证的演示文稿。 那边 是允许您这样做的不同图书馆。 您也可以使用下次中提及的回调集成 本章.

```typescript
import { PEX, IPresentation, PresentationResult } from '@sphereon/pex';

const pex: PEX = new PEX();

// Construct presentation from selected credentials
const presentationResult: PresentationResult = pex.presentationFrom(presentationDefinition, selectedCredentials, { holderDIDs: [holderDID] });
const presentation = presentationResult.presentation;
/** presentation object:
 *
 *   {
 *     "@context": [
 *       "https://www.w3.org/2018/credentials/v1",
 *       "https://identity.foundation/presentation-exchange/submission/v1"
 *     ],
 *     "type": [
 *       "VerifiablePresentation",
 *       "PresentationSubmission"
 *     ],
 *     presentation_submission: presentationSubmission,
 *     verifiableCredential: selectedCredentials
 *   };
 */
// Presentation would need to be signed and sent to verifier
```

### Holder: 可验证的回调演示文稿

**注:** PEX不支持签名本身的创建. 这和我们不想 依赖各种签名套房和图书馆。 PEX 目前有最小的依赖性,因此可用于 各种情景.

我们怎么解决的? 我们创建了回调机制,允许您提供回调功能,以获取全部 输入允许您使用您选择的库创建签名。 回电需要接受 (单位:千美元) `PresentationSignCallBackParams` 对象.

**注:** 方法 `verifiablePresentationFrom` 接受列报定义,选择可验证的全权证书作为 前两个论点,就像 `presentationFrom` 方法。 接下来它接受调用函数作为参数和 (单位:千美元) `VerifiablePresentationFromOpts` 对象作为最后一个参数。 标志召回参数,允许您控制签名 进程。 你也可以在回话中 访问这些参数.

在调用回调功能之前, 会发生一些事情。 首先,就跟 `presentationFrom` 方法,它 将评估所提供的全权证书是否符合所提供的列报定义。 然后,它创造了一个 演示文稿,就像 `presentationFrom`本演示文稿是为您方便而提供的,可用于您 调用简单的使用大小写。 在较为详细的情况下,例如,有比较复杂的签名套房和/或 有选择的披露,你可能不会直接使用 IPresentation 并使用其他被传递到 呼唤,像 `EvaluationResults`, (中文(简体) ), `PresentationSubmission` 财务报告和审定财务报表 `Partial<IProof>`。 。 。 .

这个 `proofOptions` 财务报告和审定财务报表 `signatureOptions`,允许您直接填充证明值。 在这种情况下 页:1 `Partial<IProof>` 将填充所有字段,仅添加到您的回调中作为演示文稿的证明。 这个 意味着你必须先创建IPresentation 并签名, 这意味着你可能没有用 调用。 如果您不提供这些值,则 `Partial<IProof>`,仍然会有人居住 没有证明Value和 jws,基于你的选项.

#### 演示文稿符号选项

秘书处接受的备选方案 `verifiablePresentationFrom` 它们是:

```typescript
interface VerifiablePresentationFromOpts {
  /**
   * The optional holderDID of the presentation
   */
  holderDID?: string;

  /**
   * The presentation submission data location.
   *
   * Can be External, which means it is only returned and not embedded into the VP,
   * or Presentation, which means it will become part of the VP
   */
  presentationSubmissionLocation?: PresentationSubmissionLocation;

  /**
   * A base presentation payload. Can be used to provide default values. Be aware that any verifiable credential will always be overwritten
   */
  basePresentationPayload?: IPresentation;

  /**
   * IProof options
   */
  proofOptions?: ProofOptions;

  /**
   * The signature options
   */
  signatureOptions?: SignatureOptions;
}

interface ProofOptions {
  /**
   * The signature type. For instance RsaSignature2018
   */
  type?: ProofType | string;

  /**
   * Type supports selective disclosure?
   */
  typeSupportsSelectiveDisclosure?: boolean;

  /**
   * A challenge protecting against replay attacks
   */
  challenge?: string;

  /**
   * A domain protecting against replay attacks
   */
  domain?: string;

  /**
   * The purpose of this proof, for instance assertionMethod or authentication, see https://www.w3.org/TR/vc-data-model/#proofs-signatures-0
   */
  proofPurpose?: ProofPurpose | string;

  /**
   * The ISO8601 date-time string for creation. You can update the IProof value later in the callback. If not supplied the current date/time will be used
   */
  created?: string;

  /**
   * Similar to challenge. A nonce to protect against replay attacks, used in some ZKP proofs
   */
  nonce?: string;
}

interface SignatureOptions {
  /**
   * The private key
   */
  privateKey?: string;

  /**
   * Key encoding
   */
  keyEncoding?: KeyEncoding;

  /**
   * The verification method value
   */
  verificationMethod?: string;

  /**
   * Can be used if you want to provide the Json-ld proof value directly without relying on the callback function generating it
   */
  proofValue?: string; // One of any number of valid representations of proof values

  /**
   * Can be used if you want to provide the JSW proof value directly without relying on the callback function generating it
   */
  jws?: string; // JWS based proof
}
```

这些选项可以通过访问 `options` 输入 页:1 `PresentationSignCallBackParams`。 。 。 .

#### 回调参数对象

调用参数作为您调用函数的单个参数来提供 。 它包含 `Presentation`页:1 部分“ Proof” 通常缺少证据Value/ jws 签名。 里面还装有最初提供的可验证的 全权证书和列报 定义以及您提供的选项.

如果包含演示文稿提交对象,该对象也存在于演示文稿中. 您可以使用它来创建您的 如果您需要, 则拥有 IPresentation 对象。 最后载有评价结果,其中包括绘图和日志 关于评估.

您可以选择使用 `Presentation` 和部分 `Proof` 一、导 言 `options`,或更详细 选择使用 `PresentationSubmission`, (中文(简体) ), `EvaluationResults` 编辑 `options` 举个例子.

```typescript
export interface PresentationSignCallBackParams {
  /**
   * The originally supplied presentation sign options
   */
  options: VerifiablePresentationFromOpts;

  /**
   * The presentation definition
   */
  presentationDefinition: PresentationDefinition;

  /**
   * The selected credentials to include in the eventual VP as determined by PEX and/or user
   */
  selectedCredentials: (IVerifiableCredential | JwtWrappedVerifiableCredential | string)[];

  /**
   * The presentation object created from the definition and verifiable credentials.
   * Can be used directly or in more complex situations can be discarded by using the definition, credentials, proof options, submission and evaluation results
   */
  presentation: IPresentation;

  /**
   * A partial proof value the callback can use to complete. If proofValue or JWS was supplied the proof could be complete already
   */
  proof: Partial<IProof>;

  /**
   * The presentation submission data, which can also be found in the presentation itself
   */
  presentationSubmission: PresentationSubmission;

  /**
   * The evaluation results, which the callback function could use to create a VP using the proof(s) using the supplied credentials
   */
  evaluationResults: EvaluationResults;
}
```

#### 回调函数的简单示例

使用您所选择的库进行非选择性披露的简单使用大小写 .

```typescript
import { PEX, IProof, ProofPurpose, ProofType, IVerifiablePresentation, PresentationSignOptions, KeyEncoding } from '@sphereon/pex';

const pex: PEX = new PEX();

const params: VerifiablePresentationFromOpts = {
  holderDID: 'did:example:1234....',
  proofOptions: {
    type: ProofType.Ed25519Signature2018,
    proofPurpose: ProofPurpose.assertionMethod,
  },
  signatureOptions: {
    verificationMethod: 'did:example:"1234......#key',
    keyEncoding: KeyEncoding.Base58,
    privateKey: 'base58 (key encoding type) key here',
  },
};

const vp = await pex.verifiablePresentationFrom(presentationDefinition, selectedCredentials, simpleSignedProofCallback, params);

function simpleSignedProofCallback(callBackParams: PresentationSignCallBackParams): IVerifiablePresentation {
  // Prereq is properly filled out `proofOptions` and `signatureOptions`, together with a `proofValue` or `jws` value.
  // And thus a generated signature
  const { presentation, proof, options } = callBackParams; // The created partial proof and presentation, as well as original supplied options
  const { signatureOptions, proofOptions } = options; // extract the orignially supploed signature and proof Options
  const privateKeyBase58 = signatureOptions.privateKey; // Please check keyEncoding from signatureOptions first!

  /**
   * IProof looks like this:
   * {
   *    type: 'Ed25519Signature2018',
   *    created: '2021-12-01T20:10:45.000Z',
   *    proofPurpose: 'assertionMethod',
   *    verificationMethod: 'did:example:"1234......#key',
   *    .....
   * }
   */

  // Just an example. Obviously your lib will have a different method signature
  const vp = myVPSignLibrary(presentation, { ...proof, privateKeyBase58 });

  return vp;
}
```

### 公用事业

除以上核心功能外,基础验证方法被曝光为低级帮助器 函数.

```typescript
import { PEX } from '@sphereon/pex';

const presentationDefinition = {
  ...
};

const result = PEX.definitionVersionDiscovery(presentationDefinition);
const { warnings: pdWarnings, errors: pdErrors } = PEX.validateDefinition(presentationDefinition);

const presentationSubmission = {
  ...
};

const { warnings: psWarnings, errors: psErrors } = PEX.validateSubmission(presentationSubmission);
```

## API 密码

### 评价

```typescript
PEX.evaluatePresentation(presentationDefinition, verifiablePresentation);
PEXv1.evaluatePresentation(presentationDefinition, verifiablePresentation);
PEXv2.evaluatePresentation(presentationDefinition, verifiablePresentation);
```

##### 说明

这三种方法相当相似. 第一个收到演示文稿定义对象,决定版本 根据特征检测和相应的行为。 另外两种是特定于其列报交换定义的 版本.

**请将v1和v2的更详细区别改为: [从V1到V2区](https://npmcn.com/package/%40animo-id/pex/#readme-from-v1-to-v2)**。 。 。 .

评估演示文稿是否符合所要求的演示文稿定义,因为将使用这种方法 两者 **在此之前** 财务报告和审定财务报表 **之后** 创建一个可验证的介绍, 我们接受两者 _签名_ 财务报告和审定财务报表 _未签名_ 版本 a 在这里展示.

#### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `presentationDefinition` | `PresentationDefinition` | 发起核查者请求的演示文稿定义 |
| `presentation` | `IPresentation` | 内有所需全权证书和 `presentation_submission` 对象映射到演示文稿定义 |

#### 返回值

如果评价成功, `value` 将是一个无核 `PresentationSubmission` 将提交的全权证书映射到 请输入.

```typescript
interface EvaluationResults {
  value?: PresentationSubmission;
  warnings?: string[];
  errors?: Error[];
  verifiableCredential: (IVerifiableCredential | JwtWrappedVerifiableCredential | string)[];
}
```

### 从

```typescript
PEX.selectFrom(presentationDefinition, credentials, { holderDIDs });
PEXv1.selectFrom(presentationDefinitionV1, credentials, { holderDIDs });
PEXv2.selectFrom(presentationDefinitionV2, credentials, { holderDIDs });
```

##### 说明

这三种方法相当相似. 第一个收到演示文稿定义对象,决定版本 根据特征检测和相应的行为。 其他两种是其版本所特有的.

**请将该规格的v1和v2的更详细区别改为: [从V1到V2区](https://npmcn.com/package/%40animo-id/pex/#readme-from-v1-to-v2)**。 。 。 .

收集符合特定演示文稿定义的匹配证书。 请注意可能存在多种情况 符合同样标准的结果。 这基本上只过滤出不符合定义的证书. 您, 或更确切地说, 用户通常必须进行最后的选择 .

#### 从参数中选择

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `presentationDefinition` | `PresentationDefinition` | 发起核查者请求的演示文稿定义 |
| `credentials` | `(IVerifiableCredential or JwtWrappedVerifiableCredential or string)[]` | 从 |
| `{ holderDIDs }` | `string[]` | 持枪者做。 可以在 VeriblePresentation 的持有者属性说明中找到, 钱包可以让许多持有者 DID 从不同的地方检索到 |

#### 返回值

-   如果选择成功或部分成功 `matches` 数组将包含 联 合 国 `SubmissionRequirementMatch` 对象,代表每个对象的匹配证书 `SubmissionRequirement` 内 页:1 `presentationDefinition` 输入参数.
-   如果选择不成功,则 `errors` 阵列将由 `Checked` 对象,代表什么 选择过程中失败 .

```typescript
import { Status } from './ConstraintUtils';

interface SelectResults {
  errors?: Checked[];
  matches?: SubmissionRequirementMatch[];
  /**
   * This is the parameter that the PEX library user should look into to determine what to do next
   * Status can have three values:
   *  1. INFO: everything is fine, you can call `presentationFrom` after this method
   *  2. WARN: method was called with more credentials than required.
   *       To enhance credential holderDID's privacy it is recommended to select credentials which are absolutely required.
   *  3. Error: the credentials you've sent didn't satisfy the requirement defined presentationDefinition object. Do not submit!
   */
  areRequiredCredentialsPresent: Status;
  /**
   * All matched/selectable credentials
   */
  verifiableCredential?: (IVerifiableCredential | JwtWrappedVerifiableCredential | string)[];
  /**
   * Following are indexes of the verifiableCredentials passed to the selectFrom method that have been selected.
   */
  vcIndexes?: number[];
  warnings?: Checked[];
}

interface SubmissionRequirementMatch {
  name?: string;
  rule: Rules;
  min?: number;
  count?: number;
  max?: number;
  vc_path: string[];
  from?: string[];
  from_nested?: SubmissionRequirementMatch[]; // VerifiableCredential Address
}
```

### 演示文稿来源

```typescript
PEX.presentationFrom(presentationDefinition, selectedCredentials, { holderDID });
PEXv1.presentationFrom(presentationDefinitionV1, selectedCredentials, { holderDID });
PEXv2.presentationFrom(presentationDefinitionV2, selectedCredentials, { holderDID });
```

##### 说明

这三种方法相当相似. 第一个收到演示文稿定义对象,决定版本 根据特征检测和相应的行为。 其他两种是其版本所特有的.

\*\* 关于v1和v2规格的更详细区别,请读 [从V1到V2区](https://npmcn.com/package/%40animo-id/pex/#readme-from-v1-to-v2) 页:1.

创建相应的演示文稿提交对象,以包含在可验证的演示文稿响应中 将提交的全权证书映射到 `presentationDefinition` 输入参数.

#### 从 V1 参数显示

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `presentationDefinition` | `PresentationDefinitionV1` | 启动验证人请求的 v1 演示文稿定义 |
| `selectedCredentials` | `(IVerifiableCredential or JwtWrappedVerifiableCredential or string)[]` | 符合列报定义中提交要求的可核查全权证书数量 |
| `{ holderDID }` | `string` | 持枪者做了。 这可见于VerablePresentation的持有者财产附注,即钱包可以让许多持有者DID从不同地点检索到 |

#### 来自V2参数的演示文稿

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `presentationDefinition` | `PresentationDefinitionV2` | 启动验证人请求的 v2 演示文稿定义 |
| `selectedCredentials` | `(IVerifiableCredential or JwtWrappedVerifiableCredential or string)[]` | 符合列报定义中提交要求的可核查全权证书数量 |
| `{ holderDID }` | `string` | 持枪者做了。 这可见于VerablePresentation的持有者财产附注,即钱包可以让许多持有者DID从不同地点检索到 |

#### 返回值

如果选中的证书成功地符合演示文稿定义中的提交要求,则返回 值将是一个非null “介绍” ,其中包含 `PresentationSubmission`

```typescript
interface PresentationSubmission {
  id?: string;
  definition_id: string;
  descriptor_map: Descriptor[];
}
```

### 验证

```typescript
PEX.validateDefinition(objToValidate);
PEXv1.validateDefinition(objToValidate);
PEXv2.validateDefinition(objToValidate);
```

```typescript
validateSubmission(objToValidate);
```

#### 说明

用于验证的功能 `PresentationDefinition` 财务报告和审定财务报表 `PresentationSubmission` 对象。 如果你知道这个版本 定义。 否则,您可拨打普通电话(地址: PEX),首先确定版本,然后根据该版本的具体内容验证演示文稿定义对象 规则.

#### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `objToValidate` | `PresentationDefinition | PresentationSubmission` | 有待验证的列报定义或列报呈件 |

#### 返回值

这个 `validate` 方法返回已验证的结果阵列 `NonEmptyArray<Checked>` ,结构:

```typescript
interface Checked {
  tag: string;
  status: Status;
  message?: string;
}
```

状态可以有以下的值 `'info' | 'warn' | 'error'`

### 定义版本发现

```typescript
PEX.definitionVersionDiscovery(presentationDefinition);
```

#### 说明

用于 `PresentationDefinition` 对象。 此方法将决定您的版本 演示文稿定义对象.

#### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `presentationDefinition` | `PresentationDefinition` | 您需要决定版本的演示文稿定义 |

#### 返回值

这个 `definitionVersionDiscovery` 方法返回一个版本或错误,结构如下:

```typescript
interface DiscoveredVersion {
  version?: PEVersion;
  error?: string;
}

enum PEVersion {
  v1 = 'v1',
  v2 = 'v2',
}
```

## 从V1到V2

以下修改为v2版本的"演示交换"规格. V1还是最厉害的 主导版本,因为它在OpenID4VC情景和互通剖面图中通常被相当地使用.

1.  所需数额 `schema` 已完全删除 `InputDescriptor` 属性,因为它令人困惑 冗余.
2.  `presentation_definition` 拥有另一个名为 `frame` 如果存在, 它的价值必须是 JSON LD Framing 文档对象 。 用于选择性披露. 虽然这个图书馆目前没有使用,因为我们可以表演 没有框.
3.  `filter` 还有几个过滤选项:
    -   格式宏
    -   格式最小值
    -   格式 专有元素
    -   最小范围

因此,我们引入了 `PEX` 类来取代前者 `PEJS` 课。 此类的特性检测 演示文稿定义以确定它是v1还是v2 spec. 然后将功能委托给PEXv1或 分别为PEXv2级. 另见: [v0.6 断裂变化](https://npmcn.com/package/%40animo-id/pex/#readme-breaking-change-class-and-package-renamed-as-of-v060)

**警告:请注意,这个库不支持最新的V2规格! 支助将增加为 本库V3主要版本的一部分**

## 工作流程图

下面的图显示了一个验证器和一个钱包之间的典型互动的外观. 它对实际运输不作假设(DIDComm、SIOPv2/OIDC4VP、CHAPI、REST)

![Flow diagram](https://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/Sphereon-Opensource/pex/develop/docs/simple-scenario.puml)

## 对于 PEX 开发者

这个项目是通过以下方法创建的:

-   `yarn` 1.22.5版 翻译
-   `node` 第16个版本

### 安装

```shell
yarn install
```

### 构建

```shell
yarn build
```

### 测试

测试命令运行 :

-   `eslint`
-   `prettier`
-   `unit`

您也可以只运行这些测试的单个部分, 例如使用 `yarn test:unit`。 。 。 .

```shell
yarn test
```

### 工具脚本

还有几种其他的效用脚本可以帮助开发.

-   `yarn fix` - 运行 `eslint --fix` 以及 `prettier` 以修正代码样式
-   `yarn cov` - 生成代码覆盖报告

# 词汇表

| 任期 | 定义 |
| --- | --- |
| 证书 | 发行人提出的一套一项或多项债权. |
| 可验证证书 | 是一个不言自明的证书 拥有可以加密验证的作者身份 可验证的证书可用于构建可验证的演示文稿,也可以通过加密验证. 证书中的主张可以针对不同的主体. PEX接受可验证的证书,有三种形式: 1. JSON LD在我们系统中称为"可验证证书", 2. JWT- Wrapped VC 在我们的系统中被称为 JwtWrapped 验证证书或字符串,属于有效的验证证书jwt |
| 列报方式 定义 | 列报定义是指阐明验证者所要求的证据的对象. |
| 持有者 | 持有者是拥有一项或多项可核查证书的实体。 持有者也是向验证人提交证据以满足列报定义所描述要求的实体. |
| 持枪者已死亡 | 独特的 ID URI 字符串和 PKI 元数据文档格式,用于描述密码密钥和与持有人钱包中唯一,用户控制,自我主权标识符相链接的其他基本的 PKI 值 |
| 验证人 | 验证者是指为了进行互动而界定其从Holder(通过演示文稿定义)那里需要的证据的实体. |
| 发行人 | 一个实体可以发挥作用,就一个或多个主体提出权利要求,从这些要求中产生可核查的证明,并将可核查的证明传递给持有人. |
| 列报 | 一个或多个签发人签发的一项或多项可核查证书的数据 |
| 可核实的演示文稿 | 一种不言自明的演示文稿是否以这样的方式编码,在加密核实之后,可以信任数据的作者身份. |

## 进一步工作:

这一实施完全支持列报交换规格的V1和部分2,具体如下: 例外:

-   V1 规格中计划部分对散列链接核查的支持没有完全纳入,因为它取决于 显示缺少外部图书馆支持。 如果我们遇到他们,我们就会发出关于缺乏核查的警告.
-   支持完成 [json-schema (日语)](http://json-schema.org/draft-07/schema#) 内 `pex-models`
    -   这意味着如果你依赖于我们的版本发现特性(使用调用通用 `PEX`和 发送 `presentation_definition` 不支持的字段对象,将获得例外。 不过如果你打电话 其PEX(PEXv1或PEXv2)的特定版本将有效.
-   V2执行并不包含最新的V2变化. 这些将在该图书馆的V3中提供

## 中断更改

### v2.0.0 参数和结果对象略有变化

在图书馆的V2中,我们在PEX外部接口上做了一些重构,使其更加统一.

所有PEX方法的可选论点现在都属于可选论点的一部分 `opts` 对象参数。 这样可以更干净 未来延期,以及 也解决了在需要多个可选参数的情况下可选参数顺序的问题.

PEX/PEXv1/PEXv2类中某些与状态无关的方法已转向静态方法,以便 (b) 更明确地区分与国家有关的方法和与非国家有关的方法.

`presentationFrom` 财务报告和审定财务报表 `verifiablePresentationFrom` 现在返回结果对象,而不是直接返回 a( (原始内容存档于2017-10-21) (中文(简体) ). Official Presentation. 理由是,在某些用途中,您想要有一个外部演示文稿提交对象,例如 在 OpenID4VP 中.

您现在可以提供演示文稿对象的可选参数。 永远如此 返回方法中,以及显示是否外部使用或嵌入(可验证)方法中 介绍.

(可验证)演示对象在演示文稿resp中的结果对象中存在. 可核查 列报 属性.

在演示文稿定义中不再需要 const 和 enum 模型/属性。 他们现在 `const` 财务报告和审定财务报表 `enum` (已固定) 在OpenAPI模型生成中). 代码替换了之前的版本,以便确定.

### v. 6.0: 类和包重命名

作为引入演示文稿交换 v1和v2 特性检测支持的一部分,用于我们的演示文稿交换 我们决定更改软件包和主条目类的名称:

-   软件包改为 `@sphereon/pe-js` 改为 `@sphereon/pex`
-   主课改为 `PEJS` 改为 `PEX`。后一类有内部特性检测支持 定义,将实际执行委托给新的 `PEXv1` 或者说 `PEXv2` 课堂内部。 如果你没有 想要自动特性检测,您也可以选择使用 `PEXv1` 财务报告和审定财务报表 `PEXv2` 直接上课.

## 许可证

此演示文稿交换库开放源码软件,在 页:1 [Apache 2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0.html)。 。 。 .

## 由

![](https://npmcn.com/package/%40animo-id/pex/logos-supporter.png)

## 常见问题

### @animo-id/pex 是什么？

V1 和 v2 的 Typescription 执行

### 如何安装 @animo-id/pex？

在项目目录运行 npm install @animo-id/pex，或使用 pnpm add / yarn add / bun add。

### @animo-id/pex 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @animo-id/pex 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @animo-id/pex 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @animo-id/pex 可以商用吗？

@animo-id/pex 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @animo-id/pex 的下载量有多少？

根据 npm 官方下载统计，@animo-id/pex 在 2026/10/06 – 2026/11/04 这 30 天内被下载 45,505 次，日均约 1,517 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @animo-id/pex 还在维护吗？

最新版本 6\.1\.1 发布于 2025/06/24（1\.4 年前）；至今共发布 12 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/11/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。