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/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..95221ee --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,2 @@ +config: + line-length: false 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..ab21d1b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,8 @@ -# 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 +13,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,11 +23,11 @@ ___***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: -``` +```sh $> go version go version go1.17.6 darwin/amd64 ``` @@ -37,7 +37,8 @@ If you do not have go, we recommend installing it by: #### MacOS ##### Homebrew -``` + +```sh $> brew install go ``` @@ -51,7 +52,7 @@ The build is run by Mage. You may verify your `mage` installation via the terminal: -``` +```sh $> mage --version Mage Build Tool 1.12.1 Build Date: 2021-12-15T21:00:02Z @@ -73,13 +74,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: @@ -87,7 +88,7 @@ After you've installed SDKMan, you may install Java: #### SDKMan (cross-platform instructions) ```shell -$> sdk install java +$> sdk install java ... Do you want java 17.0.2-open to be set as default? (Y/n): Y Setting java 17.0.2-open as default. @@ -122,11 +123,13 @@ $> mage build ## Build (Java / Gradle) ### macOS / Linux + ```shell $> ./gradlew build ``` ### Windows + ```shell $> gradlew.bat build ``` @@ -140,11 +143,13 @@ $> mage test ## Test (Java / Gradle) ### macOS / Linux + ```shell $> ./gradlew test ``` ### Windows + ```shell $> gradlew.bat test ``` @@ -164,7 +169,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 +184,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 c67d7a7..72a631b 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 -## 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 +- 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 > [!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 + +- Each Release will have an accompanying Github Release -## 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 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 | Feature | Typescript | Kotlin | Rust | Swift | @@ -169,9 +176,9 @@ Each SDK will use Github Actions for CI/CD | Publishing API Reference Docs | ❌ | ✅ | ❌ | ❌ | | Publish Example Feature Usage | ❌ | ✅ | ❌ | ❌ | -## 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 | | ---------- | ------------- | @@ -180,9 +187,9 @@ Each SDK will be published to the most widely adopted registry/repository for th | Rust | ? | | Swift | ? | +### 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 --- @@ -198,27 +205,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 | @@ -230,8 +237,9 @@ 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 @@ -242,26 +250,28 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu > [!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` | ⚠️ | ⚠️ | ❌ | ❌ | @@ -270,8 +280,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` | ⚠️ | ⚠️ | ❌ | ❌ | @@ -280,15 +290,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 | ❌ | ❌ | ❌ | ❌ | @@ -296,7 +306,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 | ❌ | ❌ | ❌ | ❌ | @@ -304,7 +315,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 | ❌ | ❌ | ❌ | ❌ | @@ -312,14 +324,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 | | ------------ | ---------- | ------ | ---- | ----- | @@ -328,8 +341,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 | | ------------ | ---------- | ------ | ---- | ----- | @@ -338,8 +350,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 | | ------------ | ---------- | ------ | ---- | ----- | @@ -349,7 +360,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 | | ------------ | ---------- | ------ | ---- | ----- | @@ -359,7 +370,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 | | ------------ | ---------- | ------ | ---- | ----- | @@ -369,7 +380,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 | | ------------ | ---------- | ------ | ---- | ----- | @@ -379,7 +390,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 | | ------------ | ---------- | ------ | ---- | ----- | @@ -389,7 +400,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 | | ------------ | ---------- | ------ | ---- | ----- | @@ -397,4 +408,4 @@ Further, the key manager interface **must** be passed as an argument to _all_ pu | Validation | ✅ | ✅ | ❌ | ❌ | | Signing | ✅ | ✅ | ❌ | ❌ | | Verification | ✅ | ✅ | ❌ | ❌ | -| Parsing | ✅ | ✅ | ❌ | ❌ | \ No newline at end of file +| Parsing | ✅ | ✅ | ❌ | ❌ |