@keytrace/runner 0.0.3

package/dist/types.d.ts

@@ -0,0 +1,165 @@
+/**
+ * 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 declare 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * Claim status enum
+ */
+export var ClaimStatus;
+(function (ClaimStatus) {
+    ClaimStatus["INIT"] = "init";
+    ClaimStatus["MATCHED"] = "matched";
+    ClaimStatus["VERIFIED"] = "verified";
+    ClaimStatus["FAILED"] = "failed";
+    ClaimStatus["ERROR"] = "error";
+})(ClaimStatus || (ClaimStatus = {}));
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAyFA;;GAEG;AACH,MAAM,CAAN,IAAY,WAMX;AAND,WAAY,WAAW;IACrB,4BAAa,CAAA;IACb,kCAAmB,CAAA;IACnB,oCAAqB,CAAA;IACrB,gCAAiB,CAAA;IACjB,8BAAe,CAAA;AACjB,CAAC,EANW,WAAW,KAAX,WAAW,QAMtB"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@keytrace/runner",
+  "version": "0.0.3",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo 'lint not configured'"
+  },
+  "dependencies": {
+    "@atproto/api": "^0.14.0",
+    "cheerio": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "oxfmt": "^0.27.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/actions/css-select.ts

@@ -0,0 +1,14 @@
+import * as cheerio from "cheerio";
+
+/**
+ * Parse HTML and extract text content using a CSS selector.
+ * Uses cheerio for server-side HTML parsing.
+ */
+export function cssSelect(html: string, selector: string): string {
+  const $ = cheerio.load(html);
+  const elements = $(selector);
+  if (elements.length === 0) {
+    throw new Error(`No elements matched selector: "${selector}"`);
+  }
+  return elements.first().text().trim();
+}

package/src/actions/dns-txt.ts

@@ -0,0 +1,16 @@
+/**
+ * Perform a DNS TXT record lookup for a domain.
+ * Node only - throws a descriptive error in browser environments.
+ */
+export async function dnsTxt(domain: string): Promise<string[]> {
+  let dns: typeof import("node:dns/promises");
+  try {
+    dns = await import("node:dns/promises");
+  } catch {
+    throw new Error("DNS TXT lookups are not available in the browser. " + "Use the server-side proxy endpoint (POST /api/proxy/dns) instead.");
+  }
+
+  const records = await dns.resolveTxt(domain);
+  // resolveTxt returns string[][] - flatten to string[]
+  return records.map((chunks) => chunks.join(""));
+}

package/src/actions/http-get.ts

@@ -0,0 +1,19 @@
+import type { FetchFn } from "../types.js";
+
+/**
+ * Fetch a URL using the injected fetch function and return the response body as text.
+ */
+export async function httpGet(url: string, fetchFn: FetchFn, timeout?: number): Promise<string> {
+  const controller = new AbortController();
+  const timeoutId = timeout ? setTimeout(() => controller.abort(), timeout) : undefined;
+
+  try {
+    const response = await fetchFn(url, { signal: controller.signal });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    return await response.text();
+  } finally {
+    if (timeoutId !== undefined) clearTimeout(timeoutId);
+  }
+}

package/src/actions/index.ts

@@ -0,0 +1,5 @@
+export { httpGet } from "./http-get.js";
+export { jsonPath } from "./json-path.js";
+export { cssSelect } from "./css-select.js";
+export { regexMatch } from "./regex-match.js";
+export { dnsTxt } from "./dns-txt.js";

package/src/actions/json-path.ts

@@ -0,0 +1,29 @@
+/**
+ * Extract data from a JSON string (or parsed object) using a simple dot-notation path.
+ *
+ * Supports paths like:
+ *   "$.keytrace"      -> obj.keytrace
+ *   "$.data.name"     -> obj.data.name
+ *   "$.items[0].id"   -> obj.items[0].id
+ *
+ * The leading "$." is optional.
+ */
+export function jsonPath(data: string | object, selector: string): unknown {
+  const obj = typeof data === "string" ? JSON.parse(data) : data;
+
+  // Strip leading $. if present
+  const path = selector.startsWith("$.") ? selector.slice(2) : selector;
+
+  // Split on dots and bracket notation
+  const segments = path.split(/\.|\[(\d+)\]/).filter((s) => s !== "" && s !== undefined);
+
+  let current: unknown = obj;
+  for (const segment of segments) {
+    if (current == null || typeof current !== "object") {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+
+  return current;
+}

package/src/actions/regex-match.ts

@@ -0,0 +1,13 @@
+/**
+ * Match content against a regex pattern.
+ * Returns the first capture group if present, otherwise the full match.
+ */
+export function regexMatch(content: string, pattern: string): string {
+  const regex = new RegExp(pattern);
+  const match = content.match(regex);
+  if (!match) {
+    throw new Error(`Pattern "${pattern}" did not match content`);
+  }
+  // Return first capture group if available, otherwise the full match
+  return match[1] ?? match[0];
+}

package/src/claim.ts

@@ -0,0 +1,293 @@
+import { ClaimStatus } from "./types.js";
+import { DEFAULT_TIMEOUT } from "./constants.js";
+import { matchUri, type ServiceProviderMatch, type ProofRequest, type ProofTarget } from "./serviceProviders/index.js";
+import * as fetchers from "./fetchers/index.js";
+import type { VerifyOptions, ClaimVerificationResult, IdentityMetadata, ProofDetails, ProofTargetResult } from "./types.js";
+
+// did:plc identifiers are base32-encoded, lowercase
+const DID_PLC_RE = /^did:plc:[a-z2-7]{24}$/;
+// did:web uses a domain name (with optional port and path segments encoded as colons)
+const DID_WEB_RE = /^did:web:[a-zA-Z0-9._:%-]+$/;
+
+/**
+ * Validate a DID string. Accepts did:plc and did:web formats.
+ */
+export function isValidDid(did: string): boolean {
+  return DID_PLC_RE.test(did) || DID_WEB_RE.test(did);
+}
+
+/**
+ * A single identity claim linking a DID to an external account
+ */
+export interface ClaimState {
+  uri: string;
+  did: string;
+  status: ClaimStatus;
+  matches: ServiceProviderMatch[];
+  errors: string[];
+}
+
+/**
+ * Create a new claim state
+ */
+export function createClaim(uri: string, did: string): ClaimState {
+  if (!isValidDid(did)) {
+    throw new Error(`Invalid DID format: ${did}`);
+  }
+  return {
+    uri,
+    did,
+    status: ClaimStatus.INIT,
+    matches: [],
+    errors: [],
+  };
+}
+
+/**
+ * Match the claim URI against known service providers
+ */
+export function matchClaim(claim: ClaimState): void {
+  claim.matches = matchUri(claim.uri);
+  claim.status = claim.matches.length > 0 ? ClaimStatus.MATCHED : ClaimStatus.ERROR;
+
+  if (claim.matches.length === 0) {
+    claim.errors.push(`No service provider matched URI: ${claim.uri}`);
+  }
+}
+
+/**
+ * Check if the claim is ambiguous (matches multiple providers)
+ */
+export function isClaimAmbiguous(claim: ClaimState): boolean {
+  return claim.matches.length > 1 || (claim.matches.length === 1 && claim.matches[0].isAmbiguous);
+}
+
+/**
+ * Get the matched service provider (first unambiguous match, or first match)
+ */
+export function getMatchedProvider(claim: ClaimState): ServiceProviderMatch | undefined {
+  return claim.matches[0];
+}
+
+/**
+ * Verify the claim by fetching proof and checking for DID
+ */
+export async function verifyClaim(claim: ClaimState, opts: VerifyOptions = {}): Promise<ClaimVerificationResult> {
+  if (claim.status === ClaimStatus.INIT) {
+    matchClaim(claim);
+  }
+
+  if (claim.matches.length === 0) {
+    return {
+      status: ClaimStatus.ERROR,
+      errors: claim.errors,
+      timestamp: new Date(),
+    };
+  }
+
+  // Track proof details for the response
+  let proofDetails: ProofDetails | undefined;
+
+  // Try each matched provider until one succeeds
+  for (const match of claim.matches) {
+    try {
+      const config = match.provider.processURI(claim.uri, match.match);
+      const proofData = await fetchProof(config.proof.request, opts);
+
+      // Build proof details
+      const patterns = generateProofPatterns(claim.did);
+      const targetResults = checkProofWithDetails(proofData, config.proof.target, patterns);
+
+      proofDetails = {
+        fetchUrl: config.proof.request.uri,
+        fetcher: config.proof.request.fetcher,
+        content: truncateContent(proofData),
+        targets: targetResults,
+        patterns,
+      };
+
+      const verified = targetResults.some((t) => t.matched);
+
+      if (verified) {
+        claim.status = ClaimStatus.VERIFIED;
+
+        // Extract identity metadata via postprocess if available
+        let identity: IdentityMetadata | undefined;
+        if (match.provider.postprocess) {
+          const metadata = match.provider.postprocess(proofData, match.match);
+          identity = {
+            subject: metadata.subject,
+            avatarUrl: metadata.avatarUrl,
+            profileUrl: metadata.profileUrl,
+            displayName: metadata.displayName,
+          };
+        }
+
+        return {
+          status: ClaimStatus.VERIFIED,
+          errors: [],
+          timestamp: new Date(),
+          identity,
+          proofDetails,
+        };
+      }
+    } catch (err) {
+      claim.errors.push(`${match.provider.id}: ${err instanceof Error ? err.message : "Unknown error"}`);
+    }
+
+    // Stop on unambiguous match
+    if (!match.isAmbiguous) break;
+  }
+
+  claim.status = ClaimStatus.FAILED;
+  return {
+    status: ClaimStatus.FAILED,
+    errors: claim.errors,
+    timestamp: new Date(),
+    proofDetails,
+  };
+}
+
+async function fetchProof(request: ProofRequest, opts: VerifyOptions): Promise<unknown> {
+  const fetcher = fetchers.get(request.fetcher);
+  if (!fetcher) {
+    throw new Error(`Unknown fetcher: ${request.fetcher}`);
+  }
+  console.log(`[runner] Fetching proof: ${request.fetcher} ${request.uri} (format: ${request.format})`);
+  const data = await fetcher.fetch(request.uri, {
+    format: request.format,
+    timeout: opts.timeout ?? DEFAULT_TIMEOUT,
+    headers: request.options?.headers,
+  });
+  const fileKeys = data && typeof data === "object" && "files" in data ? Object.keys((data as Record<string, unknown>).files as object) : [];
+  console.log(`[runner] Fetched proof, files: ${JSON.stringify(fileKeys)}`);
+  return data;
+}
+
+function checkProofWithDetails(data: unknown, targets: ProofTarget[], patterns: string[]): ProofTargetResult[] {
+  console.log(`[runner] Checking proof, patterns: ${JSON.stringify(patterns)}`);
+  console.log(`[runner] Proof targets: ${JSON.stringify(targets.map((t) => t.path.join(".")))}`);
+
+  const results: ProofTargetResult[] = [];
+
+  for (const target of targets) {
+    const values = extractValues(data, target.path);
+    console.log(`[runner] Target ${target.path.join(".")}: found ${values.length} value(s)${values.length > 0 ? `: ${JSON.stringify(values.map((v) => v.slice(0, 100)))}` : ""}`);
+
+    let matched = false;
+    for (const value of values) {
+      if (matchesPattern(value, patterns, target.relation)) {
+        console.log(`[runner] Match found at ${target.path.join(".")} (relation: ${target.relation})`);
+        matched = true;
+        break;
+      }
+    }
+
+    results.push({
+      path: target.path,
+      relation: target.relation,
+      valuesFound: values.map((v) => v.slice(0, 500)), // Truncate long values
+      matched,
+    });
+  }
+
+  if (!results.some((r) => r.matched)) {
+    console.log(`[runner] No match found in any target`);
+  }
+
+  return results;
+}
+
+function truncateContent(data: unknown): string {
+  const MAX_LENGTH = 2000;
+  let content: string;
+
+  if (data === null || data === undefined) {
+    return "(no content returned)";
+  }
+
+  if (typeof data === "string") {
+    content = data;
+  } else {
+    try {
+      content = JSON.stringify(data, null, 2);
+    } catch {
+      content = String(data);
+    }
+  }
+
+  if (content.length > MAX_LENGTH) {
+    return content.slice(0, MAX_LENGTH) + "\n... (truncated)";
+  }
+  return content;
+}
+
+function generateProofPatterns(did: string): string[] {
+  const patterns = [did];
+
+  if (did.startsWith("did:plc:")) {
+    patterns.push(did.replace("did:plc:", ""));
+  }
+
+  return patterns;
+}
+
+function extractValues(data: unknown, path: string[]): string[] {
+  const results: string[] = [];
+  extractValuesRecursive(data, path, 0, results);
+  return results;
+}
+
+function extractValuesRecursive(data: unknown, path: string[], index: number, results: string[]): void {
+  if (data === null || data === undefined) return;
+
+  if (index >= path.length) {
+    if (typeof data === "string") {
+      results.push(data);
+    } else if (Array.isArray(data)) {
+      for (const item of data) {
+        if (typeof item === "string") {
+          results.push(item);
+        }
+      }
+    }
+    return;
+  }
+
+  const key = path[index];
+
+  if (key === "*") {
+    if (Array.isArray(data)) {
+      // Wildcard for arrays: iterate all items
+      for (const item of data) {
+        extractValuesRecursive(item, path, index + 1, results);
+      }
+    } else if (typeof data === "object" && data !== null) {
+      // Wildcard for objects: iterate all values
+      const record = data as Record<string, unknown>;
+      for (const value of Object.values(record)) {
+        extractValuesRecursive(value, path, index + 1, results);
+      }
+    }
+  } else if (typeof data === "object" && data !== null) {
+    const record = data as Record<string, unknown>;
+    extractValuesRecursive(record[key], path, index + 1, results);
+  }
+}
+
+function matchesPattern(value: string, patterns: string[], relation: "contains" | "equals" | "startsWith"): boolean {
+  for (const pattern of patterns) {
+    switch (relation) {
+      case "contains":
+        if (value.includes(pattern)) return true;
+        break;
+      case "equals":
+        if (value === pattern) return true;
+        break;
+      case "startsWith":
+        if (value.startsWith(pattern)) return true;
+        break;
+    }
+  }
+  return false;
+}

package/src/constants.ts

@@ -0,0 +1,19 @@
+/**
+ * The ATProto collection NSID for identity claims
+ */
+export const COLLECTION_NSID = "dev.keytrace.claim";
+
+/**
+ * Default timeout for fetcher operations in milliseconds
+ */
+export const DEFAULT_TIMEOUT = 5000;
+
+/**
+ * PLC directory URL for resolving did:plc DIDs
+ */
+export const PLC_DIRECTORY_URL = "https://plc.directory";
+
+/**
+ * Fallback public ATProto API URL (used only when PDS resolution fails)
+ */
+export const PUBLIC_API_URL = "https://public.api.bsky.app";

package/src/expect.ts

@@ -0,0 +1,36 @@
+/**
+ * Parse an expect string and compare against a value.
+ *
+ * Supported formats:
+ *   "equals:{value}"   - exact string match
+ *   "contains:{value}" - substring match
+ */
+export function checkExpect(expectStr: string, actual: unknown): { pass: boolean; message: string } {
+  const colonIdx = expectStr.indexOf(":");
+  if (colonIdx === -1) {
+    return {
+      pass: false,
+      message: `Invalid expect format: "${expectStr}" (expected "type:value")`,
+    };
+  }
+
+  const type = expectStr.slice(0, colonIdx);
+  const expected = expectStr.slice(colonIdx + 1);
+  const actualStr = String(actual ?? "");
+
+  switch (type) {
+    case "equals":
+      return actualStr === expected ? { pass: true, message: `Value equals "${expected}"` } : { pass: false, message: `Expected "${expected}" but got "${actualStr}"` };
+
+    case "contains":
+      return actualStr.includes(expected)
+        ? { pass: true, message: `Value contains "${expected}"` }
+        : {
+            pass: false,
+            message: `Expected value to contain "${expected}" but got "${actualStr}"`,
+          };
+
+    default:
+      return { pass: false, message: `Unknown expect type: "${type}"` };
+  }
+}