@keytrace/runner 0.0.3

package/src/runner.ts

@@ -0,0 +1,116 @@
+import type { Recipe, ClaimContext, RunnerConfig, VerificationResult, StepResult, VerificationStep, FetchFn } from "./types.js";
+import { interpolate } from "./interpolate.js";
+import { checkExpect } from "./expect.js";
+import { httpGet } from "./actions/http-get.js";
+import { jsonPath } from "./actions/json-path.js";
+import { cssSelect } from "./actions/css-select.js";
+import { regexMatch } from "./actions/regex-match.js";
+import { dnsTxt } from "./actions/dns-txt.js";
+
+const DEFAULT_TIMEOUT = 10_000;
+
+/**
+ * Execute a recipe's verification steps against a claim context.
+ * Returns a full result with per-step details. Stops on first failure.
+ */
+export async function runRecipe(recipe: Recipe, context: ClaimContext, config?: RunnerConfig): Promise<VerificationResult> {
+  const fetchFn: FetchFn = config?.fetch ?? globalThis.fetch;
+  const timeout = config?.timeout ?? DEFAULT_TIMEOUT;
+  const steps: StepResult[] = [];
+
+  // Extract subject from params if a param defines extractFrom
+  let subject: string | undefined;
+  if (recipe.params) {
+    for (const param of recipe.params) {
+      if (param.extractFrom && context.params[param.key]) {
+        const regex = new RegExp(param.extractFrom);
+        const match = context.params[param.key].match(regex);
+        if (match?.[1]) {
+          subject = `${recipe.type.split("-")[0]}:${match[1]}`;
+        }
+      }
+    }
+  }
+
+  // Tracks the last "fetch" output (http-get, dns-txt) for extraction steps to use.
+  // Extraction steps (json-path, css-select, regex-match) always operate on the
+  // last fetch output, not on each other's output.
+  let lastFetchOutput: unknown = undefined;
+
+  for (const step of recipe.verification.steps) {
+    const isFetchAction = step.action === "http-get" || step.action === "dns-txt";
+    const result = await executeStep(step, context, lastFetchOutput, fetchFn, timeout);
+    steps.push(result);
+
+    if (!result.success) {
+      return { success: false, steps, subject, error: result.error };
+    }
+
+    if (isFetchAction) {
+      lastFetchOutput = result.data;
+    }
+  }
+
+  return { success: true, steps, subject };
+}
+
+async function executeStep(step: VerificationStep, context: ClaimContext, previousOutput: unknown, fetchFn: FetchFn, timeout: number): Promise<StepResult> {
+  try {
+    let data: unknown;
+
+    switch (step.action) {
+      case "http-get": {
+        const url = interpolate(step.url!, context);
+        data = await httpGet(url, fetchFn, timeout);
+        break;
+      }
+
+      case "json-path": {
+        const selector = interpolate(step.selector!, context);
+        const input = previousOutput ?? "";
+        data = jsonPath(input as string | object, selector);
+        break;
+      }
+
+      case "css-select": {
+        const selector = interpolate(step.selector!, context);
+        const input = previousOutput as string;
+        if (typeof input !== "string") {
+          throw new Error("css-select requires string input from a previous step");
+        }
+        data = cssSelect(input, selector);
+        break;
+      }
+
+      case "regex-match": {
+        const pattern = interpolate(step.pattern!, context);
+        const input = typeof previousOutput === "string" ? previousOutput : String(previousOutput ?? "");
+        data = regexMatch(input, pattern);
+        break;
+      }
+
+      case "dns-txt": {
+        const domain = step.url ? interpolate(step.url, context) : interpolate(step.pattern!, context);
+        data = await dnsTxt(domain);
+        break;
+      }
+
+      default:
+        throw new Error(`Unknown action: "${step.action}"`);
+    }
+
+    // Check expect if defined
+    if (step.expect) {
+      const expectStr = interpolate(step.expect, context);
+      const result = checkExpect(expectStr, data);
+      if (!result.pass) {
+        return { action: step.action, success: false, data, error: result.message };
+      }
+    }
+
+    return { action: step.action, success: true, data };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { action: step.action, success: false, error: message };
+  }
+}

package/src/serviceProviders/activitypub.ts

@@ -0,0 +1,84 @@
+import type { ServiceProvider } from "./types.js";
+
+/**
+ * ActivityPub (Mastodon/Fediverse) service provider
+ *
+ * Users prove ownership by adding their DID to their profile bio or fields.
+ * The claim URI is the profile URL (e.g., https://mastodon.social/@username)
+ */
+const activitypub: ServiceProvider = {
+  id: "activitypub",
+  name: "Mastodon",
+  homepage: "https://joinmastodon.org",
+
+  // Match Mastodon-style profile URLs: https://instance/@username
+  reUri: /^https:\/\/([^/]+)\/@([^/]+)\/?$/,
+
+  // Could match other ActivityPub software with same URL pattern
+  isAmbiguous: true,
+
+  ui: {
+    description: "Link your Mastodon or Fediverse account",
+    icon: "at-sign",
+    inputLabel: "Profile URL",
+    inputPlaceholder: "https://mastodon.social/@username",
+    instructions: [
+      "Go to your Mastodon instance and open **Edit profile**",
+      "Add your DID to your **bio** or create a new **profile metadata field**",
+      "For metadata fields, set the label to `keytrace` and paste your DID as the value",
+      "Save your profile changes",
+      "Paste your full profile URL below (e.g., `https://mastodon.social/@username`)",
+    ],
+    proofTemplate: "{did}",
+  },
+
+  processURI(uri, match) {
+    const [, domain, username] = match;
+
+    return {
+      profile: {
+        display: `@${username}@${domain}`,
+        uri,
+      },
+      proof: {
+        request: {
+          uri,
+          fetcher: "activitypub",
+          format: "json",
+        },
+        target: [
+          // Check profile bio/summary (HTML content)
+          { path: ["summary"], relation: "contains", format: "text" },
+          // Check profile fields (Mastodon-style verification fields)
+          { path: ["attachment", "*", "value"], relation: "contains", format: "text" },
+        ],
+      },
+    };
+  },
+
+  postprocess(data) {
+    const actor = data as { preferredUsername?: string; name?: string; icon?: { url?: string } };
+    return {
+      displayName: actor.name || actor.preferredUsername,
+      avatarUrl: actor.icon?.url,
+    };
+  },
+
+  getProofText(did) {
+    return did;
+  },
+
+  getProofLocation() {
+    return `Add to your profile bio or a profile metadata field`;
+  },
+
+  tests: [
+    { uri: "https://mastodon.social/@alice", shouldMatch: true },
+    { uri: "https://fosstodon.org/@bob/", shouldMatch: true },
+    { uri: "https://hachyderm.io/@user", shouldMatch: true },
+    { uri: "https://twitter.com/alice", shouldMatch: false },
+    { uri: "https://mastodon.social/alice", shouldMatch: false },
+  ],
+};
+
+export default activitypub;

package/src/serviceProviders/bsky.ts

@@ -0,0 +1,73 @@
+import type { ServiceProvider } from "./types.js";
+
+/**
+ * Bluesky service provider
+ *
+ * Users prove ownership of another Bluesky account by adding their DID to the profile bio.
+ * The claim URI is the bsky.app profile URL.
+ */
+const bsky: ServiceProvider = {
+  id: "bsky",
+  name: "Bluesky",
+  homepage: "https://bsky.app",
+
+  // Match Bluesky profile URLs: https://bsky.app/profile/handle or did
+  reUri: /^https:\/\/bsky\.app\/profile\/([^/]+)\/?$/,
+
+  isAmbiguous: false,
+
+  ui: {
+    description: "Link another Bluesky account",
+    icon: "cloud",
+    inputLabel: "Profile URL",
+    inputPlaceholder: "https://bsky.app/profile/username.bsky.social",
+    instructions: [
+      "Log into the Bluesky account you want to link",
+      "Go to **Settings** → **Edit Profile**",
+      "Add your DID to your **bio** (the verification DID, not this account's DID)",
+      "Save your profile changes",
+      "Paste the profile URL below",
+    ],
+    proofTemplate: "{did}",
+  },
+
+  processURI(uri, match) {
+    const [, handle] = match;
+
+    return {
+      profile: {
+        display: handle.startsWith("did:") ? handle : `@${handle}`,
+        uri,
+      },
+      proof: {
+        request: {
+          uri: `https://public.api.bsky.app/xrpc/app.bsky.actor.getProfile?actor=${encodeURIComponent(handle)}`,
+          fetcher: "http",
+          format: "json",
+        },
+        target: [
+          // Check profile description/bio
+          { path: ["description"], relation: "contains", format: "text" },
+        ],
+      },
+    };
+  },
+
+  getProofText(did) {
+    return did;
+  },
+
+  getProofLocation() {
+    return `Add to your profile bio`;
+  },
+
+  tests: [
+    { uri: "https://bsky.app/profile/alice.bsky.social", shouldMatch: true },
+    { uri: "https://bsky.app/profile/did:plc:abc123", shouldMatch: true },
+    { uri: "https://bsky.app/profile/alice.bsky.social/", shouldMatch: true },
+    { uri: "https://bsky.app/profile/alice/post/123", shouldMatch: false },
+    { uri: "https://bsky.social/profile/alice", shouldMatch: false },
+  ],
+};
+
+export default bsky;

package/src/serviceProviders/dns.ts

@@ -0,0 +1,75 @@
+import type { ServiceProvider } from "./types.js";
+
+/**
+ * DNS TXT record service provider
+ *
+ * Users prove domain ownership by adding a TXT record containing their DID.
+ * The claim URI format is: dns:example.com
+ */
+const dns: ServiceProvider = {
+  id: "dns",
+  name: "Domain",
+  homepage: "",
+
+  // Match dns:domain.tld URIs (must contain at least one dot)
+  reUri: /^dns:([a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?)+)$/,
+
+  isAmbiguous: false,
+
+  ui: {
+    description: "Link via DNS TXT record",
+    icon: "globe",
+    inputLabel: "Domain",
+    inputPlaceholder: "example.com",
+    instructions: [
+      "Open your domain's DNS settings (usually in your registrar or hosting provider)",
+      "Add a new **TXT record** at the root domain (or at `_keytrace.yourdomain.com`)",
+      "Set the record value to the verification content below",
+      "Save and wait for DNS propagation (may take a few minutes to an hour)",
+      "Enter your domain below and verify",
+    ],
+    proofTemplate: "keytrace-verification={did}",
+  },
+
+  processURI(uri, match) {
+    const [, domain] = match;
+
+    return {
+      profile: {
+        display: domain,
+        uri: `https://${domain}`,
+      },
+      proof: {
+        request: {
+          uri: domain,
+          fetcher: "dns",
+          format: "json",
+        },
+        target: [
+          // Look for DID in any TXT record
+          { path: ["records", "txt"], relation: "contains", format: "text" },
+        ],
+      },
+    };
+  },
+
+  getProofText(did) {
+    return `keytrace-verification=${did}`;
+  },
+
+  getProofLocation(match) {
+    const [, domain] = match;
+    return `Add a TXT record at the root of ${domain} (or at _keytrace.${domain})`;
+  },
+
+  tests: [
+    { uri: "dns:example.com", shouldMatch: true },
+    { uri: "dns:sub.example.com", shouldMatch: true },
+    { uri: "dns:a.b.c.example.com", shouldMatch: true },
+    { uri: "dns:example", shouldMatch: false },
+    { uri: "dns:-invalid.com", shouldMatch: false },
+    { uri: "https://example.com", shouldMatch: false },
+  ],
+};
+
+export default dns;

package/src/serviceProviders/github.ts

@@ -0,0 +1,112 @@
+import type { ServiceProvider } from "./types.js";
+
+/**
+ * GitHub Gist service provider
+ *
+ * Users prove ownership by creating a public gist containing their DID.
+ * The gist URL is used as the claim URI.
+ */
+const github: ServiceProvider = {
+  id: "github",
+  name: "GitHub",
+  homepage: "https://github.com",
+
+  // Match GitHub Gist URLs: https://gist.github.com/username/gistid
+  reUri: /^https:\/\/gist\.github\.com\/([^/]+)\/([a-f0-9]+)\/?$/,
+
+  isAmbiguous: false,
+
+  ui: {
+    description: "Link via a public gist",
+    icon: "github",
+    inputLabel: "Gist URL",
+    inputPlaceholder: "https://gist.github.com/username/abc123...",
+    instructions: [
+      "Go to [gist.github.com](https://gist.github.com) and create a new gist",
+      "Name the file `keytrace.json` (or `keytrace.md` or `proof.md`)",
+      "Paste the verification content below into the file",
+      "Make sure the gist is **public**, then save it",
+      "Copy the gist URL and paste it below",
+    ],
+    proofTemplate: '{\n  "did": "{did}"\n}',
+  },
+
+  processURI(uri, match) {
+    const [, username, gistId] = match;
+
+    return {
+      profile: {
+        display: `@${username}`,
+        uri: `https://github.com/${username}`,
+      },
+      proof: {
+        request: {
+          uri: `https://api.github.com/gists/${gistId}`,
+          fetcher: "http",
+          format: "json",
+          options: {
+            headers: {
+              Accept: "application/vnd.github.v3+json",
+            },
+          },
+        },
+        target: [
+          // Check keytrace.json file content
+          {
+            path: ["files", "keytrace.json", "content"],
+            relation: "contains",
+            format: "text",
+          },
+          // Check proof.md file content
+          {
+            path: ["files", "proof.md", "content"],
+            relation: "contains",
+            format: "text",
+          },
+          // Check keytrace.md file content
+          {
+            path: ["files", "keytrace.md", "content"],
+            relation: "contains",
+            format: "text",
+          },
+          // Check openpgp.md for backwards compatibility with Keyoxide
+          {
+            path: ["files", "openpgp.md", "content"],
+            relation: "contains",
+            format: "text",
+          },
+          // Check gist description
+          { path: ["description"], relation: "contains", format: "text" },
+        ],
+      },
+    };
+  },
+
+  postprocess(data, match) {
+    const [, username] = match;
+    const gist = data as { owner?: { avatar_url?: string; login?: string } };
+
+    return {
+      subject: gist.owner?.login ?? username,
+      avatarUrl: gist.owner?.avatar_url,
+      profileUrl: `https://github.com/${gist.owner?.login ?? username}`,
+    };
+  },
+
+  getProofText(did) {
+    return `Verifying my identity on keytrace: ${did}`;
+  },
+
+  getProofLocation() {
+    return `Create a public gist with a file named keytrace.json, keytrace.md, or proof.md containing the proof text`;
+  },
+
+  tests: [
+    { uri: "https://gist.github.com/alice/abc123def456", shouldMatch: true },
+    { uri: "https://gist.github.com/alice/abc123def456/", shouldMatch: true },
+    { uri: "https://github.com/alice", shouldMatch: false },
+    { uri: "https://gist.gitlab.com/alice/abc123", shouldMatch: false },
+  ],
+};
+
+export default github;

package/src/serviceProviders/index.ts

@@ -0,0 +1,65 @@
+import github from "./github.js";
+import dns from "./dns.js";
+import activitypub from "./activitypub.js";
+import bsky from "./bsky.js";
+import npm from "./npm.js";
+import type { ServiceProvider, ServiceProviderMatch } from "./types.js";
+
+export type { ServiceProvider, ServiceProviderMatch, ServiceProviderUI, ProofTarget, ProofRequest, ProcessedURI } from "./types.js";
+
+const providers: Record<string, ServiceProvider> = {
+  github,
+  dns,
+  activitypub,
+  bsky,
+  npm,
+};
+
+/**
+ * Get a service provider by ID
+ */
+export function getProvider(id: string): ServiceProvider | undefined {
+  return providers[id];
+}
+
+/**
+ * Get all registered service providers
+ */
+export function getAllProviders(): ServiceProvider[] {
+  return Object.values(providers);
+}
+
+/**
+ * Match a URI against all service providers
+ * Returns all matching providers, with unambiguous matches stopping the search
+ */
+export function matchUri(uri: string): ServiceProviderMatch[] {
+  const matches: ServiceProviderMatch[] = [];
+
+  for (const provider of Object.values(providers)) {
+    const match = uri.match(provider.reUri);
+    if (match) {
+      matches.push({
+        provider,
+        match,
+        isAmbiguous: provider.isAmbiguous ?? false,
+      });
+      // Stop on unambiguous match
+      if (!provider.isAmbiguous) {
+        break;
+      }
+    }
+  }
+
+  return matches;
+}
+
+/**
+ * Get the proof text a user should add to verify a claim
+ */
+export function getProofTextForProvider(providerId: string, did: string, handle?: string): string | undefined {
+  const provider = providers[providerId];
+  return provider?.getProofText(did, handle);
+}
+
+export { github, dns, activitypub, bsky, npm };

package/src/serviceProviders/npm.ts

@@ -0,0 +1,116 @@
+import type { ServiceProvider } from "./types.js";
+
+/**
+ * Slugify a handle for use in npm package names.
+ * Replaces dots with dashes since npm doesn't allow dots.
+ * e.g. "orta.io" -> "orta-io"
+ */
+function slugifyHandle(handle: string): string {
+  return handle.replace(/\./g, "-").toLowerCase();
+}
+
+/**
+ * npm service provider
+ *
+ * Users prove ownership by publishing an npm package named keytrace-[handle]
+ * containing their DID in the package.json keytrace field.
+ */
+const npm: ServiceProvider = {
+  id: "npm",
+  name: "npm",
+  homepage: "https://www.npmjs.com",
+
+  // Match npm package URLs: https://www.npmjs.com/package/keytrace-username
+  reUri: /^https:\/\/(?:www\.)?npmjs\.com\/package\/(keytrace-[a-z0-9_-]+)\/?$/i,
+
+  isAmbiguous: false,
+
+  ui: {
+    description: "Link via an npm package",
+    icon: "npm",
+    inputLabel: "npm Package URL",
+    inputPlaceholder: "https://www.npmjs.com/package/keytrace-yourhandle",
+    inputDefaultTemplate: "https://www.npmjs.com/package/keytrace-{slugHandle}",
+    instructions: [
+      "Create a new folder with a `package.json` containing the verification content below",
+      "Run `npm publish --access public` to publish",
+      "Paste the npm package URL below",
+    ],
+    proofTemplate: `{
+  "name": "keytrace-{slugHandle}",
+  "version": "0.0.1",
+  "keytrace": "{claimId}",
+  "did": "{did}"
+}`,
+  },
+
+  processURI(uri, match) {
+    const [, packageName] = match;
+    // Extract the handle from keytrace-handle
+    const handle = packageName.replace(/^keytrace-/i, "");
+
+    return {
+      profile: {
+        display: `~${handle}`,
+        uri: `https://www.npmjs.com/~${handle}`,
+      },
+      proof: {
+        request: {
+          // Use npm registry to get the packument with full metadata
+          uri: `https://registry.npmjs.org/${packageName}`,
+          fetcher: "http",
+          format: "json",
+        },
+        target: [
+          // Check for DID in the did field of any version
+          // The packument has versions as an object: { versions: { "0.0.1": { did: "did:...", keytrace: "..." } } }
+          {
+            path: ["versions", "*", "did"],
+            relation: "contains",
+            format: "text",
+          },
+        ],
+      },
+    };
+  },
+
+  postprocess(data, _match) {
+    const packument = data as {
+      maintainers?: Array<{ name: string; email?: string }>;
+      author?: { name?: string; email?: string } | string;
+    };
+
+    // Get the first maintainer's npm username
+    const maintainer = packument.maintainers?.[0];
+    const npmUsername = maintainer?.name;
+
+    return {
+      subject: npmUsername,
+      profileUrl: npmUsername ? `https://www.npmjs.com/~${npmUsername}` : undefined,
+    };
+  },
+
+  getProofText(did, handle) {
+    const slug = handle ? slugifyHandle(handle) : "[your-handle]";
+    return `{
+  "name": "keytrace-${slug}",
+  "version": "0.0.1",
+  "keytrace": "[claim-id]",
+  "did": "${did}"
+}`;
+  },
+
+  getProofLocation() {
+    return `Publish an npm package named keytrace-[your-handle] with your DID in the keytrace field of package.json`;
+  },
+
+  tests: [
+    { uri: "https://www.npmjs.com/package/keytrace-alice", shouldMatch: true },
+    { uri: "https://npmjs.com/package/keytrace-alice", shouldMatch: true },
+    { uri: "https://www.npmjs.com/package/keytrace-alice/", shouldMatch: true },
+    { uri: "https://www.npmjs.com/package/some-other-pkg", shouldMatch: false },
+    { uri: "https://www.npmjs.com/~alice", shouldMatch: false },
+  ],
+};
+
+export default npm;