this repo has no description
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

Adds a readme for the keytrace runner

orta e7badfdc 1b3ba9d5

+139
+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 + ```