Suite of AT Protocol TypeScript libraries built on web standards
identity documentation
+89
-20
+14
-6
AGENTS.md
+14
-6
AGENTS.md
···
1
1
# Agent Guidelines for ATP Monorepo
2
2
3
3
## Build & Test Commands
4
+
4
5
- Run all tests: `deno test -P`
5
6
- Run single test file: `deno test -P path/to/file_test.ts`
6
7
- Run specific test: `deno test -P --filter "test name" path/to/file_test.ts`
···
9
10
- Check code: `deno check`
10
11
11
12
## Code Style
13
+
12
14
- **NO COMMENTS** unless explicitly requested
13
-
- Use JSDoc only for exported types/functions with `@prop`, `@param`, `@returns` tags
14
-
- Test files: `*_test.ts` pattern (e.g., `car_test.ts`), use Deno.test(), imports from `@std/assert`
15
-
- Types: Explicit types for function parameters/returns, prefer `interface` over `type` for objects
16
-
- Error handling: Use custom error classes extending base errors, include `ErrorOptions` with `cause`
17
-
- Imports: Use JSR/npm imports from deno.json, absolute imports (e.g., `@atp/crypto`, `@std/assert`)
18
-
- Naming: camelCase for vars/functions, PascalCase for classes/types, UPPER_CASE for constants
15
+
- Use JSDoc only for exported types/functions with `@prop`, `@param`, `@returns`
16
+
tags
17
+
- Test files: `*_test.ts` pattern (e.g., `car_test.ts`), use Deno.test(),
18
+
imports from `@std/assert`
19
+
- Types: Explicit types for function parameters/returns, prefer `interface` over
20
+
`type` for objects
21
+
- Error handling: Use custom error classes extending base errors, include
22
+
`ErrorOptions` with `cause`
23
+
- Imports: Use JSR/npm imports from deno.json, absolute imports (e.g.,
24
+
`@atp/crypto`, `@std/assert`)
25
+
- Naming: camelCase for vars/functions, PascalCase for classes/types, UPPER_CASE
26
+
for constants
19
27
- Exports: Use `export` directly, re-export from `mod.ts` for public API
20
28
- Async: Prefer async/await over promises, use AsyncGenerator for streams
21
29
- Formatting: 2 spaces indent, semicolons, trailing commas, 80 char soft limit
+40
-13
README.md
+40
-13
README.md
···
6
6
7
7
## Overview
8
8
9
-
This monorepo provides modular, standards-based TypeScript implementations of core AT Protocol components, based on the @atproto NPM packages.
9
+
This monorepo provides modular, standards-based TypeScript implementations of
10
+
core AT Protocol components, based on the @atproto NPM packages.
10
11
11
-
Each package is designed to work across JavaScript runtimes (Deno, Node.js, Bun, Cloudflare Workers) and can be used independently or together.
12
+
Each package is designed to work across JavaScript runtimes (Deno, Node.js, Bun,
13
+
Cloudflare Workers) and can be used independently or together.
12
14
13
15
## Packages
14
16
15
17
### [@atp/xrpc-server](./xrpc-server)
16
-
Hono-based XRPC server implementation with lexicon validation, authentication, rate limiting, and WebSocket streaming support. Works across JavaScript runtimes with comprehensive error handling and type safety.
18
+
19
+
Hono-based XRPC server implementation with lexicon validation, authentication,
20
+
rate limiting, and WebSocket streaming support. Works across JavaScript runtimes
21
+
with comprehensive error handling and type safety.
17
22
18
23
### [@atp/xrpc](./xrpc)
19
-
XRPC client library for calling AT Protocol services with lexicon schema validation.
20
24
25
+
XRPC client library for calling AT Protocol services with lexicon schema
26
+
validation.
21
27
22
28
### [@atp/sync](./sync)
23
-
Tools for syncing data from AT Protocol, including firehose (relay) subscriptions with authentication and filtering.
29
+
30
+
Tools for syncing data from AT Protocol, including firehose (relay)
31
+
subscriptions with authentication and filtering.
24
32
25
33
### [@atp/lex-cli](./lex-cli)
26
-
Command-line tool for generating documentation, servers, and clients from AT Protocol lexicon files.
34
+
35
+
Command-line tool for generating documentation, servers, and clients from AT
36
+
Protocol lexicon files.
27
37
28
38
### [@atp/crypto](./crypto)
29
-
Cryptographic primitives for AT Protocol supporting P-256 and K-256 (secp256k1) elliptic curves. Includes key generation, signing, verification, DID key serialization, and hashing utilities.
39
+
40
+
Cryptographic primitives for AT Protocol supporting P-256 and K-256 (secp256k1)
41
+
elliptic curves. Includes key generation, signing, verification, DID key
42
+
serialization, and hashing utilities.
30
43
31
44
### [@atp/identity](./identity)
32
-
Decentralized identity resolution for DIDs and handles. Resolves handles to DIDs, DIDs to DID documents, and provides caching and verification methods.
45
+
46
+
Decentralized identity resolution for DIDs and handles. Resolves handles to
47
+
DIDs, DIDs to DID documents, and provides caching and verification methods.
33
48
34
49
### [@atp/lexicon](./lexicon)
35
-
Validation utilities for AT Protocol lexicons. Validates records, XRPC parameters, inputs, and outputs against lexicon schemas.
50
+
51
+
Validation utilities for AT Protocol lexicons. Validates records, XRPC
52
+
parameters, inputs, and outputs against lexicon schemas.
36
53
37
54
### [@atp/repo](./repo)
38
-
Repository utilities including the Merkle Search Tree (MST) implementation. Handles signed key/value stores with CBOR-encoded data records, CAR files, and repo synchronization.
55
+
56
+
Repository utilities including the Merkle Search Tree (MST) implementation.
57
+
Handles signed key/value stores with CBOR-encoded data records, CAR files, and
58
+
repo synchronization.
39
59
40
60
### [@atp/syntax](./syntax)
41
-
Validation and parsing for AT Protocol string formats including DIDs, handles, NSIDs, AT URIs, TIDs, record keys, and datetimes.
61
+
62
+
Validation and parsing for AT Protocol string formats including DIDs, handles,
63
+
NSIDs, AT URIs, TIDs, record keys, and datetimes.
42
64
43
65
### [@atp/common](./common)
44
-
Shared utilities for server-oriented applications, including IPLD handling, streams, async helpers, obfuscation, retry logic, and TID generation.
66
+
67
+
Shared utilities for server-oriented applications, including IPLD handling,
68
+
streams, async helpers, obfuscation, retry logic, and TID generation.
45
69
46
70
### [@atp/bytes](./bytes)
47
-
Simple `Uint8Array` utilities including allocation, comparison, concatenation, string conversion (with multibase encoding support), and XOR operations. Based on the uint8arrays npm package.
71
+
72
+
Simple `Uint8Array` utilities including allocation, comparison, concatenation,
73
+
string conversion (with multibase encoding support), and XOR operations. Based
74
+
on the uint8arrays npm package.
48
75
49
76
## Installation
50
77
+5
identity/did/atproto-data.ts
+5
identity/did/atproto-data.ts
···
17
17
getPdsEndpoint as getPds,
18
18
};
19
19
20
+
/** Resolve a did to its `did:key` signing key, stringified */
20
21
export const getKey = (doc: DidDocument): string | undefined => {
21
22
const key = getSigningKey(doc);
22
23
if (!key) return undefined;
23
24
return getDidKeyFromMultibase(key);
24
25
};
25
26
27
+
/** Extract and format a `did:key` signing key from multibase */
26
28
export const getDidKeyFromMultibase = (key: {
27
29
type: string;
28
30
publicKeyMultibase: string;
···
40
42
return didKey;
41
43
};
42
44
45
+
/** Parse an atproto document ("did doc") to its atproto data*/
43
46
export const parseToAtprotoDocument = (
44
47
doc: DidDocument,
45
48
): Partial<AtprotoData> => {
···
52
55
};
53
56
};
54
57
58
+
/** Authenticate and verify the existance of an atproto Did Document */
55
59
export const ensureAtpDocument = (doc: DidDocument): AtprotoData => {
56
60
const { did, signingKey, handle, pds } = parseToAtprotoDocument(doc);
57
61
if (!did) {
···
69
73
return { did, signingKey, handle, pds };
70
74
};
71
75
76
+
/** Parse a `did:key` signing key from a Did Document */
72
77
export const ensureAtprotoKey = (doc: DidDocument): string => {
73
78
const { signingKey } = parseToAtprotoDocument(doc);
74
79
if (!signingKey) {
+4
identity/did/base-resolver.ts
+4
identity/did/base-resolver.ts
···
13
13
} from "../types.ts";
14
14
import * as atprotoData from "./atproto-data.ts";
15
15
16
+
/**
17
+
* Core functionality of did and handle resolution and validation,
18
+
* including cache handling.
19
+
*/
16
20
export abstract class BaseResolver {
17
21
constructor(public cache?: DidCache) {}
18
22
+4
identity/did/did-resolver.ts
+4
identity/did/did-resolver.ts
···
7
7
import { DidPlcResolver } from "./plc-resolver.ts";
8
8
import { DidWebResolver } from "./web-resolver.ts";
9
9
10
+
/**
11
+
* Did Resolver class combining DidPlcResolver and DidWebResolver,
12
+
* resolves did:plc and did:web dids with optional caching.
13
+
*/
10
14
export class DidResolver extends BaseResolver {
11
15
methods: Record<string, BaseResolver>;
12
16
+5
identity/did/memory-cache.ts
+5
identity/did/memory-cache.ts
···
1
1
import { DAY, HOUR } from "@atp/common";
2
2
import type { CacheResult, DidCache, DidDocument } from "../types.ts";
3
3
4
+
/**
5
+
* Value stored in cache for a DID doc
6
+
* @prop doc - DID Document object
7
+
* @prop updatedAt - Last time DID doc cached was updated
8
+
*/
4
9
type CacheVal = {
5
10
doc: DidDocument;
6
11
updatedAt: number;
+5
identity/did/plc-resolver.ts
+5
identity/did/plc-resolver.ts
···
2
2
import { BaseResolver } from "./base-resolver.ts";
3
3
import { timed } from "./util.ts";
4
4
5
+
/**
6
+
* Did resolver for resolving DIDs to atproto
7
+
* data, specifically `did:plc` DIDs.
8
+
* Can optionally cache resolved DID docs.
9
+
*/
5
10
export class DidPlcResolver extends BaseResolver {
6
11
constructor(
7
12
public plcUrl: string,
+1
identity/did/util.ts
+1
identity/did/util.ts
+5
identity/did/web-resolver.ts
+5
identity/did/web-resolver.ts
···
9
9
/** Path to the DID document on a `did:web` DID. */
10
10
export const DOC_PATH = "/.well-known/did.json";
11
11
12
+
/**
13
+
* Did resolver for resolving DIDs to atproto
14
+
* data, specifically `did:web` DIDs.
15
+
* Can optionally cache resolved DID docs.
16
+
*/
12
17
export class DidWebResolver extends BaseResolver {
13
18
constructor(
14
19
public timeout: number,
+2
-1
identity/id-resolver.ts
+2
-1
identity/id-resolver.ts
···
3
3
import type { IdentityResolverOpts } from "./types.ts";
4
4
5
5
/**
6
-
* Combines Handle and DID resolvers into a single identity resolver class.
6
+
* A single identity resolver class combining Did resolver and Handle resolver.
7
+
* Can resolve handles and dids to atproto data with an optional cache.
7
8
*/
8
9
export class IdResolver {
9
10
public handle: HandleResolver;