From 1fd775c7bc3076739d5c1a23cde8f6c4c8b8adec Mon Sep 17 00:00:00 2001 From: Ashley Harwood Date: Fri, 2 Aug 2024 09:11:56 +1000 Subject: [PATCH] docs: technical interoperability testing --- .eslintrc.json | 15 +- ...ocs.yml.disabled => buld_publish_docs.yml} | 4 +- documentation/docs/test-suites/index.md | 24 +++ .../cli/configuration.md | 169 ++++++++++++++++++ .../cli/extensions.md | 53 ++++++ .../semantic-interoperability/cli/index.md | 18 ++ .../cli/installation.md | 47 +++++ .../semantic-interoperability/cli/usage.md | 56 ++++++ .../getting-started.md | 20 +++ .../semantic-interoperability/index.md | 36 ++++ .../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 ++ documentation/docusaurus.config.ts | 24 ++- 25 files changed, 873 insertions(+), 27 deletions(-) rename .github/workflows/{buld_publish_docs.yml.disabled => buld_publish_docs.yml} (97%) create mode 100644 documentation/docs/test-suites/index.md create mode 100644 documentation/docs/test-suites/semantic-interoperability/cli/configuration.md create mode 100644 documentation/docs/test-suites/semantic-interoperability/cli/extensions.md create mode 100644 documentation/docs/test-suites/semantic-interoperability/cli/index.md create mode 100644 documentation/docs/test-suites/semantic-interoperability/cli/installation.md create mode 100644 documentation/docs/test-suites/semantic-interoperability/cli/usage.md create mode 100644 documentation/docs/test-suites/semantic-interoperability/getting-started.md create mode 100644 documentation/docs/test-suites/semantic-interoperability/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..f02a6df8 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -1,9 +1,7 @@ { "root": true, - "plugins": [ - "@typescript-eslint", - "prettier" - ], + "plugins": ["@typescript-eslint", "prettier"], + "ignorePatterns": ["documentation"], "parser": "@typescript-eslint/parser", "extends": [ "eslint:recommended", @@ -11,10 +9,7 @@ "plugin:@typescript-eslint/recommended-requiring-type-checking" ], "parserOptions": { - "project": [ - "./packages/tsconfig.settings.json", - "./packages/*/tsconfig.json" - ] + "project": ["./packages/tsconfig.settings.json", "./packages/*/tsconfig.json"] }, "rules": { "no-console": "warn", @@ -30,9 +25,7 @@ }, "overrides": [ { - "files": [ - "*.js" - ], + "files": ["*.js"], "rules": { "@typescript-eslint/no-var-requires": "off" } diff --git a/.github/workflows/buld_publish_docs.yml.disabled b/.github/workflows/buld_publish_docs.yml similarity index 97% rename from .github/workflows/buld_publish_docs.yml.disabled rename to .github/workflows/buld_publish_docs.yml index 720307a1..d150787a 100644 --- a/.github/workflows/buld_publish_docs.yml.disabled +++ b/.github/workflows/buld_publish_docs.yml @@ -2,9 +2,9 @@ name: Deploy to GitHub Pages on: - push: + pull_request: branches: - - main + - next jobs: deploy: 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/semantic-interoperability/cli/configuration.md b/documentation/docs/test-suites/semantic-interoperability/cli/configuration.md new file mode 100644 index 00000000..280085d5 --- /dev/null +++ b/documentation/docs/test-suites/semantic-interoperability/cli/configuration.md @@ -0,0 +1,169 @@ +--- +sidebar_position: 5 +title: Configuration +--- + +import Disclaimer from './../../../\_disclaimer.mdx'; + + + +Before proceeding, we need to create the configuration file. The Tier 2 test suite config file defines the credentials being tested, the schema version to test against, and the location of the credential being tested. + +## Generating the configuration file + +To generate the configuration file, run the following command: + +```bash +yarn run untp config +``` + +This will create a base configuration file named `credentials.json` in the base directory of the Tier 2 test suite folder: `tests-untp/packages/untp-test-suite/credentials.json`. + +## Structure of the configuration file + +The generated configuration file will have the following structure: + +```json +{ + "credentials": [ + { + "type": "aggregationEvent", + "version": "v0.0.1", + "dataPath": "" + }, + { + "type": "conformityCredential", + "version": "v0.0.1", + "dataPath": "" + }, + { + "type": "objectEvent", + "version": "v0.0.1", + "dataPath": "" + }, + { + "type": "productPassport", + "version": "v0.0.1", + "dataPath": "" + }, + { + "type": "transactionEvent", + "version": "v0.0.1", + "dataPath": "" + }, + { + "type": "transformationEvent", + "version": "v0.0.1", + "dataPath": "" + } + ] +} +``` + +### Credentials +The value of the credentials property is an array of objects containing information about the credential type (corresponding to a schema), the credential schema version, and the location of the credential to be tested. + +### Schema and version structure + +The schemas used in the test suite are located in the following directory structure: + +``` +packages/ +└── untp-test-suite/ + └── src/ + └── schemas/ + ├── aggregationEvent/ + │ └── v0.0.1/ + │ └── schema.json + ├── conformityCredential/ + │ └── v0.0.1/ + │ └── schema.json + ├── objectEvent/ + │ └── v0.0.1/ + │ └── schema.json + ├── productPassport/ + │ └── v0.0.1/ + │ └── schema.json + ├── transactionEvent/ + │ └── v0.0.1/ + │ └── schema.json + └── transformationEvent/ + └── v0.0.1/ + └── schema.json +``` + +### Type +The `type` property value corresponds to the folder name within the `src/schemas` directory of the test suite. This allows logical grouping of schema versions. For example, `"type": "aggregationEvent"` corresponds to the `aggregationEvent` folder. + +### Version +The `version` property value corresponds to the folder name within the respective credential type folder. For example, `"version": "v0.0.1"` corresponds to the `v0.0.1` folder within the credential type folder. + +### Data Path + +The `dataPath` value is the relative location of the credential you want to test against the schema type and version. + +## Adding test credentials + +To test credentials developed or produced by a UNTP implementation against the core UNTP data model: + +1. Create a directory to store the credentials you want to test: + +```bash +cd packages/untp-test-suite +mkdir credentials +``` + +2. Add the credentials you want to test to the directory created in the previous step. The files should have unique names and be in JSON format: + +``` +packages/ +└── untp-test-suite/ + ├── credentials/ + ├── aggregationEvent-sample.json + ├── conformityCredential-sample.json + ├── objectEvent-sample.json + ├── productPassport-sample.json + ├── transactionEvent-sample.json + └── transformationEvent-sample.json +``` + +3. Update the config file to point to the location of the credential you want to test within the corresponding object and save the file: + +```json +{ + "credentials": [ + { + "type": "aggregationEvent", + "version": "v0.0.1", + "dataPath": "credentials/aggregationEvent-sample.json" + }, + { + "type": "conformityCredential", + "version": "v0.0.1", + "dataPath": "credentials/conformityCredential-sample.json" + }, + { + "type": "objectEvent", + "version": "v0.0.1", + "dataPath": "credentials/objectEvent-sample.json" + }, + { + "type": "productPassport", + "version": "v0.0.1", + "dataPath": "credentials/productPassport-sample.json" + }, + { + "type": "transactionEvent", + "version": "v0.0.1", + "dataPath": "credentials/transactionEvent-sample.json" + }, + { + "type": "transformationEvent", + "version": "v0.0.1", + "dataPath": "credentials/transformationEvent-sample.json" + } + ] +} +``` + +You have now successfully configured the Tier 2 test suite to test your credentials against the core UNTP data model. \ No newline at end of file diff --git a/documentation/docs/test-suites/semantic-interoperability/cli/extensions.md b/documentation/docs/test-suites/semantic-interoperability/cli/extensions.md new file mode 100644 index 00000000..a21e98e7 --- /dev/null +++ b/documentation/docs/test-suites/semantic-interoperability/cli/extensions.md @@ -0,0 +1,53 @@ +--- +sidebar_position: 7 +title: Extensions +--- + +import Disclaimer from './../../../_disclaimer.mdx'; + + + +The [United Nations Transparency Protocol (UNTP)](https://uncefact.github.io/spec-untp/) allows for extensions to its core data model. The UNTP Semantic Interoperability Test Suite can validate these extensions, ensuring they remain compliant with the core UNTP data model. This enables implementors to prototype and test custom credential types or additional properties while maintaining conformance with the UNTP protocol. + +## Adding a Custom Schema + +1. Create a new directory for your schema: + +``` +packages/ +└── untp-test-suite/ + └── src/ + └── schemas/ + └── myCustomCredential/ + └── v0.0.1/ + └── schema.json +``` + +2. Define your schema in `schema.json`, extending the core UNTP model as needed. + +3. Update `credentials.json` to include your new credential type: + +```json +{ + "credentials": [ + // ... existing credentials + { + "type": "myCustomCredential", + "version": "v0.0.1", + "dataPath": "credentials/myCustomCredential-sample.json" + } + ] +} +``` + +4. Create a sample credential file matching your schema. + +5. Run the test suite to validate your extended credential: + +```bash +yarn run untp test +``` + +By following these steps, you can prototype extensions to the UNTP data model while ensuring compatibility with the core specification. + +Remember to thoroughly test your extensions and consider submitting valuable additions to the [UNTP community](https://github.com/uncefact/tests-untp) for potential inclusion in future versions of the protocol or submit your extension to the [extensions register](https://uncefact.github.io/spec-untp/docs/extensions). \ No newline at end of file diff --git a/documentation/docs/test-suites/semantic-interoperability/cli/index.md b/documentation/docs/test-suites/semantic-interoperability/cli/index.md new file mode 100644 index 00000000..17ac8a76 --- /dev/null +++ b/documentation/docs/test-suites/semantic-interoperability/cli/index.md @@ -0,0 +1,18 @@ +--- +sidebar_position: 3 +title: CLI +--- + +import Disclaimer from './../../../\_disclaimer.mdx'; + + + +The [United Nations Transparency Protocol (UNTP)](https://uncefact.github.io/spec-untp/) Semantic Interoperability Test Suite CLI is a powerful tool designed for rapid validation of credentials produced by UNTP implementers and implementations. This suite ensures that the credentials comply with the core UNTP data model, making it an essential resource for developers, organisations and communities working with the UNTP protocol. + +## Key Features + +- **Rapid Validation**: Quickly verify the compliance of UNTP credentials with the core data model. +- **Prototype Testing**: Ideal for credential development, allowing you to prototype and test extensions to the UNTP protocol. +- **Flexibility**: Suitable for both implementation testing and exploratory development. + +By the end of this section, you will have a solid understanding of how to install, configure and use the CLI to validate UNTP credentials. You will be familiar with the configuration file structure, available commands and how to test your extensions against the core UNTP data model. \ No newline at end of file diff --git a/documentation/docs/test-suites/semantic-interoperability/cli/installation.md b/documentation/docs/test-suites/semantic-interoperability/cli/installation.md new file mode 100644 index 00000000..8583bfba --- /dev/null +++ b/documentation/docs/test-suites/semantic-interoperability/cli/installation.md @@ -0,0 +1,47 @@ +--- +sidebar_position: 4 +title: Installation +--- + +import Disclaimer from './../../../\_disclaimer.mdx'; + + + +Before you begin installing the Tier 2 test suite CLI, ensure that you have 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.17: Ensure that you have Yarn version 1.22.17 installed. You can install it by running the following command: + ``` + npm install -g yarn@1.22.17 + ``` + +### Installation Steps + +Once you have met the prerequisites, follow these steps to install the dependencies: + +1. Navigate to the cloned repository directory: + ``` + cd tests-untp/packages/untp-test-suite + ``` + +2. Install the dependencies using Yarn: + ``` + yarn install + ``` + +3. Build the test suite: + ``` + yarn build + ``` + +After completing these steps, you will have all the necessary dependencies installed. + +In the next section, we will initialise and explore the configuration file for the test suite. \ No newline at end of file diff --git a/documentation/docs/test-suites/semantic-interoperability/cli/usage.md b/documentation/docs/test-suites/semantic-interoperability/cli/usage.md new file mode 100644 index 00000000..40f61cd9 --- /dev/null +++ b/documentation/docs/test-suites/semantic-interoperability/cli/usage.md @@ -0,0 +1,56 @@ +--- +sidebar_position: 6 +title: Usage +--- + +import Disclaimer from './../../../_disclaimer.mdx'; + + + +Once you have configured the test suite, you can run it to validate your UNTP credentials. + +## Running the Test Suite + +To run the test suite with the configuration defined in the [Configuration section](/docs/test-suites/semantic-interoperability/cli/configuration): + +```bash +yarn run untp test +``` + +To use a specific configuration file: + +```bash +yarn run untp test --config path/to/credentials.json +``` + +## Test Results + +The test suite validates each credential against its corresponding schema and provides a summary of results. + +### Result Overview + +For each tested credential, you will see: +- Credential type +- Version tested +- Test result status + +### Result Categories + +1. **Pass**: The credential fully conforms to the core UNTP data model without extensions. + +2. **Warn**: The credential conforms to the core UNTP data model but includes extensions. + - Review your extensions to ensure they are intentional. + +3. **Fail**: The credential does not conform to the core UNTP data model. + - Review and address each error to ensure compliance. + +### Detailed Feedback + +For warnings and failures, you will receive: +- Specific properties causing issues +- Brief descriptions of each problem +- Suggestions for resolution (where applicable) + +## Next Steps + +After successfully validating your credentials, you may want to explore extending the UNTP data model for your specific use case in the next section. \ No newline at end of file diff --git a/documentation/docs/test-suites/semantic-interoperability/getting-started.md b/documentation/docs/test-suites/semantic-interoperability/getting-started.md new file mode 100644 index 00000000..10b4830d --- /dev/null +++ b/documentation/docs/test-suites/semantic-interoperability/getting-started.md @@ -0,0 +1,20 @@ +--- +sidebar_position: 2 +title: Getting Started +--- + +import Disclaimer from '../.././\_disclaimer.mdx'; + + + +The Getting Started section covers the following topics for each: + +1. [**Installation**](/docs/test-suites/semantic-interoperability/cli/installation): Learn how to install the necessary dependencies and set up the Tier 2 test suite on your system. + +2. [**Configuration**](/docs/test-suites/semantic-interoperability/cli/configuration): Understand how to configure the test suite. We'll cover the structure of the configuration file, how to specify credential types and versions, and how to reference your test credential files. + +3. [**Usage**](/docs/test-suites/semantic-interoperability/cli/usage): Learn how to run the test suite, interpret the results. This section will guide you through validating your UNTP credentials against the core data model. + +4. [**Extending the Test Suite**](/docs/test-suites/semantic-interoperability/cli/extensions): Discover how to extend the test suite to accommodate custom credential types or additional properties. This section will be particularly useful if you're prototyping extensions to the UNTP protocol. + +By the end of this section, you will have a solid foundation for installing, configuring, and using the UNTP Semantic Interoperability Tier 2 Test Suite. You'll be able to validate your UNTP credentials against the core data model and explore extending the test suite for your specific use cases. \ No newline at end of file diff --git a/documentation/docs/test-suites/semantic-interoperability/index.md b/documentation/docs/test-suites/semantic-interoperability/index.md new file mode 100644 index 00000000..9eb41b37 --- /dev/null +++ b/documentation/docs/test-suites/semantic-interoperability/index.md @@ -0,0 +1,36 @@ +--- +sidebar_position: 2 +title: Semantic Interoperability +--- + +import Disclaimer from './../../\_disclaimer.mdx'; + + + +The [United Nations Transparency Protocol (UNTP)](https://uncefact.github.io/spec-untp/) Semantic Interoperability Test Suite is a vital tool for implementers working on UNTP implementations and extensions. This comprehensive suite, designed for the second tier of UNTP testing, enables implementers to: + +1. Verify their implementations' conformance to core UNTP credential data models, including Digital Product Passports, Digital Conformity Credentials, Digital Traceability Events, and Digital Identity Credentials. + +2. Develop and validate UNTP credential extensions whilst ensuring adherence to the core data model. + +By utilising this test suite, implementers can ensure their implementations and extensions align with the core UNTP data model, facilitating seamless integration within the UNTP ecosystem. + +## Key Features and Benefits: + +1. **Comprehensive Conformance Testing**: + Ensures implementers' adherence to core UNTP credential data models, promoting standardisation across the UNTP ecosystem. + +2. **Extension Development Support**: + Facilitates the creation of UNTP credential extensions whilst maintaining compatibility with the core data model. + +3. **Dual Interface Flexibility**: + Offers both CLI and Library interfaces, catering to various development workflows and integration requirements. + +4. **Cross-Actor Compatibility**: + Promotes interoperability among different UNTP actors by ensuring conformance to a common data model. + +5. **Rapid Validation**: + Enables quick verification of UNTP credentials against the core data model, streamlining the development and testing process. + +6. **Prototype Testing**: + Ideal for credential development, allowing implementers to prototype and test extensions to the UNTP protocol in a controlled environment. 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. diff --git a/documentation/docusaurus.config.ts b/documentation/docusaurus.config.ts index c851b881..72a52c7f 100644 --- a/documentation/docusaurus.config.ts +++ b/documentation/docusaurus.config.ts @@ -9,8 +9,8 @@ const config: Config = { tagline: 'A comprehensive suite of tools for testing conformance to the UNTP Specification.', favicon: 'img/favicon.ico', - url, - baseUrl, + url: 'https://ashleythedeveloper.github.io', + baseUrl: '/tests-untp/', organizationName: 'uncefact', // Replace with your GitHub org/user name projectName: 'tests-untp', // Replace with your repo name @@ -37,12 +37,9 @@ const config: Config = { }, blog: false, theme: { - customCss: [ - require.resolve('./src/css/custom.scss'), - require.resolve('./src/css/index.scss'), - ], + customCss: [require.resolve('./src/css/custom.scss'), require.resolve('./src/css/index.scss')], }, - } + }, ], ], @@ -51,21 +48,20 @@ const config: Config = { themes: ['@docusaurus/theme-mermaid'], themeConfig: { - slackLink: - 'https://join.slack.com/t/uncefact/shared_invite/zt-1d7hd0js1-sS1Xgk8DawQD9VgRvy1QHQ', + slackLink: 'https://join.slack.com/t/uncefact/shared_invite/zt-1d7hd0js1-sS1Xgk8DawQD9VgRvy1QHQ', repoLink: 'https://github.com/uncefact/tests-untp', colorMode: { disableSwitch: true, }, - image: 'img/un-crm-social-card.png', - navbar: { + image: 'img/un-crm-social-card.png', + navbar: { title: 'TP', logo: { alt: 'UNTP Test Suite Logo', src: 'img/logo.svg', }, items: [ - {to: '/docs/introduction', label: 'Introduction', position: 'right'}, + { to: '/docs/introduction', label: 'Introduction', position: 'right' }, { to: '/docs/mock-apps/', label: 'Getting started', @@ -76,7 +72,7 @@ const config: Config = { label: 'Tools and support', position: 'right', }, - {to: 'https://uncefact.github.io/spec-untp/docs/extensions/', label: 'Extensions', position: 'right'}, + { to: 'https://uncefact.github.io/spec-untp/docs/extensions/', label: 'Extensions', position: 'right' }, { to: 'https://github.com/uncefact/tests-untp', label: 'Contribute', @@ -162,7 +158,7 @@ const config: Config = { theme: prismThemes.github, darkTheme: prismThemes.dracula, }, - } + }, }; export default config;