@keytrace/runner

Core verification library for Keytrace identity claims. Matches claim URIs to service providers, fetches proofs, and verifies ownership.

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/claims to get a list of claims and verify they are real based on public key encryption.

This would allow you to do the HTTP and DNS requests necessary to make the initial proof.

Installation

npm install @keytrace/runner

Usage

Verify a Claim

import { createClaim, verifyClaim, ClaimStatus } from '@keytrace/runner';

// Create and verify a claim
const claim = createClaim('https://gist.github.com/octocat/abc123', 'did:plc:xyz789');
const result = await verifyClaim(claim);

if (result.status === ClaimStatus.VERIFIED) {
  console.log('Claim verified!');
  console.log('Identity:', result.identity);
} else {
  console.log('Verification failed:', result.errors);
}

Fetch a User's Profile and Claims

import { fetchProfile, verifyAllClaims, getProfileSummary } from '@keytrace/runner';

// Fetch profile and claims from ATProto
const profile = await fetchProfile('alice.bsky.social');

// Verify all claims
const verified = await verifyAllClaims(profile);

// Get summary
const summary = getProfileSummary(verified);
console.log(`${summary.verified}/${summary.total} claims verified`);

Match URIs to Service Providers

import { serviceProviders } from '@keytrace/runner';

const matches = serviceProviders.matchUri('https://gist.github.com/octocat/abc123');
// [{ provider: { id: 'github', name: 'GitHub', ... }, match: [...], isAmbiguous: false }]

const matches2 = serviceProviders.matchUri('dns:example.com');
// [{ provider: { id: 'dns', name: 'Domain', ... }, match: [...], isAmbiguous: false }]

Service Providers

Built-in providers for identity verification:

| Provider | URI Pattern | Proof Location | |----------|-------------|----------------| | GitHub | https://gist.github.com/user/id | Gist content | | DNS | dns:example.com | TXT record | | Mastodon | https://instance/@user | Profile bio/fields | | Bluesky | https://bsky.app/profile/handle | Profile bio | | npm | https://npmjs.com/package/keytrace-handle | package.json |

API

Claims

// Create a claim
createClaim(uri: string, did: string): ClaimState

// Match claim to service providers
matchClaim(claim: ClaimState): void

// Verify claim by fetching proof
verifyClaim(claim: ClaimState, options?: VerifyOptions): Promise<ClaimVerificationResult>

// Check if claim matches multiple providers
isClaimAmbiguous(claim: ClaimState): boolean

Profiles

// Fetch profile and claims from ATProto
fetchProfile(handleOrDid: string): Promise<FetchedProfile>

// Verify all claims in a profile
verifyAllClaims(profile: FetchedProfile): Promise<FetchedProfile>

// Get verification summary
getProfileSummary(profile: FetchedProfile): { total: number; verified: number; failed: number }

Service Providers

import { serviceProviders } from '@keytrace/runner';

// Match URI to providers
serviceProviders.matchUri(uri: string): ServiceProviderMatch[]

// Get all providers
serviceProviders.all: ServiceProvider[]

// Get provider by ID
serviceProviders.get(id: string): ServiceProvider | undefined

Claim Status

enum ClaimStatus {
  INIT = 'init',           // Created, not yet matched
  MATCHED = 'matched',     // URI matched to provider
  VERIFIED = 'verified',   // Proof verified successfully
  FAILED = 'failed',       // Proof verification failed
  ERROR = 'error',         // Error during verification
}

Verification Options

interface VerifyOptions {
  timeout?: number;        // Request timeout in ms (default: 10000)
  fetch?: typeof fetch;    // Custom fetch function
}