did:web

Tools for DID documents using the did:web method.

• What is did:web?
• Featuring
• Install
  • Global Install
  • Local Install
• Use
  • CLI
  • Library
• API Reference
  • did(options)
• Type Definitions
  • DidDocument
  • VerificationMethod
  • Service
  • DidResolutionResult
• Examples
  • Creating a DID document with multiple verification methods
• Develop
  • Build
  • Test
• Specifications
• More Things
• License
• Author

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

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

Run the global script:

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

Local Install

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

Run the locally installed script with npx:

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.

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:

did --host "example.com" --public-key "z6MkhaXg..." | jq

Library

Import and use in your application:

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:

{
  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 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

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

npm run build

Builds ESM output to ./dist with TypeScript declarations.

Test

npm test

Specifications

This library implements the following:

• W3C Decentralized Identifiers (DIDs) v1.0 — Core DID specification
• did:web Method Specification — The web DID method
• [Decentralized Identifier Resolution (DID Resolution)] (https://w3c-ccg.github.io/did-resolution/) — DID resolution

More Things

• W3C DID Working Group
• DID Specification Registries
• Bluesky AT Protocol - Used in service endpoint examples

License

SEE LICENSE IN LICENSE

Author

nichoth