# The Repo DID method

This is the formal specification for a DID method used by the Hyperledger Aries open source community, and perhaps by others.

## Core Characteristics

### Method Name

The method name that identifies this DID method is: `repo`

### Target Scope

Repo DIDs are intended to expose the collective identity of a community that collaborates through a publicly browsable source code repository. If you want DIDs optimized for managing the identity of individual contributors, you might consider [did:git](https://github.com/dhuseby/did-git-spec/blob/master/did-git-spec.md). If you want privacy and pairwise, consider [did:peer](https://openssi.github.io/peer-did-method-spec/).

The Repo DID method is intentionally limited and simple. It is only suitable for managing small numbers of DIDs. It is decentralized in the same way and to the same extent that its associated source code repos are decentralized.

The initial user of this method is the Hyperledger Aries community, but the spec allows other communities to adopt it. This may be useful in the broader Hyperledger greenhouse, or elsewhere. It also gives some flexibility so the Aries community identity could tolerate rebranding or partitioning into new repos in the future.

### Method-Specific Identifier

The repo DID scheme is defined by the following ABNF (see [RFC 5234](https://tools.ietf.org/html/rfc5234) for syntax):

repo-did = "did:repo:" repo "." filename
repo = 1*ALPHANUMERIC
name = 1*ALPHANUMERIC

The `repo` component of an Aries DID references a publicly browsable source code repository that acts as the "face" of its community. Its value is a short mnemonic, and its meaning is defined in the following table.

##### Resolvable Repos

|mnemonic|repo URI|branch|path in branch|comment|
|--------|--------|------|--------------|-------|
|rfcs|https://github.com/hyperledger/aries-rfcs|master|/dids|The Hyperledger Aries community|

If additional repos use this method, new and namespace-unique mnemonics must be chosen, and this section of the spec MUST be updated so those mnemonics are publicly known. Any repo that appears in this table is called a __resolvable repo__. Pull requests against this spec that append a new resolvable repo to this table will be promptly accepted.

Except for the comment field, rows in this table are intended to be immutable; new rows can be added, but the mapping between a mnemonic and its repo URI and path should not change. This means the table above can usually be cached for a long time with confidence. PRs against this spec that change an existing repo URI value may be accepted with special justification, as when an org merges, divests, or rebrands itself.

In this version of the spec, only HTTPS URIs are supported for repos.

### Namestring Generation Method

The `filename` component of a repo DID is a short, convenient token that might be used to name a file. It is used to look up a file that's checked in to the repo in question. See [Create](#create) in the CRUD section below.

## CRUD Operations

### Create

Whenever a community wants to create a repo DID, they choose a `filename` value, and then commit to their repo a file named `<filename>.diddoc`, in the branch and path specified for their entry in the [Resolvable Repos table above](#resolvable-repos). For example, if the Hyperledger Aries community wants to create a DID with the value `did:aries:rfcs.1`, they create a DID doc named `1.diddoc` and commit it to the `/dids` folder of the master branch of the repo at https://github.com/hyperledger/aries-rfcs.

### Read (Resolve)

Reading or resolving the DID Doc of a repo DID can done locally or remotely. The algorithm is:

1. Isolate the `repo` component of the DID and find its corresponding URI, branch, and path.

If the mapping for the relevant repo is cached, and there is no unusual reason to believe a repo URI has changed, use cached data. Otherwise, fetch this specification document from HEAD of the master branch of the Aries RFCs repo, find the Resolvable Repos table by looking for the anchor `#resolvable-repos`, and find the row where the token is defined.

2. If you have a local clone of the repo, and it is using the branch required by the mapping for the resolvable repo, and if your clone is acceptably up-to-date, you can do resolution locally. Compose a local __resolution URI__ by combining the filesystem path for the local clone, the `path` and `filename` components of the DID, and the extension `.diddoc`. Goto step 5.

3. If you want to do remote resolution, convert the repo's URI and branch into a __browse root URI__ -- the URI at which source code for that branch of the repo can be browsed via HTTPS as a file hierarchy. For example, github repo URIs in the form:

    https://github.com/<user>/<repo>

... become browse root URIs when transformed to:

    https://raw.githubusercontent.com/<user>/<repo>/<branch>

4. Compose a remote __resolution URI__ for the DID doc by combining the browse root URI, the `path` and `filename` components of the DID, and the extension `.diddoc`.

4. Fetch the document at the resolution URI, using local file I/O or HTTPS, as appropriate.

Different versions of this document can be fetched, using commit identifiers from the repository. History is likewise accessible.

### Update

Changing a DID Doc is as simple as committing an update to the DID doc in its associated repo.

### Delete (Deactivate)

Deleting or deactivating a DID requires a commit that removes the associated DID Doc from the HEAD of the associated repo. The DID retains a historic footprint in commit logs, but is deemed unusable or retired from the moment it disappears from the repo's current snapshot.

## Security Considerations

The trust, ownership, control, and decentralization properties of Aries DIDs exactly matches those properties in the management of the resolvable repo that hosts their DID docs.

## Privacy Considerations

This method is not intended to provide personal privacy. It is for use by public communities.

All DIDs using this method are discoverable by reading the table of resolvable repos from this specification, and then walking each repo to discover their full inventory of DID docs.