OpenAttestation (验证) (英文)
使用 OpenAttestation (验证) (英文) 寄存器为 npm 模块,您可以校验 包裹的文档 在方案方面。 如果您正在构建自己的 API 或 web 组件, 此选项将有所帮助 。 以下是您需要此模块的常用案例 :
该模块不提供下列功能:
- 对 OA 文档进行程序包装(参见 开口站(中文(简体) )
- OA 文档的加密或解密(参见 OpenAttestation (催泪瓦斯)(中文(简体) )
- 对Ethereum区块链上的任何文件进行程序发布或撤销
核查流量
简言之,核查流程对文件进行了三项检查:
- 文档完整性检查
- 发放状况检查
- 签发身份证
只有在通过所有三种检查时,它才会算作有效的OA文件.
以利亚
下图显示使用Ethereum方法发布的OA文件的核查流程:
没有
下图显示使用DID方法发布的OA文件的核查流程:
安装
要在您的机器上安装 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运行这些验证器 :OpenAttestationEthereumDocumentStoreStatusOpenAttestationEthereumTokenRegistryStatusDidSignedDocumentStatus
-
类型
DOCUMENT_INTEGRITY运行此验证符 :OpenAttestationHash
-
类型
ISSUER_IDENTITY运行这些验证器 :OpenAttestationDnsTxtDnsDidProof
所有这些核查员都是作为 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
高级用途
扩展自定义验证
从 自定义验证 中,您将学习如何写出自定义的验证方法以及如何分发自己的验证器.
构建自定义验证方法
您将按照下列规则写出核查方法:
-
它只能在文件上运行,其版本相当于
https://schema.openattestation.com/2.0/schema.json -
它必须返回有效的碎片,只有当文档数据持有
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 软件公司
- 支助提供者包括:
切换网络
您可以通过下列方式创建验证器来检查自定义网络:
-
提供自己的 Web3 提供者
-
指定网络名称
这样,提供者就会使用默认的.
提供者
以下代码示例显示您如何指定自定义提供者 :
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 解析器 :
提供者
您可以使用支持这些提供者的提供者生成一个提供者:
INFURAALCHEMYETHERSCANJsonRPC
这需要一套选项:
network: 指定为 字符串 用于通用网络名称,即"homestead","mainnet",或"sepolia"provider: 指定为 字符串,即"infura","alchemy",或"jsonrpc"url: 指定为 字符串,用于连接 JSON-RPC HTTP APIapiKey: 指定为 字符串 与提供者一起使用。 如果没有提供值,将使用默认共享的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直接通过数据.
公用事业清单
getOpenAttestationHashFragmentgetOpenAttestationDidSignedDocumentStatusFragmentgetOpenAttestationEthereumDocumentStoreStatusFragmentgetOpenAttestationEthereumTokenRegistryStatusFragmentgetOpenAttestationDidIdentityProofFragmentgetOpenAttestationDnsDidIdentityProofFragmentgetOpenAttestationDnsTxtIdentityProofFragmentgetDocumentIntegrityFragmentsgetDocumentStatusFragmentsgetIssuerIdentityFragmentsisValidFragment: 仅过滤此选项的守护类型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 版。 。 。 .