@keytrace/runner 0.0.3

package/src/serviceProviders/types.ts

@@ -0,0 +1,121 @@
+/**
+ * A match between a URI and a service provider
+ */
+export interface ServiceProviderMatch {
+  provider: ServiceProvider;
+  match: RegExpMatchArray;
+  isAmbiguous: boolean;
+}
+
+/**
+ * Where to look for proof in the fetched response
+ */
+export interface ProofTarget {
+  /** JSON path to search for proof (e.g., ['description'], ['files', '*', 'content']) */
+  path: string[];
+  /** How to match: 'contains', 'equals', 'startsWith' */
+  relation: "contains" | "equals" | "startsWith";
+  /** Format of data at path */
+  format: "text" | "uri" | "json";
+}
+
+/**
+ * How to fetch the proof
+ */
+export interface ProofRequest {
+  /** URL template with {placeholders} */
+  uri: string;
+  /** Fetcher to use: 'http', 'dns', 'activitypub' */
+  fetcher: string;
+  /** Expected response format */
+  format: "json" | "text";
+  /** Additional fetch options */
+  options?: {
+    headers?: Record<string, string>;
+  };
+}
+
+/**
+ * Result of processing a URI
+ */
+export interface ProcessedURI {
+  /** Profile display info */
+  profile: {
+    /** Display name for the identity (e.g., username, domain) */
+    display: string;
+    /** URL to the identity's profile page */
+    uri: string;
+  };
+  /** How to fetch and verify the proof */
+  proof: {
+    request: ProofRequest;
+    target: ProofTarget[];
+  };
+}
+
+/**
+ * UI configuration for the add claim wizard
+ */
+export interface ServiceProviderUI {
+  /** Short description for service picker (e.g., "Link via a public gist") */
+  description: string;
+  /** Lucide icon name (e.g., "github", "globe") */
+  icon: string;
+  /** Label for the claim URI input field */
+  inputLabel: string;
+  /** Placeholder text for the claim URI input */
+  inputPlaceholder: string;
+  /** Default value template for input. Supports {did}, {handle}, {slugHandle} placeholders */
+  inputDefaultTemplate?: string;
+  /** Step-by-step instructions (markdown supported) */
+  instructions: string[];
+  /** Template for proof content. Supports {did} and {handle} placeholders */
+  proofTemplate: string;
+}
+
+/**
+ * A service provider that can verify identity claims
+ */
+export interface ServiceProvider {
+  /** Unique identifier */
+  id: string;
+  /** Display name */
+  name: string;
+  /** Homepage URL */
+  homepage: string;
+
+  /** Regex to match claim URIs */
+  reUri: RegExp;
+
+  /** Whether matches are potentially ambiguous (could match multiple providers) */
+  isAmbiguous?: boolean;
+
+  /** UI configuration for the add claim wizard */
+  ui: ServiceProviderUI;
+
+  /** Process matched URI into verification config */
+  processURI(uri: string, match: RegExpMatchArray): ProcessedURI;
+
+  /** Optional post-processing after fetch to extract identity metadata */
+  postprocess?(
+    data: unknown,
+    match: RegExpMatchArray,
+  ): {
+    subject?: string;
+    avatarUrl?: string;
+    profileUrl?: string;
+    displayName?: string;
+  };
+
+  /** Generate proof text for user to add to their profile */
+  getProofText(did: string, handle?: string): string;
+
+  /** Human-readable instructions for where to place the proof */
+  getProofLocation?(match: RegExpMatchArray): string;
+
+  /** Test cases for validation */
+  tests: {
+    uri: string;
+    shouldMatch: boolean;
+  }[];
+}

package/src/types.ts

@@ -0,0 +1,181 @@
+/**
+ * Identity metadata extracted during verification
+ */
+export interface IdentityMetadata {
+  /** Display name / username */
+  subject?: string;
+  /** Avatar/profile image URL */
+  avatarUrl?: string;
+  /** Profile page URL */
+  profileUrl?: string;
+  /** Display name if different from subject */
+  displayName?: string;
+}
+
+/**
+ * Details about a single proof target check
+ */
+export interface ProofTargetResult {
+  path: string[];
+  relation: string;
+  valuesFound: string[];
+  matched: boolean;
+}
+
+/**
+ * Details about the proof fetching and matching process
+ */
+export interface ProofDetails {
+  /** The URL that was fetched */
+  fetchUrl: string;
+  /** The fetcher used (http, dns, etc.) */
+  fetcher: string;
+  /** Raw content that was fetched (truncated if large) */
+  content: string;
+  /** The proof targets that were checked */
+  targets: ProofTargetResult[];
+  /** The patterns used for matching (DID variations) */
+  patterns: string[];
+}
+
+/**
+ * Result of verifying a claim
+ */
+export interface ClaimVerificationResult {
+  status: ClaimStatus;
+  errors: string[];
+  timestamp: Date;
+  /** Identity metadata extracted from the proof source */
+  identity?: IdentityMetadata;
+  /** Details about the proof fetching and verification process */
+  proofDetails?: ProofDetails;
+}
+
+/**
+ * Profile data from ATProto
+ */
+export interface ProfileData {
+  did: string;
+  handle: string;
+  displayName?: string;
+  avatar?: string;
+  claims: ClaimData[];
+}
+
+/**
+ * Individual claim data from ATProto record
+ */
+export interface ClaimData {
+  uri: string;
+  did: string;
+  type?: string;
+  comment?: string;
+  createdAt: string;
+  rkey: string;
+  identity?: IdentityMetadata;
+}
+
+/**
+ * Options for verification operations
+ */
+export interface VerifyOptions {
+  /** Timeout for fetcher operations in ms */
+  timeout?: number;
+  /** Skip cache and force fresh verification */
+  skipCache?: boolean;
+  /** Proxy URL for browser-based DNS/HTTP requests */
+  proxyUrl?: string;
+}
+
+/**
+ * Claim status enum
+ */
+export enum ClaimStatus {
+  INIT = "init",
+  MATCHED = "matched",
+  VERIFIED = "verified",
+  FAILED = "failed",
+  ERROR = "error",
+}
+
+/** Injected fetch function - allows caller to provide proxy, auth, etc. */
+export type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
+
+/** Configuration for the recipe runner */
+export interface RunnerConfig {
+  /** Custom fetch function (defaults to global fetch) */
+  fetch?: FetchFn;
+  /** Request timeout in ms (default: 10000) */
+  timeout?: number;
+}
+
+/** Context for a claim verification attempt */
+export interface ClaimContext {
+  /** Unique claim ID for this verification attempt */
+  claimId: string;
+  /** User's ATProto DID */
+  did: string;
+  /** User's ATProto handle */
+  handle: string;
+  /** User-provided params from recipe (e.g., { gistUrl: "..." }) */
+  params: Record<string, string>;
+}
+
+/** Result of running a full recipe verification */
+export interface VerificationResult {
+  success: boolean;
+  steps: StepResult[];
+  /** Extracted subject from params (e.g., "github:octocat") */
+  subject?: string;
+  error?: string;
+}
+
+/** Result of a single verification step */
+export interface StepResult {
+  action: string;
+  success: boolean;
+  data?: unknown;
+  error?: string;
+}
+
+/** A recipe parameter definition */
+export interface RecipeParam {
+  key: string;
+  label: string;
+  type: "url" | "text" | "domain";
+  placeholder?: string;
+  pattern?: string;
+  extractFrom?: string;
+}
+
+/** User-facing instructions for how to set up a claim */
+export interface RecipeInstructions {
+  steps: string[];
+  proofTemplate?: string;
+  proofLocation?: string;
+}
+
+/** A single verification step in a recipe */
+export interface VerificationStep {
+  action: "http-get" | "json-path" | "css-select" | "regex-match" | "dns-txt";
+  url?: string;
+  selector?: string;
+  pattern?: string;
+  expect?: string;
+}
+
+/** Machine-readable verification definition */
+export interface RecipeVerification {
+  steps: VerificationStep[];
+}
+
+/** A claim verification recipe */
+export interface Recipe {
+  $type?: string;
+  type: string;
+  version: number;
+  displayName: string;
+  params?: RecipeParam[];
+  instructions: RecipeInstructions;
+  verification: RecipeVerification;
+}