@kirkelabs/agent-readiness-scan 0.1.0 → 0.2.0

package/src/generators.js

@@ -1,174 +1,228 @@
-/**
- * generators.js
- *
- * Produces the "customs declaration" — a drop-in set of files ready to
- * paste at the site root that close most of the policy gaps the
- * scanner identifies. The user reviews and edits before deploy;
- * these are conservative scaffolds, not finished output.
- *
- * Generated artefacts:
- *   - robots.txt                            (per-bot policy + Content-Signals)
- *   - .well-known/security.txt              (RFC 9116)
- *   - .well-known/mcp/server-card.json      (MCP server card scaffold)
- *   - .well-known/acp/manifest.json         (ACP manifest scaffold)
- */
-
-const AI_BOTS = {
-  training: [
-    'GPTBot',
-    'ClaudeBot',
-    'Google-Extended',
-    'anthropic-ai',
-    'CCBot',
-    'Bytespider',
-    'Amazonbot',
-    'Applebot-Extended',
-    'meta-externalagent',
-  ],
-  grounding: ['OAI-SearchBot', 'PerplexityBot', 'Claude-Web'],
-  userDirected: ['ChatGPT-User', 'Claude-User'],
-};
-
-function generateRobotsTxt(origin) {
-  const lines = [];
-  lines.push('# robots.txt — Customs Declaration');
-  lines.push('# Generated by @kirkelabs/agent-readiness-scan.');
-  lines.push('# Review and edit before deploying. Tighten or loosen rules to match');
-  lines.push('# your stated bargain with AI agents (training vs grounding vs user-directed).');
-  lines.push('');
-  lines.push('# --- Default allow-all baseline ---');
-  lines.push('User-agent: *');
-  lines.push('Allow: /');
-  lines.push('');
-  lines.push('# --- Training crawlers (use your content to train foundation models) ---');
-  for (const bot of AI_BOTS.training) {
-    lines.push(`User-agent: ${bot}`);
-    lines.push('Disallow:                       # TODO: set to / to disallow, blank to allow');
-    lines.push('');
-  }
-  lines.push('# --- Grounding crawlers (fetch in real time for answer-engine retrieval) ---');
-  for (const bot of AI_BOTS.grounding) {
-    lines.push(`User-agent: ${bot}`);
-    lines.push('Allow: /');
-    lines.push('');
-  }
-  lines.push('# --- User-directed crawlers (fetched on behalf of a logged-in user) ---');
-  for (const bot of AI_BOTS.userDirected) {
-    lines.push(`User-agent: ${bot}`);
-    lines.push('Allow: /');
-    lines.push('');
-  }
-  lines.push('# --- Cloudflare Content Signals (which uses you permit) ---');
-  lines.push('# See https://contentsignals.org/');
-  lines.push('Content-Signal: search=yes, ai-input=yes, ai-train=no');
-  lines.push('');
-  lines.push(`Sitemap: ${origin}/sitemap.xml`);
-  lines.push('');
-  return lines.join('\n');
-}
-
-function generateSecurityTxt() {
-  const expires = new Date();
-  expires.setFullYear(expires.getFullYear() + 1);
-  const lines = [];
-  lines.push('# /.well-known/security.txt — RFC 9116');
-  lines.push('# Generated by @kirkelabs/agent-readiness-scan. Review before deploying.');
-  lines.push('');
-  lines.push('Contact: mailto:security@your-domain.example');
-  lines.push(`Expires: ${expires.toISOString()}`);
-  lines.push('Preferred-Languages: en');
-  lines.push('# Canonical: https://your-domain.example/.well-known/security.txt');
-  lines.push('# Encryption: https://your-domain.example/pgp-key.asc');
-  lines.push('');
-  return lines.join('\n');
-}
-
-function generateMcpServerCard(origin, name) {
-  return JSON.stringify(
-    {
-      $schema: 'https://modelcontextprotocol.io/schemas/server-card/v1',
-      name: name || 'TODO: Your service name',
-      description: 'TODO: One-sentence description of what this MCP server lets agents do.',
-      version: '0.1.0',
-      url: `${origin}/mcp`,
-      contact: {
-        name: 'TODO: maintainer',
-        email: 'mcp@your-domain.example',
-      },
-      tools: [
-        {
-          name: 'TODO_tool_name',
-          description: 'TODO: what this tool does',
-          inputSchema: {
-            type: 'object',
-            properties: {},
-            required: [],
-          },
-        },
-      ],
-      authentication: {
-        type: 'oauth2',
-        authorizationEndpoint: `${origin}/oauth/authorize`,
-        tokenEndpoint: `${origin}/oauth/token`,
-        pkce: { codeChallengeMethods: ['S256'] },
-      },
-    },
-    null,
-    2,
-  );
-}
-
-function generateAcpManifest(origin, name) {
-  return JSON.stringify(
-    {
-      version: '2026-04-17',
-      merchant: {
-        name: name || 'TODO: Your merchant name',
-        url: origin,
-        contact: 'merchant@your-domain.example',
-      },
-      capabilities: {
-        checkout: { endpoint: `${origin}/acp/checkout`, supportedMethods: ['card'] },
-        productCatalog: { endpoint: `${origin}/acp/products` },
-      },
-      keys: [
-        {
-          kty: 'TODO',
-          kid: 'TODO',
-          alg: 'RS256',
-          use: 'sig',
-          n: 'TODO: base64url-encoded RSA modulus',
-          e: 'AQAB',
-        },
-      ],
-    },
-    null,
-    2,
-  );
-}
-
-function deriveName($, finalUrl) {
-  const t = ($('title').first().text() || '').trim();
-  if (t) return t.split('—')[0].split('|')[0].trim();
-  try {
-    return new URL(finalUrl).hostname.replace(/^www\./, '');
-  } catch {
-    return 'Your Brand';
-  }
-}
-
-export function generateCustomsDeclaration(ctx) {
-  let origin = ctx.finalUrl;
-  try {
-    origin = new URL(ctx.finalUrl).origin;
-  } catch {
-    /* keep */
-  }
-  const name = deriveName(ctx.$, ctx.finalUrl);
-  return {
-    'robots.txt': generateRobotsTxt(origin),
-    '.well-known/security.txt': generateSecurityTxt(),
-    '.well-known/mcp/server-card.json': generateMcpServerCard(origin, name),
-    '.well-known/acp/manifest.json': generateAcpManifest(origin, name),
-  };
-}
+/**
+ * generators.js
+ *
+ * Produces the "customs declaration" — a drop-in set of files ready to
+ * paste at the site root that close most of the policy gaps the
+ * scanner identifies. The user reviews and edits before deploy;
+ * these are conservative scaffolds, not finished output.
+ *
+ * Generated artefacts:
+ *   - robots.txt                            (per-bot policy + Content-Signals)
+ *   - .well-known/security.txt              (RFC 9116)
+ *   - .well-known/mcp/server-card.json      (MCP server card scaffold)
+ *   - .well-known/acp/manifest.json         (ACP manifest scaffold)
+ *   - .well-known/agent-access.json         (Open Agent Access + x402 scaffold)
+ *
+ * The OAA scaffold is offered alongside ACP/UCP as one of several live
+ * agent-commerce/agent-auth declarations. Disclosure: Open Agent Access is
+ * implemented by Kirke Labs, the author of this tool; it is scaffolded as a
+ * neutral option, not a default the user is steered toward.
+ */
+
+const AI_BOTS = {
+  training: [
+    'GPTBot',
+    'ClaudeBot',
+    'Google-Extended',
+    'anthropic-ai',
+    'CCBot',
+    'Bytespider',
+    'Amazonbot',
+    'Applebot-Extended',
+    'meta-externalagent',
+  ],
+  grounding: ['OAI-SearchBot', 'PerplexityBot', 'Claude-Web'],
+  userDirected: ['ChatGPT-User', 'Claude-User'],
+};
+
+function generateRobotsTxt(origin) {
+  const lines = [];
+  lines.push('# robots.txt — Customs Declaration');
+  lines.push('# Generated by @kirkelabs/agent-readiness-scan.');
+  lines.push('# Review and edit before deploying. Tighten or loosen rules to match');
+  lines.push(
+    '# your stated bargain with AI agents (training vs grounding vs user-directed).',
+  );
+  lines.push('');
+  lines.push('# --- Default allow-all baseline ---');
+  lines.push('User-agent: *');
+  lines.push('Allow: /');
+  lines.push('');
+  lines.push('# --- Training crawlers (use your content to train foundation models) ---');
+  for (const bot of AI_BOTS.training) {
+    lines.push(`User-agent: ${bot}`);
+    lines.push(
+      'Disallow:                       # TODO: set to / to disallow, blank to allow',
+    );
+    lines.push('');
+  }
+  lines.push(
+    '# --- Grounding crawlers (fetch in real time for answer-engine retrieval) ---',
+  );
+  for (const bot of AI_BOTS.grounding) {
+    lines.push(`User-agent: ${bot}`);
+    lines.push('Allow: /');
+    lines.push('');
+  }
+  lines.push('# --- User-directed crawlers (fetched on behalf of a logged-in user) ---');
+  for (const bot of AI_BOTS.userDirected) {
+    lines.push(`User-agent: ${bot}`);
+    lines.push('Allow: /');
+    lines.push('');
+  }
+  lines.push('# --- Cloudflare Content Signals (which uses you permit) ---');
+  lines.push('# See https://contentsignals.org/');
+  lines.push('Content-Signal: search=yes, ai-input=yes, ai-train=no');
+  lines.push('');
+  lines.push(`Sitemap: ${origin}/sitemap.xml`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function generateSecurityTxt() {
+  const expires = new Date();
+  expires.setFullYear(expires.getFullYear() + 1);
+  const lines = [];
+  lines.push('# /.well-known/security.txt — RFC 9116');
+  lines.push('# Generated by @kirkelabs/agent-readiness-scan. Review before deploying.');
+  lines.push('');
+  lines.push('Contact: mailto:security@your-domain.example');
+  lines.push(`Expires: ${expires.toISOString()}`);
+  lines.push('Preferred-Languages: en');
+  lines.push('# Canonical: https://your-domain.example/.well-known/security.txt');
+  lines.push('# Encryption: https://your-domain.example/pgp-key.asc');
+  lines.push('');
+  return lines.join('\n');
+}
+
+function generateMcpServerCard(origin, name) {
+  return JSON.stringify(
+    {
+      $schema: 'https://modelcontextprotocol.io/schemas/server-card/v1',
+      name: name || 'TODO: Your service name',
+      description:
+        'TODO: One-sentence description of what this MCP server lets agents do.',
+      version: '0.1.0',
+      url: `${origin}/mcp`,
+      contact: {
+        name: 'TODO: maintainer',
+        email: 'mcp@your-domain.example',
+      },
+      tools: [
+        {
+          name: 'TODO_tool_name',
+          description: 'TODO: what this tool does',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+      ],
+      authentication: {
+        type: 'oauth2',
+        authorizationEndpoint: `${origin}/oauth/authorize`,
+        tokenEndpoint: `${origin}/oauth/token`,
+        pkce: { codeChallengeMethods: ['S256'] },
+      },
+      // Scoped per-tool authorization via an Open Agent Access policy. This
+      // is an alternative to (or complement of) the OAuth flow above.
+      authorization: {
+        model: 'open-agent-access',
+        policy: `${origin}/.well-known/agent-access.json`,
+      },
+    },
+    null,
+    2,
+  );
+}
+
+function generateAgentAccess(origin, name) {
+  return JSON.stringify(
+    {
+      $schema: 'https://openagentaccess.org/schema/agent-access/v1',
+      version: '0.1',
+      service: { name: name || 'TODO: Your service name', url: origin },
+      // Require a verifiable agent passport before any gated call.
+      defaults: { requireAgentIdentity: true, decision: 'allow' },
+      passport: {
+        required: true,
+        trustedIssuers: ['TODO: agent-passport issuer URL(s)'],
+      },
+      rules: [
+        { match: { purpose: 'read' }, decision: 'allow' },
+        { match: { purpose: 'summarize' }, decision: 'allow' },
+        { match: { purpose: 'ai-train' }, decision: 'deny' },
+        {
+          // A paid, agent-transactable capability settled via x402.
+          match: { tool: 'TODO_paid_tool' },
+          decision: 'charge',
+          payment: {
+            type: 'x402',
+            network: 'algorand',
+            settlement: 'TODO: receiver address / ASA id',
+            amount: 'TODO: price (e.g. "0.50 USDC")',
+          },
+        },
+      ],
+    },
+    null,
+    2,
+  );
+}
+
+function generateAcpManifest(origin, name) {
+  return JSON.stringify(
+    {
+      version: '2026-04-17',
+      merchant: {
+        name: name || 'TODO: Your merchant name',
+        url: origin,
+        contact: 'merchant@your-domain.example',
+      },
+      capabilities: {
+        checkout: { endpoint: `${origin}/acp/checkout`, supportedMethods: ['card'] },
+        productCatalog: { endpoint: `${origin}/acp/products` },
+      },
+      keys: [
+        {
+          kty: 'TODO',
+          kid: 'TODO',
+          alg: 'RS256',
+          use: 'sig',
+          n: 'TODO: base64url-encoded RSA modulus',
+          e: 'AQAB',
+        },
+      ],
+    },
+    null,
+    2,
+  );
+}
+
+function deriveName($, finalUrl) {
+  const t = ($('title').first().text() || '').trim();
+  if (t) return t.split('—')[0].split('|')[0].trim();
+  try {
+    return new URL(finalUrl).hostname.replace(/^www\./, '');
+  } catch {
+    return 'Your Brand';
+  }
+}
+
+export function generateCustomsDeclaration(ctx) {
+  let origin = ctx.finalUrl;
+  try {
+    origin = new URL(ctx.finalUrl).origin;
+  } catch {
+    /* keep */
+  }
+  const name = deriveName(ctx.$, ctx.finalUrl);
+  return {
+    'robots.txt': generateRobotsTxt(origin),
+    '.well-known/security.txt': generateSecurityTxt(),
+    '.well-known/mcp/server-card.json': generateMcpServerCard(origin, name),
+    '.well-known/acp/manifest.json': generateAcpManifest(origin, name),
+    '.well-known/agent-access.json': generateAgentAccess(origin, name),
+  };
+}