Rename recipes to services

CLAUDE.md

···
 
 ## Project Overview
 
-Keytrace is an identity verification system for ATProto. Users link their decentralized identities (DIDs) to external accounts (GitHub, DNS, ActivityPub, Bluesky, npm, PGP, Tangled, Twitter, LinkedIn) by creating claims that are cryptographically verified and stored as ATProto records.
+Keytrace is an identity verification system for ATProto. Users link their decentralized identities (DIDs) to external accounts (GitHub, DNS, ActivityPub, Bluesky, npm, PGP, Tangled, Twitter, LinkedIn, Instagram) by creating claims that are cryptographically verified and stored as ATProto records.
 
 ## Workflow
 
···
 
 ### Monorepo Structure
 
-- **`packages/runner`** - Core verification library (`@keytrace/runner`). Recipe-based claim verification with service providers for GitHub, DNS, ActivityPub, Bluesky, npm, PGP, Tangled, Twitter, LinkedIn.
+- **`packages/runner`** - Core verification library (`@keytrace/runner`). Recipe-based claim verification with service providers for GitHub, DNS, ActivityPub, Bluesky, npm, PGP, Tangled, Twitter, LinkedIn, Instagram.
 - **`packages/claims`** - Client-side claim verification library (`@keytrace/claims`). ES256 signature verification, ATProto record fetching.
 - **`packages/lexicon`** - ATProto lexicon JSON schemas and generated TypeScript types. Lexicons: `dev.keytrace.claim`, `dev.keytrace.signature`, `dev.keytrace.serverPublicKey`, `dev.keytrace.statement`, `dev.keytrace.userPublicKey`, `dev.keytrace.recipe`, `dev.keytrace.profile`. Run `yarn codegen` in this package after editing lexicon JSON to regenerate `types/`.
 - **`apps/keytrace.dev`** - Nuxt 3 full-stack web application with OAuth, API, and SSR.

README.md

···
 # Keytrace
 
-Identity verification for ATProto. Link your decentralized identity (DID) to external accounts like GitHub, LinkedIn, DNS, and Mastodon with cryptographically signed attestations.
+Identity verification for ATProto. Link your decentralized identity (DID) to external accounts like GitHub, LinkedIn, Instagram, DNS, and Mastodon with cryptographically signed attestations.
 
 ## What is Keytrace?
 

apps/keytrace.dev/components/ui/ClaimCard.vue

···
       </a>
 
       <div class="flex items-center flex-wrap gap-x-3 gap-y-1 text-xs text-zinc-500">
-        <NuxtLink v-if="claim.serviceType" :to="`/recipes/${claim.serviceType}`" class="hover:text-zinc-300 transition-colors">
+        <NuxtLink v-if="claim.serviceType" :to="`/services/${claim.serviceType}`" class="hover:text-zinc-300 transition-colors">
           via {{ claim.recipeName || claim.serviceType }}
         </NuxtLink>
         <span v-else-if="claim.recipeName">via {{ claim.recipeName }}</span>

apps/keytrace.dev/layouts/default.vue

···
             </div>
             <span class="text-xs text-zinc-500">keytrace.dev</span>
           </div>
-          <NuxtLink to="/recipes" class="text-xs text-zinc-600 hover:text-zinc-400 transition-colors">
-            How it works
+          <NuxtLink to="/services" class="text-xs text-zinc-600 hover:text-zinc-400 transition-colors">
+            Services
           </NuxtLink>
           <NuxtLink to="/developers" class="text-xs text-zinc-600 hover:text-zinc-400 transition-colors">
             For Developers

apps/keytrace.dev/pages/recipes/[provider].vue apps/keytrace.dev/pages/services/[provider].vue

···
 <template>
   <div class="max-w-3xl mx-auto px-4 py-12">
     <!-- Back link -->
-    <NuxtLink to="/recipes" class="text-sm text-zinc-500 hover:text-zinc-300 mb-6 inline-flex items-center gap-1">
+    <NuxtLink to="/services" class="text-sm text-zinc-500 hover:text-zinc-300 mb-6 inline-flex items-center gap-1">
       <ArrowLeftIcon class="w-4 h-4" />
-      All recipes
+      All services
     </NuxtLink>
 
     <div v-if="pending" class="space-y-6 mt-6">
···
     </div>
 
     <div v-else-if="error" class="text-center py-12">
-      <p class="text-zinc-400">Recipe not found</p>
-      <NuxtLink to="/recipes" class="text-violet-400 hover:text-violet-300 mt-2 inline-block">
-        View all recipes
+      <p class="text-zinc-400">Service not found</p>
+      <NuxtLink to="/services" class="text-violet-400 hover:text-violet-300 mt-2 inline-block">
+        View all services
       </NuxtLink>
     </div>
 
···
 const route = useRoute();
 const providerId = computed(() => route.params.provider as string);
 
-const { data: recipe, pending, error } = await useFetch(`/api/recipes/${providerId.value}`);
+const { data: recipe, pending, error } = await useFetch(`/api/services/${providerId.value}`);
 
 const testUri = ref("");
 const testDid = ref("");

apps/keytrace.dev/pages/recipes/index.vue apps/keytrace.dev/pages/services/index.vue

···
       </p>
       <p class="text-zinc-400 text-md-start mt-4">
         All of the identity claims are public and can be independently verified by anyone using the same steps using an npm module or by re-running them in this website. Below are
-        our recipes for how we verify whether you have access to an identity:
+        the services we support for verifying your identity:
       </p>
     </div>
 
···
       </div>
     </div>
 
-    <div v-else-if="recipes" class="space-y-4">
+    <div v-else-if="services" class="space-y-4">
       <NuxtLink
-        v-for="recipe in recipes"
-        :key="recipe.id"
-        :to="`/recipes/${recipe.id}`"
+        v-for="service in services"
+        :key="service.id"
+        :to="`/services/${service.id}`"
         class="block bg-kt-card border border-zinc-800 rounded-lg p-5 hover:border-zinc-700 transition-colors group"
       >
         <div class="flex items-start justify-between">
-          <div>
-            <h2 class="text-lg font-semibold text-zinc-200 group-hover:text-violet-400 transition-colors">
-              {{ recipe.name }}
-            </h2>
-            <p class="text-sm text-zinc-500 mt-1">
-              {{ recipe.description }}
-            </p>
+          <div class="flex items-start gap-3">
+            <GithubIcon
+              v-if="service.id === 'github'"
+              class="w-6 h-6 mt-0.5 text-zinc-400"
+            />
+            <FileCodeIcon
+              v-else-if="service.id === 'tangled'"
+              class="w-6 h-6 mt-0.5 text-zinc-400"
+            />
+            <img
+              v-else-if="service.homepage"
+              :src="`https://www.google.com/s2/favicons?domain=${getDomain(service.homepage)}&sz=32`"
+              :alt="`${service.name} favicon`"
+              class="w-6 h-6 mt-0.5 rounded"
+            />
+            <div>
+              <h2 class="text-lg font-semibold text-zinc-200 group-hover:text-violet-400 transition-colors">
+                {{ service.name }}
+              </h2>
+              <p class="text-sm text-zinc-500 mt-1">
+                {{ service.description }}
+              </p>
+            </div>
           </div>
           <div class="flex items-center gap-2 text-zinc-500">
-            <span v-if="recipe.homepage" class="text-xs">{{ getDomain(recipe.homepage) }}</span>
+            <span v-if="service.homepage" class="text-xs">{{ getDomain(service.homepage) }}</span>
             <ArrowRightIcon class="w-4 h-4 group-hover:text-violet-400 transition-colors" />
           </div>
         </div>
···
     <div class="mt-12 bg-kt-card border border-zinc-800 rounded-lg p-6">
       <h2 class="text-sm font-semibold text-zinc-300 mb-3">How Verification Works</h2>
       <div class="text-sm text-zinc-400 space-y-3">
-        <p>Each Keytrace recipe defines a specific way to verify ownership of an external identity. The process is fully transparent and reproducible:</p>
+        <p>Each Keytrace service defines a specific way to verify ownership of an external identity. The process is fully transparent and reproducible:</p>
         <ol class="list-decimal list-inside space-y-2 text-zinc-500">
           <li>You create a proof at the external service (e.g., a GitHub gist, DNS TXT record)</li>
           <li>The proof contains your ATProto DID to link the identities</li>
···
 </template>
 
 <script setup lang="ts">
-import { ArrowRight as ArrowRightIcon } from "lucide-vue-next";
+import { ArrowRight as ArrowRightIcon, Github as GithubIcon, FileCode as FileCodeIcon } from "lucide-vue-next";
 
-const { data: recipes, pending } = await useFetch("/api/recipes");
+const { data: services, pending } = await useFetch("/api/services");
 
 function getDomain(url: string): string {
   try {

apps/keytrace.dev/server/api/recipes/[provider].get.ts apps/keytrace.dev/server/api/services/[provider].get.ts

···
 /**
- * GET /api/recipes/:provider
+ * GET /api/services/:provider
  *
- * Get verification recipe details for a service provider.
+ * Get verification details for a service provider.
  * Returns the provider info and verification steps.
  */
 

apps/keytrace.dev/server/api/recipes/index.get.ts

···
-/**
- * GET /api/recipes
- *
- * List all available service providers/recipes.
- */
-
-import { serviceProviders } from "@keytrace/runner";
-
-export default defineEventHandler(async () => {
-  const providers = serviceProviders.getAllProviders();
-
-  return providers.map((provider) => ({
-    id: provider.id,
-    name: provider.name,
-    description: provider.ui.description,
-    homepage: provider.homepage,
-    isAmbiguous: provider.isAmbiguous ?? false,
-  }));
-});

apps/keytrace.dev/server/api/services/index.get.ts

···
 /**
  * GET /api/services
  *
- * Get all available service providers with their UI configuration.
- * Used by the add claim wizard to display service options and instructions.
+ * List all available service providers.
  */
 
 import { serviceProviders } from "@keytrace/runner";
 
-export default defineEventHandler(() => {
+export default defineEventHandler(async () => {
   const providers = serviceProviders.getAllProviders();
 
   return providers.map((provider) => ({
     id: provider.id,
     name: provider.name,
+    description: provider.ui.description,
     homepage: provider.homepage,
-    ui: provider.ui,
+    isAmbiguous: provider.isAmbiguous ?? false,
   }));
 });

packages/runner/src/fetchers/http.ts

···
 import * as cheerio from "cheerio";
 
 export interface HttpFetchOptions {
-  format: "json" | "text" | "json-ld";
+  format: "json" | "text" | "json-ld" | "og-meta";
   headers?: Record<string, string>;
   timeout?: number;
 }
···
       } catch (err) {
         throw new Error(`Failed to parse JSON-LD: ${err instanceof Error ? err.message : 'Unknown error'}`);
       }
+    }
+
+    if (options.format === "og-meta") {
+      const html = await response.text();
+      const $ = cheerio.load(html);
+      const ogData: Record<string, string> = {};
+
+      // Extract all Open Graph meta tags
+      $('meta[property^="og:"]').each((_, elem) => {
+        const property = $(elem).attr('property');
+        const content = $(elem).attr('content');
+        if (property && content) {
+          // Convert og:title to title, og:description to description, etc.
+          const key = property.replace('og:', '');
+          ogData[key] = content;
+        }
+      });
+
+      if (Object.keys(ogData).length === 0) {
+        throw new Error('No Open Graph meta tags found in HTML');
+      }
+
+      return ogData;
     }
 
     return await response.text();

packages/runner/src/serviceProviders/index.ts

···
 import pgp from "./pgp.js";
 import twitter from "./twitter.js";
 import linkedin from "./linkedin.js";
+import instagram from "./instagram.js";
 import type { ServiceProvider, ServiceProviderMatch } from "./types.js";
 
 export type { ServiceProvider, ServiceProviderMatch, ServiceProviderUI, ExtraInput, ProofTarget, ProofRequest, ProcessedURI } from "./types.js";
···
   pgp,
   twitter,
   linkedin,
+  instagram,
 };
 
 /**
···
   return provider?.getProofText(did, handle);
 }
 
-export { github, dns, activitypub, bsky, npm, tangled, pgp, twitter, linkedin };
+export { github, dns, activitypub, bsky, npm, tangled, pgp, twitter, linkedin, instagram };

packages/runner/src/serviceProviders/instagram.ts

···
+import type { ServiceProvider } from "./types.js";
+
+/**
+ * Instagram service provider
+ *
+ * Users prove ownership of their Instagram account by posting a public post
+ * containing their DID. The post URL is used as the claim URI.
+ *
+ * Fetching uses the og-meta format to extract Open Graph meta tags from the
+ * Instagram post page HTML.
+ */
+const instagram: ServiceProvider = {
+  id: "instagram",
+  name: "Instagram",
+  homepage: "https://www.instagram.com",
+
+  // Match Instagram post URLs
+  // Format: https://www.instagram.com/p/{post-id}/
+  // Or: https://www.instagram.com/{username}/p/{post-id}/
+  reUri: /^https:\/\/www\.instagram\.com\/(?:([^/]+)\/)?p\/([A-Za-z0-9_-]+)\/?$/,
+
+  isAmbiguous: false,
+
+  ui: {
+    description: "Link via an Instagram post",
+    icon: "instagram",
+    inputLabel: "Instagram Post URL",
+    inputPlaceholder: "https://www.instagram.com/p/...",
+    instructions: [
+      "Post a new **public post** on Instagram",
+      "Paste the verification content below as the post caption",
+      "Make sure the post is **public** (not private or for close friends)",
+      "Copy the URL of the post (tap ... → Copy link)",
+      "Paste the post URL below",
+    ],
+    proofTemplate: "Linking my keytrace.dev - {did}",
+  },
+
+  processURI(uri, match) {
+    const [, username, postId] = match;
+
+    // Clean URL - remove query parameters and trailing slashes
+    const cleanUri = `https://www.instagram.com/p/${postId}/`;
+
+    return {
+      profile: {
+        display: username ? `@${username}` : postId,
+        uri: username ? `https://www.instagram.com/${username}/` : cleanUri,
+      },
+      proof: {
+        request: {
+          uri: cleanUri,
+          fetcher: "http",
+          format: "og-meta",
+          options: {
+            headers: {
+              "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
+            },
+          },
+        },
+        target: [
+          // Check og:title (format: "Author Name on Instagram: "post text"")
+          {
+            path: ["title"],
+            relation: "contains",
+            format: "text",
+          },
+          // Check og:description (format: "X likes, Y comments - username on date: "post text"")
+          {
+            path: ["description"],
+            relation: "contains",
+            format: "text",
+          },
+        ],
+      },
+    };
+  },
+
+  postprocess(data, match) {
+    const [, usernameFromUrl] = match;
+
+    type InstagramOgMeta = {
+      title?: string;
+      description?: string;
+      url?: string;
+      username?: string;
+      image?: string;
+    };
+
+    const ogData = data as InstagramOgMeta;
+
+    // Extract username from various sources
+    let username = usernameFromUrl || ogData.username;
+
+    // Try to extract from og:title (format: "Author Name on Instagram: ...")
+    if (!username && ogData.title) {
+      const titleMatch = ogData.title.match(/^([^:]+) on Instagram:/);
+      if (titleMatch) {
+        username = titleMatch[1];
+      }
+    }
+
+    // Try to extract from og:description (format: "... - username on ...")
+    if (!username && ogData.description) {
+      const descMatch = ogData.description.match(/- ([a-zA-Z0-9._]+) on /);
+      if (descMatch) {
+        username = descMatch[1];
+      }
+    }
+
+    // Try to extract from og:url
+    if (!username && ogData.url) {
+      const urlMatch = ogData.url.match(/instagram\.com\/([^/]+)\//);
+      if (urlMatch) {
+        username = urlMatch[1];
+      }
+    }
+
+    const displayName = ogData.title?.split(' on Instagram:')[0];
+    const avatarUrl = ogData.image;
+
+    return {
+      subject: username || "unknown",
+      avatarUrl,
+      profileUrl: username ? `https://www.instagram.com/${username}/` : undefined,
+      displayName,
+    };
+  },
+
+  getProofText(did) {
+    return `Linking my keytrace.dev - ${did}`;
+  },
+
+  getProofLocation() {
+    return `Post a public Instagram post containing your DID in the caption`;
+  },
+
+  tests: [
+    { uri: "https://www.instagram.com/p/DVS8Tm6DWzP/", shouldMatch: true },
+    { uri: "https://www.instagram.com/p/ABC123xyz/", shouldMatch: true },
+    { uri: "https://www.instagram.com/orta/p/DVS8Tm6DWzP/", shouldMatch: true },
+    { uri: "https://www.instagram.com/alice/p/ABC123/", shouldMatch: true },
+    // With trailing slash
+    { uri: "https://www.instagram.com/p/ABC123/", shouldMatch: true },
+    // Profile URLs should NOT match
+    { uri: "https://www.instagram.com/orta/", shouldMatch: false },
+    { uri: "https://www.instagram.com/alice", shouldMatch: false },
+    // Reel URLs should NOT match
+    { uri: "https://www.instagram.com/reel/ABC123/", shouldMatch: false },
+    // Stories should NOT match
+    { uri: "https://www.instagram.com/stories/alice/123/", shouldMatch: false },
+    // Wrong domain
+    { uri: "https://twitter.com/alice/status/123", shouldMatch: false },
+    { uri: "https://facebook.com/alice/posts/123", shouldMatch: false },
+  ],
+};
+
+export default instagram;

packages/runner/src/serviceProviders/types.ts

···
   /** Fetcher to use: 'http', 'dns', 'activitypub' */
   fetcher: string;
   /** Expected response format */
-  format: "json" | "text" | "json-ld";
+  format: "json" | "text" | "json-ld" | "og-meta";
   /** Additional fetch options */
   options?: {
     headers?: Record<string, string>;

packages/runner/tests/serviceProviders/instagram.test.ts

···
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import instagram from "../../src/serviceProviders/instagram.js";
+import { createClaim, verifyClaim } from "../../src/claim.js";
+import { ClaimStatus } from "../../src/types.js";
+
+describe("instagram service provider", () => {
+  describe("URI matching", () => {
+    for (const { uri, shouldMatch } of instagram.tests) {
+      it(`${shouldMatch ? "accepts" : "rejects"} ${uri}`, () => {
+        const match = uri.match(instagram.reUri);
+        expect(Boolean(match)).toBe(shouldMatch);
+      });
+    }
+  });
+
+  describe("processURI", () => {
+    it("extracts post ID from standard post URL", () => {
+      const uri = "https://www.instagram.com/p/DVS8Tm6DWzP/";
+      const match = uri.match(instagram.reUri)!;
+      const result = instagram.processURI(uri, match);
+
+      expect(result.profile.display).toBe("DVS8Tm6DWzP");
+      expect(result.proof.request.fetcher).toBe("http");
+      expect(result.proof.request.uri).toBe("https://www.instagram.com/p/DVS8Tm6DWzP/");
+      expect(result.proof.request.format).toBe("og-meta");
+      expect(result.proof.request.options?.headers?.["User-Agent"]).toContain("Mozilla");
+    });
+
+    it("extracts username and post ID from URL with username", () => {
+      const uri = "https://www.instagram.com/orta/p/DVS8Tm6DWzP/";
+      const match = uri.match(instagram.reUri)!;
+      const result = instagram.processURI(uri, match);
+
+      expect(result.profile.display).toBe("@orta");
+      expect(result.profile.uri).toBe("https://www.instagram.com/orta/");
+      expect(result.proof.request.uri).toBe("https://www.instagram.com/p/DVS8Tm6DWzP/");
+    });
+
+    it("sets proof targets to title and description", () => {
+      const uri = "https://www.instagram.com/p/ABC123/";
+      const match = uri.match(instagram.reUri)!;
+      const result = instagram.processURI(uri, match);
+
+      expect(result.proof.target).toHaveLength(2);
+      expect(result.proof.target[0].path).toEqual(["title"]);
+      expect(result.proof.target[0].relation).toBe("contains");
+      expect(result.proof.target[1].path).toEqual(["description"]);
+    });
+  });
+
+  describe("postprocess", () => {
+    it("extracts username and display name from Open Graph data", () => {
+      const uri = "https://www.instagram.com/orta/p/DVS8Tm6DWzP/";
+      const match = uri.match(instagram.reUri)!;
+
+      const ogData = {
+        type: "article",
+        site_name: "Instagram",
+        title: "Orta Therox on Instagram: \"Linking my keytrace.dev - did:plc:test123\"",
+        description: "0 likes, 0 comments - orta on February 28, 2026: \"Linking my keytrace.dev - did:plc:test123\"",
+        url: "https://www.instagram.com/orta/p/DVS8Tm6DWzP/",
+        image: "https://scontent.cdninstagram.com/example.jpg",
+        username: "orta",
+      };
+
+      const result = instagram.postprocess!(ogData, match);
+
+      expect(result.subject).toBe("orta");
+      expect(result.displayName).toBe("Orta Therox");
+      expect(result.profileUrl).toBe("https://www.instagram.com/orta/");
+      expect(result.avatarUrl).toBe("https://scontent.cdninstagram.com/example.jpg");
+    });
+
+    it("extracts username from URL when not in og data", () => {
+      const uri = "https://www.instagram.com/alice/p/ABC123/";
+      const match = uri.match(instagram.reUri)!;
+
+      const ogData = {
+        title: "Alice Smith on Instagram: \"Test post\"",
+        description: "5 likes - alice on January 1, 2026: \"Test post\"",
+      };
+
+      const result = instagram.postprocess!(ogData, match);
+      expect(result.subject).toBe("alice");
+    });
+
+    it("falls back to unknown when no username available", () => {
+      const uri = "https://www.instagram.com/p/ABC123/";
+      const match = uri.match(instagram.reUri)!;
+
+      const result = instagram.postprocess!({}, match);
+      expect(result.subject).toBe("unknown");
+    });
+  });
+
+  describe("verifyClaim integration (mocked fetch)", () => {
+    // Valid did:plc uses base32 alphabet (a-z, 2-7), exactly 24 chars
+    const did = "did:plc:abcdefghijklmnopqrst2345";
+
+    beforeEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    function mockFetchHtml(caption: string, username: string = "alice") {
+      const html = `
+<!DOCTYPE html>
+<html>
+<head>
+  <meta property="og:type" content="article" />
+  <meta property="og:site_name" content="Instagram" />
+  <meta property="og:title" content="${username} on Instagram: &quot;${caption}&quot;" />
+  <meta property="og:description" content="0 likes, 0 comments - ${username} on February 28, 2026: &quot;${caption}&quot;" />
+  <meta property="og:url" content="https://www.instagram.com/${username}/p/ABC123/" />
+  <meta property="og:image" content="https://scontent.cdninstagram.com/test.jpg" />
+</head>
+<body>
+  <p>${caption}</p>
+</body>
+</html>
+      `;
+
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValueOnce({
+          ok: true,
+          text: () => Promise.resolve(html),
+        }),
+      );
+    }
+
+    it("verifies an Instagram post containing the DID", async () => {
+      mockFetchHtml(`Linking my keytrace.dev - ${did}`, "alice");
+
+      const claim = createClaim("https://www.instagram.com/p/ABC123/", did);
+      const result = await verifyClaim(claim);
+
+      expect(result.status).toBe(ClaimStatus.VERIFIED);
+      expect(result.identity?.subject).toBe("alice");
+    });
+
+    it("fails when post does not contain the DID", async () => {
+      mockFetchHtml("Just a regular Instagram post", "alice");
+
+      const claim = createClaim("https://www.instagram.com/p/ABC123/", did);
+      const result = await verifyClaim(claim);
+
+      expect(result.status).toBe(ClaimStatus.FAILED);
+    });
+
+    it("verifies with username in URL", async () => {
+      mockFetchHtml(`Verifying: ${did}`, "bob");
+
+      const claim = createClaim("https://www.instagram.com/bob/p/XYZ789/", did);
+      const result = await verifyClaim(claim);
+
+      expect(result.status).toBe(ClaimStatus.VERIFIED);
+      expect(result.identity?.subject).toBe("bob");
+      expect(result.identity?.profileUrl).toBe("https://www.instagram.com/bob/");
+    });
+  });
+});