@ahtmljs/next 0.1.0

package/dist/policy.js

@@ -0,0 +1,79 @@
+/**
+ * Policy enforcement at the route handler edge.
+ *
+ * AHTML is opt-in. Sites that don't want agents do not install this plugin
+ * and continue to ship HTML behind their existing defenses (CAPTCHA,
+ * Cloudflare, etc). Sites that DO want agents install the plugin and use
+ * this layer to set the terms:
+ *
+ *   - Identity: agents present a user-agent and (optionally) a signed
+ *     identity token from the AI provider.
+ *   - Rate limit: per-IP token bucket.
+ *   - Auth: certain action endpoints require OAuth2 bearer tokens.
+ *
+ * This module ONLY enforces the read side (snapshot fetch). Action
+ * execution is enforced by the host application's own action handlers
+ * — AHTML just publishes the *contract* that says auth is required.
+ */
+const buckets = new Map();
+const ALLOW = {
+    deny: false,
+    response: new Response(null),
+};
+export async function enforcePolicy(req, config) {
+    if (config.policy?.agents_welcome === false) {
+        return deny(403, 'agents_not_welcome', 'this site has not opted into agent traffic');
+    }
+    const limit = parseRateLimit(config.policy?.rate_limit);
+    if (limit) {
+        const key = clientKey(req);
+        const ok = consume(key, limit);
+        if (!ok) {
+            return deny(429, 'rate_limited', `rate limit ${config.policy?.rate_limit} exceeded`);
+        }
+    }
+    return ALLOW;
+}
+function deny(status, code, message) {
+    return {
+        deny: true,
+        response: new Response(JSON.stringify({ error: code, message }), {
+            status,
+            headers: { 'content-type': 'application/json', 'x-ahtml-policy': code },
+        }),
+    };
+}
+function clientKey(req) {
+    const fwd = req.headers.get('x-forwarded-for');
+    const real = req.headers.get('x-real-ip');
+    return (fwd?.split(',')[0]?.trim() || real || 'anon').toLowerCase();
+}
+/** Token bucket. Refills `tokens` per `windowMs`. */
+function consume(key, limit) {
+    const now = Date.now();
+    let b = buckets.get(key);
+    if (!b) {
+        b = { tokens: limit.tokens, last: now };
+        buckets.set(key, b);
+    }
+    const elapsed = now - b.last;
+    const refill = (elapsed / limit.windowMs) * limit.tokens;
+    b.tokens = Math.min(limit.tokens, b.tokens + refill);
+    b.last = now;
+    if (b.tokens < 1)
+        return false;
+    b.tokens -= 1;
+    return true;
+}
+function parseRateLimit(s) {
+    if (!s)
+        return null;
+    const m = s.match(/^(\d+)\/(s|sec|min|hr|hour)$/i);
+    if (!m)
+        return null;
+    const tokens = parseInt(m[1], 10);
+    const unit = m[2].toLowerCase();
+    const windowMs = unit.startsWith('s') ? 1_000 : unit.startsWith('m') ? 60_000 : 3_600_000;
+    return { tokens, windowMs };
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}

package/dist/well-known.d.ts

@@ -0,0 +1,40 @@
+/**
+ * /.well-known/ahtml.json — the site-wide AHTML manifest.
+ *
+ * Tells agents:
+ *   - this site speaks AHTML
+ *   - the policy (terms, rate limit, auth scheme, contact)
+ *   - the route map (what kinds of pages exist + where to fetch their snapshots)
+ *   - where to find the MCP and OpenAPI emissions
+ *
+ * Single source of truth. Agents fetch this ONCE, then resolve any URL
+ * on the site to its snapshot endpoint deterministically.
+ */
+import { type AHTMLConfig } from './index.js';
+export interface WellKnownManifest {
+    ahtml: '0.1';
+    site: string;
+    policy: Record<string, unknown>;
+    snapshot_url_template: string;
+    routes?: Array<{
+        path: string;
+        page_type: string;
+        snapshot_url: string;
+    }>;
+    endpoints: {
+        snapshot: string;
+        diff_param: string;
+        mcp?: string;
+        openapi?: string;
+    };
+    formats: Array<{
+        media_type: string;
+        description: string;
+    }>;
+    generated_at: string;
+}
+export declare function buildManifest(configOverride?: AHTMLConfig): WellKnownManifest;
+export declare function createWellKnownRoute(configOverride?: AHTMLConfig): {
+    GET: (_req: Request) => Response;
+};
+//# sourceMappingURL=well-known.d.ts.map

package/dist/well-known.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known.d.ts","sourceRoot":"","sources":["../src/well-known.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1E,SAAS,EAAE;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,OAAO,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,aAAa,CAAC,cAAc,CAAC,EAAE,WAAW,GAAG,iBAAiB,CA2B7E;AAED,wBAAgB,oBAAoB,CAAC,cAAc,CAAC,EAAE,WAAW;gBAC5C,OAAO,KAAG,QAAQ;EAYtC"}

package/dist/well-known.js

@@ -0,0 +1,56 @@
+/**
+ * /.well-known/ahtml.json — the site-wide AHTML manifest.
+ *
+ * Tells agents:
+ *   - this site speaks AHTML
+ *   - the policy (terms, rate limit, auth scheme, contact)
+ *   - the route map (what kinds of pages exist + where to fetch their snapshots)
+ *   - where to find the MCP and OpenAPI emissions
+ *
+ * Single source of truth. Agents fetch this ONCE, then resolve any URL
+ * on the site to its snapshot endpoint deterministically.
+ */
+import { getConfig } from './index.js';
+export function buildManifest(configOverride) {
+    const cfg = configOverride ?? getConfig();
+    const base = cfg.site.replace(/\/$/, '');
+    const snapshotTemplate = `${base}/ahtml/{path}`;
+    return {
+        ahtml: '0.1',
+        site: base,
+        policy: cfg.policy ?? { agents_welcome: true },
+        snapshot_url_template: snapshotTemplate,
+        routes: cfg.routes?.map((r) => ({
+            path: r.path,
+            page_type: r.page_type,
+            snapshot_url: `${base}/ahtml${r.path.startsWith('/') ? r.path : '/' + r.path}`,
+        })),
+        endpoints: {
+            snapshot: snapshotTemplate,
+            diff_param: 'since',
+            mcp: cfg.emit_mcp !== false ? `${base}/ahtml/mcp.json` : undefined,
+            openapi: cfg.emit_openapi !== false ? `${base}/ahtml/openapi.json` : undefined,
+        },
+        formats: [
+            { media_type: 'application/ahtml+text', description: 'Token-optimal compact text. Default for LLM agents.' },
+            { media_type: 'application/ahtml+json', description: 'Canonical JSON. Use for programmatic consumers and signature verification.' },
+            { media_type: 'application/ahtml-diff+json', description: 'Returned for ?since=<etag> requests; minimal change list.' },
+        ],
+        generated_at: new Date().toISOString(),
+    };
+}
+export function createWellKnownRoute(configOverride) {
+    function GET(_req) {
+        const m = buildManifest(configOverride);
+        return new Response(JSON.stringify(m, null, 2), {
+            status: 200,
+            headers: {
+                'content-type': 'application/json',
+                'cache-control': 'public, max-age=300, must-revalidate',
+                'x-ahtml-version': '0.1',
+            },
+        });
+    }
+    return { GET };
+}
+//# sourceMappingURL=well-known.js.map

package/dist/well-known.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known.js","sourceRoot":"","sources":["../src/well-known.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAoB,MAAM,YAAY,CAAC;AAkBzD,MAAM,UAAU,aAAa,CAAC,cAA4B;IACxD,MAAM,GAAG,GAAG,cAAc,IAAI,SAAS,EAAE,CAAC;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzC,MAAM,gBAAgB,GAAG,GAAG,IAAI,eAAe,CAAC;IAChD,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,IAAI,EAAE,IAAI;QACV,MAAM,EAAG,GAAG,CAAC,MAA6C,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;QACtF,qBAAqB,EAAE,gBAAgB;QACvC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9B,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,YAAY,EAAE,GAAG,IAAI,SAAS,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE;SAC/E,CAAC,CAAC;QACH,SAAS,EAAE;YACT,QAAQ,EAAE,gBAAgB;YAC1B,UAAU,EAAE,OAAO;YACnB,GAAG,EAAE,GAAG,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,iBAAiB,CAAC,CAAC,CAAC,SAAS;YAClE,OAAO,EAAE,GAAG,CAAC,YAAY,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,qBAAqB,CAAC,CAAC,CAAC,SAAS;SAC/E;QACD,OAAO,EAAE;YACP,EAAE,UAAU,EAAE,wBAAwB,EAAE,WAAW,EAAE,qDAAqD,EAAE;YAC5G,EAAE,UAAU,EAAE,wBAAwB,EAAE,WAAW,EAAE,4EAA4E,EAAE;YACnI,EAAE,UAAU,EAAE,6BAA6B,EAAE,WAAW,EAAE,2DAA2D,EAAE;SACxH;QACD,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACvC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,cAA4B;IAC/D,SAAS,GAAG,CAAC,IAAa;QACxB,MAAM,CAAC,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;QACxC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;YAC9C,MAAM,EAAE,GAAG;YACX,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,eAAe,EAAE,sCAAsC;gBACvD,iBAAiB,EAAE,KAAK;aACzB;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,CAAC;AACjB,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ahtmljs/next",
+  "version": "0.1.0",
+  "description": "Next.js plugin for AHTML. Adds /.well-known/ahtml.json, /ahtml/[...path] route handlers, content negotiation, ETag-based incremental fetch, MCP + OpenAPI emitters, and a per-route snapshot builder.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./handler": { "types": "./dist/handler.d.ts", "import": "./dist/handler.js" },
+    "./well-known": { "types": "./dist/well-known.d.ts", "import": "./dist/well-known.js" },
+    "./llms-txt": { "types": "./dist/llms-txt.d.ts", "import": "./dist/llms-txt.js" },
+    "./extractors": { "types": "./dist/extractors/index.d.ts", "import": "./dist/extractors/index.js" },
+    "./mcp": { "types": "./dist/mcp.d.ts", "import": "./dist/mcp.js" },
+    "./openapi": { "types": "./dist/openapi.d.ts", "import": "./dist/openapi.js" }
+  },
+  "files": ["dist"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "dependencies": {
+    "@ahtmljs/schema": "0.1.0"
+  },
+  "peerDependencies": {
+    "next": ">=14"
+  },
+  "peerDependenciesMeta": {
+    "next": { "optional": true }
+  },
+  "license": "MIT"
+}