@agents-txt/express 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agents-txt contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,135 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  RateLimiter: () => RateLimiter,
+  agentsTxt: () => agentsTxt
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/middleware.ts
+var import_core = require("@agents-txt/core");
+
+// src/rate-limiter.ts
+var RateLimiter = class {
+  windows = /* @__PURE__ */ new Map();
+  cleanupTimer;
+  windowMs;
+  defaultLimit;
+  maxEntries;
+  constructor(options = {}) {
+    this.windowMs = options.windowMs ?? 6e4;
+    this.defaultLimit = options.defaultLimit ?? 60;
+    this.maxEntries = options.maxEntries ?? 1e4;
+    this.cleanupTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [key, entry] of this.windows) {
+        entry.timestamps = entry.timestamps.filter((t) => now - t < this.windowMs);
+        if (entry.timestamps.length === 0) this.windows.delete(key);
+      }
+    }, options.cleanupIntervalMs ?? 6e4);
+  }
+  check(key, limit) {
+    const effectiveLimit = limit ?? this.defaultLimit;
+    const now = Date.now();
+    if (!this.windows.has(key) && this.windows.size >= this.maxEntries) {
+      return { allowed: false, remaining: 0, retryAfterMs: this.windowMs };
+    }
+    let entry = this.windows.get(key);
+    if (!entry) {
+      entry = { timestamps: [] };
+      this.windows.set(key, entry);
+    }
+    entry.timestamps = entry.timestamps.filter((t) => now - t < this.windowMs);
+    if (entry.timestamps.length >= effectiveLimit) {
+      const retryAfterMs = this.windowMs - (now - entry.timestamps[0]);
+      return { allowed: false, remaining: 0, retryAfterMs };
+    }
+    entry.timestamps.push(now);
+    return { allowed: true, remaining: effectiveLimit - entry.timestamps.length };
+  }
+  destroy() {
+    clearInterval(this.cleanupTimer);
+    this.windows.clear();
+  }
+};
+
+// src/middleware.ts
+function agentsTxt(options) {
+  const doc = {
+    specVersion: "1.0",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    site: options.site,
+    capabilities: options.capabilities,
+    access: options.access ?? { allow: ["*"], disallow: [] },
+    agents: options.agents ?? { "*": {} }
+  };
+  const txtContent = (0, import_core.generate)(doc);
+  const jsonContent = (0, import_core.generateJSON)(doc);
+  const txtPath = options.paths?.txt ?? "/.well-known/agents.txt";
+  const jsonPath = options.paths?.json ?? "/.well-known/agents.json";
+  const rateLimiter = options.rateLimit !== false ? new RateLimiter({ defaultLimit: (options.rateLimit && options.rateLimit.defaultLimit) ?? 60 }) : null;
+  const corsOrigins = options.corsOrigins ?? ["*"];
+  return function agentsTxtMiddleware(req, res, next) {
+    if (req.path !== txtPath && req.path !== jsonPath) {
+      next();
+      return;
+    }
+    const origin = req.headers.origin;
+    if (corsOrigins.includes("*")) {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+    } else if (origin && corsOrigins.includes(origin)) {
+      res.setHeader("Access-Control-Allow-Origin", origin);
+    }
+    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+    res.setHeader("Vary", "Origin");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("X-Frame-Options", "DENY");
+    if (req.method === "OPTIONS") {
+      res.status(204).end();
+      return;
+    }
+    if (rateLimiter) {
+      const ip = req.ip ?? req.socket?.remoteAddress ?? "unknown";
+      const result = rateLimiter.check(ip);
+      res.setHeader("X-RateLimit-Remaining", String(result.remaining));
+      if (!result.allowed) {
+        res.setHeader("Retry-After", String(Math.ceil((result.retryAfterMs || 6e4) / 1e3)));
+        res.status(429).json({ error: "Rate limit exceeded" });
+        return;
+      }
+    }
+    if (req.path === txtPath) {
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.setHeader("Cache-Control", "public, max-age=300");
+      res.send(txtContent);
+    } else {
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.setHeader("Cache-Control", "public, max-age=300");
+      res.send(jsonContent);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RateLimiter,
+  agentsTxt
+});

package/dist/index.d.cts

@@ -0,0 +1,53 @@
+import { SiteInfo, Capability, AccessControl, AgentPolicy } from '@agents-txt/core';
+import { Request, Response, NextFunction } from 'express';
+
+interface AgentsTxtOptions {
+    /** Site identity. */
+    site: SiteInfo;
+    /** Capabilities to declare. */
+    capabilities: Capability[];
+    /** Access control rules. Default: allow all. */
+    access?: AccessControl;
+    /** Per-agent policies. Default: wildcard. */
+    agents?: Record<string, AgentPolicy>;
+    /** Rate limiting options. Set to false to disable. */
+    rateLimit?: {
+        enabled?: boolean;
+        defaultLimit?: number;
+    } | false;
+    /** Allowed CORS origins. Default: ["*"]. */
+    corsOrigins?: string[];
+    /** Serve paths. Default: /.well-known/agents.txt and /.well-known/agents.json */
+    paths?: {
+        txt?: string;
+        json?: string;
+    };
+}
+declare function agentsTxt(options: AgentsTxtOptions): (req: Request, res: Response, next: NextFunction) => void;
+
+interface RateLimiterOptions {
+    /** Default requests per window. Default: 60. */
+    defaultLimit?: number;
+    /** Window size in ms. Default: 60000 (1 minute). */
+    windowMs?: number;
+    /** Cleanup interval in ms. Default: 60000. */
+    cleanupIntervalMs?: number;
+    /** Max tracked keys (OOM protection). Default: 10000. */
+    maxEntries?: number;
+}
+declare class RateLimiter {
+    private windows;
+    private cleanupTimer;
+    private windowMs;
+    private defaultLimit;
+    private maxEntries;
+    constructor(options?: RateLimiterOptions);
+    check(key: string, limit?: number): {
+        allowed: boolean;
+        remaining: number;
+        retryAfterMs?: number;
+    };
+    destroy(): void;
+}
+
+export { type AgentsTxtOptions, RateLimiter, type RateLimiterOptions, agentsTxt };

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { SiteInfo, Capability, AccessControl, AgentPolicy } from '@agents-txt/core';
+import { Request, Response, NextFunction } from 'express';
+
+interface AgentsTxtOptions {
+    /** Site identity. */
+    site: SiteInfo;
+    /** Capabilities to declare. */
+    capabilities: Capability[];
+    /** Access control rules. Default: allow all. */
+    access?: AccessControl;
+    /** Per-agent policies. Default: wildcard. */
+    agents?: Record<string, AgentPolicy>;
+    /** Rate limiting options. Set to false to disable. */
+    rateLimit?: {
+        enabled?: boolean;
+        defaultLimit?: number;
+    } | false;
+    /** Allowed CORS origins. Default: ["*"]. */
+    corsOrigins?: string[];
+    /** Serve paths. Default: /.well-known/agents.txt and /.well-known/agents.json */
+    paths?: {
+        txt?: string;
+        json?: string;
+    };
+}
+declare function agentsTxt(options: AgentsTxtOptions): (req: Request, res: Response, next: NextFunction) => void;
+
+interface RateLimiterOptions {
+    /** Default requests per window. Default: 60. */
+    defaultLimit?: number;
+    /** Window size in ms. Default: 60000 (1 minute). */
+    windowMs?: number;
+    /** Cleanup interval in ms. Default: 60000. */
+    cleanupIntervalMs?: number;
+    /** Max tracked keys (OOM protection). Default: 10000. */
+    maxEntries?: number;
+}
+declare class RateLimiter {
+    private windows;
+    private cleanupTimer;
+    private windowMs;
+    private defaultLimit;
+    private maxEntries;
+    constructor(options?: RateLimiterOptions);
+    check(key: string, limit?: number): {
+        allowed: boolean;
+        remaining: number;
+        retryAfterMs?: number;
+    };
+    destroy(): void;
+}
+
+export { type AgentsTxtOptions, RateLimiter, type RateLimiterOptions, agentsTxt };

package/dist/index.js

@@ -0,0 +1,107 @@
+// src/middleware.ts
+import { generate, generateJSON } from "@agents-txt/core";
+
+// src/rate-limiter.ts
+var RateLimiter = class {
+  windows = /* @__PURE__ */ new Map();
+  cleanupTimer;
+  windowMs;
+  defaultLimit;
+  maxEntries;
+  constructor(options = {}) {
+    this.windowMs = options.windowMs ?? 6e4;
+    this.defaultLimit = options.defaultLimit ?? 60;
+    this.maxEntries = options.maxEntries ?? 1e4;
+    this.cleanupTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [key, entry] of this.windows) {
+        entry.timestamps = entry.timestamps.filter((t) => now - t < this.windowMs);
+        if (entry.timestamps.length === 0) this.windows.delete(key);
+      }
+    }, options.cleanupIntervalMs ?? 6e4);
+  }
+  check(key, limit) {
+    const effectiveLimit = limit ?? this.defaultLimit;
+    const now = Date.now();
+    if (!this.windows.has(key) && this.windows.size >= this.maxEntries) {
+      return { allowed: false, remaining: 0, retryAfterMs: this.windowMs };
+    }
+    let entry = this.windows.get(key);
+    if (!entry) {
+      entry = { timestamps: [] };
+      this.windows.set(key, entry);
+    }
+    entry.timestamps = entry.timestamps.filter((t) => now - t < this.windowMs);
+    if (entry.timestamps.length >= effectiveLimit) {
+      const retryAfterMs = this.windowMs - (now - entry.timestamps[0]);
+      return { allowed: false, remaining: 0, retryAfterMs };
+    }
+    entry.timestamps.push(now);
+    return { allowed: true, remaining: effectiveLimit - entry.timestamps.length };
+  }
+  destroy() {
+    clearInterval(this.cleanupTimer);
+    this.windows.clear();
+  }
+};
+
+// src/middleware.ts
+function agentsTxt(options) {
+  const doc = {
+    specVersion: "1.0",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    site: options.site,
+    capabilities: options.capabilities,
+    access: options.access ?? { allow: ["*"], disallow: [] },
+    agents: options.agents ?? { "*": {} }
+  };
+  const txtContent = generate(doc);
+  const jsonContent = generateJSON(doc);
+  const txtPath = options.paths?.txt ?? "/.well-known/agents.txt";
+  const jsonPath = options.paths?.json ?? "/.well-known/agents.json";
+  const rateLimiter = options.rateLimit !== false ? new RateLimiter({ defaultLimit: (options.rateLimit && options.rateLimit.defaultLimit) ?? 60 }) : null;
+  const corsOrigins = options.corsOrigins ?? ["*"];
+  return function agentsTxtMiddleware(req, res, next) {
+    if (req.path !== txtPath && req.path !== jsonPath) {
+      next();
+      return;
+    }
+    const origin = req.headers.origin;
+    if (corsOrigins.includes("*")) {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+    } else if (origin && corsOrigins.includes(origin)) {
+      res.setHeader("Access-Control-Allow-Origin", origin);
+    }
+    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+    res.setHeader("Vary", "Origin");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("X-Frame-Options", "DENY");
+    if (req.method === "OPTIONS") {
+      res.status(204).end();
+      return;
+    }
+    if (rateLimiter) {
+      const ip = req.ip ?? req.socket?.remoteAddress ?? "unknown";
+      const result = rateLimiter.check(ip);
+      res.setHeader("X-RateLimit-Remaining", String(result.remaining));
+      if (!result.allowed) {
+        res.setHeader("Retry-After", String(Math.ceil((result.retryAfterMs || 6e4) / 1e3)));
+        res.status(429).json({ error: "Rate limit exceeded" });
+        return;
+      }
+    }
+    if (req.path === txtPath) {
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.setHeader("Cache-Control", "public, max-age=300");
+      res.send(txtContent);
+    } else {
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.setHeader("Cache-Control", "public, max-age=300");
+      res.send(jsonContent);
+    }
+  };
+}
+export {
+  RateLimiter,
+  agentsTxt
+};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@agents-txt/express",
+  "version": "0.1.0",
+  "description": "Express middleware for serving agents.txt — one line to make your site AI-agent ready",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "agents.txt",
+    "agents-txt",
+    "ai-agents",
+    "express",
+    "middleware",
+    "llm",
+    "mcp",
+    "well-known",
+    "robots-txt",
+    "capability-declaration",
+    "web-standard",
+    "anthropic",
+    "claude",
+    "openai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kaylacar/agents-txt.git",
+    "directory": "packages/express"
+  },
+  "homepage": "https://github.com/kaylacar/agents-txt",
+  "bugs": {
+    "url": "https://github.com/kaylacar/agents-txt/issues"
+  },
+  "dependencies": {
+    "@agents-txt/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "express": "^5.1.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}