this repo has no description
Adds a readme for the keytrace runner
+139
+139
packages/runner/README.md
+139
packages/runner/README.md
···
1
+
# @keytrace/runner
2
+
3
+
Core verification library for Keytrace identity claims. Matches claim URIs to service providers, fetches proofs, and verifies ownership.
4
+
5
+
This library is still very work in progress, and not fully built out for folks who want to run the full verification proofing system. You can use @keytrace/verify to get a list of claims and verify they are real based on public key encryption.
6
+
7
+
This would allow you to do the HTTP and DNS requests necessary to make the initial proof.
8
+
9
+
## Installation
10
+
11
+
```bash
12
+
npm install @keytrace/runner
13
+
```
14
+
15
+
## Usage
16
+
17
+
### Verify a Claim
18
+
19
+
```typescript
20
+
import { createClaim, verifyClaim, ClaimStatus } from '@keytrace/runner';
21
+
22
+
// Create and verify a claim
23
+
const claim = createClaim('https://gist.github.com/octocat/abc123', 'did:plc:xyz789');
24
+
const result = await verifyClaim(claim);
25
+
26
+
if (result.status === ClaimStatus.VERIFIED) {
27
+
console.log('Claim verified!');
28
+
console.log('Identity:', result.identity);
29
+
} else {
30
+
console.log('Verification failed:', result.errors);
31
+
}
32
+
```
33
+
34
+
### Fetch a User's Profile and Claims
35
+
36
+
```typescript
37
+
import { fetchProfile, verifyAllClaims, getProfileSummary } from '@keytrace/runner';
38
+
39
+
// Fetch profile and claims from ATProto
40
+
const profile = await fetchProfile('alice.bsky.social');
41
+
42
+
// Verify all claims
43
+
const verified = await verifyAllClaims(profile);
44
+
45
+
// Get summary
46
+
const summary = getProfileSummary(verified);
47
+
console.log(`${summary.verified}/${summary.total} claims verified`);
48
+
```
49
+
50
+
### Match URIs to Service Providers
51
+
52
+
```typescript
53
+
import { serviceProviders } from '@keytrace/runner';
54
+
55
+
const matches = serviceProviders.matchUri('https://gist.github.com/octocat/abc123');
56
+
// [{ provider: { id: 'github', name: 'GitHub', ... }, match: [...], isAmbiguous: false }]
57
+
58
+
const matches2 = serviceProviders.matchUri('dns:example.com');
59
+
// [{ provider: { id: 'dns', name: 'Domain', ... }, match: [...], isAmbiguous: false }]
60
+
```
61
+
62
+
## Service Providers
63
+
64
+
Built-in providers for identity verification:
65
+
66
+
| Provider | URI Pattern | Proof Location |
67
+
|----------|-------------|----------------|
68
+
| GitHub | `https://gist.github.com/user/id` | Gist content |
69
+
| DNS | `dns:example.com` | TXT record |
70
+
| Mastodon | `https://instance/@user` | Profile bio/fields |
71
+
| Bluesky | `https://bsky.app/profile/handle` | Profile bio |
72
+
| npm | `https://npmjs.com/package/keytrace-handle` | package.json |
73
+
74
+
## API
75
+
76
+
### Claims
77
+
78
+
```typescript
79
+
// Create a claim
80
+
createClaim(uri: string, did: string): ClaimState
81
+
82
+
// Match claim to service providers
83
+
matchClaim(claim: ClaimState): void
84
+
85
+
// Verify claim by fetching proof
86
+
verifyClaim(claim: ClaimState, options?: VerifyOptions): Promise<ClaimVerificationResult>
87
+
88
+
// Check if claim matches multiple providers
89
+
isClaimAmbiguous(claim: ClaimState): boolean
90
+
```
91
+
92
+
### Profiles
93
+
94
+
```typescript
95
+
// Fetch profile and claims from ATProto
96
+
fetchProfile(handleOrDid: string): Promise<FetchedProfile>
97
+
98
+
// Verify all claims in a profile
99
+
verifyAllClaims(profile: FetchedProfile): Promise<FetchedProfile>
100
+
101
+
// Get verification summary
102
+
getProfileSummary(profile: FetchedProfile): { total: number; verified: number; failed: number }
103
+
```
104
+
105
+
### Service Providers
106
+
107
+
```typescript
108
+
import { serviceProviders } from '@keytrace/runner';
109
+
110
+
// Match URI to providers
111
+
serviceProviders.matchUri(uri: string): ServiceProviderMatch[]
112
+
113
+
// Get all providers
114
+
serviceProviders.all: ServiceProvider[]
115
+
116
+
// Get provider by ID
117
+
serviceProviders.get(id: string): ServiceProvider | undefined
118
+
```
119
+
120
+
## Claim Status
121
+
122
+
```typescript
123
+
enum ClaimStatus {
124
+
INIT = 'init', // Created, not yet matched
125
+
MATCHED = 'matched', // URI matched to provider
126
+
VERIFIED = 'verified', // Proof verified successfully
127
+
FAILED = 'failed', // Proof verification failed
128
+
ERROR = 'error', // Error during verification
129
+
}
130
+
```
131
+
132
+
## Verification Options
133
+
134
+
```typescript
135
+
interface VerifyOptions {
136
+
timeout?: number; // Request timeout in ms (default: 10000)
137
+
fetch?: typeof fetch; // Custom fetch function
138
+
}
139
+
```