# did:web
[![tests](https://img.shields.io/github/actions/workflow/status/substrate-system/did-web/nodejs.yml?style=flat-square)](https://github.com/substrate-system/did-web/actions/workflows/nodejs.yml)
[![types](https://img.shields.io/npm/types/@substrate-system/icons?style=flat-square)](README.md)
[![module](https://img.shields.io/badge/module-ESM%2FCJS-blue?style=flat-square)](README.md)
[![semantic versioning](https://img.shields.io/badge/semver-2.0.0-blue?logo=semver&style=flat-square)](https://semver.org/)
[![Common Changelog](https://nichoth.github.io/badge/common-changelog.svg)](./CHANGELOG.md)
[![install size](https://flat.badgen.net/packagephobia/install/@substrate-system/did-web)](https://packagephobia.com/result?p=@substrate-system/did-web)
[![gzip size](https://img.shields.io/bundlephobia/minzip/@substrate-system/did-web?style=flat-square)](https://bundlephobia.com/@substrate-system/name/did-web/route-event)
[![license](https://img.shields.io/badge/license-Big_Time-blue?style=flat-square)](LICENSE)

Tools for [DID documents](https://www.w3.org/TR/did-core/) using the
[did:web method](https://w3c-ccg.github.io/did-method-web/).

<details><summary><h2>Contents</h2></summary>

<!-- toc -->

- [What is `did:web`?](#what-is-didweb)
- [_Featuring_](#_featuring_)
- [Install](#install)
  * [Global Install](#global-install)
  * [Local Install](#local-install)
- [Use](#use)
  * [CLI](#cli)
  * [Library](#library)
- [API Reference](#api-reference)
  * [`did(options)`](#didoptions)
- [Type Definitions](#type-definitions)
  * [`DidDocument`](#diddocument)
  * [`VerificationMethod`](#verificationmethod)
  * [`Service`](#service)
  * [`DidResolutionResult`](#didresolutionresult)
- [Examples](#examples)
  * [Creating a DID document with multiple verification methods](#creating-a-did-document-with-multiple-verification-methods)
- [Develop](#develop)
  * [Build](#build)
  * [Test](#test)
- [Specifications](#specifications)
- [More Things](#more-things)
- [License](#license)
- [Author](#author)

<!-- tocstop -->

</details>


## What is `did:web`?

DIDs created with `did:web` are resolved by fetching a DID document from
a well-known HTTPS URL, so they are easy to host with standard web stuff.

A `did:web` identifier like `did:web:example.com` resolves to
`https://example.com/.well-known/did.json`.

## _Featuring_

* **CLI tool**: Generate DID documents from the command line
* **JS API**: Import and use in your Node.js or browser
  applications
* **Standards compliant**: Implements W3C DID Core and did:web method
  specifications

## Install

### Global Install

```sh
npm i -g @substrate-system/did-web
```

Run the global script:

```sh
did -h example.com -p "z6MkhaXg..."
```

### Local Install

```sh
npm i -D @substrate-system/did-web
```

Run the locally installed script with `npx`:

```sh
npx did -h example.com -p "z6MkhaXg..."
```

## Use

### CLI

Generate a DID document using the command line. The CLI outputs canonical
JSON format (single line with deterministic key ordering), suitable for
cryptographic signatures.

```sh
did --host "example.com" --public-key "z6MkhaXg..."
```

**Options:**
- `--host, -h`: The host domain (required)
- `--publicKey, -p`: The public key in multibase format (required)
- `--help, -?`: Show help


> [!TIP]
> For pretty-printed output, pipe through `jq`:
> ```sh
> did --host "example.com" --public-key "z6MkhaXg..." | jq
> ```

### Library

Import and use in your application:

```ts
import { did } from '@substrate-system/did-web'

const didDocument = did({
  host: 'example.com',
  publicKey: 'z6MkhaXgBZDvotDkL52...'
})

console.log(didDocument)
```

## API Reference

### `did(options)`

Creates a DID document with a verification method and Bluesky Feed
Generator service endpoint.

**Parameters:**

```ts
{
  host:string;       // The host domain (e.g., "example.com")
  aka?:string[];     // Alternative identifiers (optional)
  publicKey:string;  // The public key in multibase format
  service;           // services
}
```

**Returns:** `DidDocument`

## Type Definitions

### `DidDocument`

The main DID interface for the W3C DID Core specification.

**Properties:**
- `id:string` - The DID subject (required)
- `@context?:string|string[]|Record<string, unknown>` - JSON-LD
  context
- `alsoKnownAs?:string[]` - Alternative identifiers
- `controller?:string|string[]` - DID controller(s)
- `verificationMethod?:VerificationMethod[]` - Public keys and
  verification methods
- `authentication?:VerificationRelationship[]` - Keys for
  authentication
- `assertionMethod?:VerificationRelationship[]` - Keys for
  assertions/claims
- `keyAgreement?:VerificationRelationship[]` - Keys for key exchange
- `capabilityInvocation?:VerificationRelationship[]` - Keys for
  capability invocation
- `capabilityDelegation?:VerificationRelationship[]` - Keys for
  capability delegation
- `service?:Service[]` - Service endpoints

### `VerificationMethod`

Cryptographic public key information.

**Properties:**
- `id:string` - Verification method identifier
- `type:string` - Key type (e.g., "JsonWebKey2020", "Multikey")
- `controller:string` - DID that controls this key
- `publicKeyJwk?:JsonWebKey` - Public key in JWK format
- `publicKeyMultibase?:string` - Public key in multibase format
- `publicKeyBase58?:string` - Public key in base58 format
- `publicKeyHex?:string` - Public key in hex format

### `Service`

[Service endpoint](https://www.w3.org/TR/did-1.0/#dfn-service) for DID
subject interaction.

**Properties:**
- `id:string` - Service identifier
- `type:string|string[]` - Service type(s)
- `serviceEndpoint:string|string[]|Record<string, unknown>` -
  Service endpoint URL(s)

### `DidResolutionResult`

Result of DID resolution process.

**Properties:**
- `didResolutionMetadata:DidResolutionMetadata` - Resolution metadata
- `didDocument:DidDocument|null` - The resolved DID document
- `didDocumentMetadata:DidDocumentMetadata` - Document metadata

## Examples

### Creating a DID document with multiple verification methods


```ts
import type { DidDocument, did } from '@substrate-system/did-web'

// create a new DID record

const doc:DidDocument = did({
  host: 'abc123.com',
  aka: [
    "at://abc123.com",
    "https://github.com/abc123/"
  ],
  publicKey: 'z6MktJ6T...',  // < -- multikey format
})
// => {
//   '@context': [
//     'https://www.w3.org/ns/did/v1',
//     "https://w3id.org/security/multikey/v1"
//   ],
//   id: 'did:web:abc123.com',
//   verificationMethod: [
//     {
//       id: 'did:web:abc123.com#main-key',
//       type": "Multikey",
//       controller": "did:web:nichoth.com",
//       publicKeyMultibase": "z6MktJ6Tv1kuh4Dwybs5dcmvrXKkar5CkFFqrJPeL6wgMbKf"
//     },
//   authentication: ['did:web:abc123.com#main-key'],
//   assertionMethod: ['did:web:example.com#main-key']
// }
```

## Develop

### Build

```sh
npm run build
```

Builds ESM output to `./dist` with TypeScript declarations.

### Test

```sh
npm test
```

## Specifications

This library implements the following:

- [W3C Decentralized Identifiers (DIDs) v1.0](https://www.w3.org/TR/did-core/)
  &mdash; Core DID specification
- [did:web Method Specification](https://w3c-ccg.github.io/did-method-web/)
  &mdash; The web DID method
- [Decentralized Identifier Resolution (DID Resolution)]
  (https://w3c-ccg.github.io/did-resolution/) &mdash; DID resolution

## More Things

- [W3C DID Working Group](https://www.w3.org/2019/did-wg/)
- [DID Specification Registries](https://www.w3.org/TR/did-spec-registries/)
- [Bluesky AT Protocol](https://atproto.com/) - Used in service
  endpoint examples

## License

SEE LICENSE IN LICENSE

## Author

[nichoth](https://github.com/nichoth)