Host web5 vectors example

.github/workflows/pages.yaml

@@ -1,6 +1,6 @@
 on:
   push:
-    branches: [main]
+    branches: ["main"]
 jobs:
   pages:
     permissions:
@@ -12,6 +12,8 @@ jobs:
       - uses: actions/setup-go@v4
       - name: run for all SDKs
         run: cd test-harness && go run ./cmd/web5-test-harness many sdks/* && mv _site ../_site
+      - name: Copy test-vectors
+        run: cp -r ./web5-test-vectors _site/
       - uses: actions/upload-pages-artifact@v2
       - name: deploy GitHub Pages
         uses: actions/deploy-pages@v2

.github/workflows/validate-test-vectors.yaml

@@ -0,0 +1,30 @@
+name: Validate Test Vectors
+
+on:
+  push:
+    paths:
+      - 'web5-test-vectors/**'
+      - 'scripts/test-vector-validation/**'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v2
+        with:
+          node-version: '20'
+
+      - name: Install dependencies for test vector validation script
+        run: |
+          cd scripts/test-vector-validation
+          npm install
+
+      - name: Validate test vectors
+        run: |
+          cd scripts/test-vector-validation
+          node main.js

README.md

@@ -15,6 +15,8 @@
   - [Publishing Artifacts](#publishing-artifacts)
   - [Publishing API Reference Documentation](#publishing-api-reference-documentation)
   - [Example Feature Usage](#example-feature-usage)
+- [Test Vectors](#test-vectors)
+  - [Usage](#usage)
 - [Web5 SDK Features](#web5-sdk-features)
   - [Cryptographic Digital Signature Algorithms (DSA)](#cryptographic-digital-signature-algorithms-dsa)
   - [Key Management](#key-management)
@@ -233,6 +235,46 @@ Each SDK will auto generate API reference documentation using the respective lan
 
 Each SDK will **publish** example usage for _each_ implemented feature. This can either be included as a part of API reference documentation _or_ published separately
 
+## Test Vectors
+
+Test vectors ensure interoporability of features across SDKs and language implementations by providing common test cases with an input and expected output pair. They include both success and failure cases that can be vectorized.
+
+This repo serves as the home for all web5 feature related vectors. They are available in the [web5-test-vectors](./web5-test-vectors/) directory and hosted on [Github Pages](https://tbd54566975.github.io/sdk-development/web5-test-vectors).
+
+The `tbdex` repo houses tbdex feature related vectors. They are available in the [test-vectors](https://github.com/TBD54566975/tbdex/test-vectors) directory and hosted on [Github Pages](https://tbdex.dev/).
+
+### Usage
+
+#### Local Dev
+
+SDK implementers should import vectors in order to test their implementation. The recommended pathway to consume them is as follows:
+
+Fetch the vector and read it into a data model representing the vector structure or a JSON object like so:
+
+```kt
+// for web5 vectors
+val stream = URL("https://tbd54566975.github.io/sdk-development/web5-test-vectors/did-jwk/resolve.json").openStream()
+val vectorsJson = BufferedReader(InputStreamReader(stream)).readText()
+return Json.jsonMapper.readTree(vectorsJson)
+
+// for tbdex vectors
+val stream = URL("https://tbdex.dev/test-vectors/resources/marshal.json").openStream()
+val vectorsJson = BufferedReader(InputStreamReader(stream)).readText()
+return Json.jsonMapper.readTree(vectorsJson)
+```
+
+The data model or JSON object can then be used in the implementer's unit testing framework of choice.
+
+#### Adding/Updating Vectors
+
+New test vectors should follow the standard [vector structure](/web5-test-vectors/vector-structure.json.schema). Vectors are automatically validated against the JSON schema via CI.
+
+Create a PR in this repo for web5 vectors, or in [`tbdex`](https://github.com/TBD54566975/tbdex) for tbdex vectors with the proposed changes or additions.
+
+#### Feature Completeness By SDK
+
+Test vectors are also used to determine feature completeness via our [test harness](./test-harness/README.md). Results of test harness runs can be found [here](https://tbd54566975.github.io/sdk-development/).
+
 ## Web5 SDK Features
 
 ### Cryptographic Digital Signature Algorithms (DSA)

scripts/test-vector-validation/.gitignore

@@ -0,0 +1 @@
+node_modules

scripts/test-vector-validation/README.md

@@ -0,0 +1,20 @@
+# Test Vector Validation
+
+## Description
+
+Validates test vectors in [`web5-test-vectors`](../../web5-test-vectors/) directory. Uses [vectors.schema.json](../../web5-test-vectors/vectors.schema.json) to validate.
+
+> [!NOTE]
+> Runs automatically anytime a change is made in [`web5-test-vectors`](../../web5-test-vectors/) or to anything in this directory
+
+## Setup
+
+```bash
+npm install
+```
+
+## Run
+
+```bash
+node main.js
+```

scripts/test-vector-validation/main.js

@@ -0,0 +1,46 @@
+import fs from 'node:fs'
+import path from 'path'
+import Ajv from 'ajv'
+
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const vectorsDir = `${__dirname}/../../web5-test-vectors`
+
+let vectorsSchema = fs.readFileSync(`${vectorsDir}/vectors.schema.json`, 'utf8')
+vectorsSchema = JSON.parse(vectorsSchema)
+
+const ajv = new Ajv()
+const validate = ajv.compile(vectorsSchema)
+
+function validateTestVectors() {
+  const entries = fs.readdirSync(vectorsDir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue
+    }
+
+    const featureDir = path.join(vectorsDir, entry.name)
+    const files = fs.readdirSync(featureDir)
+
+    for (const file of files) {
+      if (path.extname(file) === '.json') {
+        const filePath = path.join(featureDir, file)
+        const fileContent = fs.readFileSync(filePath, 'utf8')
+        const testData = JSON.parse(fileContent)
+
+        if (!validate(testData)) {
+          console.log(`Validation failed for ${filePath}:`, validate.errors)
+          process.exit(1)
+        } else {
+          console.log(`Validation passed for ${filePath}`)
+        }
+      }
+    }
+  }
+}
+
+validateTestVectors()

scripts/test-vector-validation/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "test-vector-validation",
+  "type": "module",
+  "dependencies": {
+    "ajv": "8.12.0"
+  }
+}

web5-test-vectors/did-jwk/resolve.json

@@ -0,0 +1,98 @@
+{
+  "description": "did:jwk resolution test vectors",
+  "vectors": [
+    {
+      "description": "resolves did:jwk 1",
+      "input": "did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9",
+      "output": {
+        "didResolutionResult": {
+          "@context": "https://w3id.org/did-resolution/v1",
+          "didDocument": {
+            "@context": [
+              "https://www.w3.org/ns/did/v1",
+              "https://w3id.org/security/suites/jws-2020/v1"
+            ],
+            "id": "did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9",
+            "verificationMethod": [
+              {
+                "type": "JsonWebKey2020",
+                "id": "did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0",
+                "controller": "did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9",
+                "publicKeyJwk": {
+                  "kty": "EC",
+                  "crv": "P-256",
+                  "x": "acbIQiuMs3i8_uszEjJ2tpTtRM4EU3yz91PH6CdH2V0",
+                  "y": "_KcyLj9vWMptnmKtm46GqDz8wf74I5LKgrl2GzH3nSE"
+                }
+              }
+            ],
+            "authentication": [
+              "did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0"
+            ],
+            "assertionMethod": [
+              "did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0"
+            ],
+            "keyAgreement": [
+              "did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0"
+            ],
+            "capabilityInvocation": [
+              "did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0"
+            ],
+            "capabilityDelegation": [
+              "did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0"
+            ]
+          }
+        }
+      },
+      "errors": false
+    },
+    {
+      "description": "resolves did:jwk 2",
+      "input": "did:jwk:eyJrdHkiOiJPS1AiLCJjcnYiOiJYMjU1MTkiLCJ1c2UiOiJlbmMiLCJ4IjoiM3A3YmZYdDl3YlRUVzJIQzdPUTFOei1EUThoYmVHZE5yZngtRkctSUswOCJ9",
+      "output": {
+        "didResolutionResult": {
+          "@context": "https://w3id.org/did-resolution/v1",
+          "didDocument": {
+            "@context": [
+              "https://www.w3.org/ns/did/v1",
+              "https://w3id.org/security/suites/jws-2020/v1"
+            ],
+            "id": "did:jwk:eyJrdHkiOiJPS1AiLCJjcnYiOiJYMjU1MTkiLCJ1c2UiOiJlbmMiLCJ4IjoiM3A3YmZYdDl3YlRUVzJIQzdPUTFOei1EUThoYmVHZE5yZngtRkctSUswOCJ9",
+            "verificationMethod": [
+              {
+                "type": "JsonWebKey2020",
+                "id": "did:jwk:eyJrdHkiOiJPS1AiLCJjcnYiOiJYMjU1MTkiLCJ1c2UiOiJlbmMiLCJ4IjoiM3A3YmZYdDl3YlRUVzJIQzdPUTFOei1EUThoYmVHZE5yZngtRkctSUswOCJ9#0",
+                "controller": "did:jwk:eyJrdHkiOiJPS1AiLCJjcnYiOiJYMjU1MTkiLCJ1c2UiOiJlbmMiLCJ4IjoiM3A3YmZYdDl3YlRUVzJIQzdPUTFOei1EUThoYmVHZE5yZngtRkctSUswOCJ9",
+                "publicKeyJwk": {
+                  "kty": "OKP",
+                  "use": "enc",
+                  "crv": "X25519",
+                  "x": "3p7bfXt9wbTTW2HC7OQ1Nz-DQ8hbeGdNrfx-FG-IK08"
+                }
+              }
+            ],
+            "keyAgreement": [
+              "did:jwk:eyJrdHkiOiJPS1AiLCJjcnYiOiJYMjU1MTkiLCJ1c2UiOiJlbmMiLCJ4IjoiM3A3YmZYdDl3YlRUVzJIQzdPUTFOei1EUThoYmVHZE5yZngtRkctSUswOCJ9#0"
+            ]
+          }
+        }
+      },
+      "errors": false
+    },
+    {
+      "description": "resolution for invalid did",
+      "input": "did:jwk:hehe",
+      "output": {
+        "didResolutionResult": {
+          "@context": "https://w3id.org/did-resolution/v1",
+          "didDocument": null,
+          "didResolutionMetadata": {
+            "error": "invalidDid"
+          },
+          "didDocumentMetadata": {}
+        }
+      },
+      "errors": false
+    }
+  ]
+}

web5-test-vectors/index.html

@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Web5 Test Vectors</title>
+</head>
+
+<body>
+    <div>
+        <div>
+            <h1>Standard Vector Structure</h1>
+            <ul>
+                <li><a class="vector-structure"
+                        href="https://tbd54566975.github.io/sdk-development/web5-test-vectors/vector-structure.json"
+                        class="href">all vectors use this structure</a>
+                </li>
+            </ul>
+        </div>
+
+        <div>
+            <h1>Test Vectors</h1>
+        </div>
+        <div>
+            <h2>Crypto</h2>
+        </div>
+
+        <div>
+            <h2>DIDs</h2>
+            <ul>
+                <li><a class="did-jwk-resolve"
+                        href="https://tbd54566975.github.io/sdk-development/web5-test-vectors/did-jwk/resolve.json"
+                        class="href">did:jwk resolve</a>
+                </li>
+            </ul>
+        </div>
+
+        <div>
+            <h2>VCs</h2>
+        </div>
+
+    </div>
+</body>
+
+</html>