@keytrace/runner 0.0.3

package/src/fetchers/activitypub.ts

@@ -0,0 +1,53 @@
+import { DEFAULT_TIMEOUT } from "../constants.js";
+
+export interface ActivityPubActor {
+  id: string;
+  type: string;
+  preferredUsername?: string;
+  name?: string;
+  summary?: string;
+  attachment?: Array<{
+    type: string;
+    name?: string;
+    value?: string;
+  }>;
+  attributedTo?: string;
+}
+
+export interface ActivityPubFetchOptions {
+  timeout?: number;
+}
+
+/**
+ * Fetch an ActivityPub actor document
+ */
+export async function fetchActor(uri: string, options: ActivityPubFetchOptions = {}): Promise<ActivityPubActor> {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await globalThis.fetch(uri, {
+      headers: {
+        Accept: 'application/activity+json, application/ld+json; profile="https://www.w3.org/ns/activitystreams"',
+        "User-Agent": "keytrace-runner/1.0",
+      },
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return (await response.json()) as ActivityPubActor;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * Fetch data from an ActivityPub URL (alias for http fetch with AP headers)
+ */
+export async function fetch(uri: string, options: ActivityPubFetchOptions = {}): Promise<unknown> {
+  return fetchActor(uri, options);
+}

package/src/fetchers/dns.ts

@@ -0,0 +1,82 @@
+import { DEFAULT_TIMEOUT } from "../constants.js";
+
+export interface DnsFetchResult {
+  domain: string;
+  records: {
+    txt: string[];
+  };
+  /** Debug info showing which locations were checked */
+  _locations?: {
+    root: string[];
+    _keytrace: string[];
+  };
+}
+
+export interface DnsFetchOptions {
+  timeout?: number;
+}
+
+/**
+ * Check if the Node.js `dns` module is available.
+ * This is more reliable than checking `typeof window` since SSR frameworks
+ * and edge runtimes can have `window` defined or `dns` unavailable.
+ */
+async function hasDnsModule(): Promise<boolean> {
+  try {
+    await import("dns");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Fetch DNS TXT records for a domain.
+ * Checks both the root domain and _keytrace subdomain.
+ * Returns null in environments where DNS resolution is not available.
+ */
+export async function fetch(domain: string, options: DnsFetchOptions = {}): Promise<DnsFetchResult | null> {
+  if (!(await hasDnsModule())) {
+    console.debug("DNS fetching is not available in this environment");
+    return null;
+  }
+
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+
+  try {
+    const dns = await import("dns");
+    const dnsPromises = dns.promises;
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => reject(new Error("DNS timeout")), timeout);
+    });
+
+    // Check both root domain and _keytrace subdomain
+    const rootDomain = domain;
+    const keytraceDomain = `_keytrace.${domain}`;
+
+    const fetchPromise = Promise.all([
+      dnsPromises.resolveTxt(rootDomain).catch(() => []),
+      dnsPromises.resolveTxt(keytraceDomain).catch(() => []),
+    ]).then(([rootRecords, keytraceRecords]) => ({
+      domain,
+      records: {
+        txt: [...rootRecords.flat(), ...keytraceRecords.flat()],
+      },
+      // Include which locations were checked for debugging
+      _locations: {
+        root: rootRecords.flat(),
+        _keytrace: keytraceRecords.flat(),
+      },
+    }));
+
+    return await Promise.race([fetchPromise, timeoutPromise]);
+  } catch (error) {
+    if (error instanceof Error && error.message === "DNS timeout") {
+      throw error;
+    }
+    // DNS lookup failed (NXDOMAIN, etc.)
+    console.debug(`DNS lookup failed for ${domain}: ${error instanceof Error ? error.message : "Unknown error"}`);
+    return null;
+  }
+}

package/src/fetchers/http.ts

@@ -0,0 +1,38 @@
+import { DEFAULT_TIMEOUT } from "../constants.js";
+
+export interface HttpFetchOptions {
+  format: "json" | "text";
+  headers?: Record<string, string>;
+  timeout?: number;
+}
+
+/**
+ * Fetch data from an HTTP/HTTPS URL
+ */
+export async function fetch(url: string, options: HttpFetchOptions): Promise<unknown> {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await globalThis.fetch(url, {
+      headers: {
+        "User-Agent": "keytrace-runner/1.0",
+        Accept: options.format === "json" ? "application/json" : "text/plain",
+        ...options.headers,
+      },
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    if (options.format === "json") {
+      return await response.json();
+    }
+    return await response.text();
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/fetchers/index.ts

@@ -0,0 +1,30 @@
+import * as http from "./http.js";
+import * as dns from "./dns.js";
+import * as activitypub from "./activitypub.js";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface Fetcher {
+  fetch: (uri: string, options?: any) => Promise<unknown>;
+}
+
+const fetchers: Record<string, Fetcher> = {
+  http,
+  dns,
+  activitypub,
+};
+
+/**
+ * Get a fetcher by name
+ */
+export function get(name: string): Fetcher | undefined {
+  return fetchers[name];
+}
+
+/**
+ * Get all available fetchers
+ */
+export function getAll(): Record<string, Fetcher> {
+  return { ...fetchers };
+}
+
+export { http, dns, activitypub };

package/src/index.ts

@@ -0,0 +1,57 @@
+// Core runner
+export { runRecipe } from "./runner.js";
+
+// Types
+export type {
+  Recipe,
+  RecipeParam,
+  RecipeInstructions,
+  RecipeVerification,
+  VerificationStep,
+  ClaimContext,
+  VerificationResult,
+  StepResult,
+  RunnerConfig,
+  FetchFn,
+  ClaimVerificationResult,
+  ProfileData,
+  ClaimData,
+  VerifyOptions,
+  IdentityMetadata,
+  ProofDetails,
+  ProofTargetResult,
+} from "./types.js";
+export { ClaimStatus } from "./types.js";
+
+// Template interpolation
+export { interpolate } from "./interpolate.js";
+
+// Expect matchers
+export { checkExpect } from "./expect.js";
+
+// Individual actions
+export { httpGet } from "./actions/http-get.js";
+export { jsonPath } from "./actions/json-path.js";
+export { cssSelect } from "./actions/css-select.js";
+export { regexMatch } from "./actions/regex-match.js";
+export { dnsTxt } from "./actions/dns-txt.js";
+
+// Built-in recipes
+export { githubGistRecipe } from "./recipes/github-gist.js";
+export { dnsTxtRecipe } from "./recipes/dns-txt.js";
+
+// Claim & Profile (from runner)
+export { createClaim, matchClaim, verifyClaim, isClaimAmbiguous, getMatchedProvider, isValidDid } from "./claim.js";
+export type { ClaimState } from "./claim.js";
+export { fetchProfile, resolvePds, verifyAllClaims, getProfileSummary, getClaimsByStatus } from "./profile.js";
+export type { FetchedProfile } from "./profile.js";
+
+// Constants
+export { COLLECTION_NSID, DEFAULT_TIMEOUT, PUBLIC_API_URL, PLC_DIRECTORY_URL } from "./constants.js";
+
+// Service providers
+export * as serviceProviders from "./serviceProviders/index.js";
+export type { ServiceProvider, ServiceProviderMatch, ServiceProviderUI, ProofTarget, ProofRequest, ProcessedURI } from "./serviceProviders/types.js";
+
+// Fetchers
+export * as fetchers from "./fetchers/index.js";

package/src/interpolate.ts

@@ -0,0 +1,20 @@
+import type { ClaimContext } from "./types.js";
+
+/**
+ * Interpolate {variable} placeholders in a template string using claim context.
+ *
+ * Replaces:
+ *   {claimId} - from context.claimId
+ *   {did}     - from context.did
+ *   {handle}  - from context.handle
+ *   {anyKey}  - from context.params[anyKey]
+ */
+export function interpolate(template: string, context: ClaimContext): string {
+  return template.replace(/\{([^}]+)\}/g, (_match, key: string) => {
+    if (key === "claimId") return context.claimId;
+    if (key === "did") return context.did;
+    if (key === "handle") return context.handle;
+    if (key in context.params) return context.params[key];
+    return `{${key}}`;
+  });
+}

package/src/profile.ts

@@ -0,0 +1,229 @@
+import { AtpAgent } from "@atproto/api";
+import { createClaim, verifyClaim, type ClaimState } from "./claim.js";
+import { ClaimStatus } from "./types.js";
+import { COLLECTION_NSID, PUBLIC_API_URL, PLC_DIRECTORY_URL } from "./constants.js";
+import type { ProfileData, ClaimData, VerifyOptions, IdentityMetadata } from "./types.js";
+
+/**
+ * DID document service entry
+ */
+interface DidService {
+  id: string;
+  type: string;
+  serviceEndpoint: string;
+}
+
+/**
+ * DID document shape (subset of fields we need)
+ */
+interface DidDocument {
+  id: string;
+  service?: DidService[];
+}
+
+/**
+ * A fetched profile with resolved claims
+ */
+export interface FetchedProfile extends ProfileData {
+  claims: ClaimData[];
+  claimInstances: ClaimState[];
+}
+
+/**
+ * Resolve the PDS endpoint from a DID document.
+ * For did:plc, fetches from plc.directory.
+ * For did:web, fetches from the well-known DID path.
+ * Falls back to PUBLIC_API_URL on failure.
+ */
+export async function resolvePds(did: string): Promise<string> {
+  try {
+    let url: string;
+    if (did.startsWith("did:plc:")) {
+      url = `${PLC_DIRECTORY_URL}/${did}`;
+    } else if (did.startsWith("did:web:")) {
+      const host = did.replace("did:web:", "").replaceAll(":", "/");
+      url = `https://${host}/.well-known/did.json`;
+    } else {
+      return PUBLIC_API_URL;
+    }
+
+    const response = await globalThis.fetch(url, {
+      headers: { Accept: "application/json" },
+    });
+
+    if (!response.ok) {
+      return PUBLIC_API_URL;
+    }
+
+    const doc = (await response.json()) as DidDocument;
+    const pdsService = doc.service?.find((s) => s.id === "#atproto_pds" || s.type === "AtprotoPersonalDataServer");
+
+    return pdsService?.serviceEndpoint ?? PUBLIC_API_URL;
+  } catch {
+    return PUBLIC_API_URL;
+  }
+}
+
+/**
+ * Parse an AT URI and extract the rkey (record key).
+ * AT URIs have the format: at://did/collection/rkey
+ */
+function parseAtUriRkey(atUri: string): string {
+  const match = atUri.match(/^at:\/\/[^/]+\/[^/]+\/(.+)$/);
+  return match?.[1] ?? "";
+}
+
+/**
+ * Internal: fetch profile data using an already-configured agent
+ */
+async function fetchWithAgent(agent: AtpAgent, did: string): Promise<FetchedProfile> {
+  // Fetch Bluesky profile for display info via public API (not PDS)
+  // The PDS doesn't serve app.bsky.actor.getProfile - only the AppView does
+  let bskyProfile: { handle: string; displayName?: string; avatar?: string } | null = null;
+  try {
+    const publicAgent = new AtpAgent({ service: PUBLIC_API_URL });
+    const profileRes = await publicAgent.getProfile({ actor: did });
+    bskyProfile = {
+      handle: profileRes.data.handle,
+      displayName: profileRes.data.displayName,
+      avatar: profileRes.data.avatar,
+    };
+  } catch (err: unknown) {
+    // Profile fetch is optional - user may not have a Bluesky profile
+    // 404 is expected; log other errors at debug level
+    if (err instanceof Error && !err.message.includes("404")) {
+      console.debug(`Failed to fetch profile for ${did}: ${err.message}`);
+    }
+  }
+
+  // List all claim records with cursor-based pagination
+  const claims: ClaimData[] = [];
+  try {
+    let cursor: string | undefined;
+    do {
+      const records = await agent.com.atproto.repo.listRecords({
+        repo: did,
+        collection: COLLECTION_NSID,
+        limit: 100,
+        cursor,
+      });
+
+      for (const record of records.data.records) {
+        const value = record.value as {
+          claimUri?: string;
+          type?: string;
+          comment?: string;
+          createdAt?: string;
+          identity?: IdentityMetadata;
+        };
+        if (value.claimUri) {
+          claims.push({
+            uri: value.claimUri,
+            did,
+            type: value.type,
+            comment: value.comment,
+            createdAt: value.createdAt ?? new Date().toISOString(),
+            rkey: parseAtUriRkey(record.uri),
+            identity: value.identity,
+          });
+        }
+      }
+
+      cursor = records.data.cursor;
+    } while (cursor);
+  } catch (err: unknown) {
+    // 404 means no records yet; log other errors
+    if (err instanceof Error && !err.message.includes("404")) {
+      console.debug(`Failed to list claim records for ${did}: ${err.message}`);
+    }
+  }
+
+  return {
+    did,
+    handle: bskyProfile?.handle ?? did,
+    displayName: bskyProfile?.displayName,
+    avatar: bskyProfile?.avatar,
+    claims,
+    claimInstances: claims.map((c) => createClaim(c.uri, did)),
+  };
+}
+
+/**
+ * Fetch a profile from ATProto by DID or handle
+ */
+export async function fetchProfile(didOrHandle: string, serviceUrl?: string): Promise<FetchedProfile> {
+  // Resolve PDS from DID document unless an explicit serviceUrl was provided
+  let resolvedServiceUrl: string;
+  let did = didOrHandle;
+
+  if (serviceUrl) {
+    resolvedServiceUrl = serviceUrl;
+  } else if (didOrHandle.startsWith("did:")) {
+    resolvedServiceUrl = await resolvePds(didOrHandle);
+  } else {
+    // Handle - we need to resolve via the public API first, then resolve PDS
+    resolvedServiceUrl = PUBLIC_API_URL;
+  }
+
+  const agent = new AtpAgent({ service: resolvedServiceUrl });
+
+  // Resolve handle to DID if needed
+  if (!didOrHandle.startsWith("did:")) {
+    const resolved = await agent.resolveHandle({ handle: didOrHandle });
+    did = resolved.data.did;
+
+    // Now that we have the DID, resolve the actual PDS if no explicit serviceUrl
+    if (!serviceUrl) {
+      const pdsUrl = await resolvePds(did);
+      if (pdsUrl !== resolvedServiceUrl) {
+        resolvedServiceUrl = pdsUrl;
+        // Re-create agent pointed at the user's actual PDS
+        const pdsAgent = new AtpAgent({ service: pdsUrl });
+        return fetchWithAgent(pdsAgent, did);
+      }
+    }
+  }
+
+  return fetchWithAgent(agent, did);
+}
+
+/**
+ * Verify all claims in a profile
+ */
+export async function verifyAllClaims(profile: FetchedProfile, opts?: VerifyOptions): Promise<void> {
+  await Promise.all(profile.claimInstances.map((claim) => verifyClaim(claim, opts)));
+}
+
+/**
+ * Get verification summary for a profile
+ */
+export function getProfileSummary(profile: FetchedProfile): {
+  total: number;
+  verified: number;
+  failed: number;
+  pending: number;
+} {
+  const claims = profile.claimInstances;
+  return {
+    total: claims.length,
+    verified: claims.filter((c) => c.status === ClaimStatus.VERIFIED).length,
+    failed: claims.filter((c) => c.status === ClaimStatus.FAILED || c.status === ClaimStatus.ERROR).length,
+    pending: claims.filter((c) => c.status === ClaimStatus.INIT || c.status === ClaimStatus.MATCHED).length,
+  };
+}
+
+/**
+ * Get claims grouped by status
+ */
+export function getClaimsByStatus(profile: FetchedProfile): {
+  verified: ClaimState[];
+  failed: ClaimState[];
+  pending: ClaimState[];
+} {
+  const claims = profile.claimInstances;
+  return {
+    verified: claims.filter((c) => c.status === ClaimStatus.VERIFIED),
+    failed: claims.filter((c) => c.status === ClaimStatus.FAILED || c.status === ClaimStatus.ERROR),
+    pending: claims.filter((c) => c.status === ClaimStatus.INIT || c.status === ClaimStatus.MATCHED),
+  };
+}

package/src/recipes/dns-txt.ts

@@ -0,0 +1,46 @@
+import type { Recipe } from "../types.js";
+
+/**
+ * Built-in recipe: Domain verification via DNS TXT record.
+ *
+ * The user adds a TXT record to their domain containing their DID,
+ * then provides the domain name for verification.
+ */
+export const dnsTxtRecipe: Recipe = {
+  $type: "dev.keytrace.recipe",
+  type: "dns",
+  version: 1,
+  displayName: "Domain (via DNS TXT)",
+  params: [
+    {
+      key: "domain",
+      label: "Domain name",
+      type: "domain",
+      placeholder: "example.com",
+      pattern: "^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?)+$",
+    },
+  ],
+  instructions: {
+    steps: [
+      "Log into your domain's DNS management panel",
+      "Add a new TXT record to the root domain (or _keytrace subdomain)",
+      "Set the value to the verification text below",
+      "Wait for DNS propagation (may take a few minutes)",
+    ],
+    proofTemplate: "keytrace-verification={did}",
+    proofLocation: "DNS TXT record on your domain",
+  },
+  verification: {
+    steps: [
+      {
+        action: "dns-txt",
+        url: "{domain}",
+      },
+      {
+        action: "regex-match",
+        pattern: "keytrace-verification=({did})",
+        expect: "equals:{did}",
+      },
+    ],
+  },
+};

package/src/recipes/github-gist.ts

@@ -0,0 +1,53 @@
+import type { Recipe } from "../types.js";
+
+/**
+ * Built-in recipe: GitHub Account verification via public Gist.
+ *
+ * The user creates a public gist named keytrace.json containing
+ * their claim ID and DID, then provides the gist URL for verification.
+ */
+export const githubGistRecipe: Recipe = {
+  $type: "dev.keytrace.recipe",
+  type: "github-gist",
+  version: 1,
+  displayName: "GitHub Account (via Gist)",
+  params: [
+    {
+      key: "gistUrl",
+      label: "Gist URL",
+      type: "url",
+      placeholder: "https://gist.github.com/octocat/abc123...",
+      pattern: "^https://gist\\.github\\.com/([^/]+)/([a-f0-9]+)$",
+      extractFrom: "^https://gist\\.github\\.com/([^/]+)/",
+    },
+  ],
+  instructions: {
+    steps: [
+      "Go to https://gist.github.com",
+      "Create a new public gist",
+      "Name the file `keytrace.json`",
+      "Paste the verification content below into the file",
+      "Save the gist and paste the URL below",
+    ],
+    proofTemplate: '{\n  "keytrace": "{claimId}",\n  "did": "{did}"\n}',
+    proofLocation: "Public gist with keytrace.json",
+  },
+  verification: {
+    steps: [
+      {
+        action: "http-get",
+        url: "{gistUrl}/raw/keytrace.json",
+      },
+      {
+        action: "json-path",
+        selector: "$.keytrace",
+        expect: "equals:{claimId}",
+      },
+      {
+        action: "json-path",
+        selector: "$.did",
+        expect: "equals:{did}",
+      },
+    ],
+  },
+};

package/src/recipes/index.ts

@@ -0,0 +1,2 @@
+export { githubGistRecipe } from "./github-gist.js";
+export { dnsTxtRecipe } from "./dns-txt.js";