• This repository has been archived on 11/Jun/2023
  • Stars
    star
    139
  • Rank 262,954 (Top 6 %)
  • Language
    JavaScript
  • License
    Apache License 2.0
  • Created about 6 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Decentralized Identity with Github

GitHub DID

Build Status codecov Docs License GitHub forks GitHub stars

DID method specification

Website

Swagger

🚧 This is experimental, not endorsed by GitHub, and under development. 🚧

^ This means don't trust signatures, messages or software related to this project AND don't import keys that are used for anything else.

GitHub DID

Decentralized Identifiers (DIDs) are a new type of identifier for verifiable, "self-sovereign" digital identity. DIDs are fully under the control of the DID subject, independent from any centralized registry, identity provider, or certificate authority. DIDs are URLs that relate a DID subject to means for trustable interactions with that subject. DIDs resolve to DID Documents β€” simple documents that describe how to use that specific DID. Each DID Document contains at least three things: cryptographic material, authentication suites, and service endpoints. Cryptographic material combined with authentication suites provide a set of mechanisms to authenticate as the DID subject (e.g., public keys, pseudonymous biometric protocols, etc.). Service endpoints enable trusted interactions with the DID subject.

Install CLI

npm i -g @github-did/cli

Install Library

npm i @github-did/lib --save

Motivation

The github method is meant to make working with DIDs very simple at the cost of trusting Github.com for assisting in resolving DID Documents.

Many developers are familar with Github, and its 2 supported public key cryptosystems, GPG and SSH.

Linked Data Signatures are difficult to work with when operating a server or running a local node of some distributed system / blockchain is a requirement.

The objective of GitHub DID is to encourage contribution to the DID Spec and Linked Data Signatures, and allow rapid development of extensions to these without requiring the use of slow, or complicated more trustless infrastructure, such as blockchains or other distributed systems.

Getting Started

Next, you will need to install the cli to complete creating your GitHub DID.

npm i -g @github-did/cli
ghdid init "my-password" https://github.com/USERNAME/ghdid

If you mess up, you can overwrite everything with:

ghdid init "my-password" https://github.com/USERNAME/ghdid --force

Don't worry about this, its all experimental for now (which means be careful!)... This will automatically revoke (according to the DID Spec, not PGP!) all keys associated with your GitHub DID.

This will clone the repo into ~/.github-did/${repo}. Your wallet will be created, encrypted and stored:

~/.github-did/wallet.enc and ~/.github-did/web.wallet.enc

Your DID Document will be:

~/.github-did/${repo}/index.jsonld;

It will be commited and push automatically by init.

Using the auto signer Github Action

The auto signer Github action will check the proof property of the did document for every commit on master, verify the validity of the signature, and automatically commit a valid proof property if necessary.

In order to use it, you need to set your wallet and password in the Github secrets of your repo: Settings -> Secrets Add a new secret and add two secrets:

  • DID_WALLET: cat ~/.github-did/web.wallet.enc | pbcopy in order to copy the valud
  • DID_WALLET_PASSWORD: the password you passed in the init command

Resolve

Now that your DID Document is on Github in the correct repo, you can use the github did method resolver, and linked data signature verification libraries.

ghdid resolve did:github:OR13

This will resolve the DID to a DID Document by using Github and https.

The signature for the DID Document will be checked.

How does the DID Resolver work?

A DID Resolver is a simple async function which takes a DID and returns a promise for a DID Document.

This one works, by converting the DID to a path in a git repo and then requesting the json-ld document at that path.

const didToDIDDocumentURL = did => {
  const [_, method, identifier] = did.split(":");
  if (_ !== "did") {
    throw new Error("Invalid DID");
  }
  if (method !== "github") {
    throw new Error("Invalid DID, should look like did:github:USERNAME");
  }

  if (method === "github") {
    const base = "https://raw.githubusercontent.com/";
    const didRepoDir = "/master/index.jsonld";
    const url = `${base}${identifier}/ghdid${didRepoDir}`;
    return url;
  }
};

Notice there is nothing here about this repo (https://github.com/decentralized-identity/github-did), this is because the github method works with any github repo that is public, the identifier includes the details needed to get the did document from dids folder. If you want to create a new folder structure, you must create a new DID method, or convince us to change this one. Since this is all highly experimental, expect this to maybe change in the future.

What can I do with my DID?

Use your DIDs to test Linked Data Signatures, such OpenPgpSignature2019 which is currently being developed. When DID Documents are signed, they include a proof attribute, which is used to provide proof that someone controlled the private key associated with the public key listed in the did document at the created datetime.

For example:

{
  "@context": "https://w3id.org/did/v1",
  "id": "did:github:OR13",
  "publicKey": [
    {
      "encoding": "application/pgp-keys",
      "type": "OpenPgpVerificationKey2019",
      "id": "did:github:OR13#kid=ibHP1ksrJp5FQjP7hhmTXV7YE5o5bB6YFoODu9n_82E",
      "controller": "did:github:OR13",
      "publicKeyPem": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\nVersion: OpenPGP.js v4.4.7\r\nComment: https://openpgpjs.org\r\n\r\nxk8EXNhPhBMFK4EEAAoCAwSTAb5KPYRzxaQoplpY8olodfbG3OxFqm6ULA6p\r\nvaCxZLKVwd4XCwSL8XcMMrPb78kmDEk0H5/Jl0qpRteRoy8CzRdhbm9uIDxh\r\nbm9uQGV4YW1wbGUuY29tPsJ3BBATCAAfBQJc2E+EBgsJBwgDAgQVCAoCAxYC\r\nAQIZAQIbAwIeAQAKCRAeL9f86407tSxDAP4/dXtxQKQxAsURQmNxwwlD03YM\r\n778dcM753Y4f96jW7QEAkLEDur/hKPLKKdFAi/9TCKNQvr7GVk1wYeYeiHMi\r\nJ/fOUwRc2E+EEgUrgQQACgIDBA7fIkmeQmvaG6a5B3X808pdFStePh7+uevf\r\njWpXbDYYTsxARpBT/xb34m0wrXGo7DEG6pAknQ6NBWiXSWX7qTkDAQgHwmEE\r\nGBMIAAkFAlzYT4QCGwwACgkQHi/X/OuNO7U8gQEAn3/lFx3C7iqzVG2BJgtH\r\n08Oc3h0YPwYnZjM9NXDsvEgA/3v5C28Jhx10RFKi9NDxAPjilwBDOZqYPK/s\r\nW3qWhGNU\r\n=RgYO\r\n-----END PGP PUBLIC KEY BLOCK-----\r\n"
    },
    {
      "encoding": "application/pgp-keys",
      "type": "OpenPgpVerificationKey2019",
      "id": "did:github:OR13#kid=jNeDDagaBn466F-wH26YdQ5_NiabBvOlXTv5xItQakU",
      "controller": "did:github:OR13",
      "publicKeyPem": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\nVersion: OpenPGP.js v4.4.7\r\nComment: https://openpgpjs.org\r\n\r\nxk8EXNhPhBMFK4EEAAoCAwRzQtkzDYQJy7xfHE0ld/Yoznx0q5bfVrx51FPG\r\nXzjd28wktnePW+3Riq0+3YUa09mZJWEuGPwrrGGXEqobjlVBzRdhbm9uIDxh\r\nbm9uQGV4YW1wbGUuY29tPsJ3BBATCAAfBQJc2E+EBgsJBwgDAgQVCAoCAxYC\r\nAQIZAQIbAwIeAQAKCRC0BtN9z0XDqWsSAQCso31Utz8xji2B7WUBX+2798ae\r\ncqxSxMPWnOQKenBA0gD+N9Qiq6sQ/sDipXuG7xIg4NH4qpf96xvPwC4hX9Jv\r\n3FzOUwRc2E+EEgUrgQQACgIDBIPkRAFeFOrFMXa4XoZ8+aZb4iXLhce6N0LE\r\nCh3YZNJLwxWVKVCxr8niWq3Fa8RTkLA+F7PvIHjnpgx5UGeqPzgDAQgHwmEE\r\nGBMIAAkFAlzYT4QCGwwACgkQtAbTfc9Fw6nomAEAl+1tioF0BlbTNm3c879W\r\nadI46tXfqHt8T6TGdIsKbmoA/RjOfCUvMT277p+v3aYjROI3M7ygh24jbjzx\r\nKBQj/GIJ\r\n=UGd9\r\n-----END PGP PUBLIC KEY BLOCK-----\r\n"
    }
  ],
  "authentication": [],
  "service": [],
  "proof": {
    "type": "OpenPgpSignature2019",
    "creator": "did:github:OR13#kid=ibHP1ksrJp5FQjP7hhmTXV7YE5o5bB6YFoODu9n_82E",
    "domain": "GitHubDID",
    "nonce": "9c28424e440806718a5165670f79bbc2",
    "created": "2019-05-12T16:53:25.038Z",
    "signatureValue": "-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.4.7\r\nComment: https://openpgpjs.org\r\n\r\nwl0EARMIAAYFAlzYT4UACgkQHi/X/OuNO7WZQAD47BbeS2pgFW/WwPbHvC8I\r\nMfsOFhSJEywkED7uz0E4RwD/RRrsmPPb4S4Z+7D2skjiFtnd2nWd+BXcxvhm\r\nGzKk1FU=\r\n=W/tu\r\n-----END PGP SIGNATURE-----\r\n"
  }
}

How do Linked Data Signatures work?

They provide authentication for JSON-LD Documents, prooving that a DID has signed the document, by attaching a signature which can be verified by resolving the DID Document. Linked Data Signatures are currently being developed and standardized, here's how they typically work:

When a user wants to sign a json-ld document, they ensure that the public key corrosponding to their private key is listed in their did document. In the document above, the public key is in publicKeyPem format and has an id which will become the creator attribute on the signed linked data. In other systems, such as ActivityPub used by Mastodon, DIDs are URLs, but the principle of retrieving cryptographic material from a downloaded json document is the same.

Next a string that will be signed is created from the document and the signatureOptions, which can include properties like nonce, domain, type, creator, etc... This step is called createVerifyData.

Create Verify Data ensures that a json document can be converted to the same hash regardless of the language (python, haskell, go, javascript, etc...). The most common cannonization algorithm is URDNA2015.

You can see how it is used in Mastodon.

Here is the method used in the OpenPgpSignature2019 Proposal.

The final string to be signed is of the following format: ${optionsHash}${documentHash}. Sometimes a signature algorithm will hash this again, be careful to ensure your implementation can verify and generate signatures that are compatible with existing implementations.

When verifying a linked data signature, first the signing key is retrieved from the creator attribute, either over https or using a DID Resolver. Once the key is available the signatureValue in the proof or signature can be verified. Often some encoding transforms are required before the signature can be verified, for example RsaSignature2017 and EcdsaKoblitzSignature2016 use base64 encoding of the result of the signature algorithm. Beware that base64 != base64url, which is commonly used with JWTs.

Danger / Fun

The Linked Data Signature Spec is still evolving, and you may find cases where a signature type such as EcdsaKoblitzSignature2016 is claimed to be used, but where the signatures cannot be verified with libraries such as jsonld-signatures. This is often due to a lack of understanding regarding Linked Data Signature type field. This field should match a value in the ld-cryptosuite-registry. Unfortunatly, this registry is very out of date and does not even contain RsaSignature2017 used by Mastodon, which is probably the mostly widely used signature suite. This can cause developers to make up their own signature type and that will work fine so long as they are the only system verifying and signing. Doing this weakens the JSON-LD Signature spec, making it harder for developers to know what EcdsaKoblitzSignature2016 means, please don't make this worse.

If you would like to develop a new signature suite, like the ones we propose such as OpenPgpSignature2019 and EcdsaKoblitzSignature2019, make sure to make it clear that it is a PROPOSAL, and get it registered once its clearly documented, has test coverage, and supports at least the fields described in terminology.

Help Wanted

The DID Spec is long, and this project does not fully support a DID implementation. If you would like to contribute, or have questions about DIDs, please feel free to open an issue or a PR.

Development

See .travis.yml.

npm i
npm run bootstrap
npm run lint
npm run test
Local API Docs
API Docs
npm i -g firebase-tools lerna
firebase login
firebase init
lerna init

Commercial Support

Commercial support for this library is available upon request from Transmute: [email protected].

Related Work

More Repositories

1

ion

The Identity Overlay Network (ION) is a DID Method implementation using the Sidetree protocol atop Bitcoin
HTML
1,225
star
2

universal-resolver

Universal Resolver implementation and drivers.
Java
545
star
3

sidetree

Sidetree Specification and Reference Implementation
HTML
438
star
4

decentralized-web-node

Decentralized data storage and message relay for decentralized identity and apps.
HTML
402
star
5

did-jwt

Create and verify DID verifiable JWT's in Javascript
TypeScript
335
star
6

did-resolver

Universal did-resolver for javascript environments
TypeScript
213
star
7

did-jwt-vc

Create and verify W3C Verifiable Credentials and Presentations in JWT format
TypeScript
179
star
8

ethr-did-resolver

DID resolver for Ethereum Addresses with support for key management
TypeScript
168
star
9

didcomm-messaging

JavaScript
163
star
10

ion-tools

Tools and utilities to make working with the ION network and using ION DIDs easy peasy lemon squeezy
JavaScript
139
star
11

element

DID Method implementation using the Sidetree protocol on top of Ethereum and IPFS
JavaScript
100
star
12

decentralized-identity.github.io

Site for the open source, community-driven group of dev and organizations working toward an interoperable, decentralized identity ecosystem
HTML
98
star
13

interoperability

The archive and information hub for the cross-community interoperability project. Focus is on education and familiarity for various efforts across multiple groups for interoperable decentralized identity infrastructure.
93
star
14

presentation-exchange

Specification that codifies an inter-related pair of data formats for defining proof presentations (Presentation Definition) and subsequent proof submissions (Presentation Submission)
JavaScript
85
star
15

confidential-storage

Confidential Storage Specification and Implementation
TypeScript
80
star
16

bbs-signature

The BBS Signature Scheme
Rust
76
star
17

keri

Key Event Receipt Infrastructure - the spec and implementation of the KERI protocol
HTML
72
star
18

web-did-resolver

DID resolver for HTTPS domains
TypeScript
70
star
19

universal-registrar

Universal Registrar implementation and drivers.
Java
64
star
20

DIDComm-js

JS implementation of pack and unpack
TypeScript
55
star
21

.well-known

Specs and documentation for all DID-related /.well-known resources
HTML
53
star
22

fuzzy-encryption

A variant of a Fuzzy Vault cryptographic scheme designed for encrypting data with better human recovery features.
C++
49
star
23

did-key.rs

Rust implementation of the did:key method
Rust
47
star
24

didcomm-rs

DIDComm messaging specifications implementation: https://identity.foundation/didcomm-messaging/spec/
Rust
46
star
25

keriox

Rust Implementation of the KERI Core Library
Rust
43
star
26

papers

Notes, ideas, and write-ups from DIF members and collaborators
40
star
27

org

DIF docs, wiki, and organizational material
Rich Text Format
39
star
28

did-auth-jose

JOSE-based implementation of DID Authenticated Encryption
TypeScript
39
star
29

did-common-java

Shared DID Java library.
Java
37
star
30

didcomm.org

TypeScript
36
star
31

did-siop

TypeScript
35
star
32

spec-up

Create beautiful, feature-rich technical specifications in markdown
HTML
32
star
33

credential-manifest

Format that normalizes the definition of requirements for the issuance of a credential
JavaScript
30
star
34

ion-sdk

TypeScript SDK for ION
TypeScript
29
star
35

keripy

Python Implementation of the KERI Core Libraries
Python
28
star
36

sidetree-ethereum

Blockchain-specific code for the Sidetree-based DID Method implementation on Ethereum
TypeScript
28
star
37

peer-did-method-spec

A rich DID method that has no blockchain dependencies. The verifiable data registry is a synchronization protocol between peers.
JavaScript
27
star
38

universal-resolver-frontend

Frontend web UI for Universal Resolver.
JavaScript
25
star
39

snark-credentials

25
star
40

identifiers-discovery

Identifiers & Discovery WG operating repo
21
star
41

trustdidweb

Trust DID Web (did:tdw)
18
star
42

waci-presentation-exchange

Wallet And Credential Interactions for Presentation Exchange (Work continues at decentralized-identity/waci-didcomm#1 )
HTML
17
star
43

did-common-dotnet

C#
17
star
44

did-methods

DID Method specs, docs, and materials
17
star
45

hub-node-core

Node.js implementation of the Identity Hub interfaces, business logic, and replication protocol.
TypeScript
17
star
46

lds-ecdsa-secp256k1-2019.js

EcdsaSecp256k1Signature2019 JSON-LD Signature Suite
TypeScript
17
star
47

vc-marketplace

To establish the reference architecture for a Verifiable Credentials Marketplace
HTML
16
star
48

didcomm-bluetooth

a specification that describes discovery and transport over Bluetooth for DIDcomm
16
star
49

horcrux

Horcrux Protocol
16
star
50

kerigo

Go implementation of KERI (Key Event Receipt Infrastructure)
Go
16
star
51

did-security-csharp

C# implementation of DID security and privacy controls
C#
15
star
52

claims-credentials

Claims and Credentials WG operations repo
15
star
53

uni-resolver-driver-did-ccp

A Universal Resolver driver for Baidu did:ccp identifiers.
Java
15
star
54

jwt-vc-presentation-profile

HTML
15
star
55

hub-reference

The official Identity Hub reference implementation bundle for Node.js
JavaScript
15
star
56

c19-vc.com

(DEMO) COVID-19 VC Issuer
JavaScript
14
star
57

didcomm-demo

In browser DIDComm v2 demo.
TypeScript
14
star
58

attestations

Attestation API implementations for various languages and platforms.
JavaScript
14
star
59

hub-sdk-js

JavaScript SDK for interacting with Identity Hubs
TypeScript
14
star
60

wallet-security

Define a common terminology for understanding the security requirements applicable to wallet architectures and wallet-to-wallet and wallet-to-issuer/verifier protocols.
14
star
61

crypto-wg

Meeting notes, transcripts previous agendas and active working group items
13
star
62

edv-spec

Encrypted Data Vault Spec
HTML
13
star
63

veramo-agent-deploy

Generic @veramo/cli agent deployment configuration https://veramo-agent.herokuapp.com
Dockerfile
12
star
64

waci-didcomm

Wallet And Credential Interactions for DIDComm
HTML
12
star
65

agent-explorer

Explore data accross multiple DID agents
TypeScript
12
star
66

uni-resolver-driver-did-ion

Universal Resolver Driver for Identity Overlay Network (ION) DIDs
C#
11
star
67

ion-cli

ION Command Line Interface to make working with the ION network and using ION DIDs easy peasy lemon squeezy
TypeScript
11
star
68

didcomm

11
star
69

did-siop-browser-ext

DID based SIOP
TypeScript
10
star
70

did-registration

A specification for DID create/update/deactivate operations.
HTML
10
star
71

kerijs

JavaScript (nodes) Implementation of the KERI core library.
JavaScript
10
star
72

go-ipfs-ds-azure

Go implementation of ipfs Azure datastore
Go
10
star
73

trust-establishment

https://identity.foundation/trust-establishment
10
star
74

dwn-user-guide

TypeScript
9
star
75

EcdsaSecp256k1RecoverySignature2020

EcdsaSecp256k1RecoverySignature2020
JavaScript
9
star
76

vc-spec-map

Verifiable Credentials Specification Relationship Map
9
star
77

JWS-Test-Suite

JsonWebSignature2020 Test Suite
JavaScript
9
star
78

universal-registrar-frontend

Frontend web UI for Universal Registrar.
JavaScript
8
star
79

presentation-exchange-implementations

Multi-language implementation of the Presentation Exchange protocol.
Go
8
star
80

jsonld-document-loader

TypeScript
8
star
81

wallet-rendering

Specifications for rendering DID and Credential-centric data in wallet applications
JavaScript
8
star
82

jsonld-common-java

Shared JSON-LD Java library.
Java
7
star
83

OpenPgpSignature2019

OpenPgpSignature2019 Linked Data Cryptographic Suite in JavaScript
JavaScript
7
star
84

didcomm-usergroup

DIDComm User Group
7
star
85

wallet-and-credential-interactions

QR Codes and Button for Claiming and Sharing Credentials (and more!)
HTML
7
star
86

schema-directory

A work item of the Claims and Credentials WG at DIF
HTML
7
star
87

did-common-typescript

A common bundle of shared code and modules for working with DIDs, DID Documents, and other DID-related activities
TypeScript
7
star
88

hub-sdk-js-sample

Sample app demonstrating use of the DIF Identity Hub JavaScript SDK.
TypeScript
7
star
89

authentication-wg

6
star
90

presentation-request

Requirements Analysis and Protocol Design for a VC Presentation Request Format
6
star
91

did-crypto-typescript

Crypto library to handle key management for DIDs
TypeScript
6
star
92

universal-wallet-backup-containers

A work Item within the DIF Wallet Security WG aimed to develop a specification for wallet containers
HTML
6
star
93

didcomm-book

5
star
94

universal-resolver-java

5
star
95

did-spec-extensions

Extension parameters, properties, and values for the DID spec registries.
JavaScript
5
star
96

sidetree-reference-impl

Sidetree Reference Implementation
TypeScript
5
star
97

linked-vp

Linked Verifiable Presentation
JavaScript
5
star
98

uni-resolver-driver-dns

A Universal Resolver driver for domain names.
Java
4
star
99

schema-forms

JSON Schema-driven form generator for the input and construction of credentials based on user input
JavaScript
4
star
100

SIG-IoT

DIF IoT Special Interest Group (Open Group)
CSS
4
star