From babc0b82a7fbaee720b53e0695461f38087da7f4 Mon Sep 17 00:00:00 2001 From: Ashley Harwood Date: Tue, 6 Aug 2024 16:05:38 +1000 Subject: [PATCH] docs: technical interoperability testing --- .eslintrc.json | 2 + documentation/docs/test-suites/index.md | 24 ++++ .../getting-started.md | 29 +++++ .../identity-resolution/index.md | 20 ++++ .../identity-resolution/testing.md | 16 +++ .../technical-interoperability/index.md | 20 ++++ .../installation.md | 48 ++++++++ .../storage/index.md | 21 ++++ .../storage/testing.md | 14 +++ .../transparency-graphs/index.md | 22 ++++ .../transparency-graphs/testing.md | 16 +++ .../untp-extensions/index.md | 17 +++ .../untp-extensions/qr-link-encryption.md | 70 ++++++++++++ .../untp-extensions/rendering.md | 107 ++++++++++++++++++ .../verifiable-credentials/index.md | 16 +++ .../verifiable-credentials/testing.md | 18 +++ 16 files changed, 460 insertions(+) create mode 100644 documentation/docs/test-suites/index.md create mode 100644 documentation/docs/test-suites/technical-interoperability/getting-started.md create mode 100644 documentation/docs/test-suites/technical-interoperability/identity-resolution/index.md create mode 100644 documentation/docs/test-suites/technical-interoperability/identity-resolution/testing.md create mode 100644 documentation/docs/test-suites/technical-interoperability/index.md create mode 100644 documentation/docs/test-suites/technical-interoperability/installation.md create mode 100644 documentation/docs/test-suites/technical-interoperability/storage/index.md create mode 100644 documentation/docs/test-suites/technical-interoperability/storage/testing.md create mode 100644 documentation/docs/test-suites/technical-interoperability/transparency-graphs/index.md create mode 100644 documentation/docs/test-suites/technical-interoperability/transparency-graphs/testing.md create mode 100644 documentation/docs/test-suites/technical-interoperability/untp-extensions/index.md create mode 100644 documentation/docs/test-suites/technical-interoperability/untp-extensions/qr-link-encryption.md create mode 100644 documentation/docs/test-suites/technical-interoperability/untp-extensions/rendering.md create mode 100644 documentation/docs/test-suites/technical-interoperability/verifiable-credentials/index.md create mode 100644 documentation/docs/test-suites/technical-interoperability/verifiable-credentials/testing.md diff --git a/.eslintrc.json b/.eslintrc.json index fc11bfd4..95ff9960 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -1,5 +1,7 @@ { "root": true, + // TODO: Enable linting for documentation folder + "ignorePatterns": ["documentation"], "plugins": [ "@typescript-eslint", "prettier" diff --git a/documentation/docs/test-suites/index.md b/documentation/docs/test-suites/index.md new file mode 100644 index 00000000..03fc8fc3 --- /dev/null +++ b/documentation/docs/test-suites/index.md @@ -0,0 +1,24 @@ +--- +sidebar_position: 1 +title: Test Suites +--- + +import Disclaimer from '../\_disclaimer.mdx'; + + + +The UNTP Test Suite comprises three test suites: + +1. [**Technical Interoperability**](/docs/test-suites/technical-interoperability): Validates the technical aspects of implementations against UNTP protocol requirements. + +2. [**Semantic Interoperability**](/docs/test-suites/semantic-interoperability): Ensures credentials produced by an implementation are semantically consistent with the UNTP protocol, allowing for conformance while permitting extensions. + +3. **Graph Validation**: Assesses the entire trust graph produced by an implementation, verifying the integrity and validity of relationships. + +The Test Suite follows a tiered approach: + +- [**Tier 1**](/docs/test-suites/technical-interoperability): Technical interoperability +- [**Tier 2**](/docs/test-suites/semantic-interoperability): Semantic interoperability +- **Tier 3**: Graph validation + +This structure enables progressive validation of UNTP implementations. The Semantic Interoperability and Graph Validation components are extensible, allowing customisation for specific industry needs whilst maintaining core UNTP compliance. diff --git a/documentation/docs/test-suites/technical-interoperability/getting-started.md b/documentation/docs/test-suites/technical-interoperability/getting-started.md new file mode 100644 index 00000000..d878185b --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/getting-started.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 2 +title: Getting Started +--- + +import Disclaimer from '../../\_disclaimer.mdx'; + + + +The Getting Started section covers the following topics for technical interoperability testing: + +1. **Installation**: Learn how to set up the necessary environment for technical interoperability testing. This includes installing required software, setting up test environments, and preparing your system for running the various test suites. + +2. **Configuration**: Understand how to configure the different components of the technical interoperability test suite. We'll cover: + + - Setting up the W3C V2 VCDM test suite for Verifiable Credentials + - Configuring UNTP-specific extension tests + - Preparing for Identity Resolution (IDR) testing + - Setting up storage service testing + - Configuring transparency graph validation tests + +3. **Usage**: Learn how to run the various components of the technical interoperability test suite and interpret the results. This section will guide you through: + - Running the W3C V2 VCDM tests + - Executing UNTP extension tests + - Performing IDR compliance checks + - Conducting storage and data retrieval tests + - Validating transparency graphs + +By the end of this section, you will have a solid foundation for installing, configuring, and using the UNTP Technical Interoperability Test Suite. You'll be able to validate your UNTP implementation's technical components against the required standards. diff --git a/documentation/docs/test-suites/technical-interoperability/identity-resolution/index.md b/documentation/docs/test-suites/technical-interoperability/identity-resolution/index.md new file mode 100644 index 00000000..3df70f38 --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/identity-resolution/index.md @@ -0,0 +1,20 @@ +--- +sidebar_position: 10 +title: Identity Resolution (IDR) +--- + +import Disclaimer from '../../../\_disclaimer.mdx'; + + + +## Overview + +The Identity Resolution (IDR) component of the UNTP ecosystem ensures that identifiers used within the system are properly managed, resolved, and interoperable. This includes: + +- Data carriers (e.g., barcodes, QR codes, RFID tags) +- Identifier structure +- IDR ISO compliance + +Proper implementation of IDR is crucial for maintaining the integrity and traceability of products and entities within the UNTP system. + +For testing procedures, please refer to the [Testing](./testing) page. diff --git a/documentation/docs/test-suites/technical-interoperability/identity-resolution/testing.md b/documentation/docs/test-suites/technical-interoperability/identity-resolution/testing.md new file mode 100644 index 00000000..40d40470 --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/identity-resolution/testing.md @@ -0,0 +1,16 @@ +--- +sidebar_position: 11 +title: Testing Identity Resolution +--- + +import Disclaimer from '../../../\_disclaimer.mdx'; + + + +Detailed testing procedures for the Identity Resolution component will be provided in future updates. These tests will cover: + +1. Data carrier compatibility and readability +2. Correct implementation of identifier structures +3. Compliance with relevant ISO standards + +Please check back later for specific testing instructions and requirements. diff --git a/documentation/docs/test-suites/technical-interoperability/index.md b/documentation/docs/test-suites/technical-interoperability/index.md new file mode 100644 index 00000000..3370c7a9 --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/index.md @@ -0,0 +1,20 @@ +--- +sidebar_position: 1 +title: Technical Interoperability +--- + +import Disclaimer from '../../\_disclaimer.mdx'; + + + +The [United Nations Transparency Protocol (UNTP)](https://uncefact.github.io/spec-untp/) Technical Interoperability test suite ensures that implementations of the UNTP protocol meet the required standards for interoperability. This suite comprises both internal tests developed by the UNTP community and external tests created by other communities. + +The test suite covers five main areas: + +1. [Verifiable Credential Interoperability](./verifiable-credentials) +2. [UNTP-specific Extensions](./untp-extensions) +3. [Identity Resolution (IDR)](./identity-resolution) +4. [Storage](./storage) +5. [Transparency Graphs](./transparency-graphs) + +Each section of the test suite focuses on different aspects of the UNTP implementation, ensuring comprehensive coverage of all technical interoperability requirements. Please refer to the individual sections for more detailed information and testing procedures. diff --git a/documentation/docs/test-suites/technical-interoperability/installation.md b/documentation/docs/test-suites/technical-interoperability/installation.md new file mode 100644 index 00000000..cf2d47f6 --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/installation.md @@ -0,0 +1,48 @@ +--- +sidebar_position: 3 +title: Installation +--- + +import Disclaimer from '../../\_disclaimer.mdx'; + + + +Before you begin installing the Tier 1 test suite, ensure that you have the [dependant services](/docs/mock-apps/dependent-services/) and the following prerequisites in place: + +### Prerequisites + +1. Clone the repository: + + ``` + git clone https://github.com/uncefact/tests-untp.git + ``` + +2. Node.js version 20.12.2: Make sure you have Node.js version 20.12.2 installed on your system. You can download it from the official Node.js website: [https://nodejs.org](https://nodejs.org) + +3. Yarn version 1.22.22: Ensure that you have Yarn version 1.22.22 installed. You can install it by running the following command: + ``` + npm install -g yarn@1.22.22 + ``` + +### Installation Steps + +Once you have met the prerequisites, follow these steps to install the test suite dependencies: + +1. Navigate to the cloned repository directory: + + ``` + cd tests-untp/packages/vc-test-suite + ``` + +2. Install the dependencies using Yarn: + + ``` + yarn install + ``` + +3. Create a folder named reports: + ``` + mkdir reports + ``` + +After completing these steps, you will have all the necessary dependencies for the internal test suite installed. diff --git a/documentation/docs/test-suites/technical-interoperability/storage/index.md b/documentation/docs/test-suites/technical-interoperability/storage/index.md new file mode 100644 index 00000000..97f18512 --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/storage/index.md @@ -0,0 +1,21 @@ +--- +sidebar_position: 8 +title: Storage +--- + +import Disclaimer from '../../../\_disclaimer.mdx'; + + + +## Overview + +The Storage component of the UNTP ecosystem ensures that credentials and related data are securely stored and easily retrievable. This section covers the testing procedures for implementing storage solutions that are compatible with the UNTP protocol. + +Key aspects of the storage system that will be tested include: + +1. Data security and encryption +2. Accessibility and retrieval mechanisms + +Proper implementation and testing of the Storage component are crucial for maintaining the security, integrity, and accessibility of credentials within the UNTP system. + +For specific testing procedures, please refer to the [Testing](./testing) page. diff --git a/documentation/docs/test-suites/technical-interoperability/storage/testing.md b/documentation/docs/test-suites/technical-interoperability/storage/testing.md new file mode 100644 index 00000000..3363f28a --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/storage/testing.md @@ -0,0 +1,14 @@ +--- +sidebar_position: 9 +title: Testing Storage +--- + +import Disclaimer from '../../../\_disclaimer.mdx'; + + + +The Storage component testing suite focuses on verifying the security and accessibility of stored credentials and related data. + +Detailed testing procedures and instructions for running the test suite will be provided in future updates. These tests will ensure that your Storage implementation meets the necessary standards for the UNTP ecosystem. + +Please check back later for specific testing instructions and requirements. diff --git a/documentation/docs/test-suites/technical-interoperability/transparency-graphs/index.md b/documentation/docs/test-suites/technical-interoperability/transparency-graphs/index.md new file mode 100644 index 00000000..599aafe2 --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/transparency-graphs/index.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 12 +title: Transparency Graphs +--- + +import Disclaimer from '../../../\_disclaimer.mdx'; + + + +## Overview + +Transparency Graphs are a key component of the UNTP ecosystem, providing a mechanism to verify the contextual scope of linked credentials and create a comprehensive view of a product's ESG footprint throughout its value chain. + +Key aspects of Transparency Graphs include: + +1. **Linked Credentials**: Assessing bundles of linked credentials drawn from all or part of a value chain. +2. **Contextual Verification**: Verifying the context of related credentials to prevent fraudulent or mismatched attestations. +3. **UNTP Core Vocabulary**: Utilizing uniquely identified linked data entities such as Product, Location, Facility, Party, Standard, Regulation, Criteria, Declaration, Attestation, and Endorsement. + +Transparency Graphs enable the construction of Digital Product Passports and Digital Conformity Credentials, allowing for a comprehensive and verifiable representation of a product's journey and characteristics. + +For testing procedures and more detailed information, please refer to the [Testing](./testing) page. diff --git a/documentation/docs/test-suites/technical-interoperability/transparency-graphs/testing.md b/documentation/docs/test-suites/technical-interoperability/transparency-graphs/testing.md new file mode 100644 index 00000000..98f9e6dc --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/transparency-graphs/testing.md @@ -0,0 +1,16 @@ +--- +sidebar_position: 13 +title: Testing Transparency Graphs +--- + +import Disclaimer from '../../../\_disclaimer.mdx'; + + + +Detailed testing procedures for Transparency Graphs will be provided in future updates. These tests will cover: + +1. Correct linking of credentials within the graph +2. Verification of contextual scope for linked credentials +3. Proper implementation of the UNTP core vocabulary + +Please check back later for specific testing instructions and requirements. diff --git a/documentation/docs/test-suites/technical-interoperability/untp-extensions/index.md b/documentation/docs/test-suites/technical-interoperability/untp-extensions/index.md new file mode 100644 index 00000000..a3686fe8 --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/untp-extensions/index.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 5 +title: UNTP Extensions +--- + +import Disclaimer from '../../../\_disclaimer.mdx'; + + + +## Overview + +The UNTP Extensions section covers specific features and functionalities that extend the core Verifiable Credentials model to meet the needs of the UNTP ecosystem. These extensions include: + +1. [QR Link / Encryption](./qr-link-encryption) +2. [Rendering](./rendering) + +These extensions are crucial for ensuring that UNTP implementations can effectively manage, verify, and display credentials in a standardised manner across different systems and applications. diff --git a/documentation/docs/test-suites/technical-interoperability/untp-extensions/qr-link-encryption.md b/documentation/docs/test-suites/technical-interoperability/untp-extensions/qr-link-encryption.md new file mode 100644 index 00000000..fe33986a --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/untp-extensions/qr-link-encryption.md @@ -0,0 +1,70 @@ +--- +sidebar_position: 6 +title: QR Link / Encryption +--- + +import Disclaimer from './../../../\_disclaimer.mdx'; + + + +The QR Link / Encryption feature is a crucial component of the UNTP ecosystem, providing a standardised way to access, verify, and render credentials. + +For detailed information about the Verify Link structure and usage, please refer to the [Verify Link documentation](/docs/mock-apps/common/verify-link). + +## Testing Instructions + +To test your QR Link / Encryption implementation, follow these steps: + +1. **Obtain a Verify Link**: Obtain a verify link produced by your implementation that you would like to test. + +2. **Update the Configuration**: + + - Navigate to the config file: `packages/vc-test-suite/config.ts` + - Update the `QrLinkEncrypted` section with your verify link (see [payload structure](/docs/test-suites/technical-interoperability/untp-extensions/qr-link-encryption#payload-structure)). The file should look similar to this: + + ```typescript + export default { + implementationName: 'UNTP ACME', + testSuites: { + QrLinkEncrypted: { + url: 'https://example.com/credential-verifier?q=%7B%22payload%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fapi.vckit.showthething.com%2Fencrypted-storage%2Fencrypted-data%2F0a6031a9-2740-49cd-b12b-1ed02820f01d%22%2C%22key%22%3A%22d0ad322ec820a0a420262a6b7dbdafb16eb1d35af459182022bc531d18643546%22%2C%20%22hash%22%3A%20%22QmX8fk9hygXQDbt4KsGEMiUXbt7HDRnb772HNcKtZcL2Zr%22%7D%7D', + headers: {}, + method: 'GET', + }, + }, + }; + ``` + + Replace the `url` value with your verify link. + +3. **Run the Test**: + + - Navigate to `packages/vc-test-suite` + - In your terminal, run the command: `yarn test` + +4. **View Test Results**: + - Navigate to `packages/vc-test-suite/reports/index.html` + - Open this file in a web browser + - Look for the "QR Link Verification" section to view your test results + +These tests will validate that your QR Link / Encryption implementation adheres to the UNTP protocol. + +## Payload Structure + +The QR Link payload is a crucial part of the verification process. Let's break down the structure of the payload: + +```javascript +QrLinkEncrypted: { + url: 'https://example.com/credential-verifier?q=%7B%22payload%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fapi.vckit.showthething.com%2Fencrypted-storage%2Fencrypted-data%2F0a6031a9-2740-49cd-b12b-1ed02820f01d%22%2C%22key%22%3A%22d0ad322ec820a0a420262a6b7dbdafb16eb1d35af459182022bc531d18643546%22%2C%20%22hash%22%3A%20%22QmX8fk9hygXQDbt4KsGEMiUXbt7HDRnb772HNcKtZcL2Zr%22%7D%7D', + headers: {}, + method: 'GET', +}, +``` + +- `url`: This is the full URL for the credential verifier, including the encoded payload. + +- `headers`: An object containing any additional HTTP headers required for the request to the storage service. In this example, it's empty, but you may need to add headers depending on your implementation. + +- `method`: The HTTP method used to request the verifiable credential from the storage service. In this case, it's set to 'GET'. + +The `uri` within the payload points to the storage service that will return the verifiable credential. The `headers` and `method` are used in the request to this storage service. diff --git a/documentation/docs/test-suites/technical-interoperability/untp-extensions/rendering.md b/documentation/docs/test-suites/technical-interoperability/untp-extensions/rendering.md new file mode 100644 index 00000000..d6fdd05f --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/untp-extensions/rendering.md @@ -0,0 +1,107 @@ +--- +sidebar_position: 7 +title: Rendering +--- + +import Disclaimer from '../../../\_disclaimer.mdx'; + + + +The Rendering component of the UNTP extensions focuses on how credential data is visually presented. It utilises a `Render Template`, which is crucial in ensuring consistent and flexible presentation of product information across different systems and applications. To support uptake across supply chain actors with varying levels of technical maturity, human rendering of digital credentials is essential. + +## Render Template Structure + +The Render Template is defined within the credential's `renderMethod` property. It includes the following key elements: + +- `name`: An optional identifier for the template +- `template`: The HTML structure with placeholders for dynamic content +- `@type`: The type of rendering template (e.g., "RenderTemplate2024") +- `mediaType`: The MIME type of the rendered output (typically "text/html") +- `mediaQuery`: Optional CSS media queries for responsive design +- `digestMultibase`: A hash of the template for integrity verification + +## Example Input + +Here's an example of a credential with a render method: + +```json +{ + "credential": { + "@context": [ + "https://www.w3.org/ns/credentials/v2", + { + "ex": "https://www.w3.org/2018/credentials#renderMethod#", + "renderMethod": "https://www.w3.org/2018/credentials#renderMethod", + "template": "ex:template", + "url": "ex:url", + "mediaQuery": "ex:mediaQuery" + } + ], + "renderMethod": [ + { + "name": "template name", + "template": "

{{credentialSubject.name}}

", + "@type": "RenderTemplate2024", + "mediaType": "text/html", + "mediaQuery": "@media (min-width: 1024px) {.name {font-weight: bold}}", + "digestMultibase": "zQmXF936JrjET6pCRdTfs5czN8Ch65NHfsGqKkAwwLkviHA" + } + ], + "credentialSubject": { + "name": "Jane Doe" + } + } +} +``` + +## Expected Output + +A successful render should return a response in the following format: + +```json +{ + "documents": [ + { + "type": "RenderTemplate2024", + "renderedTemplate": "PHN0eWxlPkBtZWRpYSAobWluLXdpZHRoOiAxMDI0cHgpIHsubmFtZSB7Zm9udC13ZWlnaHQ6IGJvbGR9fTwvc3R5bGU+PHA+SmFuZSBEb2U8L3A+", + "name": "template name" + } + ] +} +``` + +The `renderedTemplate` is a base64-encoded string representing the final HTML output, including any specified styles and the rendered credential data. + +## Testing + +To test your Rendering implementation, follow these steps: + +1. **Configure the Test Suite**: + + - Navigate to the config file: `packages/vc-test-suite/config.ts` + - Update the `RenderTemplate2024` section: + + ```javascript + export default { + implementationName: 'UNTP ACME', + testSuites: { + RenderTemplate2024: { + url: 'http://localhost:3332/agent/renderCredential', + headers: {}, + method: 'POST', + }, + }, + }; + ``` + + - Adjust the `url`, `headers`, and `method` as necessary for your implementation. + +2. **Run the Test**: + + - Navigate to `packages/vc-test-suite` + - In your terminal, run the command: `yarn test` + +3. **View Test Results**: + - Navigate to `packages/vc-test-suite/reports/index.html` + - Open this file in a web browser + - Look for the "RenderTemplate2024" section to view your test results diff --git a/documentation/docs/test-suites/technical-interoperability/verifiable-credentials/index.md b/documentation/docs/test-suites/technical-interoperability/verifiable-credentials/index.md new file mode 100644 index 00000000..f886d82c --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/verifiable-credentials/index.md @@ -0,0 +1,16 @@ +--- +sidebar_position: 3 +title: Verifiable Credentials +--- + +import Disclaimer from './../../../\_disclaimer.mdx'; + + + +## Overview + +The [Verifiable Credentials (VC)](https://uncefact.github.io/spec-untp/docs/specification/VerifiableCredentials) interoperability tests focus on ensuring that your implementation produces valid credentials conforming to the [W3C V2 Verifiable Credentials Data Model (VCDM)](https://www.w3.org/TR/vc-data-model-2.0/). + +This section utilises an [external test suite](https://github.com/w3c/vc-data-model-2.0-test-suite) developed by the W3C community. The primary goal is to verify that the VCs produced by your system are compliant with the VCDM specification and can be correctly interpreted by other systems implementing the same standard. + +For detailed testing procedures, please refer to the [Testing](./testing) page. diff --git a/documentation/docs/test-suites/technical-interoperability/verifiable-credentials/testing.md b/documentation/docs/test-suites/technical-interoperability/verifiable-credentials/testing.md new file mode 100644 index 00000000..4124c704 --- /dev/null +++ b/documentation/docs/test-suites/technical-interoperability/verifiable-credentials/testing.md @@ -0,0 +1,18 @@ +--- +sidebar_position: 4 +title: Testing Verifiable Credentials +--- + +import Disclaimer from '../../../\_disclaimer.mdx'; + + + +To test your Verifiable Credential implementation: + +1. Access the [W3C V2 VCDM Test Suite](https://github.com/w3c/vc-data-model-2.0-test-suite). +2. Follow the instructions provided in the test suite repository to set up and run the tests. +3. Ensure that your implementation passes all relevant tests (TBA). + +For more information about the W3C V2 VCDM specification, refer to the [official documentation](https://www.w3.org/TR/vc-data-model-2.0/). + +Please note that while passing these tests is necessary for UNTP compliance, it may not be sufficient. Refer to the [Verifiable Credential section](https://uncefact.github.io/spec-untp/docs/specification/VerifiableCredentials) of the UNTP specification for additional UNTP-specific requirements.