@atcute/identity

types, schemas, and utilities for working with AT Protocol identities.

npm install @atcute/identity

in AT Protocol, users are identified by DIDs (decentralized identifiers). this package provides tools for working with DIDs and DID documents - the documents that describe a user's identity, including their handle, PDS location, and cryptographic keys.

for resolving handles and DIDs (fetching their documents), see @atcute/identity-resolver.

usage

checking DID types

AT Protocol supports two DID methods: did:plc and did:web. use the type guards to check which method a DID uses:

import { isPlcDid, isWebDid, isAtprotoDid } from '@atcute/identity';

const did = 'did:plc:z72i7hdynmk6r22z27h6tvur';

if (isPlcDid(did)) {
    // did:plc identifier
    console.log('PLC DID');
}

if (isWebDid(did)) {
    // did:web identifier (general, includes custom paths)
    console.log('Web DID');
}

if (isAtprotoDid(did)) {
    // either did:plc or atproto-compatible did:web
    console.log('AT Protocol DID');
}

isAtprotoDid checks for DIDs that are valid in AT Protocol - this excludes did:web identifiers with custom paths, which atproto doesn't support.

extracting the DID method

import { extractDidMethod } from '@atcute/identity';

const method = extractDidMethod('did:plc:z72i7hdynmk6r22z27h6tvur');
// -> "plc"

working with did:web

convert a did:web identifier to its DID document URL:

import { webDidToDocumentUrl, normalizeWebDid } from '@atcute/identity';

// simple domain
const url = webDidToDocumentUrl('did:web:example.com');
// -> URL { href: "https://example.com/.well-known/did.json" }

// with path
const url2 = webDidToDocumentUrl('did:web:example.com:users:alice');
// -> URL { href: "https://example.com/users/alice/did.json" }

// normalize for comparison
const normalized = normalizeWebDid('did:web:EXAMPLE.COM');
// -> "did:web:example.com"

reading DID documents

once you have a DID document (from a resolver or API), extract information using the utility functions:

import {
    getPdsEndpoint,
    getAtprotoHandle,
    getAtprotoVerificationMaterial,
    getLabelerEndpoint,
} from '@atcute/identity';
import type { DidDocument } from '@atcute/identity';

const doc: DidDocument = {
    '@context': ['https://www.w3.org/ns/did/v1'],
    id: 'did:plc:z72i7hdynmk6r22z27h6tvur',
    alsoKnownAs: ['at://bsky.app'],
    verificationMethod: [
        {
            id: 'did:plc:z72i7hdynmk6r22z27h6tvur#atproto',
            type: 'Multikey',
            controller: 'did:plc:z72i7hdynmk6r22z27h6tvur',
            publicKeyMultibase: 'zDnaek...',
        },
    ],
    service: [
        {
            id: '#atproto_pds',
            type: 'AtprotoPersonalDataServer',
            serviceEndpoint: 'https://morel.us-east.host.bsky.network',
        },
    ],
};

// get the user's PDS URL
const pds = getPdsEndpoint(doc);
// -> "https://morel.us-east.host.bsky.network"

// get the user's handle
const handle = getAtprotoHandle(doc);
// -> "bsky.app"

// get the signing key material
const key = getAtprotoVerificationMaterial(doc);
// -> { type: "Multikey", publicKeyMultibase: "zDnaek..." }

service endpoint helpers

extract specific service endpoints from DID documents:

import {
    getPdsEndpoint,
    getLabelerEndpoint,
    getBlueskyChatEndpoint,
    getBlueskyFeedgenEndpoint,
    getBlueskyNotificationEndpoint,
    getAtprotoServiceEndpoint,
} from '@atcute/identity';

// standard helpers for common services
const pds = getPdsEndpoint(doc); // #atproto_pds
const labeler = getLabelerEndpoint(doc); // #atproto_labeler
const chat = getBlueskyChatEndpoint(doc); // #bsky_chat
const feedgen = getBlueskyFeedgenEndpoint(doc); // #bsky_fg
const notif = getBlueskyNotificationEndpoint(doc); // #bsky_notif

// or use the generic helper for custom services
const custom = getAtprotoServiceEndpoint(doc, {
    id: '#my_service',
    type: 'MyServiceType', // optional type filter
});

validating DID documents

use the validation schemas to check if a DID document is well-formed:

import { defs } from '@atcute/identity';
import * as v from 'valibot';

const result = v.safeParse(defs.didDocument, unknownData);
if (result.success) {
    // result.output is a validated DidDocument
    console.log(result.output.id);
} else {
    // validation failed
    console.error('invalid DID document', result.issues);
}

the schema validates:

• required fields (@context, id)
• DID string format
• verification method structure and key formats
• service endpoint URLs
• no duplicate entries in arrays

type definitions

the package exports TypeScript types for DID document structures:

import type { DidDocument, VerificationMethod, Service } from '@atcute/identity';

// DidDocument - the full DID document
// VerificationMethod - a verification method entry
// Service - a service endpoint entry