@nshipster/sosumi 1.0.8 → 1.1.0

package/src/lib/ard.ts

@@ -0,0 +1,77 @@
+import { PUBLISHER_DID, PUBLISHER_DOMAIN } from "./identity"
+import { SKILL_NAME } from "./skill"
+
+export const AI_CATALOG_MEDIA_TYPE = "application/ai-catalog+json"
+
+export interface AiCatalogEntry {
+  identifier: string
+  displayName: string
+  type: string
+  url: string
+  description: string
+  representativeQueries: string[]
+}
+
+export interface AiCatalog {
+  specVersion: string
+  host: {
+    displayName: string
+    identifier: string
+    documentationUrl: string
+  }
+  entries: AiCatalogEntry[]
+}
+
+/** Build the ARD capability manifest for the origin serving the request. */
+export function buildAiCatalog(origin: string): AiCatalog {
+  return {
+    specVersion: "1.0",
+    host: {
+      displayName: PUBLISHER_DOMAIN,
+      identifier: PUBLISHER_DID,
+      documentationUrl: `${origin}/`,
+    },
+    entries: [
+      {
+        identifier: `urn:air:${PUBLISHER_DOMAIN}:server:mcp`,
+        displayName: "Sosumi MCP Server",
+        type: "application/mcp-server-card+json",
+        url: `${origin}/.well-known/mcp/server-card.json`,
+        description:
+          "Searches and fetches Apple Developer documentation, Human Interface Guidelines, WWDC transcripts, and public Swift-DocC pages.",
+        representativeQueries: [
+          "Search Apple Developer documentation for URLSession",
+          "Fetch the SwiftUI View documentation as Markdown",
+          "Get the transcript for a WWDC session",
+          "Read a public Swift-DocC documentation page",
+        ],
+      },
+      {
+        identifier: `urn:air:${PUBLISHER_DOMAIN}:agent:documentation`,
+        displayName: "Sosumi Documentation Agent",
+        type: "application/a2a-agent-card+json",
+        url: `${origin}/.well-known/agent-card.json`,
+        description:
+          "An A2A agent for searching and fetching Apple and Swift-DocC documentation as Markdown.",
+        representativeQueries: [
+          "Find Apple documentation about Swift actors",
+          "Fetch /documentation/swiftui/view as Markdown",
+          "Fetch the transcript for /videos/play/wwdc2021/10133",
+        ],
+      },
+      {
+        identifier: `urn:air:${PUBLISHER_DOMAIN}:skill:${SKILL_NAME}`,
+        displayName: "Sosumi Agent Skill",
+        type: 'text/markdown; profile="urn:air:agent-skills"',
+        url: `${origin}/.well-known/agent-skills/${SKILL_NAME}/SKILL.md`,
+        description:
+          "Instructions for using Sosumi to research Apple APIs, design guidance, videos, and Swift-DocC documentation.",
+        representativeQueries: [
+          "Research an Apple framework API before writing code",
+          "Look up current SwiftUI documentation",
+          "Find Apple's design guidance for an interface",
+        ],
+      },
+    ],
+  }
+}

package/src/lib/auth.ts

@@ -0,0 +1,105 @@
+import { jwkToKeyID, type Signer } from "web-bot-auth"
+import { helpers, signerFromJWK } from "web-bot-auth/crypto"
+
+/** The public half of the application's Ed25519 signing key. */
+export interface PublicSigningKey {
+  kty: "OKP"
+  crv: "Ed25519"
+  x: string
+  kid: string
+  use: string
+}
+
+export interface SigningKeyConfig {
+  signer: Signer
+  publicKey: PublicSigningKey
+}
+
+interface Ed25519PrivateJwk {
+  kty: "OKP"
+  crv: "Ed25519"
+  x: string
+  d: string
+}
+
+let cache: { key: string; config: Promise<SigningKeyConfig> } | null = null
+
+/** Configure the application-wide signing key from a serialized private JWK. */
+export function configureSigningKey(serializedKey?: string): void {
+  const key = serializedKey?.trim()
+  if (!key) {
+    cache = null
+    return
+  }
+
+  if (cache?.key === key) {
+    return
+  }
+
+  cache = { key, config: buildSigningKeyConfig(key) }
+}
+
+/** Return the configured signer and public key, or null if unavailable. */
+export async function currentSigningKey(): Promise<SigningKeyConfig | null> {
+  const entry = cache
+  if (!entry) {
+    return null
+  }
+
+  try {
+    return await entry.config
+  } catch (error) {
+    console.error("auth: failed to load signing key", error)
+    if (cache === entry) {
+      cache = null
+    }
+    return null
+  }
+}
+
+/** Return a copy of the configured public signing key, if available. */
+export async function currentPublicSigningKey(): Promise<PublicSigningKey | null> {
+  const config = await currentSigningKey()
+  return config ? { ...config.publicKey } : null
+}
+
+function parseSigningJwk(key: string): Ed25519PrivateJwk {
+  let jwk: JsonWebKey
+  try {
+    jwk = JSON.parse(key) as JsonWebKey
+  } catch (error) {
+    throw new Error(`WEB_BOT_AUTH_KEY is not valid JSON: ${(error as Error).message}`)
+  }
+
+  if (
+    jwk.kty !== "OKP" ||
+    jwk.crv !== "Ed25519" ||
+    typeof jwk.x !== "string" ||
+    jwk.x.length === 0 ||
+    typeof jwk.d !== "string" ||
+    jwk.d.length === 0
+  ) {
+    throw new Error(
+      "WEB_BOT_AUTH_KEY must be an Ed25519 private JSON Web Key (kty=OKP, crv=Ed25519, with x and d).",
+    )
+  }
+
+  return { kty: jwk.kty, crv: jwk.crv, x: jwk.x, d: jwk.d }
+}
+
+async function buildSigningKeyConfig(key: string): Promise<SigningKeyConfig> {
+  const jwk = parseSigningJwk(key)
+  const signer = await signerFromJWK(jwk)
+  const kid = await jwkToKeyID(jwk, helpers.WEBCRYPTO_SHA256, helpers.BASE64URL_DECODE)
+
+  return {
+    signer,
+    publicKey: {
+      kty: jwk.kty,
+      crv: jwk.crv,
+      x: jwk.x,
+      kid,
+      use: "sig",
+    },
+  }
+}

package/src/lib/did.ts

@@ -0,0 +1,40 @@
+import { currentPublicSigningKey } from "./auth"
+import { PUBLISHER_DID, PUBLISHER_ORIGIN } from "./identity"
+
+export const DID_DOCUMENT_MEDIA_TYPE = "application/did+ld+json"
+
+/**
+ * Build the did:web document for Sosumi's stable publisher identity.
+ * The verification method reuses the public half of the application signing
+ * key, which is configured out of band and never committed. Returns `null`
+ * rather than publishing an unverifiable identity when that key is unavailable.
+ */
+export async function buildDidDocument() {
+  const publicKey = await currentPublicSigningKey()
+  if (!publicKey) {
+    return null
+  }
+
+  const verificationMethodId = `${PUBLISHER_DID}#${publicKey.kid}`
+
+  return {
+    "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/jws-2020/v1"],
+    id: PUBLISHER_DID,
+    alsoKnownAs: [PUBLISHER_ORIGIN],
+    verificationMethod: [
+      {
+        id: verificationMethodId,
+        type: "JsonWebKey2020",
+        controller: PUBLISHER_DID,
+        publicKeyJwk: {
+          kty: publicKey.kty,
+          crv: publicKey.crv,
+          x: publicKey.x,
+          kid: publicKey.kid,
+        },
+      },
+    ],
+    authentication: [verificationMethodId],
+    assertionMethod: [verificationMethodId],
+  }
+}

package/src/lib/hig/render.ts

@@ -516,7 +516,7 @@ function renderHIGTocItems(items: HIGTocItem[], headingLevel: number): string {
   let markdown = ""
 
   for (const item of items) {
-    if (item.type === "module" || item.type === "symbol") {
+    if (item.type === "module" || item.type === "symbol" || item.type === "collection") {
       // Ensure blank line before heading when preceding content was a list
       if (markdown && !markdown.endsWith("\n\n")) {
         markdown += "\n"

package/src/lib/hig/types.ts

@@ -29,7 +29,7 @@ export interface HIGTocItem {
   icon?: string
   path: string
   title: string
-  type: "module" | "symbol" | "article"
+  type: "module" | "symbol" | "collection" | "article"
 }
 
 /**

package/src/lib/identity.ts

@@ -0,0 +1,4 @@
+/** Stable publisher identity, intentionally independent of the request origin. */
+export const PUBLISHER_DOMAIN = "sosumi.ai"
+export const PUBLISHER_DID = `did:web:${PUBLISHER_DOMAIN}`
+export const PUBLISHER_ORIGIN = `https://${PUBLISHER_DOMAIN}`

package/src/lib/mcp.ts

@@ -4,16 +4,27 @@ import { z } from "zod"
 import type { ExternalPolicyEnv } from "./external"
 import { fetchExternalDocumentationMarkdown } from "./external"
 import { fetchHIGPageData, renderHIGFromJSON } from "./hig"
+import { PUBLISHER_DOMAIN } from "./identity"
 import { fetchJSONData, renderFromJSON } from "./reference"
 import { searchAppleDeveloperDocs } from "./search"
 import { generateAppleDocUrl, normalizeDocumentationPath } from "./url"
 import { fetchVideoTranscriptMarkdown } from "./video"
 
 export const MCP_SERVER_INFO = {
-  name: "sosumi.ai",
+  name: PUBLISHER_DOMAIN,
   version: "1.0.0",
 } as const
 
+/**
+ * Guidance for clients, kept out of the documentation itself
+ * so that fetched pages stay 1:1 with Apple's content.
+ */
+export const MCP_SERVER_INSTRUCTIONS =
+  "Sosumi returns Apple's documentation as Markdown. " +
+  'The conformance conditions in Apple\'s data, such as "Conforms when `Element` conforms to `Hashable`.", ' +
+  "can be missing or wrong. " +
+  "When a condition matters, read the declaration in the module's `.swiftinterface` file in the SDK."
+
 export interface ToolHttpBinding {
   path?: string
   pathFrom?: string
@@ -114,7 +125,7 @@ export const TOOL_DEFINITIONS = {
 } satisfies Record<string, ToolMeta>
 
 export function createMcpServer(externalPolicyEnv: ExternalPolicyEnv = {}) {
-  const server = new McpServer(MCP_SERVER_INFO)
+  const server = new McpServer(MCP_SERVER_INFO, { instructions: MCP_SERVER_INSTRUCTIONS })
 
   const search = TOOL_DEFINITIONS.searchAppleDocumentation
   server.registerTool(

package/src/lib/reference/render.ts

@@ -614,7 +614,13 @@ function renderRelationships(
       markdown += `## ${rel.title}\n\n`
       for (const id of rel.identifiers) {
         const { title, url } = resolveLink(id, variants, references, externalOrigin)
-        markdown += `- [${title}](${url})\n`
+        const condition = renderCondition(
+          references?.[id],
+          "conformancePrefix",
+          references,
+          externalOrigin,
+        )
+        markdown += `- [${title}](${url})${condition ? ` ${condition}` : ""}\n`
       }
       markdown += "\n"
     }
@@ -623,6 +629,30 @@ function renderRelationships(
   return markdown
 }
 
+/**
+ * Render the condition on a reference, or an empty string when it has none.
+ * Relationship sections use the conformance prefix
+ * ("Conforms when `Element` conforms to `Hashable`."),
+ * and topic and see also sections use the availability prefix
+ * ("Available when `Element` conforms to `Hashable`.").
+ */
+function renderCondition(
+  reference: ContentItem | undefined,
+  prefixKey: "conformancePrefix" | "availabilityPrefix",
+  references?: Record<string, ContentItem>,
+  externalOrigin?: string,
+): string {
+  const constraints = reference?.conformance?.constraints
+  if (!constraints?.length) {
+    return ""
+  }
+  const prefix = reference?.conformance?.[prefixKey] ?? []
+  const inlineContent = prefix.length
+    ? [...prefix, { type: "text", text: " " }, ...constraints]
+    : constraints
+  return renderInlineContent(inlineContent, references, 0, externalOrigin).trim()
+}
+
 /**
  * Render topic sections
  */
@@ -652,6 +682,15 @@ function renderTopicSections(
         if (abstract) {
           markdown += ` ${abstract}`
         }
+        const condition = renderCondition(
+          references?.[id],
+          "availabilityPrefix",
+          references,
+          externalOrigin,
+        )
+        if (condition) {
+          markdown += ` ${condition}`
+        }
         markdown += "\n"
       }
       markdown += "\n"
@@ -730,7 +769,13 @@ function renderSeeAlso(
       markdown += `## ${section.title}\n\n`
       for (const id of section.identifiers) {
         const { title, url } = resolveLink(id, variants, references, externalOrigin)
-        markdown += `- [${title}](${url})\n`
+        const condition = renderCondition(
+          references?.[id],
+          "availabilityPrefix",
+          references,
+          externalOrigin,
+        )
+        markdown += `- [${title}](${url})${condition ? ` ${condition}` : ""}\n`
       }
       markdown += "\n"
     }

package/src/lib/types.ts

@@ -90,6 +90,17 @@ export interface ContentItem {
 
   /** Present on reference entries for deprecated symbols. */
   deprecated?: boolean
+
+  /**
+   * Present on reference entries for conditional conformances and members
+   * (e.g. "Conforms when `Element` conforms to `Hashable`."
+   * or "Available when `Element` conforms to `Hashable`.").
+   */
+  conformance?: {
+    conformancePrefix?: ContentItem[]
+    availabilityPrefix?: ContentItem[]
+    constraints?: ContentItem[]
+  }
 }
 
 // ============================================================================

package/src/lib/webbotauth.ts

@@ -22,12 +22,11 @@
 import {
   directoryResponseHeaders,
   HTTP_MESSAGE_SIGNATURES_DIRECTORY,
-  jwkToKeyID,
   MediaType,
-  type Signer,
   signatureHeaders,
 } from "web-bot-auth"
-import { helpers, signerFromJWK } from "web-bot-auth/crypto"
+import { configureSigningKey, currentSigningKey, type PublicSigningKey } from "./auth"
+import { PUBLISHER_ORIGIN } from "./identity"
 
 export interface WebBotAuthEnv {
   /**
@@ -45,7 +44,7 @@ export const DIRECTORY_PATH = HTTP_MESSAGE_SIGNATURES_DIRECTORY
 /** Content type for the key directory response. */
 export const DIRECTORY_MEDIA_TYPE = MediaType.HTTP_MESSAGE_SIGNATURES_DIRECTORY
 
-const DEFAULT_SIGNATURE_AGENT = "https://sosumi.ai"
+const DEFAULT_SIGNATURE_AGENT = PUBLISHER_ORIGIN
 
 /**
  * How long an outbound request signature stays valid.
@@ -56,28 +55,7 @@ const OUTBOUND_SIGNATURE_TTL_MS = 5 * 60 * 1000
 /** How long the directory self-signature stays valid. */
 const DIRECTORY_SIGNATURE_TTL_MS = 60 * 60 * 1000
 
-/** A public JSON Web Key as published in the directory (RFC 8037 Ed25519). */
-export interface DirectoryKey {
-  kty?: string
-  crv?: string
-  x?: string
-  kid: string
-  use: string
-}
-
-interface WebBotAuthConfig {
-  signer: Signer
-  publicKey: DirectoryKey
-  agent: string
-}
-
-/**
- * Cached, parsed configuration.
- * The signing key is application-global (the same for every request),
- * so it is memoized across requests in the isolate
- * and only rebuilt when the underlying secret or agent changes.
- */
-let cache: { key: string; agent: string; config: Promise<WebBotAuthConfig> } | null = null
+let signatureAgent: string | null = null
 
 /**
  * Prime the signing configuration from the environment.
@@ -86,91 +64,8 @@ let cache: { key: string; agent: string; config: Promise<WebBotAuthConfig> } | n
  */
 export function configureWebBotAuth(env: WebBotAuthEnv): void {
   const key = env.WEB_BOT_AUTH_KEY?.trim()
-  if (!key) {
-    cache = null
-    return
-  }
-
-  const agent = env.SIGNATURE_AGENT?.trim() || DEFAULT_SIGNATURE_AGENT
-  if (cache && cache.key === key && cache.agent === agent) {
-    return
-  }
-
-  cache = { key, agent, config: buildConfig(key, agent) }
-}
-
-interface Ed25519PrivateJwk {
-  kty: "OKP"
-  crv: "Ed25519"
-  x: string
-  d: string
-}
-
-/**
- * Parse and validate the signing secret as an Ed25519 OKP private JWK.
- * Fails closed on anything malformed
- * so a misconfigured `WEB_BOT_AUTH_KEY` never yields a broken directory key
- * or unverifiable signatures.
- */
-function parseSigningJwk(key: string): Ed25519PrivateJwk {
-  let jwk: JsonWebKey
-  try {
-    jwk = JSON.parse(key) as JsonWebKey
-  } catch (error) {
-    throw new Error(`WEB_BOT_AUTH_KEY is not valid JSON: ${(error as Error).message}`)
-  }
-
-  if (
-    jwk.kty !== "OKP" ||
-    jwk.crv !== "Ed25519" ||
-    typeof jwk.x !== "string" ||
-    jwk.x.length === 0 ||
-    typeof jwk.d !== "string" ||
-    jwk.d.length === 0
-  ) {
-    throw new Error(
-      "WEB_BOT_AUTH_KEY must be an Ed25519 private JSON Web Key (kty=OKP, crv=Ed25519, with x and d).",
-    )
-  }
-
-  return { kty: jwk.kty, crv: jwk.crv, x: jwk.x, d: jwk.d }
-}
-
-async function buildConfig(key: string, agent: string): Promise<WebBotAuthConfig> {
-  const jwk = parseSigningJwk(key)
-  const signer = await signerFromJWK(jwk)
-  const kid = await jwkToKeyID(jwk, helpers.WEBCRYPTO_SHA256, helpers.BASE64URL_DECODE)
-
-  // Publish only the public half of the key (never the `d` parameter).
-  const publicKey: DirectoryKey = {
-    kty: jwk.kty,
-    crv: jwk.crv,
-    x: jwk.x,
-    kid,
-    use: "sig",
-  }
-
-  return { signer, publicKey, agent }
-}
-
-async function currentConfig(): Promise<WebBotAuthConfig | null> {
-  const entry = cache
-  if (!entry) {
-    return null
-  }
-
-  try {
-    return await entry.config
-  } catch (error) {
-    console.error("web-bot-auth: failed to load signing key", error)
-    // Drop the failed config so the next request rebuilds it,
-    // rather than serving the cached rejection until the isolate restarts.
-    // Guard against clobbering a newer config set by a concurrent reconfigure.
-    if (cache === entry) {
-      cache = null
-    }
-    return null
-  }
+  configureSigningKey(key)
+  signatureAgent = key ? env.SIGNATURE_AGENT?.trim() || DEFAULT_SIGNATURE_AGENT : null
 }
 
 /** Serialize a value as an RFC 8941 structured-field string (a quoted string). */
@@ -179,7 +74,7 @@ function structuredString(value: string): string {
 }
 
 export interface DirectoryResponse {
-  body: { keys: DirectoryKey[] }
+  body: { keys: PublicSigningKey[] }
   headers: Record<string, string>
 }
 
@@ -193,8 +88,8 @@ export interface DirectoryResponse {
  * demonstrating control of the published key.
  */
 export async function webBotAuthDirectory(requestUrl: string): Promise<DirectoryResponse | null> {
-  const config = await currentConfig()
-  if (!config) {
+  const signingKey = await currentSigningKey()
+  if (!signingKey) {
     return null
   }
 
@@ -205,10 +100,13 @@ export async function webBotAuthDirectory(requestUrl: string): Promise<Directory
     request: { method: "GET", url: requestUrl, headers: {} as Record<string, string> },
   }
 
-  const signature = await directoryResponseHeaders(message, [config.signer], { created, expires })
+  const signature = await directoryResponseHeaders(message, [signingKey.signer], {
+    created,
+    expires,
+  })
 
   return {
-    body: { keys: [config.publicKey] },
+    body: { keys: [signingKey.publicKey] },
     headers: {
       "Content-Type": DIRECTORY_MEDIA_TYPE,
       Signature: signature.Signature,
@@ -228,13 +126,14 @@ export async function webBotAuthHeaders(
   method: string,
   url: string | URL,
 ): Promise<Record<string, string>> {
-  const config = await currentConfig()
-  if (!config) {
+  const signingKey = await currentSigningKey()
+  const agentValue = signatureAgent
+  if (!signingKey || !agentValue) {
     return {}
   }
 
   try {
-    const agent = structuredString(config.agent)
+    const agent = structuredString(agentValue)
     // `signature-agent` must be present on the message
     // so it is covered by the signature;
     // the same value is returned for the outbound request.
@@ -245,7 +144,7 @@ export async function webBotAuthHeaders(
     const expires = new Date(created.getTime() + OUTBOUND_SIGNATURE_TTL_MS)
     const signature = await signatureHeaders(
       { method, url: url.toString(), headers },
-      config.signer,
+      signingKey.signer,
       { created, expires },
     )
 

package/wrangler.jsonc

@@ -17,12 +17,24 @@
   "assets": {
     "binding": "ASSETS",
     "directory": "./public",
-    "run_worker_first": ["/", "/.well-known/agent-card.json", "/.well-known/agent-skills/*"]
+    "run_worker_first": [
+      "/",
+      "/.well-known/agent-card.json",
+      "/.well-known/agent-skills/*",
+      "/.well-known/mcp-registry-auth",
+      "/.well-known/security.txt",
+      "/message:send",
+      "/message:stream",
+      "/tasks",
+      "/tasks/*",
+      "/extendedAgentCard"
+    ]
   },
   "observability": {
     "enabled": true
   },
   "vars": {
-    "NODE_ENV": "production"
+    "NODE_ENV": "production",
+    "MCP_REGISTRY_PUBLIC_KEY": "sL6l9eXq+RN7+VuAVWZGnSacjsgix0TVW5FDLYlBUpg="
   }
 }