@nshipster/sosumi 1.0.5 → 1.0.7

package/README.md

@@ -93,7 +93,7 @@ See [the website](https://sosumi.ai/#clients) for client-specific instructions.
   - Returns structured results with titles, URLs, descriptions, breadcrumbs, and tags
 
 - `fetchAppleDocumentation` - Fetches Apple Developer documentation and Human Interface Guidelines by path
-  - Parameters: `path` (string) - Documentation path (e.g., '/documentation/swift', 'swiftui/view', 'design/human-interface-guidelines/foundations/color')
+  - Parameters: `path` (string) - Documentation path (e.g., '/documentation/swift', '/documentation/swiftui/view', '/design/human-interface-guidelines/foundations/color')
   - Returns content as Markdown
 
 - `fetchAppleVideoTranscript` - Fetches video transcripts, including WWDC sessions
@@ -234,6 +234,49 @@ with two environment variables (both newline-delimited):
 > Hostname-based private-network checks cannot fully prevent DNS rebinding.
 > Set an explicit `EXTERNAL_DOC_HOST_ALLOWLIST` in production.
 
+### Web Bot Auth
+
+Sosumi identifies itself
+when it fetches from external Swift-DocC hosts on a user's behalf
+using [Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/),
+so those hosts can cryptographically verify the traffic.
+
+- The public key set is published at
+  [`/.well-known/http-message-signatures-directory`](https://sosumi.ai/.well-known/http-message-signatures-directory).
+- Requests to external hosts are signed
+  with an Ed25519 [HTTP Message Signature (RFC 9421)](https://www.rfc-editor.org/rfc/rfc9421)
+  and carry `Signature-Agent`, `Signature-Input`, and `Signature` headers.
+
+To enable signing on your own deployment,
+provide an Ed25519 private key (as a JSON Web Key)
+via the `WEB_BOT_AUTH_KEY` secret.
+
+Generate a key (the JSON Web Key is the format `WEB_BOT_AUTH_KEY` expects),
+then paste the printed value when `wrangler secret put` prompts for it:
+
+```bash
+node -e 'crypto.subtle.generateKey({name:"Ed25519"},true,["sign","verify"]).then(async k=>{const j=await crypto.subtle.exportKey("jwk",k.privateKey);console.log(JSON.stringify({kty:j.kty,crv:j.crv,x:j.x,d:j.d}))})'
+npx wrangler secret put WEB_BOT_AUTH_KEY
+```
+
+Or generate and upload in a single step,
+which avoids writing the key to disk or shell history:
+
+```bash
+node -e 'crypto.subtle.generateKey({name:"Ed25519"},true,["sign","verify"]).then(async k=>{const j=await crypto.subtle.exportKey("jwk",k.privateKey);console.log(JSON.stringify({kty:j.kty,crv:j.crv,x:j.x,d:j.d}))})' \
+  | npx wrangler secret put WEB_BOT_AUTH_KEY
+```
+
+The matching public key and its `kid` (JWK thumbprint) are derived automatically,
+so no key material lives in the repository.
+Set the optional `SIGNATURE_AGENT` var to override the advertised origin
+(defaults to `https://sosumi.ai`).
+When no key is configured, requests are simply sent unsigned.
+
+Cloudflare provides
+[built-in verification](https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/)
+for these signatures.
+
 ## Development
 
 ### Testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nshipster/sosumi",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Making Apple docs AI-readable",
   "license": "MIT",
   "author": "NSHipster",
@@ -61,7 +61,9 @@
     "hono": "^4.9.4",
     "robots-parser": "^3.0.1",
     "tsx": "^4.21.0",
-    "zod": "^3"
+    "web-bot-auth": "^0.1.3",
+    "zod": "^3",
+    "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.2",

package/public/index.html

@@ -36,6 +36,8 @@
 
     <link rel="preload" href="/sosumi.m4a" as="audio" type="audio/mp4">
 
+    <script src="/webmcp.js" defer></script>
+
     <style>
         :root {
             color-scheme: light dark;
@@ -809,7 +811,7 @@
                         <dl>
                             <dt><code>fetchAppleDocumentation</code></dt>
                             <dd><strong>Fetches Apple Developer documentation and Human Interface Guidelines by path</strong>
-                                <br>Parameters: <code>path</code> (string) - Documentation path (e.g., '/documentation/swift', 'design/human-interface-guidelines/foundations/color')
+                                <br>Parameters: <code>path</code> (string) - Documentation path (e.g., '/documentation/swift', '/documentation/swiftui/view', '/design/human-interface-guidelines/foundations/color')
                                 <br><em>Returns content as Markdown</em>
                             </dd>
                         </dl>

package/public/llms.txt

@@ -121,7 +121,7 @@ you can run this command to proxy over stdio:
   - Returns structured results with titles, URLs, descriptions, breadcrumbs, and tags
 
 - `fetchAppleDocumentation` - Fetches Apple Developer documentation and Human Interface Guidelines by path
-  - Parameters: `path` (string) - Documentation path (e.g., '/documentation/swift', 'design/human-interface-guidelines/foundations/color')
+  - Parameters: `path` (string) - Documentation path (e.g., '/documentation/swift', '/documentation/swiftui/view', '/design/human-interface-guidelines/foundations/color')
   - Returns content as Markdown
 
 - `fetchAppleVideoTranscript` - Fetches video transcripts, including WWDC sessions, by video path

package/public/robots.txt

@@ -1,4 +1,5 @@
 User-agent: *
+Content-Signal: search=yes, ai-input=yes, ai-train=no
 Allow: /
 Disallow: /documentation/
 Disallow: /external/

package/public/webmcp.js

@@ -0,0 +1,71 @@
+(function () {
+  const ctx =
+    (typeof navigator !== "undefined" && navigator.modelContext) || document.modelContext
+  if (!ctx) return
+  if (typeof ctx.registerTool !== "function" && typeof ctx.provideContext !== "function") return
+
+  async function runHttpTool(http, input) {
+    let pathname = http.path
+    if (http.pathFrom) {
+      const value = String(input[http.pathFrom] ?? "")
+      if (http.pathPrefix) {
+        pathname = http.pathPrefix + value.replace(/^\//, "")
+      } else {
+        pathname = value.startsWith("/") ? value : "/" + value
+      }
+    }
+    const url = new URL(pathname, location.origin)
+    if (http.query) {
+      for (const [param, key] of Object.entries(http.query)) {
+        url.searchParams.set(param, String(input[key] ?? ""))
+      }
+    }
+    const response = await fetch(url, { headers: { Accept: "application/json" } })
+    const body = await response.text()
+    let data
+    try {
+      data = JSON.parse(body)
+    } catch {
+      data = body
+    }
+    const text =
+      data && typeof data === "object" && data !== null && "content" in data
+        ? String(data.content)
+        : typeof data === "string"
+          ? data
+          : JSON.stringify(data, null, 2)
+    return { content: [{ type: "text", text }] }
+  }
+
+  function registerTool(tool) {
+    const registration = {
+      name: tool.name,
+      title: tool.title,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      annotations: { readOnlyHint: tool.readOnly },
+      execute: (input) => runHttpTool(tool.http, input),
+    }
+    try {
+      if (typeof ctx.registerTool === "function") {
+        ctx.registerTool(registration)
+      } else if (typeof ctx.provideContext === "function") {
+        ctx.provideContext({ tools: [registration] })
+      }
+    } catch {
+      // Ignore duplicate or unsupported registrations.
+    }
+  }
+
+  fetch("/webmcp/manifest.json")
+    .then((response) => {
+      if (!response.ok) throw new Error("Failed to load WebMCP manifest")
+      return response.json()
+    })
+    .then((tools) => {
+      for (const tool of tools) {
+        registerTool(tool)
+      }
+    })
+    .catch(() => {})
+})()

package/src/index.ts

@@ -5,6 +5,7 @@ import { cache } from "hono/cache"
 import { cors } from "hono/cors"
 import { HTTPException } from "hono/http-exception"
 import { trimTrailingSlash } from "hono/trailing-slash"
+import { buildAgentCard } from "./lib/a2a"
 import {
   decodeExternalTargetPath,
   ExternalAccessError,
@@ -19,7 +20,7 @@ import {
   renderHIGFromJSON,
   renderHIGTableOfContents,
 } from "./lib/hig"
-import { createMcpServer } from "./lib/mcp"
+import { createMcpServer, MCP_SERVER_INFO } from "./lib/mcp"
 import { fetchJSONData, renderFromJSON } from "./lib/reference"
 import { searchAppleDeveloperDocs } from "./lib/search"
 import {
@@ -32,17 +33,28 @@ import {
 } from "./lib/skill"
 import { generateAppleDocUrl, isValidAppleDocUrl, normalizeDocumentationPath } from "./lib/url"
 import { fetchVideoTranscriptMarkdown, TranscriptNotFoundError } from "./lib/video"
+import {
+  configureWebBotAuth,
+  DIRECTORY_PATH as WEB_BOT_AUTH_DIRECTORY_PATH,
+  webBotAuthDirectory,
+} from "./lib/webbotauth"
+import { buildWebMcpManifest } from "./lib/webmcp"
 
 interface Env {
   ASSETS: Fetcher
   NODE_ENV: string
   EXTERNAL_DOC_HOST_ALLOWLIST?: string
   EXTERNAL_DOC_HOST_BLOCKLIST?: string
+  WEB_BOT_AUTH_KEY?: string
+  SIGNATURE_AGENT?: string
 }
 
 const app = new Hono<{ Bindings: Env }>()
 
 app.use("*", async (c, next) => {
+  // Prime Web Bot Auth signing before any route or outbound fetch runs.
+  configureWebBotAuth(c.env)
+
   await next()
 
   // Security headers
@@ -59,6 +71,19 @@ app.use("*", async (c, next) => {
   if (c.env.NODE_ENV === "development") {
     c.header("Cache-Control", "no-store")
   }
+
+  if (c.req.path === "/") {
+    c.header(
+      "Link",
+      [
+        '</.well-known/api-catalog>; rel="api-catalog"',
+        '</.well-known/agent-card.json>; rel="service-desc"; type="application/json"',
+        '</.well-known/mcp/server-card.json>; rel="service-desc"; type="application/json"',
+        '</SKILL.md>; rel="service-doc"',
+        '</llms.txt>; rel="alternate"; type="text/markdown"',
+      ].join(", "),
+    )
+  }
 })
 
 app.use("*", cors())
@@ -146,6 +171,92 @@ app.all(`/.well-known/agent-skills/${SKILL_NAME}/SKILL.md`, async (c) => {
   })
 })
 
+app.get(WEB_BOT_AUTH_DIRECTORY_PATH, async (c) => {
+  const directory = await webBotAuthDirectory(c.req.url)
+  if (!directory) {
+    throw new HTTPException(404, { message: "Web Bot Auth key directory is not configured." })
+  }
+
+  return c.json(directory.body, 200, {
+    "Access-Control-Allow-Origin": "*",
+    ...directory.headers,
+  })
+})
+
+const discoveryHeaders = {
+  "Access-Control-Allow-Origin": "*",
+  "Cache-Control": "public, max-age=300, s-maxage=600",
+} as const
+
+app.get("/.well-known/api-catalog", (c) => {
+  const origin = new URL(c.req.url).origin
+
+  return c.json(
+    {
+      linkset: [
+        {
+          anchor: `${origin}/mcp`,
+          "service-desc": [
+            {
+              href: `${origin}/.well-known/mcp/server-card.json`,
+              type: "application/json",
+            },
+          ],
+          "service-doc": [{ href: `${origin}/SKILL.md`, type: "text/markdown" }],
+          status: [{ href: `${origin}/` }],
+        },
+        {
+          anchor: `${origin}/documentation`,
+          "service-doc": [{ href: `${origin}/SKILL.md`, type: "text/markdown" }],
+        },
+      ],
+    },
+    200,
+    {
+      ...discoveryHeaders,
+      "Content-Type": "application/linkset+json; charset=utf-8",
+    },
+  )
+})
+
+app.get("/.well-known/mcp/server-card.json", (c) => {
+  const origin = new URL(c.req.url).origin
+
+  return c.json(
+    {
+      serverInfo: MCP_SERVER_INFO,
+      transport: {
+        type: "streamable-http",
+        endpoint: `${origin}/mcp`,
+      },
+      capabilities: {
+        tools: {},
+      },
+    },
+    200,
+    {
+      ...discoveryHeaders,
+      "Content-Type": "application/json; charset=utf-8",
+    },
+  )
+})
+
+app.get("/.well-known/agent-card.json", (c) => {
+  const origin = new URL(c.req.url).origin
+
+  return c.json(buildAgentCard(origin), 200, {
+    ...discoveryHeaders,
+    "Content-Type": "application/json; charset=utf-8",
+  })
+})
+
+app.get("/webmcp/manifest.json", (c) =>
+  c.json(buildWebMcpManifest(), 200, {
+    ...discoveryHeaders,
+    "Content-Type": "application/json; charset=utf-8",
+  }),
+)
+
 app.get("/bot", (c) => c.redirect("/#bot", 302))
 
 app.all("/mcp", async (c) => {

package/src/lib/a2a.ts

@@ -0,0 +1,90 @@
+import { MCP_SERVER_INFO, TOOL_DEFINITIONS } from "./mcp"
+
+/**
+ * The A2A protocol version each interface exposes, as `major.minor`.
+ * See https://a2a-protocol.org/latest/specification/
+ */
+const A2A_PROTOCOL_VERSION = "0.3"
+
+/**
+ * The transport binding advertised for the agent's interface.
+ * Sosumi exposes its documentation service over plain HTTP requests,
+ * so the `HTTP+JSON` binding is the closest of A2A's officially supported bindings.
+ */
+const TRANSPORT = "HTTP+JSON"
+
+const AGENT_DESCRIPTION =
+  "Making Apple docs AI-readable. " +
+  "Sosumi converts Apple Developer documentation, Human Interface Guidelines, " +
+  "WWDC session transcripts, and public Swift-DocC sites " +
+  "into clean Markdown for AI agents."
+
+/** Keyword tags describing each skill's capabilities. */
+const SKILL_TAGS: Record<string, string[]> = {
+  searchAppleDocumentation: ["apple", "search", "documentation"],
+  fetchAppleDocumentation: ["apple", "documentation", "markdown", "hig"],
+  fetchExternalDocumentation: ["swift-docc", "documentation", "markdown"],
+  fetchAppleVideoTranscript: ["apple", "wwdc", "video", "transcript"],
+}
+
+/** Example prompts illustrating how each skill is used. */
+const SKILL_EXAMPLES: Record<string, string[]> = {
+  searchAppleDocumentation: ["Search Apple documentation for URLSession"],
+  fetchAppleDocumentation: ["Fetch /documentation/swiftui/view as Markdown"],
+  fetchExternalDocumentation: [
+    "Fetch https://apple.github.io/swift-argument-parser/documentation/argumentparser",
+  ],
+  fetchAppleVideoTranscript: ["Fetch the transcript for /videos/play/wwdc2021/10133"],
+}
+
+interface AgentInterface {
+  url: string
+  /** The A2A protocol version this interface exposes. */
+  protocolVersion: string
+  /** Transport binding. Named `protocolBinding` by the current A2A proto schema. */
+  protocolBinding: string
+  /** Alias of `protocolBinding` for clients reading the published JSON schema's `transport`. */
+  transport: string
+}
+
+/**
+ * Build an A2A Agent Card for the given origin.
+ * Conforms to the A2A Agent Card schema for agent-to-agent discovery.
+ * https://a2a-protocol.org/latest/topics/agent-discovery/
+ */
+export function buildAgentCard(origin: string) {
+  const service: AgentInterface = {
+    url: origin,
+    protocolVersion: A2A_PROTOCOL_VERSION,
+    protocolBinding: TRANSPORT,
+    transport: TRANSPORT,
+  }
+
+  const skills = Object.values(TOOL_DEFINITIONS).map((def) => ({
+    // Convert the camelCase tool name to a kebab-case skill id.
+    id: def.name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase(),
+    name: def.title,
+    description: def.description,
+    tags: SKILL_TAGS[def.name] ?? ["apple", "documentation"],
+    examples: SKILL_EXAMPLES[def.name],
+  }))
+
+  return {
+    name: MCP_SERVER_INFO.name,
+    description: AGENT_DESCRIPTION,
+    version: MCP_SERVER_INFO.version,
+    supportedInterfaces: [service],
+    provider: {
+      organization: "NSHipster",
+      url: origin,
+    },
+    documentationUrl: `${origin}/SKILL.md`,
+    capabilities: {
+      streaming: false,
+      pushNotifications: false,
+    },
+    defaultInputModes: ["text/plain"],
+    defaultOutputModes: ["text/markdown", "text/plain"],
+    skills,
+  }
+}

package/src/lib/external/fetch.ts

@@ -1,5 +1,6 @@
 import { renderFromJSON } from "../reference"
 import type { AppleDocJSON } from "../types"
+import { webBotAuthHeaders } from "../webbotauth"
 import {
   assertExternalDocumentationAccess,
   ExternalAccessError,
@@ -42,6 +43,7 @@ export async function fetchExternalDocCJSON(
     headers: {
       "User-Agent": EXTERNAL_DOC_USER_AGENT,
       Accept: "application/json",
+      ...(await webBotAuthHeaders("GET", jsonUrl)),
     },
   })
 
@@ -88,6 +90,7 @@ export async function fetchRobotsPolicy(
     headers: {
       "User-Agent": userAgent,
       Accept: "text/plain, text/*;q=0.9, */*;q=0.1",
+      ...(await webBotAuthHeaders("GET", robotsUrl)),
     },
   })