@govtechsg/oa-verify

中文文档
9.4.0发布于 2024/11/27Apache-2.0TypeScriptESM + CJS近 30 天下载 6324

使用 OpenAttestation (验证) (英文) 寄存器为 npm 模块中,您可以校验 [被包装的文档] (页:1

中文使用文档
文档目录24 节
  1. 核查流量
  2. 以利亚
  3. 没有
  4. 安装
  5. 使用量
  6. 正在验证文档
  7. 自定义验证
  8. 自定义验证
  9. 听取个别核查方法
  10. 高级用途
  11. 扩展自定义验证
  12. 环境变量
  13. 切换网络
  14. 指定解析器
  15. 提供者
  16. 示例
  17. 铀和类型
  18. 概览
  19. 示例
  20. 公用事业清单
  21. 核查方法
  22. 发展
  23. 许可证
  24. 补充资料

OpenAttestation (验证) (英文)

使用 OpenAttestation (验证) (英文) 寄存器为 npm 模块,您可以校验 包裹的文档 在方案方面。 如果您正在构建自己的 API 或 web 组件, 此选项将有所帮助 。 以下是您需要此模块的常用案例 :

该模块不提供下列功能:

  • 对 OA 文档进行程序包装(参见 开口站(中文(简体) )
  • OA 文档的加密或解密(参见 OpenAttestation (催泪瓦斯)(中文(简体) )
  • 对Ethereum区块链上的任何文件进行程序发布或撤销

核查流量

简言之,核查流程对文件进行了三项检查:

  1. 文档完整性检查
  2. 发放状况检查
  3. 签发身份证

只有在通过所有三种检查时,它才会算作有效的OA文件.

以利亚

下图显示使用Ethereum方法发布的OA文件的核查流程:

Verify OA documents issued using Ethereum

没有

下图显示使用DID方法发布的OA文件的核查流程:

Verify OA documents issued using DID

安装

要在您的机器上安装 OpenAttestation( 验证), 请运行以下命令 :

npm i @govtechsg/oa-verify

使用量

正在验证文档

对包裹的文件进行核查,进行下列核查:

  • 文件被篡改了吗?
  • 文件的签发状态是否有效?
  • 证件签发人的身份是否有效? (见 身份证明(中文(简体) )

校验需要使用 开口站。下面是包裹文件的例子,该文件是有效的,已在塞波利亚网络上发布.

{
  "version": "https://schema.openattestation.com/2.0/schema.json",
  "data": {
    "billFrom": {},
    "billTo": { "company": {} },
    "$template": {
      "type": "f76f4d39-8d23-455b-96ba-5889e0233641:string:EMBEDDED_RENDERER",
      "name": "575f0624-7f43-484c-9285-edd1ae96ebc6:string:INVOICE",
      "url": "fb61f072-64e9-4c2f-83bf-ae68fd911414:string:https://generic-templates.tradetrust.io"
    },
    "issuers": [
      {
        "name": "ed121e9e-8f70-4a01-a422-4509d837c13f:string:Demo Issuer",
        "documentStore": "08948d61-9392-459f-b476-e3c51961f04b:string:0x49b2969bF0E4aa822023a9eA2293b24E4518C1DD",
        "identityProof": {
          "type": "61c13b84-181a-43aa-85f5-dfe89e4b6963:string:DNS-TXT",
          "location": "d7ba5e33-cf5f-4fcc-a4b7-3e6e17324966:string:demo-tradetrust.openattestation.com"
        },
        "revocation": {
          "type": "23d47c6b-4384-4c31-90ca-8284602f6b3e:string:NONE"
        }
      }
    ],
    "links": {
      "self": {
        "href": "121c55c0-864d-4e54-a1f0-86bec4b9a050:string:https://action.openattestation.com?q=%7B%22type%22%3A%22DOCUMENT%22%2C%22payload%22%3A%7B%22uri%22%3A%22https%3A%2F%2Ftradetrust-functions.netlify.app%2F.netlify%2Ffunctions%2Fstorage%2Faea9cb1a-816a-4fd7-b3a9-84924dc9a9e9%22%2C%22key%22%3A%22d80b453e53bb26d3b36efe65f18f0482f52d97cffad6f6c9c195d10e165b9a83%22%2C%22permittedActions%22%3A%5B%22STORE%22%5D%2C%22redirect%22%3A%22https%3A%2F%2Fdev.tradetrust.io%2F%22%2C%22chainId%22%3A%225%22%7D%7D"
      }
    },
    "network": {
      "chain": "05eb1707-5426-41d8-8fde-bc48ff0f2182:string:ETH",
      "chainId": "ae505425-2df7-4597-87d2-037418d7bcbf:string:5"
    }
  },
  "signature": {
    "type": "SHA3MerkleProof",
    "targetHash": "f292056ed5e5535400cec63b78a84ec384d2d77117e1606a17644e7b97a03cac",
    "proof": [],
    "merkleRoot": "f292056ed5e5535400cec63b78a84ec384d2d77117e1606a17644e7b97a03cac"
  }
}

为了对文件进行核查检查,使用以下代码:

// index.ts
import { isValid, verify } from "@govtechsg/oa-verify";
import * as document from "./document.json";

const fragments = await verify(document as any);

console.log(isValid(fragments)); // output true

自定义验证

默认情况下,提供 verify 方法对文档进行多次检查.

  • 类型 DOCUMENT_STATUS 运行这些验证器 :

    • OpenAttestationEthereumDocumentStoreStatus
    • OpenAttestationEthereumTokenRegistryStatus
    • DidSignedDocumentStatus
  • 类型 DOCUMENT_INTEGRITY 运行此验证符 :

    • OpenAttestationHash
  • 类型 ISSUER_IDENTITY 运行这些验证器 :

    • OpenAttestationDnsTxt
    • DnsDidProof

所有这些核查员都是作为 openAttestationVerifiers

您可以根据默认的导出验证器构建自己的验证方法 :

// creating your own verification method using default exported verifiers
import { verificationBuilder, openAttestationVerifiers } from "@govtechsg/oa-verify";

const verify1 = verificationBuilder(openAttestationVerifiers, { network: "sepolia" }); // this verification is equivalent to the one exported by the library

const verify2 = verificationBuilder([openAttestationVerifiers[0], openAttestationVerifiers[1]], {
  network: "sepolia",
}); // this verification only runs 2 verifiers

您也可以根据自定义验证器构建自己的验证方法:

// creating your own verification using custom verifier
import { verificationBuilder, openAttestationVerifiers, Verifier } from "@govtechsg/oa-verify";
const customVerifier: Verifier<any> = {
  skip: () => {
    // returns a SkippedVerificationFragment if the verifier should be skipped or throws an error if it should always run
  },
  test: () => {
    // returns true or false
  },
  verify: async (document) => {
    // performs checks and returns a fragment
  },
};

// creates your own verify function with all verifiers and your custom one
const verify = verificationBuilder([...openAttestationVerifiers, customVerifier], { network: "sepolia" });

参见 扩展自定义验证 以查找如何创建自定义验证器.

自定义验证

将在核实文件后产生碎片。 每个片段将确定是否所指的个别类型 这里 是否有效,并将集体证明文件的有效性.

这个 isValid 函数将在碎片上执行,并确定碎片是否产生有效结果。 默认情况下,该函数将返回 true 如果文件满足下列所有条件:

  • 文件没有被篡改.
  • 和 该文件已经印发.
  • 和 该文件没有被撤销.
  • 和 发行人身份有效.

在函数中,一个类型列表也作为第二个参数来检查.

// index.ts
import { isValid, openAttestationVerifiers, verificationBuilder } from "@govtechsg/oa-verify";
import * as document from "./document.json";

const verify = verificationBuilder(openAttestationVerifiers, {
  network: "mainnet",
});

const fragments = await verify(document as any);

console.log(isValid(fragments, ["DOCUMENT_INTEGRITY"])); // output true
console.log(isValid(fragments, ["DOCUMENT_STATUS"])); // output false
console.log(isValid(fragments, ["ISSUER_IDENTITY"])); // output false
console.log(isValid(fragments)); // output false

以下解释函数返回的原因:

  • isValid(fragments, ["DOCUMENT_INTEGRITY"]) 返回时 true 因为文档的完整性并不取决于其发布的网络.
  • isValid(fragments, ["DOCUMENT_STATUS"]) 返回时 false 因为文档尚未在Ethereum主网络上发布.
  • isValid(fragments, ["ISSUER_IDENTITY"]) 返回时 false 因为没有 DNS TXT 记录 与Ethereum主网络的文档商店有关.
  • isValid(fragments) 返回时 false 因为上面至少有一个返回是虚假的.

听取个别核查方法

这个 verify 函数提供了一种可以倾听单个核查方法的选项。 例如,如果您想要在您的UI上提供单个加载器,则可能有用 .

下面是一个带有该选项的代码示例:

// index.ts
import { isValid, openAttestationVerifiers, verificationBuilder } from "@govtechsg/oa-verify";
import * as document from "./document.json";

const verify = verificationBuilder(openAttestationVerifiers, {
  network: "sepolia",
});

const promisesCallback = (verificationMethods: any) => {
  for (const verificationMethod of verificationMethods) {
    verificationMethod.then((fragment: any) => {
      console.log(`${fragment.name} has been resolved with status ${fragment.status}`);
    });
  }
};

const fragments = await verify(document as any, promisesCallBack);

console.log(isValid(fragments)); // output true

高级用途

扩展自定义验证

从 自定义验证 中,您将学习如何写出自定义的验证方法以及如何分发自己的验证器.

构建自定义验证方法

您将按照下列规则写出核查方法:

  1. 它只能在文件上运行,其版本相当于 https://schema.openattestation.com/2.0/schema.json

  2. 它必须返回有效的碎片,只有当文档数据持有 name 带有值的属性 Certificate of Completion

文件版本

这里 skip 财务报告和审定财务报表 test 需要采用各种方法。 你会使用 test 当核查方法运行时返回的方法和 skip 解释为什么不是的方法:

// index.ts
import { verificationBuilder, openAttestationVerifiers, Verifier, isValid } from "@govtechsg/oa-verify";
import { getData } from "@govtechsg/open-attestation";
import * as document from "./document.json";

const customVerifier: Verifier<any> = {
  skip: async () => {
    return {
      status: "SKIPPED",
      type: "DOCUMENT_INTEGRITY",
      name: "CustomVerifier",
      reason: {
        code: 0,
        codeString: "SKIPPED",
        message: `Document doesn't have version equal to 'https://schema.openattestation.com/2.0/schema.json'`,
      },
    };
  },
  test: () => document.version === "https://schema.openattestation.com/2.0/schema.json",
};

说明: 使用 DOCUMENT_INTEGRITY 类型来检查文档内容.

这个 name 属性

一旦你决定 when 您需要将校验方法的逻辑写入 verify 方法。 你会使用 获取数据 用于访问文档数据并视内容返回适当的碎片:

// index.ts
import { verificationBuilder, openAttestationVerifiers, Verifier, isValid } from "@govtechsg/oa-verify";
import { getData } from "@govtechsg/open-attestation";
import * as document from "./document.json";

const customVerifier: Verifier<any> = {
  skip: async () => {
    /* content has been defined in the section above */
  },
  test: () => /* content has been defined in the section above */,
  verify: async (document: any) => {
    const documentData = getData(document);
    if (documentData.name !== "Certificate of Completion") {
      return {
        type: "DOCUMENT_INTEGRITY",
        name: "CustomVerifier",
        data: documentData.name,
        reason: {
          code: 1,
          codeString: "INVALID_NAME",
          message: `Document name is ${documentData.name}`,
        },
        status: "INVALID",
      };
    }
    return {
      type: "DOCUMENT_INTEGRITY",
      name: "CustomVerifier",
      data: documentData.name,
      status: "VALID",
    };
  },
};

构建自定义验证方法

这个 verify 函数用于运行核查方法列表。 每个核查者将产生一个碎片,以确定文件是否有效。 OpenAtterstation 中有自己的一套核查方法 openAttestationVerifiers。 。 。 .

使用 verificationBuilder 函数,您可以创建自定义校验方法,并重用从库中导出的默认方法.

从 自定义验证 中,您将使用下面的自定义验证方法新建验证器:

// index.ts
import { verificationBuilder, openAttestationVerifiers, Verifier, isValid } from "@govtechsg/oa-verify";
import { getData } from "@govtechsg/open-attestation";
import document from "./document.json";

// based on the test condition specified below, your custom verifier will only check documentData.name if document.version is equal to https://schema.openattestation.com/2.0/schema.json
const customVerifier: Verifier<any> = {
  skip: async () => {
    return {
      status: "SKIPPED",
      type: "DOCUMENT_INTEGRITY",
      name: "CustomVerifier",
      reason: {
        code: 0,
        codeString: "SKIPPED",
        message: `Document doesn't have version equal to 'https://schema.openattestation.com/2.0/schema.json'`,
      },
    };
  },
  test: () => document.version === "https://schema.openattestation.com/2.0/schema.json",
  verify: async (document: any) => {
    const documentData = getData(document);
    if (documentData.name !== "Certificate of Completion") {
      return {
        type: "DOCUMENT_INTEGRITY",
        name: "CustomVerifier",
        data: documentData.name,
        reason: {
          code: 1,
          codeString: "INVALID_NAME",
          message: `Document name is ${documentData.name}`,
        },
        status: "INVALID",
      };
    }
    return {
      type: "DOCUMENT_INTEGRITY",
      name: "CustomVerifier",
      data: documentData.name,
      status: "VALID",
    };
  },
};

// create your own verify function with all verifiers and your custom one
const verify = verificationBuilder([...openAttestationVerifiers, customVerifier], { network: "sepolia" });

const fragments = await verify(document);

console.log(isValid(fragments)); // return false
console.log(fragments.find((fragment: any) => fragment.name === "CustomVerifier")); // display the details on our specific verifier

文档你 创建 根据您自己的核查人,无效,因为 name 属性不存在。 使用以下文档再次测试:

{
  "version": "https://schema.openattestation.com/2.0/schema.json",
  "data": {
    "name": "66e35a92-9e97-4ffc-b94e-769773dd7535:string:Certificate of Completion",
    "issuers": [
      {
        "documentStore": "375a13f9-ca3d-4a1f-a0c9-1fa92e43a3ec:string:0x8Fc57204c35fb9317D91285eF52D6b892EC08cD3",
        "name": "448c7f62-3a93-4792-a157-fabcbf15b91a:string:University of Blockchain",
        "identityProof": {
          "type": "dcfc17e0-a178-4bb8-b0fb-6a2cfddb8f2f:string:DNS-TXT",
          "location": "e3f54dbf-bb51-41bb-9511-e01a5c07ea86:string:example.openattestation.com"
        }
      }
    ]
  },
  "privacy": { "obfuscatedData": [] },
  "signature": {
    "type": "SHA3MerkleProof",
    "targetHash": "975887a864e11fbe27e90f4759c44db90193abc237dede81cd3cd7ca45c46522",
    "proof": [],
    "merkleRoot": "975887a864e11fbe27e90f4759c44db90193abc237dede81cd3cd7ca45c46522"
  }
}

环境变量

  • PROVIDER_API_KEY你可以提供自己的 PROVIDER API 密钥.

  • PROVIDER_ENDPOINT_URL: 您可以提供您首选的 JSON- RPC HTTP API URL .

  • PROVIDER_NETWORK:你可以指定要使用的网络,即"homestead","mainnet",或"sepolia".

  • PROVIDER_ENDPOINT_TYPE:您可以指定要使用的提供者,即"infura","alchemy"或"jsonrpc".

    • 支助提供者包括:
      • 因福拉语Name
      • 以太色扫描
      • 炼金术
      • JSON-RPC 软件公司

切换网络

您可以通过下列方式创建验证器来检查自定义网络:

  1. 提供自己的 Web3 提供者

  2. 指定网络名称

    这样,提供者就会使用默认的.

提供者

以下代码示例显示您如何指定自定义提供者 :

const verify = verificationBuilder(openAttestationVerifiers, { provider: customProvider });

网络

以下代码示例显示您如何指定网络 :

const verify = verificationBuilder(openAttestationVerifiers, { network: "sepolia" });

指定解析器

使用暴露的图像 createResolver 方法,您可以轻松创建自定义解析器以解析 DDE:

import { createResolver, verificationBuilder, openAttestationVerifiers } from "@govtechsg/oa-verify";

const resolver = createResolver({
  networks: [{ name: "my-network", rpcUrl: "https://my-private-chain/besu", registry: "0xaE5a9b9..." }],
});

const verify = verificationBuilder(openAttestationVerifiers, { resolver });

现在, oa-verify 支持两个 DDE 解析器 :


提供者

您可以使用支持这些提供者的提供者生成一个提供者:

  • INFURA
  • ALCHEMY
  • ETHERSCAN
  • JsonRPC

这需要一套选项:

  • network: 指定为 字符串 用于通用网络名称,即"homestead","mainnet",或"sepolia"
  • provider: 指定为 字符串,即"infura","alchemy",或"jsonrpc"
  • url: 指定为 字符串,用于连接 JSON-RPC HTTP API
  • apiKey: 指定为 字符串 与提供者一起使用。 如果没有提供值,将使用默认共享的API密钥,这可能导致性能下降和被节制的请求.

示例

以下是基本使用案例: provider数字 :

import { utils } from "@govtechsg/oa-verify";
const provider = utils.generateProvider();
// This will generate an infura provider using the default values.

备选方法1

这种方法使用环境变量:

// environment file
PROVIDER_NETWORK = "sepolia";
PROVIDER_ENDPOINT_TYPE = "infura";
PROVIDER_ENDPOINT_URL = "http://jsonrpc.com";
PROVIDER_API_KEY = "ajdh1j23";

// provider file
import { utils } from "@govtechsg/oa-verify";
const provider = utils.generateProvider();
// This will use the environment variables declared in the files automatically.

备选方法2

这种方法作为参数通过值:

import { utils } from "@govtechsg/oa-verify";
const providerOptions = {
  network: "sepolia",
  providerType: "infura",
  apiKey: "abdfddsfe23232",
};
const provider = utils.generateProvider(providerOptions);
// This will generate a provider based on the options provided.
// Note: Using this declaration will override all environment variables and default values.

铀和类型

概览

现有各种公用事业和类型来证明碎片的正确性。 每种核查方法都输出碎片的类型和与碎片有关的数据.

  • 分型有四种口味: VALID, (中文(简体) ), INVALID, (中文(简体) ), SKIPPED,以及 ERROR。 。 。 .
  • VALID 财务报告和审定财务报表 INVALID 大部分时间以两种口味提供碎片数据,每种版本各一个 OpenAttestation (V2或V3).

该图书馆提供下列类型和公用事业:

  • 从所有碎片中取出特定的碎片 verify 方法.
  • 缩小到特定的碎片类型.
  • 缩小到碎片的具体数据.

示例

以下代码示例显示了使用方式:

import { utils } from "@govtechsg/oa-verify";
const fragments = verify(documentValidWithCertificateStore, { network: "sepolia" });
// return the correct fragment, correctly typed
const fragment = utils.getOpenAttestationEthereumTokenRegistryStatusFragment(fragments);

if (utils.isValidFragment(fragment)) {
  // guard to narrow to the valid fragment type
  const { data } = fragment;
  if (ValidTokenRegistryDataV2.guard(data)) {
    // data is correctly typed here
  }
}

说明: 在上述例子中,可能没有必要使用 utils.isValidFragment,因为它是可能的使用 ValidTokenRegistryDataV2.guard 直接通过数据.

公用事业清单

  • getOpenAttestationHashFragment
  • getOpenAttestationDidSignedDocumentStatusFragment
  • getOpenAttestationEthereumDocumentStoreStatusFragment
  • getOpenAttestationEthereumTokenRegistryStatusFragment
  • getOpenAttestationDidIdentityProofFragment
  • getOpenAttestationDnsDidIdentityProofFragment
  • getOpenAttestationDnsTxtIdentityProofFragment
  • getDocumentIntegrityFragments
  • getDocumentStatusFragments
  • getIssuerIdentityFragments
  • isValidFragment: 仅过滤此选项的守护类型 VALID 碎片类型
  • isInvalidFragment: 仅过滤此选项的守护类型 INVALID 碎片类型
  • isErrorFragment: 仅过滤此选项的守护类型 ERROR 碎片类型
  • isSkippedFragment: 仅过滤此选项的守护类型 SKIPPED 碎片类型

核查方法

名称类型说明默认验证人在场?
OpenAttestationHash 打开站点文件编号 校验 Merkle 根和目标散列是否匹配证书对
已签名文件状态文件统计( S)验证已签名证书的签名的有效性对
OpenAtterstation 文档状态文件统计( S)校验证书已发给文档存储, 但未被撤销对
OpenAtterstation Ethreadum Token Registry status 打开电源站到此为止文件统计( S)验证证书已签发给象征性的注册人,而不撤销对
OpenAttestation 身份验证度独立验证 DDE 的身份( 类似于 OpenAttestation 已经签名文件状态)没有
OpenAttestation Dns 身份验证独立使用 DNS- TXT 验证已执行证书的身份对
OpenAttestation DnsTxtID 特性独立使用 DNS- TXT 验证文档存储证书的身份对

发展

要进行测试,请使用以下命令:

npm run test

要生成测试文档( 对于 V3 ), 请使用脚本 scripts/generate.v3.ts 并运行以下命令:

npm run generate:v3

许可证

OpenAttestation( 验证) 位于 Apache 许可证, 第 2.0 版。 。 。 .

补充资料

  • 关于核查SDK实施情况的更多信息,请沿用 验证结果。 。 。 .
  • 如果你发现一个错误,有一个问题, 或者想分享一个想法 Github 仓库。 。 。 .

版本与发布记录

@govtechsg/oa-verify 共发布 88 个版本,首次发布于 2019/04/01;过去 12 个月发布了 0 个版本。

版本发布日期距今
9.4.0latest2024/11/272 年前
9.3.22024/09/192 年前
9.3.12024/08/082 年前
9.3.0-beta.4beta2024/08/012 年前
9.3.0-beta.32024/07/182 年前
9.3.02024/07/182 年前

其他发布通道:alpha → 9.3.0-alpha.1,beta → 9.3.0-beta.4。

关于 @govtechsg/oa-verify 的常见问题

@govtechsg/oa-verify 是什么?

使用 OpenAttestation (验证) (英文) 寄存器为 npm 模块中,您可以校验 [被包装的文档] (页:1

如何安装 @govtechsg/oa-verify?

在项目目录运行 npm install @govtechsg/oa-verify,或使用 pnpm add / yarn add / bun add。

@govtechsg/oa-verify 支持 TypeScript 吗?

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

@govtechsg/oa-verify 支持 ESM 还是 CommonJS?

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

@govtechsg/oa-verify 可以商用吗?

@govtechsg/oa-verify 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@govtechsg/oa-verify 的下载量有多少?

根据 npm 官方下载统计,@govtechsg/oa-verify 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,324 次,日均约 211 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@govtechsg/oa-verify 还在维护吗?

最新版本 9.4.0 发布于 2024/11/27(2 年前);至今共发布 88 个版本,其中过去 12 个月发布了 0 个;首次发布于 2019/04/01。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。