Add spec up spec #162

decentralgabe · 2024-07-19T18:52:13Z

This is the first step in making web5 spec more formal, yay!

Next steps:

Make sure there is clear normative language (MUST, MUST NOT, etc) around features that we want implemented and tested
Open issues for all the TODOs in the spec & add more TODOs
Make sure all features are covered in the spec, and see if there are sections we can refine or remove (like that around key management)
Consider whether we want to add anything around the API to the spec (cc: @KendallWeihe @frankhinek)
Remove the README and generate a GH pages doc...then cut a first version we can publish

Separately, once we agree on the language in the spec and the features we can create a related spec for conformance testing. Here we can note the features, the associated test vectors, and whether the implementations we have are conformant against them.

Open to any & all feedback.

decentralgabe · 2024-07-31T05:59:32Z

It might be easiest for you to review this if you check out the branch and render the spec yourself.

You can do that with ...

git fetch
git checkout origin/spec-up
cd spec
npm i
npm run build
open build/index.html

nitro-neal · 2024-07-31T17:13:25Z

spec/spec.md

+1. **Web1**: Read-only, static websites
+2. **Web2**: Read-write, interactive platforms
+3. **Web3**: Read-write-own, blockchain-based applications
+4. **Web5**: Decentralized, user-centric internet, without the need for a blockchain


nitro-neal · 2024-07-31T17:15:23Z

spec/spec.md

+
+1. Key Manager Interface
+2. In-Memory Key Manager
+3. AWS KMS


are we 100% sure we need this / its required for the spec?

I copied from the current readme I'd love to kill this or just define a key manager interface

I feel strongly we should kill this as well as (4) and (5) below. I do feel that we need to add support for the 3 I'm proposing removing here, but I lack confidence the 3 belong here in this place at this time. Perhaps we could add a :::note with commentary which describes our intention of covering all major platforms' key management at a later date.

nitro-neal · 2024-07-31T17:16:04Z

spec/spec.md

+* Data Signing
+
+::: note
+[AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/asymmetric-key-specs.html#key-spec-ecc) does not support [[ref:Ed25519]]. At some point in the future, we can consider introducing support for key wrapping.


especially since it wont event work lol

hmm can you expand?

nitro-neal · 2024-07-31T17:17:49Z

spec/spec.md

+
+[[ref:JSON-SCHEMA]] support is ****REQUIRED**** for multiple features throughout [[ref:Web5 SDKs]], including, but not limited to support with [[ref:verifiable credentials]], [VC JSON Schemas](#vc-json-schema), and for use in validating the data models this specification has defined.
+
+Conformant implementations of [[ref:Web5 SDKs]] ****MUST**** support at least [[ref:JSON-SCHEMA-DRAFT-7]] and [[ref:JSON-SCHEMA-2020-12]].


Chad says JSON-SCHEMA-2020-12 is backwards compatible with JSON-SCHEMA-DRAFT-7, so just writing in JSON-SCHEMA-DRAFT-7 should be sufficient right?

And if someone used features from JSON-SCHEMA-2020-12 then it may or may not be compatible with SCHEMA-DRAFT-7... lol so it seems like everyone will / should only use SCHEMA-DRAFT-7

we should be using 2020-12 since it's the latest draft, which is being used as the input document to a LTS type draft.

more info here and here which notes that if you're using 2020-12 you'll be fine (we're not using breaking features)

it should be straightforward to convert our schemas to 2020-12, I've done so in the past using this tool https://github.com/sourcemeta/alterschema

nitro-neal · 2024-07-31T17:19:37Z

spec/spec.md

+
+| Method | Creation | Resolution | Note |
+|--------|----------|------------|------|
+| [[ref:did:web]] | ❌ | ✅ | - |


We can create a did web document (have this in the cli).. but yea they would have to host it on their domain, so the philosophical question: is a did:web created if its not hosted on a domain?

created yes, published no

okay so we should change this to

Suggested change

| [[ref:did:web]] | ❌ | ✅ | - |

| [[ref:did:web]] | ✅ | ✅ | - |

yeah?

perhaps we should add a column for Publish?

good call, yes

nitro-neal · 2024-07-31T17:20:21Z

spec/spec.md

+
+Web5 supports the following DID methods:
+
+| Method | Creation | Resolution | Note |


add update column here?

nitro-neal · 2024-07-31T17:55:25Z

spec/spec.md

+
+#### Credential Status
+
+Conformant [[ref:Web5 SDKs]] ****MUST**** support Credential Status as specified by [[ref:STATUS-LIST-2021]] for usage with the W3C Verifiable Credential Data Model 1.1 [[ref:VC-DATA-MODEL-1.1]].


not using the updated one? https://www.w3.org/TR/vc-bitstring-status-list/

there are some weird things that will break if we do, mostly incompatibility with the 1.1 data model since bitstring is designed to be used with 2.0

spec/spec.md

KendallWeihe · 2024-07-31T20:19:00Z

spec/spec.md

+| Key Type | Algorithm | Function |
+|----------|-----------|----------|
+| [[ref:secp256k1]] | `ES256K` [[spec:RFC8812]] | Signing and Verification |
+| [[ref:Ed25519]] | `EdDSA` [[spec:RFC8032]] | Signing and Verification |


FWIW I was planning on adding support for the four key types from here https://did-dht.com/registry/index.html#key-type-index

excellent, I'll add these

spec/spec.md

KendallWeihe · 2024-07-31T20:27:25Z

spec/spec.md

+| [[ref:did:web]] | ❌ | ✅ | - |
+| [[ref:did:jwk]] | ✅ | ✅ | - |
+| [[ref:did:dht]] | ✅ | ✅ | This is the "default" method for [[ref:Web5 SDKs]]. |
+| [[ref:did:key]] | ⚠️ | ⚠️ | This method has been implemented in both Kotlin and TypeScript, with no plans for support in other languages. |


I would probably just remove this line altogether

The new KT SDK (from Rust Core) won't have this

Co-authored-by: Kendall Weihe <[email protected]>

decentralgabe · 2024-08-05T21:11:35Z

@KendallWeihe @nitro-neal @frankhinek @mistermoe I have incorporated all feedback. I'd like to get this merged and publishing as-is.

Then I will work on a follow up PR for aligning normative statements (MUSTs) to test vectors we have, in addition to removing the README and GH-pageifying the spec.

nitro-neal

Looks great! The big thing I would want to see in the future is a "Recommended vc-jwt verification and parsing .

Basically this part:
https://github.com/TBD54566975/web5-rs/blob/main/crates/web5/src/credentials/verifiable_credential_1_1.rs#L271

where a vc jwt is still valid if it has the jwt parts but not the internal vc parts, like it is valid if it hass iss and now vc.issuer (and when we build it internally we add vc.issuer from the iss

Basically this part

Maybe an example section of a "minimum viable vc-jwt" and a "full featured vc jwt"

decentralgabe · 2024-08-05T23:33:51Z

thanks @nitro-neal I added links to that section of the spec and an issue marker for #134

Signed-off-by: Frank Hinek <[email protected]>

gabe added 5 commits July 19, 2024 14:16

first spec up

e4feca8

remove html

e639c92

update

983d11d

update spec

5ef9e79

ready

ff37668

decentralgabe marked this pull request as ready for review July 31, 2024 05:57

decentralgabe requested review from mistermoe, phoebe-lew, frankhinek, nitro-neal, finn-block and diehuxx as code owners July 31, 2024 05:57

decentralgabe requested review from KendallWeihe and jiyoonie9 July 31, 2024 05:59

nitro-neal reviewed Jul 31, 2024

View reviewed changes

KendallWeihe reviewed Jul 31, 2024

View reviewed changes

spec/spec.md Outdated Show resolved Hide resolved

KendallWeihe reviewed Jul 31, 2024

View reviewed changes

spec/spec.md Outdated Show resolved Hide resolved

KendallWeihe reviewed Jul 31, 2024

View reviewed changes

decentralgabe and others added 3 commits July 31, 2024 13:39

Update spec/spec.md

c4d2863

Co-authored-by: Kendall Weihe <[email protected]>

Update spec/spec.md

f102f32

Co-authored-by: Kendall Weihe <[email protected]>

pr comments

e1f1557

KendallWeihe approved these changes Aug 5, 2024

View reviewed changes

nitro-neal approved these changes Aug 5, 2024

View reviewed changes

gabe added 2 commits August 5, 2024 16:32

link to vc jwt processing

c03c775

links

a74e541

Spelling, grammar, and formatting

f038458

Signed-off-by: Frank Hinek <[email protected]>

frankhinek approved these changes Aug 9, 2024

View reviewed changes

mistermoe approved these changes Aug 9, 2024

View reviewed changes

decentralgabe merged commit 7240e88 into main Aug 9, 2024

decentralgabe deleted the spec-up branch August 9, 2024 17:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add spec up spec #162

Add spec up spec #162

decentralgabe commented Jul 19, 2024 •

edited

Loading

decentralgabe commented Jul 31, 2024

nitro-neal Jul 31, 2024

nitro-neal Jul 31, 2024

decentralgabe Jul 31, 2024

KendallWeihe Jul 31, 2024

nitro-neal Jul 31, 2024

decentralgabe Jul 31, 2024

nitro-neal Jul 31, 2024

nitro-neal Jul 31, 2024

decentralgabe Jul 31, 2024

nitro-neal Jul 31, 2024

decentralgabe Jul 31, 2024

KendallWeihe Jul 31, 2024

decentralgabe Jul 31, 2024

nitro-neal Jul 31, 2024

decentralgabe Jul 31, 2024

nitro-neal Jul 31, 2024

decentralgabe Jul 31, 2024

KendallWeihe Jul 31, 2024

decentralgabe Jul 31, 2024

KendallWeihe Jul 31, 2024

decentralgabe commented Aug 5, 2024

nitro-neal left a comment

decentralgabe commented Aug 5, 2024


		[[ref:JSON-SCHEMA]] support is **REQUIRED** for multiple features throughout [[ref:Web5 SDKs]], including, but not limited to support with [[ref:verifiable credentials]], [VC JSON Schemas](#vc-json-schema), and for use in validating the data models this specification has defined.

		Conformant implementations of [[ref:Web5 SDKs]] **MUST** support at least [[ref:JSON-SCHEMA-DRAFT-7]] and [[ref:JSON-SCHEMA-2020-12]].

	\| [[ref:did:web]] \| ❌ \| ✅ \| - \|
	\| [[ref:did:web]] \| ✅ \| ✅ \| - \|


		Web5 supports the following DID methods:

		\| Method \| Creation \| Resolution \| Note \|


		#### Credential Status

		Conformant [[ref:Web5 SDKs]] **MUST** support Credential Status as specified by [[ref:STATUS-LIST-2021]] for usage with the W3C Verifiable Credential Data Model 1.1 [[ref:VC-DATA-MODEL-1.1]].

Add spec up spec #162

Add spec up spec #162

Conversation

decentralgabe commented Jul 19, 2024 • edited Loading

decentralgabe commented Jul 31, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

decentralgabe commented Aug 5, 2024

nitro-neal left a comment

Choose a reason for hiding this comment

decentralgabe commented Aug 5, 2024

decentralgabe commented Jul 19, 2024 •

edited

Loading