diff --git a/README.md b/README.md index 5fdd028..dd5cd74 100644 --- a/README.md +++ b/README.md @@ -13,23 +13,22 @@ - [Publishing API Reference Documentation](#publishing-api-reference-documentation) - [Example Feature Usage](#example-feature-usage) - [Test Vectors](#test-vectors) - - [Adding/Updating Vectors](#addingupdating-vectors) + - [Adding & Updating Vectors](#adding--updating-test-vectors) - [Feature Completeness By SDK](#feature-completeness-by-sdk) - [Web5 SDK Features](#web5-sdk-features) - [Cryptographic Digital Signature Algorithms (DSA)](#cryptographic-digital-signature-algorithms-dsa) - [Key Management](#key-management) - - [`did:web`](#didweb) - - [`did:jwk`](#didjwk) - - [`did:dht`](#diddht) - - [`did:key`](#didkey) - - [`did:ion`](#didion) - - [DID Document \& Resolution Validation](#did-document--resolution-validation) - - [W3C Verifiable Credential Data Model 1.1](#w3c-verifiable-credential-data-model-11) - - [W3C Verifiable Credential Data Model 2.0](#w3c-verifiable-credential-data-model-20) - - [SD-JWT / SD-JWT-VC](#sd-jwt--sd-jwt-vc) - - [Bitstring Status List](#bitstring-status-list) - - [VC JSON Schema](#vc-json-schema) - - [Presentation Exchange V2](#presentation-exchange-v2) + - [Decentralized Identifiers](#decentralized-identifiers) + - [DID Documents & Resolution](#did-documents--did-resolution) + - [DID Methods](#did-methods) + - [Verifiable Credentials](#verifiable-credentials) + - [W3C Verifiable Credentials v1.1](#w3c-verifiable-credential-data-model-11) + - [W3C Verifiable Credentials v2.0](#w3c-verifiable-credential-data-model-20) + - [SD-JWT](#sd-jwt) + - [Status List 2021](#status-list-2021) + - [Bitstring Status List](#bitstring-status-list) + - [VC JSON Schema](#vc-json-schema) + - [Presentation Exchange V2](#presentation-exchange-v2) ## Purpose @@ -41,7 +40,6 @@ This repo sets forth the development process, requirements, and the desired feat - [web5-rs](https://github.com/TBD54566975/web5-rs) - [web5-swift](https://github.com/TBD54566975/web5-swift) - ## Requirements ### Feature Tracking @@ -72,12 +70,12 @@ An individual SDK will consider a feature implemented once the following require ### Review Criteria -- Propose API surface design _prior_ to implementation. This can be done by creating a draft PR for a respective feature and providing prototypal code or proposing the design in the comments +- Propose API surface design _prior_ to implementation. This can be done by opening a feature request Issue and fostering a discussion around the proposed design. This can be followed by a corresponding draft PR and providing prototypal code. -- Approval Required from a minimum of 2 people +- Approval Required from a minimum of 2 people. > [!NOTE] -> requiring two reviewers will likely slow things down at the benefit of ensuring there's a sufficient amount of visibility on the changes being made. It also prevents bottlenecks from forming. Many people on our team should be able to speak to the features landing in our SDKs +> Requiring two reviewers will likely slow things down at the benefit of ensuring there's a sufficient amount of visibility on the changes being made. It also prevents bottlenecks from forming. Many people on our team should be able to speak to the features landing in our SDKs. ### Release Criteria @@ -88,32 +86,9 @@ An individual SDK will consider a feature implemented once the following require ### CI / CD -Each SDK will use Github Actions for CI/CD and other automations - -| Feature | Typescript | Kotlin | Rust | Swift | -| ----------------------------- | ---------- | ------ | ---- | ----- | -| OSS License Check | ✅ | ✅ | ✅ | ❌ | -| Security Scanning | ✅ | ✅ | ⛔️ | ❌ | -| Static Analysis Linting/Style | ✅ | ✅ | ✅ | ❌ | -| Running Unit Tests | ✅ | ✅ | ✅ | ❌ | -| Publishing Tests Reports | ✅ | ✅ | ❌ | ❌ | -| Code Coverage (CodeCov) | ✅ | ✅ | ❌ | ❌ | -| Publishing Artifacts | ✅ | ✅ | ❌ | ❌ | -| Release Template Checklist | ❌ | ❌ | ❌ | ❌ | -| Automated GH Release Tag | ❌ | ❌ | ❌ | ❌ | -| Publishing API Reference Docs | ✅ | ✅ | ❌ | ❌ | -| Publish Example Feature Usage | ✅ | ✅ | ❌ | ❌ | - -> [!CAUTION] -> Security scanning via Snyk is currently not supported in Rust - -- GitHub Actions should run in secured runners - - A secure, authoritative build environment ensures software is compiled and packaged in a controlled, tamper-resistant setting. - - This mitigates the risk of introducing vulnerabilities or malicious code during the build process, whether through external attacks or compromised internal components. - - These runners are going to be TBD-owned and self hosted -- Ideally the above table should be represented by a "Software Catalog" with all of our SDK statuses in real time. - - The dashboard would be consuming the data sources (GitHub, CodeCov, Snyk, Npm and other registries etc.) - - Tools like Grafana, Backstage, or even Jenkins (weather flag) could aggregate them +Each SDK will use GitHub Actions for CI/CD and other automations. + +Find the latest [Projects Health Dashboard here](https://developer.tbd.website/open-source/projects-dashboard/). ### Publishing Artifacts @@ -134,7 +109,7 @@ Each SDK will auto generate API reference documentation using the respective lan --- > [!IMPORTANT] -> At a _minimum_, API reference documentation will be published to the respective sdk repository's Github Pages. e.g. `https://tbd54566975.github.io/tbdex-kt/` +> At a _minimum_, API reference documentation will be published to the respective sdk repository's Github Pages. e.g. `https://tbd54566975.github.io/tbdex-kt/`. --- @@ -147,55 +122,55 @@ Each SDK will auto generate API reference documentation using the respective lan | Go | tbd | tbd | > [!IMPORTANT] -> Producing API reference documentation is the responsibility of an _implementer_ +> Producing API reference documentation is the responsibility of an _implementer_. ### Example Feature Usage -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 +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 [test-vectors](./test-vectors/) directory +This repo serves as the home for all web5 feature related vectors. They are available in the [test-vectors](./test-vectors/) directory. -The `tbdex` repo houses tbdex feature related vectors. They are available in the [test-vectors](https://github.com/TBD54566975/tbdex/test-vectors) directory +The `tbdex` repo houses tbdex feature related vectors. They are available in the [test-vectors](https://github.com/TBD54566975/tbdex/test-vectors) directory. -The `sdk-report-runner` repo consumes the output tests for these test vectors in each repo and generates a report - [report-runner](https://github.com/TBD54566975/sdk-report-runner) +The `sdk-report-runner` repo consumes the output tests for these test vectors in each repo and generates a report - [report-runner](https://github.com/TBD54566975/sdk-report-runner). -### Adding/Updating Vectors +### Adding & Updating Test Vectors -New test vectors should follow the standard [vector structure](./test-vectors/). Vectors are automatically validated against the JSON schema via CI. +New test vectors should follow the standard [vector structure](./test-vectors/). Vectors are automatically validated against their [JSON Schema](https://json-schema.org/) via CI. -Create a PR in this repo for adding / updating web5 test vectors +Create a PR in this repo for adding / updating Web5 test vectors. ### 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 +Test vectors are 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/). + ### Cryptographic Digital Signature Algorithms (DSA) -| Algorithm | Typescript | Kotlin | Rust | Swift | -| --------------- | ---------- | ------ | ---- | ----- | -| `ES256K` | ✅ | ✅ | ✅ | ❌ | -| `EdDSA:Ed25519` | ✅ | ✅ | ✅ | ❌ | +| Key Type | Algorithm | Type | +| ------------------------------------------------- | --------------------------------------------------------------------- | ------------------------ | +| [secp256k1](https://en.bitcoin.it/wiki/Secp256k1) | [`ES256K`](https://datatracker.ietf.org/doc/html/rfc8812#section-3.1) | Signing and Verification | +| [Ed25519](https://ed25519.cr.yp.to/) | [`EdDSA`](https://datatracker.ietf.org/doc/html/rfc8032) | Signing and Verification | > [!IMPORTANT] -> In-memory signing using Secp256k1 **MUST** produce k-deterministic low-s signatures. Verification **must not require** low-s signatures +> In-memory signing using secp256k1 **MUST** produce k-deterministic low-s signatures with [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) as per [RFC6979](https://www.rfc-editor.org/rfc/rfc6979). Verification **must not require** low-s signatures. ### Key Management Each SDK will implement a consistent and extensible _public interface_ for key management minimally providing concrete implementations of: -| Feature | Typescript | Kotlin | Rust | Swift | -| --------------------- | ---------- | ------ | ---- | ----- | -| Key Manager Interface | ❌ | ✅ | ✅ | ❌ | -| In-Memory Key Manager | ❌ | ✅ | ✅ | ❌ | -| AWS KMS | ❌ | ✅ | N/A | N/A | -| Device Enclave | N/A | ❌ | N/A | ❌ | -| Keychain | N/A | ❌ | N/A | ❌ | +| Feature | +| ----------------------- | +| Key Manager Interface | +| In-Memory Key Manager | +| AWS KMS | +| Device Enclave (Mobile) | +| Keychain (Mobile) | Further, the key manager interface **must** be passed as an argument to _all_ public API methods that require key material. e.g. @@ -210,106 +185,95 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu > Consumers of our SDKs should be able to provide their own `KeyManager` implementations if desired -> [!NOTE] -> ⚠️ = implemented but no test vectors present - -### [`did:web`](https://w3c-ccg.github.io/did-method-web/) +### Decentralized Identifiers -| Feature | Typescript | Kotlin | Rust | Swift | -| ------------ | ---------- | ------ | ---- | ----- | -| `Resolution` | ❌ | ❌ | ⚠️ | ❌ | +#### [DID Documents](https://www.w3.org/TR/did-core/) & [DID Resolution](https://w3c-ccg.github.io/did-resolution/) -### [`did:jwk`](https://github.com/quartzjer/did-jwk/blob/main/spec.md) +Independent of DID Methods, we support DID Documents according to [DID Core v1.0](https://www.w3.org/TR/2022/REC-did-core-20220719/) with the adjustments specified in [this corresponding document](spec/did.md). -| Feature | Typescript | Kotlin | Rust | Swift | -| ------------ | ---------- | ------ | ---- | ----- | -| `Creation` | ❌ | ❌ | ⚠️ | ❌ | -| `Resolution` | ❌ | ❌ | ⚠️ | ❌ | +#### DID Methods -### [`did:dht`](https://tbd54566975.github.io/did-dht-method/) +| Method | Creation | Resolution | Note | +| ------------------------------------------------------ | ---------- | ---------- | ---- | +| [`did:web`](https://w3c-ccg.github.io/did-method-web/) | ❌ | ✅ | - | +| [`did:jwk`](https://github.com/quartzjer/did-jwk/blob/main/spec.md) | ✅ | ✅ | - | +| [`did:dht`](https://did-dht.com) | ✅ | ✅ | This is our default method. | +| [`did:key`](https://w3c-ccg.github.io/did-method-key/) | ⚠️ | ⚠️ | Has been implemented in both Kotlin and Typescript, no plans for support in other languages. | +| [`did:ion`](https://identity.foundation/sidetree/spec) | ⚠️ | ⚠️ | Support for `did:ion` has been deprecated. | -| Feature | Typescript | Kotlin | Rust | Swift | -| ------------ | ---------- | ------ | ---- | ----- | -| `Creation` | ⚠️ | ⚠️ | ❌ | ❌ | -| `Resolution` | ⚠️ | ⚠️ | ❌ | ❌ | +### Verifiable Credentials -### [`did:key`](https://w3c-ccg.github.io/did-method-key/) +#### [W3C Verifiable Credential Data Model 1.1](https://www.w3.org/TR/vc-data-model) -| Feature | Typescript | Kotlin | Rust | Swift | -| ------------ | ---------- | ------ | ---- | ----- | -| `Creation` | ⚠️ | ⚠️ | ⚠️ | ❌ | -| `Resolution` | ⚠️ | ⚠️ | ⚠️ | ❌ | +We support Verifiable Credentials according to the [Verifiable Credentials Data Model 1.1](https://www.w3.org/TR/vc-data-model) with the adjustments specified in [this corresponding document](spec/vc.md). > [!IMPORTANT] -> `did:key` is included because it has been implemented in both Kotlin and Typescript. I'll be creating a Github issue soon to discuss when we think it makes sense to remove ION support from both SDKs +> Credential validation will soon be [specified more clearly](https://github.com/TBD54566975/web5-spec/issues/123). + -### [`did:ion`](https://identity.foundation/sidetree/spec) +| Feature | +| ---------------------------------------------------------------- | +| Data model | +| Validation (data model, JSON Schema, status, more to come.) | +| Signing and verification of Verifiable Credentials as `vc-jwt` | +| Signing and verification of Verifiable Presentations as `vp-jwt` | -| Feature | Typescript | Kotlin | Rust | Swift | -| ------------ | ---------- | ------ | ---- | ----- | -| `Creation` | ⚠️ | ⚠️ | ❌ | ❌ | -| `Resolution` | ⚠️ | ⚠️ | ❌ | ❌ | +#### [W3C Verifiable Credential Data Model 2.0](https://www.w3.org/TR/vc-data-model-2.0/) -> [!IMPORTANT] -> `did:ion` is included because it has been implemented in both Kotlin and Typescript. I'll be creating a Github issue soon to discuss when we think it makes sense to remove ION support from both SDKs - -### [DID Document](https://www.w3.org/TR/did-core/) & [Resolution Validation](https://w3c-ccg.github.io/did-resolution/) - -| Feature | Typescript | Kotlin | Rust | Swift | -| ------------ | ---------- | ------ | ---- | ----- | -| Common Error | ❌ | ❌ | ❌ | ❌ | - -### [W3C Verifiable Credential Data Model 1.1](https://www.w3.org/TR/vc-data-model) - -| Feature | Typescript | Kotlin | Rust | Swift | -| ------------------------------------ | ---------- | ------ | ---- | ----- | -| Creation | ✅ | ✅ | ❌ | ❌ | -| Signing as `vc-jwt` | ✅ | ✅ | ❌ | ❌ | -| Verification | ✅ | ✅ | ❌ | ❌ | -| Validation | ✅ | ✅ | ❌ | ❌ | -| Verifiable Presentations as `vp-jwt` | ⚠️ | ⚠️ | ❌ | ❌ | - -### [W3C Verifiable Credential Data Model 2.0](https://www.w3.org/TR/vc-data-model-2.0/) - -| Feature | Typescript | Kotlin | Rust | Swift | -| ------------------------- | ---------- | ------ | ---- | ----- | -| Creation | ❌ | ❌ | ❌ | ❌ | -| Signing as `vc-jose-cose` | ❌ | ❌ | ❌ | ❌ | -| Verification | ❌ | ❌ | ❌ | ❌ | -| Validation | ❌ | ❌ | ❌ | ❌ | - -### [SD-JWT](https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt/) / [SD-JWT-VC](https://datatracker.ietf.org/doc/draft-ietf-oauth-sd-jwt-vc/) - -| Feature | Typescript | Kotlin | Rust | Swift | -| ------------------- | ---------- | ------ | ---- | ----- | -| Creation | ❌ | ❌ | ❌ | ❌ | -| Signing | ❌ | ❌ | ❌ | ❌ | -| Verification | ❌ | ❌ | ❌ | ❌ | -| Validation | ❌ | ❌ | ❌ | ❌ | - -### [Bitstring Status List](https://w3c.github.io/vc-bitstring-status-list/) - -| Feature | Typescript | Kotlin | Rust | Swift | -| --------------------------------- | ---------- | ------ | ---- | ----- | -| Creation using `vc-jwt` | ❌ | ❌ | ❌ | ❌ | -| Validation using `vc-jwt` | ❌ | ❌ | ❌ | ❌ | - -### [VC JSON Schema](https://www.w3.org/TR/vc-json-schema/) - -| Feature | Typescript | Kotlin | Rust | Swift | -| --------------------------------- | ---------- | ------ | ---- | ----- | -| Creation `JsonSchema` | ❌ | ❌ | ❌ | ❌ | -| Creation `JsonSchemaCredential` | ❌ | ❌ | ❌ | ❌ | -| Validation `JsonSchema` | ❌ | ❌ | ❌ | ❌ | -| Validation `JsonSchemaCredential` | ❌ | ❌ | ❌ | ❌ | - -### [Presentation Exchange V2](https://identity.foundation/presentation-exchange/spec/v2.0.0/) - -| Feature | Typescript | Kotlin | Rust | Swift | -| ---------------------- | ---------- | ------ | ---- | ----- | -| Concrete Type | ✅ | ✅ | ❌ | ❌ | -| Validation | ✅ | ✅ | ❌ | ❌ | -| Credential Evaluation | ✅ | ✅ | ❌ | ❌ | -| [Predicates](https://identity.foundation/presentation-exchange/spec/v2.0.0/#predicate-feature) | ✅ | ✅ | ❌ | ❌ | -| [Relational Constraints](https://identity.foundation/presentation-exchange/spec/v2.0.0/#relational-constraint-feature) | ✅ | ❌ | ❌ | ❌ | -| [Credential Status](https://identity.foundation/presentation-exchange/spec/v2.0.0/#credential-status-constraint-feature) | ❌ | ❌ | ❌ | ❌ | +| Feature | +| ------------------------------------------------------------------------ | +| Data model | +| Validation (data model, JSON Schema, status) | +| Signing and verification of Verifiable Credentials with `vc-jose-cose`. | +| Signing and verification of Verifiable Presentations with `vp-jose-cose` | + +#### [SD-JWT](https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt/) + +| Feature | +| ------------------------ | +| Data model | +| Signing and verification | + +#### [Status List 2021](https://www.w3.org/community/reports/credentials/CG-FINAL-vc-status-list-2021-20230102/) + +For usage with the [W3C Verifiable Credential Data Model 1.1](https://www.w3.org/TR/vc-data-model). + +| Feature | +| -------------------------------------- | +| Data model | +| Status checking (supporting at least `Revocation` and `Suspension` statuses) | +| Status setting | +| Signing and verification with `vc-jwt` | + +#### [Bitstring Status List](https://www.w3.org/TR/vc-bitstring-status-list/) + +For usage with the [W3C Verifiable Credential Data Model 2.0](https://www.w3.org/TR/vc-data-model-2.0/). + +| Feature | +| -------------------------------------------- | +| Data model | +| Status checking (supporting at least `Revocation` and `Suspension` statuses) | +| Status setting | +| Signing and verification with `vc-jose-cose` | + + +#### [VC JSON Schema](https://www.w3.org/TR/vc-json-schema/) + +For usage with both the [W3C Verifiable Credential Data Model 1.1](https://www.w3.org/TR/vc-data-model) and the [W3C Verifiable Credential Data Model 2.0](https://www.w3.org/TR/vc-data-model-2.0/). + +| Feature | +| --------------------------------------- | +| Creation and validation of `JsonSchema` | +| Creation and validation of `JsonSchemaCredential` using `vc-jwt` with the VCDM v1.1 | +| Creation and validation of `JsonSchemaCredential` using `vc-jose-cose` with the VCDM v2.0 | + +#### [Presentation Exchange v2.0](https://identity.foundation/presentation-exchange/spec/v2.0.0/) + +| Feature | +| ---------------------- | +| Data model | +| Validation | +| Credential Evaluation using the VCDM v1.1 (both `vc-jwt` and `vp-jwt`), the VCDM v2.0 using `vc-jose-cose`, and SD-JWT | +| [Predicates](https://identity.foundation/presentation-exchange/spec/v2.0.0/#predicate-feature) | +| [Relational Constraints](https://identity.foundation/presentation-exchange/spec/v2.0.0/#relational-constraint-feature) | +| [Credential Status](https://identity.foundation/presentation-exchange/spec/v2.0.0/#credential-status-constraint-feature) | \ No newline at end of file diff --git a/spec/did-metadata.json b/spec/did-metadata.json new file mode 100644 index 0000000..e69de29 diff --git a/spec/did-resolution.json b/spec/did-resolution.json new file mode 100644 index 0000000..e69de29 diff --git a/spec/did.json b/spec/did.json new file mode 100644 index 0000000..e69de29 diff --git a/spec/did.md b/spec/did.md new file mode 100644 index 0000000..f924d6f --- /dev/null +++ b/spec/did.md @@ -0,0 +1,92 @@ +# W3C Decentralized Identifiers v1.0 + +The [DID Core data model](https://www.w3.org/TR/did-core) provides optionality for many of its properties, as it is designed as an [abstract data model](https://www.w3.org/TR/did-core/#representations). This means that many properties can be represented in different ways while still being spec conformant, properties can take on multiple concrete types (i.e. sometimes a string, sometimes an array), and documents can be extended to include additional properties either through the [DID Specification Registry](https://www.w3.org/TR/did-spec-registries/) or via usage of [JSON-LD](https://www.w3.org/TR/json-ld11/). + +This optionality can be difficult to implement consistently across languages. As a consequence, this specification defines a strict subset of the DID Core v1.0 data model represented by the following table. As a utility JSON Schemas for [DID Documents](did-document.json), [DID Resolution Metadata](did-resolution.json), and [DID Document Metadata](did-metadata.json) are provided to aid in the validation of conformant documents. + +## DID Document Data Model + +Following from [this data model](https://www.w3.org/TR/did-core/#core-properties). + +| Property | JSON Representation | Required | Notes | +| ------------- | ------------------- | -------- | -------------- | +| `id` | String | Yes | Must be a URI. | +| `@context` | Array of strings | No | Depends on the DID method. | +| `controller` | Array of strings | No | Depends on the DID method. Strings must be URIs. | +| `alsoKnownAs` | Array of strings | No | Depends on the DID method. Strings must be URIs. | +| `verificationMethod` | Array of [Verification Methods](#verification-method-data-model) | Yes | There must be at least one Verification Method in each DID Document. | +| `authentication` | Array of strings | No | String values must be fully qualified DID URIs (e.g. `did:example:abcd#key-1` over `#key-1`). | +| `assertionMethod` | Array of strings | No | String values must be fully qualified DID URIs (e.g. `did:example:abcd#key-1` over `#key-1`). | +| `keyAgreement` | Array of strings | No | String values must be fully qualified DID URIs (e.g. `did:example:abcd#key-1` over `#key-1`). | +| `capabilityInvocation` | Array of strings | No | String values must be fully qualified DID URIs (e.g. `did:example:abcd#key-1` over `#key-1`). | +| `capabilityDelegation` | Array of strings | No | String values must be fully qualified DID URIs (e.g. `did:example:abcd#key-1` over `#key-1`). | +| `service` | Array of [Services](#service-data-model) | No | - | + +**Additional Notes:** +- No [JSON-LD processing](https://www.w3.org/TR/did-core/#consumption-0) is performed. +- Each [Verification Method](https://www.w3.org/TR/did-core/#verification-methods) must have at least one [Verification Relationship](https://www.w3.org/TR/did-core/#verification-relationships). + +### Verification Method Data Model + +Following form [this data model](https://www.w3.org/TR/did-core/#verification-methods). + +| Property | JSON Representation | Required | Notes | +| ------------- | ------------------- | -------- | -------------- | +| `id` | String | Yes | Must be a fully qualified DID URI (e.g. `did:example:abcd#key-1`). | +| `type` | String | Yes | Must be a URI. | +| `controller` | String | Yes | Must be a URI. | +| `publicKeyJwk` | Object | Yes | Represents a [JWK](https://www.w3.org/TR/did-core/#bib-rfc7517). | + +### Service Data Model + +Following from [this data model](https://www.w3.org/TR/did-core/#services). + +| Property | JSON Representation | Required | Notes | +| ----------------- | ------------------- | -------- | -------------- | +| `id` | String | Yes | Must be a fully qualified DID URI (e.g. `did:example:abcd#service-1`). | +| `type` | String | Yes | Must be a type defined in the [service registry](https://www.w3.org/TR/did-spec-registries/#service-types). | +| `serviceEndpoint` | Array of Strings | Yes | String values must be URIs. | +| `sig` | Array of Strings | No | - | +| `enc` | Array of Strings | No | - | + +## DID Resolution Metadata Data Model + +DID Resolution Metadata is _always optional_. This means that conformant implementations need not support the metadata, though it may be returned when interacting with DID resolvers. + +Following from [this data model](https://www.w3.org/TR/did-core/#did-resolution-metadata). + +| Property | JSON Representation | Required | Notes | +| ------------- | ------------------- | -------- | -------------- | +| `error` | String | No | Required if there was an error during resolution. One of the defined [error types](#did-resolution-metadata-error-types). | + +### DID Resolution Metadata Error Types + +Error types supported following from [this data model](https://www.w3.org/TR/did-core/#did-resolution-metadata). + +| Type | Description | +| ------------- | ------------------- | +| `invalidDid` | The requested DID was not valid and resolution could not proceed. | +| `notFound` | The requested DID was not found. | +| `representationNotSupported` | The requested representation of the DID payload is not supported by the resolver. | +| `methodNotSupported` | The requested DID method is not supported by the resolver. | +| `invalidDidDocument` | The DID Document was found but did not represent a conformant document. | +| `invalidDidDocumentLength` | The size of the DID Document was not within the method's acceptable limit. | +| `internalError` | Something went wrong during DID resolution. | + + +## DID Document Metadata Data Model + +DID Document Metadata is _always optional_. This means that conformant implementations need not support the metadata, though it may be returned when interacting with DID resolvers. + +Following from [this data model](https://www.w3.org/TR/did-core/#did-document-metadata). + +| Property | JSON Representation | Required | Notes | +| ---------- | -------------------- | -------- | -------------- | +| `created` | String | No | [XML Datetime](https://www.w3.org/TR/xmlschema11-2/#dateTime) value for when the DID was created. | +| `updated` | String | No | [XML Datetime](https://www.w3.org/TR/xmlschema11-2/#dateTime) value for when the DID was last updated. | +| `deactivated` | Boolean | No | Required to be `true` if the DID is deactivated. | +| `nextUpdate` | String | No | [XML Datetime](https://www.w3.org/TR/xmlschema11-2/#dateTime) value for when the next update of the DID. | +| `versionId` | String | No | Represents the version of the last update operation. | +| `nextversionId`| String | No | Represents the version of the next update operation. | +| `equivalentId` | Array of Strings | No | A stronger form of the `alsoKnownAs` property, guaranteed by the DID method. See [this spec text](https://www.w3.org/TR/did-core/#h-note-10) for more information. | +| `canonicalId` | String | No | Similar to `equivalentId`, though always a single value, never a set. See [this spec text](https://www.w3.org/TR/did-core/#dfn-canonicalid) for more information. | diff --git a/spec/vc-11.json b/spec/vc-11.json new file mode 100644 index 0000000..e69de29 diff --git a/spec/vc.md b/spec/vc.md new file mode 100644 index 0000000..5fb96f6 --- /dev/null +++ b/spec/vc.md @@ -0,0 +1,83 @@ +# W3C Verifiable Credentials v1.1 + +The VC Data Model provides optionality for many of its properties. This means they can take on multiple concrete types, for example an [`issuer` property](https://www.w3.org/TR/vc-data-model/#issuer) can either be repreesnted as a JSON string representing a URI or a JSON object that must contain an `id` property. Additionally, the data model follows an [open world](https://www.w3.org/TR/vc-data-model/#extensibility) model for extensibility via the usage of [JSON-LD](https://www.w3.org/TR/json-ld11/). As a consequence, conformant Verifiable Credentials may contain properties that are not defined by the specification itself, but by [JSON-LD Contexts](https://www.w3.org/TR/json-ld11/#the-context). + +This optionality can be difficult to implement consistently across languages. As a consequence, this specification defines a strict subset of the VC Data Model v1.1 that supports the [plain JSON syntax](https://www.w3.org/TR/vc-data-model/#json), represented by the following table. As a utility JSON Schemas for [Verifiable Credentials](vc-11.json) and [Verifiable Presentations](vp-11.json) are provided to aid in the validation of conformant documents. + +## Verifiable Credential Data Model + +Following from [this data model](https://www.w3.org/TR/vc-data-model/#basic-concepts). + +| Property | JSON Representation | Required | Notes | +| ------------- | ------------------- | -------- | -------------- | +| `@context` | Array of strings | Yes | Contexts defining the meaning of terms within the credential. Must include at least `"https://www.w3.org/2018/credentials/v1"`. | +| `id` | String | Yes | A URI representing a unique identifier for the credential. Recommended to be of form `urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5`. | +| `type` | Array of strings | Yes | Type(s) of the credential. Must include `VerifiableCredential`. | +| `issuer` | String OR Object | Yes | Recommended to be a string; a DID representing a unique identifier for the entity that issued the credential. We also need to support the case where `issuer` is a JSON Object with an `id` propertery (following prior guidance) and a `name` property representing the Issuer's name. | +| `issuanceDate`| String | Yes | [XML Datetime](https://www.w3.org/TR/xmlschema11-2/#dateTime) value for when the credential was issued. | +| `expirationDate` | String | No | [XML Datetime](https://www.w3.org/TR/xmlschema11-2/#dateTime) value after which the credential is no longer valid. | +| `credentialSubject` | Object | Yes | Data about the subject of the credential. Can be any JSON object. | +| `credentialSubject.id` | String | Yes | A DID representing a unique identifier for whom the credential's claims are made. | +| `credentialStatus` | Object defined by [Credential Status](#credential-status) | No | Only to be used with [Status List 2021](https://www.w3.org/community/reports/credentials/CG-FINAL-vc-status-list-2021-20230102/). | +| `credentialSchema` | Object defined by [Credential Schema](#credential-schema) | No | Recommended. Only to be used with the type [`JsonSchema`](https://w3c.github.io/vc-json-schema/#jsonschema). | +| `evidence` | Array of objects | No | An array of JSON objects as per [Evidence](https://www.w3.org/TR/vc-data-model/#evidence). | + +**Additional Notes:** +- The `credentialSubject` property can be any JSON object. It is recommended that this object is defined by an associated `credentialSchema`. +- No [JSON-LD processing](https://www.w3.org/TR/vc-data-model/#json-ld) is performed. +- Embedded proofs, using the `proof` property must not be present. JWTs with the `proof` property present must not be processed. +- The `type` property must always contain `VerifiableCredential` but may also contain the URI(s) of a JSON Schema, if one is used for the credential. +- We do not support multiple credential subjects. +- Verifiable Credentials must be secured as JWTs according to the [rules laid out in the specification](https://www.w3.org/TR/vc-data-model/#json-web-token). +- XML Datetime values may be represented by conforming to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) or [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) formats, as they are subsets of XML Datetime. +- For the `evidence` property no further implementation is needed until we are able to specify an evidence [type](https://www.w3.org/TR/vc-data-model/#dfn-type), such as those provided by [this registry](https://w3c.github.io/vc-specs-dir/#evidence). + +### Credential Status Data Model + +Following from [this data model](https://www.w3.org/community/reports/credentials/CG-FINAL-vc-status-list-2021-20230102/). + +**StatusList2021Entry** + +| Property | JSON Representation | Required | Notes | +| --------------- | ------------------- | -------- | -------------- | +| `id` | String | Yes | A URL which uniquely identifies the status of the associated verifiable credential. | +| `type` | String | Yes | Must be set to `StatusList2021Entry`. | +| `statusPurpose` | String | Yes | Describes the type of status the object represents (e.g. `revocation` or `suspension`). | +| `statusListIndex` | String | Yes | An integer >= 0 expressed as a string that identifies the bit position of the status of the associated verifiable credential. | +| `statusListCredential` | String | Yes | A URL which uniquely identifies a verifiable credential whose type is `StatusList2021Credential`. | + +**Additional Notes:** +- When representing Status List Credentials, as opposed to including a status in another VC, the Status List Credential must [follow the guidance here](https://www.w3.org/community/reports/credentials/CG-FINAL-vc-status-list-2021-20230102/#statuslist2021credential). + +### Credential Schema Data Model + +Following from [this data model](https://w3c.github.io/vc-json-schema/#jsonschema). + +| Property | JSON Representation | Required | Notes | +| --------------- | ------------------- | -------- | -------------- | +| `id` | String | Yes | A URL which uniquely identifies the JSON Schema for the associated Verifiable Credential. | +| `type` | String | Yes | Must be set to `JsonSchema`. | + +**Additional Notes:** +- Although [the referenced spec](https://w3c.github.io/vc-json-schema/) is designed for v2 of the VC Data Model, we apply it to v1.1 as a standard means to implement the `credentialSchema`. + +## Verifiable Presentation Data Model + +Following from [this guidance](https://www.w3.org/TR/vc-data-model/#presentations-0), which extends on the data model above. + +| Property | JSON Representation | Required | Notes | +| ------------- | ------------------- | -------- | -------------- | +| `@context` | Array of strings | Yes | Contexts defining the meaning of terms within the presentation. Must include at least `"https://www.w3.org/2018/credentials/v1"`. | +| `id` | String | Yes | A URI representing a unique identifier for the presentation. Recommended to be of form `urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5`. | +| `type` | Array of strings | Yes | Type(s) of the presentation. Must include `VerifiablePresentation`. | +| `holder` | String | Yes | A DID representing a unique identifier for the entity that created the presentation. | +| `issuanceDate`| String | Yes | [XML Datetime](https://www.w3.org/TR/xmlschema11-2/#dateTime) value for when the presentation was created. | +| `expirationDate` | String | No | [XML Datetime](https://www.w3.org/TR/xmlschema11-2/#dateTime) value after which the presentation is no longer valid. | +| `verifiableCredential` | Array of strings | Yes | An array with at least one value, containing the JWT representation of [Verifiable Credential](#verifiable-credential-data-model) objects. | + +**Additional Notes:** +- No [JSON-LD processing](https://www.w3.org/TR/vc-data-model/#json-ld) is performed. +- Embedded proofs, using the `proof` property must not be present. +- The `type` property must always contain `VerifiablePresentation` but may also contain the URI(s) of a JSON Schema, if one is used for the presentation. +- Verifiable Presentations must be secured as JWTs according to the [rules laid out in the specification](https://www.w3.org/TR/vc-data-model/#json-web-token). +- XML Datetime values may be represented by conforming to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) or [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) formats, as they are subsets of XML Datetime. diff --git a/spec/vp-11.json b/spec/vp-11.json new file mode 100644 index 0000000..e69de29 diff --git a/test-vectors/did_dht/create.json b/test-vectors/did_dht/create.json index 46ef41d..c4ac38e 100644 --- a/test-vectors/did_dht/create.json +++ b/test-vectors/did_dht/create.json @@ -88,7 +88,9 @@ }, "output": { "id": "did:dht:cyuoqaf7itop8ohww4yn5ojg13qaq83r9zihgqntc5i9zwrfdfoo", - "controller": "did:example:abcd", + "controller": [ + "did:example:abcd" + ], "alsoKnownAs": [ "did:example:efgh", "did:example:ijkl" diff --git a/test-vectors/did_jwk/resolve.json b/test-vectors/did_jwk/resolve.json index b1aec6b..2782cb7 100644 --- a/test-vectors/did_jwk/resolve.json +++ b/test-vectors/did_jwk/resolve.json @@ -8,13 +8,12 @@ "@context": "https://w3id.org/did-resolution/v1", "didDocument": { "@context": [ - "https://www.w3.org/ns/did/v1", - "https://w3id.org/security/suites/jws-2020/v1" + "https://www.w3.org/ns/did/v1" ], "id": "did:jwk:eyJrdHkiOiJFQyIsInVzZSI6InNpZyIsImNydiI6InNlY3AyNTZrMSIsImtpZCI6ImkzU1BSQnRKS292SEZzQmFxTTkydGk2eFFDSkxYM0U3WUNld2lIVjJDU2ciLCJ4IjoidmRyYnoyRU96dmJMRFZfLWtMNGVKdDdWSS04VEZaTm1BOVlnV3p2aGg3VSIsInkiOiJWTEZxUU1aUF9Bc3B1Y1hvV1gyLWJHWHBBTzFmUTVMbjE5VjVSQXhyZ3ZVIiwiYWxnIjoiRVMyNTZLIn0", "verificationMethod": [ { - "type": "JsonWebKey2020", + "type": "JsonWebKey", "id": "did:jwk:eyJrdHkiOiJFQyIsInVzZSI6InNpZyIsImNydiI6InNlY3AyNTZrMSIsImtpZCI6ImkzU1BSQnRKS292SEZzQmFxTTkydGk2eFFDSkxYM0U3WUNld2lIVjJDU2ciLCJ4IjoidmRyYnoyRU96dmJMRFZfLWtMNGVKdDdWSS04VEZaTm1BOVlnV3p2aGg3VSIsInkiOiJWTEZxUU1aUF9Bc3B1Y1hvV1gyLWJHWHBBTzFmUTVMbjE5VjVSQXhyZ3ZVIiwiYWxnIjoiRVMyNTZLIn0#0", "controller": "did:jwk:eyJrdHkiOiJFQyIsInVzZSI6InNpZyIsImNydiI6InNlY3AyNTZrMSIsImtpZCI6ImkzU1BSQnRKS292SEZzQmFxTTkydGk2eFFDSkxYM0U3WUNld2lIVjJDU2ciLCJ4IjoidmRyYnoyRU96dmJMRFZfLWtMNGVKdDdWSS04VEZaTm1BOVlnV3p2aGg3VSIsInkiOiJWTEZxUU1aUF9Bc3B1Y1hvV1gyLWJHWHBBTzFmUTVMbjE5VjVSQXhyZ3ZVIiwiYWxnIjoiRVMyNTZLIn0", "publicKeyJwk": { @@ -53,13 +52,12 @@ "@context": "https://w3id.org/did-resolution/v1", "didDocument": { "@context": [ - "https://www.w3.org/ns/did/v1", - "https://w3id.org/security/suites/jws-2020/v1" + "https://www.w3.org/ns/did/v1" ], "id": "did:jwk:eyJrdHkiOiJPS1AiLCJ1c2UiOiJzaWciLCJjcnYiOiJFZDI1NTE5Iiwia2lkIjoiVnRTSFhQbEtEdzFFRW9PajVYTjNYV2hqU1BZVk52WC1lNHZqUk8weVlKQSIsIngiOiJpejcwc3ZTTHhOWmhzRHhlSlFfam5PVmJYM0tGTmtjQmNNaldqWm1YRXNBIiwiYWxnIjoiRWREU0EifQ", "verificationMethod": [ { - "type": "JsonWebKey2020", + "type": "JsonWebKey", "id": "did:jwk:eyJrdHkiOiJPS1AiLCJ1c2UiOiJzaWciLCJjcnYiOiJFZDI1NTE5Iiwia2lkIjoiVnRTSFhQbEtEdzFFRW9PajVYTjNYV2hqU1BZVk52WC1lNHZqUk8weVlKQSIsIngiOiJpejcwc3ZTTHhOWmhzRHhlSlFfam5PVmJYM0tGTmtjQmNNaldqWm1YRXNBIiwiYWxnIjoiRWREU0EifQ#0", "controller": "did:jwk:eyJrdHkiOiJPS1AiLCJ1c2UiOiJzaWciLCJjcnYiOiJFZDI1NTE5Iiwia2lkIjoiVnRTSFhQbEtEdzFFRW9PajVYTjNYV2hqU1BZVk52WC1lNHZqUk8weVlKQSIsIngiOiJpejcwc3ZTTHhOWmhzRHhlSlFfam5PVmJYM0tGTmtjQmNNaldqWm1YRXNBIiwiYWxnIjoiRWREU0EifQ", "publicKeyJwk": {