Skip to content

Commit

Permalink
feat: idvc on v4 (#6)
Browse files Browse the repository at this point in the history
* chore: ds store

* feat: init release

* chore: commit lock

* feat: idvc feature

* feat: idvc feature

* chore: fix lint errors

* feat: regenerate test fixtures for ttv4

* fix: lint errors

* chore: update readme

* chore: fix lint errors

* feat: add additional fixtures for invalid idvc case

* feat: add fixtures for error case when idvc is missing

* fix: lint errors
  • Loading branch information
cavacado authored Nov 10, 2023
1 parent 5f7b366 commit bde00cf
Show file tree
Hide file tree
Showing 93 changed files with 14,077 additions and 13,845 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
.DS_Store
/node_modules
/coverage
.nyc_output
Expand Down
64 changes: 27 additions & 37 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
[![CircleCI](https://circleci.com/gh/Open-Attestation/open-attestation.svg?style=svg)](https://circleci.com/gh/Open-Attestation/open-attestation)
![Release]
(https://github.com/TradeTrust/open-attestation/actions/workflows/release.yml/badge.svg)

# Open Attestation

Expand All @@ -8,12 +9,12 @@ OpenAttestation allows any entity to prove the existence of a document or a batc

Alternatively, OpenAttestation can be used to make digitally verifiable documents using digital signatures, forgoing the need to pay for Ethereum transactions.

The [Open Attestation](https://github.com/Open-Attestation/open-attestation) repository allows you to batch the documents to obtain the merkle root of the batch to be committed to the blockchain. It also allows you to verify the signature of the document wrapped using the OpenAttestation framework.
The [Open Attestation](https://github.com/TradeTrust/open-attestation) repository allows you to batch the documents to obtain the merkle root of the batch to be committed to the blockchain. It also allows you to verify the signature of the document wrapped using the OpenAttestation framework.

## Installation

```bash
npm i @govtechsg/open-attestation
npm i @tradetrust/open-attestation
```

---
Expand All @@ -24,12 +25,14 @@ npm i @govtechsg/open-attestation

`wrapDocuments` takes in an array of documents and returns the wrapped batch. Each document must be valid regarding the version of the schema used (see below) It computes the Merkle root of the batch and appends it to each document. This Merkle root can be published on the blockchain and queried against to prove the provenance of the document issued this way. Alternatively, the Merkle root may be signed by the document issuer's private key, which may be cryptographically verified using the issuer's public key or Ethereum account.

In the future, this function may accept a second optional parameter to specify the version of open-attestation you want to use. Currently, open-attestation will use schema 2.0. See [Additional Information](#additional-information) for information on using experimental v3.0 documents, which aim to be compatible with the W3C's data model for [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/).
In the future, this function may accept a second optional parameter to specify the version of open-attestation you want to use. Currently, open-attestation will use schema 2.0.

See [Additional Information](#additional-information) for information on using experimental v4.0-alpha documents, which aim to be compatible with the W3C's data model for [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/).

The `wrapDocument` function is identical but accepts only one document.

```js
import { wrapDocuments } from "@govtechsg/open-attestation";
import { wrapDocuments } from "@tradetrust/open-attestation";
const document = {
id: "SERIAL_NUMBER_123",
$template: {
Expand Down Expand Up @@ -84,7 +87,7 @@ console.log(wrappedDocuments);
#### Example with public/private key pair

```js
import { signDocument, SUPPORTED_SIGNING_ALGORITHM } from "@govtechsg/open-attestation";
import { signDocument, SUPPORTED_SIGNING_ALGORITHM } from "@tradetrust/open-attestation";
await signDocument(wrappedV2Document, SUPPORTED_SIGNING_ALGORITHM.Secp256k1VerificationKey2018, {
public: "did:ethr:0xE712878f6E8d5d4F9e87E10DA604F9cB564C9a89#controller",
private: "0x497c85ed89f1874ba37532d1e33519aba15bd533cdcb90774cc497bfe3cde655",
Expand All @@ -94,7 +97,7 @@ await signDocument(wrappedV2Document, SUPPORTED_SIGNING_ALGORITHM.Secp256k1Verif
#### Example with signer

```js
import { signDocument, SUPPORTED_SIGNING_ALGORITHM } from "@govtechsg/open-attestation";
import { signDocument, SUPPORTED_SIGNING_ALGORITHM } from "@tradetrust/open-attestation";
import { Wallet } from "ethers";

const wallet = Wallet.fromMnemonic("tourist quality multiply denial diary height funny calm disease buddy speed gold");
Expand All @@ -110,19 +113,19 @@ const { proof } = await signDocument(
`validateSchema` checks that the document conforms to open attestation data structure.

```js
import { validateSchema } from "@govtechsg/open-attestation";
import { validateSchema } from "@tradetrust/open-attestation";
const validatedSchema = validateSchema(wrappedDocument);
console.log(validatedSchema);
```

### Verify signature of document

`verifysignature` checks that the signature of the document corresponds to the actual content in the document. In addition, it checks that the target hash (hash of the document content), is part of the set of documents wrapped in the batch using the proofs.
`verifySignature` checks that the signature of the document corresponds to the actual content in the document. In addition, it checks that the target hash (hash of the document content), is part of the set of documents wrapped in the batch using the proofs.

Note that this method does not check against the blockchain or any registry if this document has been published. The merkle root of this document need to be checked against a publicly accessible document store (can be a smart contract on the blockchain).

```js
import { verifySignature } from "@govtechsg/open-attestation";
import { verifySignature } from "@tradetrust/open-attestation";
const verified = verifySignature(wrappedDocument);
console.log(verified);
```
Expand All @@ -132,22 +135,26 @@ console.log(verified);
`getData` returns the original data stored in the document, in a readable format.

```js
import { getData } from "@govtechsg/open-attestation";
import { getData } from "@tradetrust/open-attestation";
const data = getData(wrappedDocument);
console.log(data);
```

### Utils

```js
import { utils } from "@govtechsg/open-attestation";
import { utils } from "@tradetrust/open-attestation";
utils.isWrappedV3Document(document);
```

- `isWrappedV2Document` type guard for wrapped v2 document
- `isSignedWrappedV2Document` type guard for signed v2 document
- `isSignedWrappedV3Document` type guard for signed v3 document
- `isWrappedV3Document` type guard for wrapped v3 document
- `isSignedWrappedOAV4Document` type guard for signed OA v4 document
- `isWrappedOAV4Document` type guard for wrapped OA v4 document
- `isSignedWrappedTTV4Document` type guard for signed TT v4 document
- `isWrappedTTV4Document` type guard for wrapped TT v4 document
- `diagnose` tool to find out why a document is not a valid open attestation file (wrapped or signed document)

### Obfuscating data
Expand All @@ -167,32 +174,15 @@ To run tests
npm run test
```

### vc-test-suite

You can run the vc-test-suite against `open-attestation` by running `npm run test:vc`. This command will:

- clone https://github.com/w3c/vc-test-suite.git
- copy the local configuration (`vc-test-suite-config.json`) into the cloned repository
- install the latest version of `@govtechsg/open-attestation-cli`
- monkey patch `open-attestation` in `@govtechsg/open-attestation-cli`. That means that the current version of the project will be built and replace the one installed with `@govtechsg/open-attestation-cli`.

#### Local debug

In the event you face a problem with one test and want to debug locally:

1. Ensure the folder `vc-test-suite` is available from the root of the project. If that's not the case, run `npm run test:vc` first.
1. Open `runVcTest.sh` and update `install_vc_test_suite=true` to `install_vc_test_suite=false`. This line will help to preserve the `vc-test-suite` folder untouched.

You can now debug from the `vc-test-suite` folder the way you need it.

## Additional information

- Found a bug? Have a question? Want to share an idea? Reach us at our [Github repository](https://github.com/Open-Attestation/open-attestation).
- We are currently building a new version of the schema, compatible with W3C VC. This is very experimental and whatever is available for v2 documents are also available for v3 documents:
- [OA schema v3](https://schema.openattestation.com/3.0/schema.json)
- Typings: `import {v3} from "@govtechsg/open-attestation"`.
- Type guard: `utils.isWrappedV3Document`.
- Wrapping: `__unsafe__use__it__at__your__own__risks__wrapDocument` (future usage: `wrapDocument(document, {version: "open-attestation/3.0"})`
- Example docs in `tests/fixtures/v3`
- We are currently building a new version of the schema, compatible with W3C VC. This is very experimental and whatever is available for v2 documents are also available for v4 documents:
- [OA schema v4](https://schemata.openattestation.com/io/tradetrust/4.0/alpha-schema.json)
- [TT schema v4](https://schemata.openattestation.com/com/openattestation/4.0/alpha-schema.json)
- Typings: `import {OAv4, TTv4} from "@tradetrust/open-attestation"`.
- Type guard: `utils.isWrappedOAV4Document`, `utils.isWrappedTTV4Document`.
- Wrapping: `_unsafe_use_it_at_your_own_risk_v4_alpha_oa_wrapDocument`, `_unsafe_use_it_at_your_own_risk_v4_alpha_tt_wrapDocument`
- Example docs in `tests/fixtures/v4`
- There are extra utilities available:
- Refer to the [utils](https://github.com/Open-Attestation/open-attestation/blob/master/src/shared/utils/utils.ts) component for the full list of utilities.
- Refer to the [utils](https://github.com/TradeTrust/open-attestation/blob/master/src/shared/utils/utils.ts) component for the full list of utilities.
Loading

0 comments on commit bde00cf

Please sign in to comment.