diff --git a/.github/_ISSUE_TEMPLATE/bug-report.md b/.github/_ISSUE_TEMPLATE/bug-report.md index 25f0bc5..8c37af0 100644 --- a/.github/_ISSUE_TEMPLATE/bug-report.md +++ b/.github/_ISSUE_TEMPLATE/bug-report.md @@ -12,6 +12,7 @@ assignees: add codeowner's @name here **To Reproduce:** *Steps to reproduce the behavior:* + 1. Go to '...' 2. Click on '....' 3. Scroll down to '....' @@ -24,8 +25,9 @@ assignees: add codeowner's @name here *If applicable, add screenshots, output log and/or other documentation to help explain your problem.* **Environment (please complete the following information):** - - OS: [ex: iOS] - - Version + +- OS: [ex: iOS] +- Version **Additional context** Add any other context that you feel is relevant about the problem here. diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml new file mode 100644 index 0000000..61fdcc2 --- /dev/null +++ b/.github/workflows/lint.yaml @@ -0,0 +1,13 @@ +name: Lint + +on: [push, pull_request] + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - uses: DavidAnson/markdownlint-cli2-action@v13 + with: + globs: "**/*.md" diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..4754387 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,2 @@ +config: + line-length: false \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 8128d59..d444650 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -5,7 +5,6 @@ TBD builds infrastructure for the next wave of innovation in financial services The code of conduct below reflects the expectations for ourselves and for our community. - ## Our Pledge We as members, contributors, and leaders pledge to make participation in our @@ -90,7 +89,7 @@ actions. interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels -like social media and forums. +like social media and forums. Although this list cannot be exhaustive, we explicitly honor diversity in age, culture, ethnicity, gender identity or expression, language, national origin, political beliefs, profession, race, religion, sexual orientation, socioeconomic status, and technical ability. We will not tolerate discrimination based on any of the protected characteristics above, including participants with disabilities. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ad2bf02..d5e1554 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,9 @@ -# Contribution Guide +# Contribution Guide + There are many ways to be an open source contributor, and we're here to help you on your way! You may: -* Propose ideas in our +* Propose ideas in our [discord](https://discord.gg/tbd) * Raise an issue or feature request in our [issue tracker](https://github.com/TBD54566975/web5-spec/issues) * Help another contributor with one of their questions, or a code review @@ -13,7 +14,7 @@ This guide is for you. ## Development Prerequisites -___***UPDATE TABLE OF PROJECT DEPS AND INSTALLATION NOTES***___ +___*__UPDATE TABLE OF PROJECT DEPS AND INSTALLATION NOTES__*___ | Requirement | Tested Version | Installation Instructions | |-------------|----------------|------------------------------------------------------| @@ -23,7 +24,7 @@ ___***UPDATE TABLE OF PROJECT DEPS AND INSTALLATION NOTES***___ ### Go -This project is written in Go, a modern, open source programming language. +This project is written in Go, a modern, open source programming language. You may verify your `go` installation via the terminal: @@ -37,6 +38,7 @@ If you do not have go, we recommend installing it by: #### MacOS ##### Homebrew + ``` $> brew install go ``` @@ -73,13 +75,13 @@ Installation instructions are on the [Magefile home page](https://magefile.org/) ### Java -This project is written in Java, a typesafe, compiled programming language. +This project is written in Java, a typesafe, compiled programming language. You may verify your `java` installation via the terminal by running `java -version`. -If you do not have Java, we recommend installing it -via [SDKMan](https://sdkman.io/install). This is a project which will allow you -to easily install the Java Development Kit (JDK), runtime (JRE), and related frameworks, +If you do not have Java, we recommend installing it +via [SDKMan](https://sdkman.io/install). This is a project which will allow you +to easily install the Java Development Kit (JDK), runtime (JRE), and related frameworks, build tools, and runtimes. After you've installed SDKMan, you may install Java: @@ -122,11 +124,13 @@ $> mage build ## Build (Java / Gradle) ### macOS / Linux + ```shell $> ./gradlew build ``` ### Windows + ```shell $> gradlew.bat build ``` @@ -140,11 +144,13 @@ $> mage test ## Test (Java / Gradle) ### macOS / Linux + ```shell $> ./gradlew test ``` ### Windows + ```shell $> gradlew.bat test ``` @@ -164,7 +170,7 @@ $> ./gradlew clean build test ### Issues -Anyone from the community is welcome (and encouraged!) to raise issues via +Anyone from the community is welcome (and encouraged!) to raise issues via [GitHub Issues](https://github.com/TBD54566975/web5-spec/issues). ### Discussions @@ -179,34 +185,34 @@ Build and Test cycles are run on every commit to every branch on [GitHub Actions ## Contribution -We review contributions to the codebase via GitHub's Pull Request mechanism. We have -the following guidelines to ease your experience and help our leads respond quickly +We review contributions to the codebase via GitHub's Pull Request mechanism. We have +the following guidelines to ease your experience and help our leads respond quickly to your valuable work: -* Start by proposing a change either in Issues (most appropriate for small - change requests or bug fixes) or in Discussions (most appropriate for design - and architecture considerations, proposing a new feature, or where you'd +* Start by proposing a change either in Issues (most appropriate for small + change requests or bug fixes) or in Discussions (most appropriate for design + and architecture considerations, proposing a new feature, or where you'd like insight and feedback) -* Cultivate consensus around your ideas; the project leads will help you - pre-flight how beneficial the proposal might be to the project. Developing early - buy-in will help others understand what you're looking to do, and give you a - greater chance of your contributions making it into the codebase! No one wants to +* Cultivate consensus around your ideas; the project leads will help you + pre-flight how beneficial the proposal might be to the project. Developing early + buy-in will help others understand what you're looking to do, and give you a + greater chance of your contributions making it into the codebase! No one wants to see work done in an area that's unlikely to be incorporated into the codebase. * Fork the repo into your own namespace/remote -* Work in a dedicated feature branch. Atlassian wrote a great +* Work in a dedicated feature branch. Atlassian wrote a great [description of this workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow) * When you're ready to offer your work to the project, first: -* Squash your commits into a single one (or an appropriate small number of commits), and - rebase atop the upstream `main` branch. This will limit the potential for merge - conflicts during review, and helps keep the audit trail clean. A good writeup for - how this is done is - [here](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec), and if you're - having trouble - feel free to ask a member or the community for help or leave the commits as-is, and flag that you'd like +* Squash your commits into a single one (or an appropriate small number of commits), and + rebase atop the upstream `main` branch. This will limit the potential for merge + conflicts during review, and helps keep the audit trail clean. A good writeup for + how this is done is + [here](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec), and if you're + having trouble - feel free to ask a member or the community for help or leave the commits as-is, and flag that you'd like rebasing assistance in your PR! We're here to support you. * Open a PR in the project to bring in the code from your feature branch. -* The maintainers noted in the `CODEOWNERS` file will review your PR and optionally +* The maintainers noted in the `CODEOWNERS` file will review your PR and optionally open a discussion about its contents before moving forward. * Remain responsive to follow-up questions, be open to making requested changes, and... You're a contributor! -* And remember to respect everyone in our global development community. Guidelines +* And remember to respect everyone in our global development community. Guidelines are established in our `CODE_OF_CONDUCT.md`. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index d02f5ad..2443555 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -27,7 +27,7 @@ Maintainers have write access to GitHub repositories and act as project administ * Commit access to their project's repositories * Write access to continuous integration (CI) jobs -Both maintainers and non-maintainers may propose changes to +Both maintainers and non-maintainers may propose changes to source code. The mechanism to propose such a change is a GitHub pull request. Maintainers review and merge (_land_) pull requests. If a maintainer opposes a proposed change, then the change cannot land. The exception is if the Governance Committee (GC) votes to approve the change despite the opposition. Usually, involving the GC is unnecessary. diff --git a/README.md b/README.md index 91dd358..3f1d2a6 100644 --- a/README.md +++ b/README.md @@ -37,27 +37,29 @@ - [tbDEX Order-Status Message](#tbdex-order-status-message) - [tbDEX Close Message](#tbdex-close-message) - -# Purpose +## Purpose This repo sets forth the development process, requirements, and desired feature set for the following SDKs: -* [tbdex-js](https://github.com/TBD54566975/tbdex-js) -* [tbdex-kt](https://github.com/TBD54566975/tbdex-kt) -* [tbdex-rs](https://github.com/TBD54566975/tbdex-rs) -* [web5-js](https://github.com/TBD54566975/web5-js) -* [web5-kt](https://github.com/TBD54566975/web5-kt) -* [web5-rs](https://github.com/TBD54566975/web5-rs) +- [tbdex-js](https://github.com/TBD54566975/tbdex-js) +- [tbdex-kt](https://github.com/TBD54566975/tbdex-kt) +- [tbdex-rs](https://github.com/TBD54566975/tbdex-rs) +- [web5-js](https://github.com/TBD54566975/web5-js) +- [web5-kt](https://github.com/TBD54566975/web5-kt) +- [web5-rs](https://github.com/TBD54566975/web5-rs) Github Issues and PRs created in this repo address topics that impact / span all SDKs we have in development. See section on [Feature Acceptance](#feature-acceptance) for information on submitting proposals for new features across all of our SDKs (e.g. implement Presentation Exchange v9) -# Known Unknowns -* We don't yet have a cemented path for supporting Android. It could either be through our pre-existing Kotlin SDK or bindings exposed via Rust -* We're not yet in a place where we can confidently state that a rust core can support a broad surface area of target languages. We're confident in pursuing rust development for the purposes of surfacing swift bindings. +## Known Unknowns + +- We don't yet have a cemented path for supporting Android. It could either be through our pre-existing Kotlin SDK or bindings exposed via Rust + +- We're not yet in a place where we can confidently state that a rust core can support a broad surface area of target languages. We're confident in pursuing rust development for the purposes of surfacing swift bindings. + +## Requirements -# Requirements +### Feature Tracking -## Feature Tracking Feature tracking will take place entirely on GitHub through Github Issues and the [SDK development Github project](https://github.com/orgs/TBD54566975/projects/29). --- @@ -77,7 +79,7 @@ Work item progress is tracked using the `Status` attribute on a GH issue. This s --- -### Labels +#### Labels > [!IMPORTANT] > A label should be created for each feature, in each respective repo. @@ -107,14 +109,13 @@ The following labels should exist in all relevant repos | `tbdex-orderstatus` | `#D68910` | tbDEX Order-Status Message | | `tbdex-close` | `#34495E` | tbDEX Close Message | - - > [!NOTE] > This list will change over time as features are added or removed --- -### Milestones +#### Milestones + Github Repo Milestones will be used to track work for specific codenamed projects (e.g. Eagle, Pigeon, Black Swan, etc.). The following milestones should exist in all relevant repos @@ -127,38 +128,44 @@ The following milestones should exist in all relevant repos > [!NOTE] > This list will change over time as projects are added -## Feature Acceptance +### Feature Acceptance + Proposing new features that impact all SDKs will occur by creating a Github Issue in this repo. The Issue should include motivation or rationale in addition to any relevant reading material. New features will be discussed and decided upon during weekly syncs > [!IMPORTANT] > Language agnostic test vectors **must** be produced _prior_ to commencing implementation beyond the first SDK +### Work Prioritization -## Work Prioritization Prioritization of features or specific work items will be reflected during weekly sync meetings. -## Implementation Criteria +### Implementation Criteria + An individual SDK will consider a feature implemented once the following requirements have been met: -* Produce/update API reference documentation for any/all methods added to the _public_ API surface. documenting private API methods is optional -* Produce/update relevant example usage -* Test coverage must be provided for _all_ public API methods. -* Tests that consume shared test vectors must all be passing +- Produce/update API reference documentation for any/all methods added to the _public_ API surface. documenting private API methods is optional +- Produce/update relevant example usage +- Test coverage must be provided for _all_ public API methods. +- Tests that consume shared test vectors must all be passing + +### 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 -## 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 -* 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 +### Release Criteria -## Release Criteria -* Each Release will have an accompanying Github Release -* Each Github Release will have an accompanying git tag that matches the version being published -* For the forseeable future, each SDK is free to publish releases at a frequency that the SDK's respective DRI sees fit +- Each Release will have an accompanying Github Release + +- Each Github Release will have an accompanying git tag that matches the version being published +- For the forseeable future, each SDK is free to publish releases at a frequency that the SDK's respective DRI sees fit + +### CI / CD -## CI / CD Each SDK will use Github Actions for CI/CD and other automations | Feature | Typescript | Kotlin | Rust | Swift | @@ -175,17 +182,17 @@ Each SDK will use Github Actions for CI/CD and other automations | Publishing API Reference Docs | ❌ | ✅ | ❌ | ❌ | | Publish Example Feature Usage | ❌ | ✅ | ❌ | ❌ | -* 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 +- 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 -## Publishing Artifacts -Each SDK will be published to the most widely adopted registry/repository for the respective language +### Publishing Artifacts +Each SDK will be published to the most widely adopted registry/repository for the respective language | SDK | Repository | | ---------- | ------------- | @@ -194,9 +201,9 @@ Each SDK will be published to the most widely adopted registry/repository for th | Rust | crates | | Swift | swift package index | +### Publishing API Reference Documentation -## Publishing API Reference Documentation -Each SDK will auto generate API reference documentation using the respective language's commenting convention and doc gen tooling +Each SDK will auto generate API reference documentation using the respective language's commenting convention and doc gen tooling --- @@ -212,27 +219,27 @@ Each SDK will auto generate API reference documentation using the respective lan | Rust | ? | ? | | Swift | ? | ? | - -> [!IMPORTANT] +> [!IMPORTANT] > Producing API reference documentation is the responsibility of an _implementer_ -## Example Feature Usage +### 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 -# Features +## Features + +### Cryptographic Digital Signature Algorithms (DSA) -## Cryptographic Digital Signature Algorithms (DSA) | Algorithm | Typescript | Kotlin | Rust | Swift | | --------------- | ---------- | ------ | ---- | ----- | | `ES256K` | ✅ | ✅ | ❌ | ❌ | | `EdDSA:Ed25519` | ✅ | ✅ | ❌ | ❌ | - > [!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. Verification **must not require** low-s signatures +### Key Management -## 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 | @@ -244,38 +251,43 @@ Each SDK will implement a consistent and extensible _public interface_ for key m | Keychain | N/A | ❌ | N/A | ❌ | Further, the key manager interface **must** be passed as an argument to _all_ public API methods that require key material. e.g. -* DID Creation -* Data Signing + +- DID Creation +- Data Signing > [!IMPORTANT] > AWS KMS does **not** support `Ed25519`. At some point in the future, we can consider introducing support for key wrapping + > [!IMPORTANT] > Consumers of our SDKs should be able to provide their own `KeyManager` implementations if desired + > [!NOTE] > ⚠️ = implemented but no test vectors present -## `did:web` +### `did:web` + | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | | `Resolution` | ❌ | ❌ | ❌ | ❌ | -## `did:jwk` +### `did:jwk` + | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | | `Creation` | ❌ | ❌ | ❌ | ❌ | | `Resolution` | ❌ | ❌ | ❌ | ❌ | +### `did:dht` -## `did:dht` | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | | `Creation` | ⚠️ | ⚠️ | ❌ | ❌ | | `Resolution` | ⚠️ | ⚠️ | ❌ | ❌ | +### `did:key` -## `did:key` | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | | `Creation` | ⚠️ | ⚠️ | ❌ | ❌ | @@ -284,8 +296,8 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu > [!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 +### `did:ion` -## `did:ion` | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | | `Creation` | ⚠️ | ⚠️ | ❌ | ❌ | @@ -294,15 +306,15 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu > [!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 & Resolution Validation -## DID Document & Resolution Validation | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | | JSON Schema | ❌ | ❌ | ❌ | ❌ | | Common Error | ❌ | ❌ | ❌ | ❌ | +### W3C Verifiable Credential Data Model 1.1 -## W3C Verifiable Credential Data Model 1.1 | Feature | Typescript | Kotlin | Rust | Swift | | ------------------- | ---------- | ------ | ---- | ----- | | Creation | ❌ | ❌ | ❌ | ❌ | @@ -310,7 +322,8 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu | Verification | ❌ | ❌ | ❌ | ❌ | | Validation | ❌ | ❌ | ❌ | ❌ | -## W3C Verifiable Credential Data Model 2.0 +### W3C Verifiable Credential Data Model 2.0 + | Feature | Typescript | Kotlin | Rust | Swift | | ------------------- | ---------- | ------ | ---- | ----- | | Creation | ❌ | ❌ | ❌ | ❌ | @@ -318,7 +331,8 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu | Verification | ❌ | ❌ | ❌ | ❌ | | Validation | ❌ | ❌ | ❌ | ❌ | -## SD-JWT / SD-JWT-VC +### SD-JWT / SD-JWT-VC + | Feature | Typescript | Kotlin | Rust | Swift | | ------------------- | ---------- | ------ | ---- | ----- | | Creation | ❌ | ❌ | ❌ | ❌ | @@ -326,14 +340,15 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu | Verification | ❌ | ❌ | ❌ | ❌ | | Validation | ❌ | ❌ | ❌ | ❌ | -## Presentation Definition V2 +### Presentation Definition V2 + | Feature | Typescript | Kotlin | Rust | Swift | | --------------------- | ---------- | ------ | ---- | ----- | | Concrete Type | ❌ | ❌ | ❌ | ❌ | | Validation | ❌ | ❌ | ❌ | ❌ | | Credential Evaluation | ❌ | ❌ | ❌ | ❌ | -## tbDEX Message +### tbDEX Message | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | @@ -342,8 +357,7 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu | Verification | ✅ | ✅ | ❌ | ❌ | | Parsing | ✅ | ✅ | ❌ | ❌ | - -## tbDEX Resource +### tbDEX Resource | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | @@ -352,8 +366,7 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu | Verification | ✅ | ✅ | ❌ | ❌ | | Parsing | ✅ | ✅ | ❌ | ❌ | - -## tbDEX Offering Resource +### tbDEX Offering Resource | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | @@ -363,7 +376,7 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu | Verification | ✅ | ✅ | ❌ | ❌ | | Parsing | ✅ | ✅ | ❌ | ❌ | -## tbDEX RFQ Message +### tbDEX RFQ Message | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | @@ -373,7 +386,7 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu | Verification | ✅ | ✅ | ❌ | ❌ | | Parsing | ✅ | ✅ | ❌ | ❌ | -## tbDEX Quote Message +### tbDEX Quote Message | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | @@ -383,7 +396,7 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu | Verification | ✅ | ✅ | ❌ | ❌ | | Parsing | ✅ | ✅ | ❌ | ❌ | -## tbDEX Order Message +### tbDEX Order Message | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | @@ -393,7 +406,7 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu | Verification | ✅ | ✅ | ❌ | ❌ | | Parsing | ✅ | ✅ | ❌ | ❌ | -## tbDEX Order-Status Message +### tbDEX Order-Status Message | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | @@ -403,7 +416,7 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu | Verification | ✅ | ✅ | ❌ | ❌ | | Parsing | ✅ | ✅ | ❌ | ❌ | -## tbDEX Close Message +### tbDEX Close Message | Feature | Typescript | Kotlin | Rust | Swift | | ------------ | ---------- | ------ | ---- | ----- | diff --git a/test-harness/README.md b/test-harness/README.md index 9eff754..4e0657f 100644 --- a/test-harness/README.md +++ b/test-harness/README.md @@ -11,18 +11,20 @@ This repo houses the specification and test suite for Web5 SDKs. | [GOVERNANCE.md](./GOVERNANCE.md) | Project governance | | [LICENSE](./LICENSE) | Apache License, Version 2.0 | - To generate the golang open api models: + ```bash make ``` To generate the javascript open api models: + ```bash npx openapi-typescript openapi.yaml -o sdks/web5-js/openapi.d.ts ``` To generate the kotlin open api models: + ```bash # Note: After running the above command, you will need to manually copy the generated model files into the correct directory in the sdk/web5-kt models directory and delete the generated folder. openapi-generator generate -i openapi.yaml -g kotlin-server -o ./kotlin-server-generated-server --skip-validate-spec @@ -38,4 +40,4 @@ To run the tests for kotlin: ```bash go run ./cmd/web5-spec-test sdks/web5-kt -``` \ No newline at end of file +``` diff --git a/test-harness/reports/report-template.md b/test-harness/reports/report-template.md index 0b21255..8da8bc8 100644 --- a/test-harness/reports/report-template.md +++ b/test-harness/reports/report-template.md @@ -1,4 +1,4 @@ -# web5 conformance report +# web5 conformance report SDK: [{{ .TestServerID.Name }}]({{ .TestServerID.Url }}) ({{ .TestServerID.Language }}) diff --git a/test-harness/sdks/web5-kt/README.md b/test-harness/sdks/web5-kt/README.md index 826694d..92b3c28 100644 --- a/test-harness/sdks/web5-kt/README.md +++ b/test-harness/sdks/web5-kt/README.md @@ -9,10 +9,11 @@ go run ./cmd/web5-spec-test sdks/web5-kt ``` ## Generating Model Files + To generate the model files, use the openapi-generator with the following command: ```bash openapi-generator generate -i openapi.yaml -g kotlin-server -o ./kotlin-server-generated-server --skip-validate-spec ``` -Note: After running the above command, you will need to manually copy the generated model files into the correct directory in the sdk/web5-kt models directory. \ No newline at end of file +Note: After running the above command, you will need to manually copy the generated model files into the correct directory in the sdk/web5-kt models directory. diff --git a/test-harness/spec/README.md b/test-harness/spec/README.md index 98575a8..d4ef3e0 100644 --- a/test-harness/spec/README.md +++ b/test-harness/spec/README.md @@ -1,15 +1,19 @@ +# Test Harness + + ## Dependencies -* [Encoders SDK](#Encoders-SDK) + +* [Encoders SDK](#encoders-sdk) * CBOR * SHA256 * Base64 -* [Crypto SDK](#Crypto-SDK) +* [Crypto SDK](#crypto-sdk) * Key Manager * JWS Signatures * JWS Verification -* [DIDs SDK](#DIDs-SDK) +* [DIDs SDK](#dids-sdk) * DID Resolution -* [Credentials SDK](#Credentials-SDK) +* [Credentials SDK](#credentials-sdk) * Concrete Presentation Definition Types * Concrete Presentation Submission Types * Presentation Exchange Eval - Evaluate Presentation Submission against Presentation Definition @@ -19,6 +23,7 @@ * VP Verification ## Features + | Feature | Typescript | Kotlin | Swift | | ------------------------- | ---------- | ------ | ----- | | Create Offering | :x: | :x: | :x: | @@ -35,21 +40,21 @@ | Validate Message | :x: | :x: | :x: | | Hash Private fields | :x: | :x: | :x: | +References: -## References * [tbDEX Protocol Spec](https://github.com/TBD54566975/tbdex-protocol/blob/rest-api-spec/README.md) +## DIDs SDK -# DIDs SDK SDK used to create and resolve DIDs -## Dependencies -* [Encoders SDK](#Encoders-SDK) -* [Crypto SDK](#Crypto-SDK) +Dependencies: + +* [Encoders SDK](#encoders-sdk) +* [Crypto SDK](#crypto-sdk) ## DID ION -### Features | Feature | Typescript | Kotlin | Swift | | ---------------------------------------------------------------------------- | -------------- | ------ | ----- | | [`CreateRequest`](https://identity.foundation/sidetree/spec/#create) | ✅ | :x: | :x: | @@ -63,33 +68,35 @@ SDK used to create and resolve DIDs * `UpdateRequest` - used to update an ION DID * `RecoverRequest` - used to recover an ION DID * `DeactivateRequest` - used to decomission an ION DID -* Resolution - used to resolve an ION DID. +* Resolution - used to resolve an ION DID. * Needed for decentralized discovery * Needed for signature verification ## DID Key -### Features | Feature | Typescript | Kotlin | Swift | | ---------- | ---------- | ------ | ----- | | Creation | ✅ | :x: | :x: | | Resolution | ✅ | :x: | :x: | +References: -## References * [DID Spec](https://www.w3.org/TR/did-core/) * [DID ION aka Sidetree Spec](https://identity.foundation/sidetree/spec/) * [Typescript DIDs Package](https://github.com/TBD54566975/web5-js/tree/main/packages/dids) # Credentials SDK + SDK used to create, verify and construct data structures needed to exchange Verifiable Credentials ## Dependencies -* [Encoders SDK](#Encoders-SDK) -* [Crypto SDK](#Crypto-SDK) -* [DIDs SDK](#DIDs-SDK) + +* [Encoders SDK](#encoders-sdk) +* [Crypto SDK](#crypto-sdk) +* [DIDs SDK](#dids-sdk) ## Features + | Feature | Typescript | Kotlin | Swift | | --------------------- | ---------- | -------------- | ----- | | Presentation Exchange | ✅ | :construction: | :x: | @@ -99,7 +106,6 @@ SDK used to create, verify and construct data structures needed to exchange Veri | VP Verification | ✅ | :construction: | :x: | | StatusList lookup | :x: | :x: | :x: | - * [Presentation Exchange](https://identity.foundation/presentation-exchange/) * Presentation Definition - Data Structure used by PFIs to express their VC requirements * Presentation Submission - Data Structure used by Alice to fulfill the VC requirements expressed by a PFI @@ -111,8 +117,8 @@ SDK used to create, verify and construct data structures needed to exchange Veri * VP Verification - Used by PFI to perform integrity check on Presentation Submission provided by Alice * [StatusList](https://www.w3.org/TR/vc-status-list/) Lookup - Used by PFI as part of privacy preserving integrity check +References: -## References * [VC Spec](https://www.w3.org/TR/vc-data-model/) * [Presentation Exchange Spec](https://identity.foundation/presentation-exchange/) * [StatusList 2021 Spec](https://www.w3.org/TR/vc-status-list/) @@ -121,13 +127,12 @@ SDK used to create, verify and construct data structures needed to exchange Veri * [PEX](https://github.com/TBD54566975/web5-js/pull/164) * [VC Creation](https://github.com/TBD54566975/web5-js/pull/148) - # Crypto SDK + SDK that contains the cryptographic foundation needed for DIDs, VCs, and tbDEX messages ## Key Generation -### Features | Feature | Typescript | Kotlin | Swift | | ----------- | ---------- | ------ | ----- | | `secp256k1` | ✅ | :x: | :x: | @@ -138,7 +143,6 @@ SDK that contains the cryptographic foundation needed for DIDs, VCs, and tbDEX m ## Signing -### Features | Feature | Typescript | Kotlin | Swift | | ----------- | ---------- | ------ | ----- | | `secp256k1` | ✅ | :x: | :x: | @@ -147,7 +151,6 @@ SDK that contains the cryptographic foundation needed for DIDs, VCs, and tbDEX m ## Verification -### Features | Feature | Typescript | Kotlin | Swift | | ----------- | ---------- | ------ | ----- | | `secp256k1` | ✅ | :x: | :x: | @@ -156,7 +159,6 @@ SDK that contains the cryptographic foundation needed for DIDs, VCs, and tbDEX m ## JOSE -### Features | Feature | Typescript | Kotlin | Swift | | ------------ | -------------- | ------ | ----- | | `JWS create` | :construction: | :x: | :x: | @@ -168,10 +170,8 @@ SDK that contains the cryptographic foundation needed for DIDs, VCs, and tbDEX m > :information_source: prefer Compact JWS. Can work with General JWS - ## Key Manager -### Features | Feature | Typescript | Kotlin | Swift | | -------------- | ---------- | ------ | ----- | | `Generate Key` | ✅ | :x: | :x: | @@ -179,17 +179,17 @@ SDK that contains the cryptographic foundation needed for DIDs, VCs, and tbDEX m | `Sign` | ✅ | :x: | :x: | | `Verify` | ✅ | :x: | :x: | +References: -## References * [JWS Spec](https://datatracker.ietf.org/doc/html/rfc7515) * [JWK Spec](https://datatracker.ietf.org/doc/html/rfc7517) * [JWT Spec](https://datatracker.ietf.org/doc/html/rfc7519) * [Typescript Crypto Package](https://github.com/TBD54566975/web5-js/tree/main/packages/crypto) # Encoders SDK + SDK that contains encode/decode utility functions needed for DIDs, VCs, and tbDEX -## Features | Feature | Typescript | Kotlin | Swift | | --------------- | ---------- | ------ | ----- | | `base64 encode` | ✅ | :x: | :x: | @@ -200,6 +200,6 @@ SDK that contains encode/decode utility functions needed for DIDs, VCs, and tbDE | `cbor encode` | :x: | :x: | :x: | | `cbor decode` | :x: | :x: | :x: | +References: -## References -* [Typescript Encoders Package](https://github.com/TBD54566975/web5-js/tree/main/packages/common) \ No newline at end of file +* [Typescript Encoders Package](https://github.com/TBD54566975/web5-js/tree/main/packages/common)