@agentronics/sdk 0.6.0 → 0.7.0

package/dist/{chunk-X7NFMFN6.js → chunk-6QQS26AP.js}

@@ -1,12 +1,105 @@
+// src/server/ipRanges.ts
+var PUBLISHED_IP_RANGES = {
+  GPTBot: ["https://openai.com/gptbot.json"],
+  "OAI-SearchBot": ["https://openai.com/searchbot.json"],
+  "ChatGPT-User": ["https://openai.com/chatgpt-user.json"],
+  PerplexityBot: ["https://www.perplexity.ai/perplexitybot.json"],
+  "Perplexity-User": ["https://www.perplexity.ai/perplexity-user.json"],
+  Googlebot: ["https://developers.google.com/static/crawling/ipranges/common-crawlers.json"],
+  Bingbot: ["https://www.bing.com/toolbox/bingbot.json"],
+  DuckDuckBot: ["https://duckduckgo.com/duckduckbot.json"],
+  CCBot: ["https://index.commoncrawl.org/ccbot.json"]
+};
+var TTL_MS = 24 * 36e5;
+var FAILED_TTL_MS = 10 * 6e4;
+var cache = /* @__PURE__ */ new Map();
+async function loadUrl(url, fetcher) {
+  const hit = cache.get(url);
+  if (hit && hit.until > Date.now()) return hit.cidrs;
+  try {
+    const res = await fetcher(url, { signal: AbortSignal.timeout(5e3), redirect: "follow" });
+    if (!res.ok) throw new Error(String(res.status));
+    const body = await res.json();
+    const cidrs = (body.prefixes ?? []).flatMap((p) => [p.ipv4Prefix, p.ipv6Prefix]).filter((c) => typeof c === "string");
+    cache.set(url, { cidrs, until: Date.now() + TTL_MS });
+    return cidrs;
+  } catch {
+    const cidrs = hit?.cidrs ?? [];
+    cache.set(url, { cidrs, until: Date.now() + FAILED_TTL_MS });
+    return cidrs;
+  }
+}
+async function rangesFor(name, options = {}) {
+  const fixed = options.ipRanges?.[name];
+  if (fixed) return fixed;
+  const urls = PUBLISHED_IP_RANGES[name];
+  if (!urls) return null;
+  const fetcher = options.fetcher ?? fetch;
+  return (await Promise.all(urls.map((u) => loadUrl(u, fetcher)))).flat();
+}
+function v4ToBigInt(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let n = 0n;
+  for (const p of parts) {
+    if (!/^\d{1,3}$/.test(p) || Number(p) > 255) return null;
+    n = n << 8n | BigInt(p);
+  }
+  return n;
+}
+function v6ToBigInt(ip) {
+  let s = ip.toLowerCase().replace(/^\[|\]$/g, "");
+  const zone = s.indexOf("%");
+  if (zone >= 0) s = s.slice(0, zone);
+  const v4 = s.match(/(\d+\.\d+\.\d+\.\d+)$/);
+  if (v4) {
+    const n2 = v4ToBigInt(v4[1]);
+    if (n2 === null) return null;
+    s = s.slice(0, -v4[1].length) + (n2 >> 16n & 0xffffn).toString(16) + ":" + (n2 & 0xffffn).toString(16);
+  }
+  const halves = s.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(":") : [];
+  const tail = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+  const missing = 8 - head.length - tail.length;
+  if (halves.length === 1 ? missing !== 0 : missing < 1) return null;
+  const groups = [...head, ...Array(halves.length === 2 ? missing : 0).fill("0"), ...tail];
+  let n = 0n;
+  for (const g of groups) {
+    if (!/^[0-9a-f]{1,4}$/.test(g)) return null;
+    n = n << 16n | BigInt(parseInt(g, 16));
+  }
+  return n;
+}
+function ipInCidr(ip, cidr) {
+  const [range, bitsRaw] = cidr.split("/");
+  if (!range) return false;
+  const isV6 = range.includes(":");
+  const mapped = ip.toLowerCase().match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  const candidate = !isV6 && mapped ? mapped[1] : ip;
+  const width = isV6 ? 128 : 32;
+  const bits = bitsRaw === void 0 ? width : Number(bitsRaw);
+  if (!Number.isInteger(bits) || bits < 0 || bits > width) return false;
+  const a = isV6 ? v6ToBigInt(candidate) : v4ToBigInt(candidate);
+  const b = isV6 ? v6ToBigInt(range) : v4ToBigInt(range);
+  if (a === null || b === null) return false;
+  const shift = BigInt(width - bits);
+  return a >> shift === b >> shift;
+}
+var ipInRanges = (ip, cidrs) => cidrs.some((c) => ipInCidr(ip, c));
+
 // src/detection/crawler.ts
 var CRAWLER_SIGNATURES = [
   // AI / LLM crawlers
   { name: "GPTBot", category: "ai", pattern: /GPTBot/i },
   { name: "OAI-SearchBot", category: "ai", pattern: /OAI-SearchBot/i },
   { name: "ChatGPT-User", category: "ai", pattern: /ChatGPT-User/i },
+  { name: "Claude-User", category: "ai", pattern: /Claude-User/i },
+  { name: "Claude-SearchBot", category: "ai", pattern: /Claude-SearchBot/i },
   { name: "ClaudeBot", category: "ai", pattern: /ClaudeBot/i },
   { name: "Claude-Web", category: "ai", pattern: /Claude-Web/i },
   { name: "anthropic-ai", category: "ai", pattern: /anthropic-ai/i },
+  { name: "Perplexity-User", category: "ai", pattern: /Perplexity-User/i },
   { name: "PerplexityBot", category: "ai", pattern: /PerplexityBot/i },
   { name: "Google-Extended", category: "ai", pattern: /Google-Extended/i },
   { name: "Applebot-Extended", category: "ai", pattern: /Applebot-Extended/i },
@@ -62,14 +155,19 @@ async function nodeResolver() {
   }
 }
 var rdnsCache = /* @__PURE__ */ new Map();
-async function verifyCrawler(claim, ip, resolver) {
+async function verifyCrawler(claim, ip, resolver, ranges = {}) {
   const domains = RDNS_DOMAINS[claim.name];
-  if (!domains) return { status: "unverified", name: claim.name, reason: "no_rdns_method_for_vendor" };
+  const cidrs = await rangesFor(claim.name, ranges);
+  if (!domains && !cidrs) return { status: "unverified", name: claim.name, reason: "no_verification_method_for_vendor" };
   if (!ip) return { status: "unverified", name: claim.name, reason: "client_ip_unknown" };
+  if (cidrs?.length && ipInRanges(ip, cidrs)) {
+    return { status: "verified", name: claim.name, host: ip, ip, via: "ip-range" };
+  }
+  if (!domains) return { status: "unverified", name: claim.name, reason: "ip_outside_published_ranges" };
   const key = `${claim.name}|${ip}`;
   const hit = rdnsCache.get(key);
   if (hit && hit.until > Date.now()) {
-    return hit.ok ? { status: "verified", name: claim.name, host: hit.host, ip } : { status: "unverified", name: claim.name, reason: "rdns_mismatch" };
+    return hit.ok ? { status: "verified", name: claim.name, host: hit.host, ip, via: "rdns" } : { status: "unverified", name: claim.name, reason: "rdns_mismatch" };
   }
   const dns = resolver ?? await nodeResolver();
   if (!dns) return { status: "unverified", name: claim.name, reason: "dns_unavailable_in_runtime" };
@@ -85,7 +183,7 @@ async function verifyCrawler(claim, ip, resolver) {
       const forward = await dns.lookup(host);
       if (forward.includes(ip)) {
         remember(true, host);
-        return { status: "verified", name: claim.name, host, ip };
+        return { status: "verified", name: claim.name, host, ip, via: "rdns" };
       }
     }
     remember(false);
@@ -318,6 +416,135 @@ function bytesToBase64(bytes) {
 }
 var bytesToBase64Url = (bytes) => bytesToBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 
+// src/server/oauth.ts
+var josePromise;
+var loadJose = () => josePromise ??= import('jose');
+var remoteSets = /* @__PURE__ */ new Map();
+var ASYMMETRIC = ["RS256", "PS256", "ES256", "EdDSA"];
+function unverifiedIssuer(token) {
+  try {
+    const payload = token.split(".")[1];
+    const json = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
+    const iss = JSON.parse(json).iss;
+    return typeof iss === "string" ? iss : null;
+  } catch {
+    return null;
+  }
+}
+var str = (v) => typeof v === "string" && v ? v : void 0;
+async function sha256B64u(text) {
+  const d = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+  return bytesToBase64Url(new Uint8Array(d));
+}
+var htuOf = (url) => {
+  const u = new URL(url);
+  return `${u.origin}${u.pathname}`;
+};
+async function verifyDpopProof(jose, proof, token, jkt, request, replay) {
+  try {
+    const { payload, protectedHeader } = await jose.jwtVerify(proof, jose.EmbeddedJWK, {
+      typ: "dpop+jwt",
+      algorithms: ASYMMETRIC
+    });
+    const jwk = protectedHeader.jwk;
+    if (!jwk) return "dpop_missing_jwk";
+    if (await jose.calculateJwkThumbprint(jwk, "sha256") !== jkt) return "dpop_key_mismatch";
+    if (str(payload.htm)?.toUpperCase() !== request.method.toUpperCase()) return "dpop_htm_mismatch";
+    if (str(payload.htu) === void 0 || htuOf(str(payload.htu)) !== htuOf(request.url)) return "dpop_htu_mismatch";
+    const iat = typeof payload.iat === "number" ? payload.iat : NaN;
+    if (!Number.isFinite(iat) || Math.abs(Date.now() / 1e3 - iat) > 300) return "dpop_stale";
+    if (str(payload.ath) !== await sha256B64u(token)) return "dpop_ath_mismatch";
+    const jti = str(payload.jti);
+    if (!jti) return "dpop_missing_jti";
+    if (replay) {
+      const key = `dpop:${jkt}:${jti}`;
+      if (await replay.has(key)) return "dpop_replayed";
+      await replay.add(key, 600);
+    }
+    return null;
+  } catch (e) {
+    return `dpop_invalid:${e.code ?? e.message}`;
+  }
+}
+async function verifyOAuthToken(token, o, ctx) {
+  const jose = await loadJose();
+  const keySet = o.jwks ? jose.createLocalJWKSet(o.jwks) : (() => {
+    const uri = o.jwksUri ?? `${o.issuer.replace(/\/$/, "")}/.well-known/jwks.json`;
+    let s = remoteSets.get(uri);
+    if (!s) {
+      s = jose.createRemoteJWKSet(new URL(uri), { cacheMaxAge: 36e5, cooldownDuration: 3e4 });
+      remoteSets.set(uri, s);
+    }
+    return s;
+  })();
+  let payload;
+  try {
+    ;
+    ({ payload } = await jose.jwtVerify(token, keySet, {
+      issuer: o.issuer,
+      audience: o.audience,
+      algorithms: o.algorithms ?? ASYMMETRIC,
+      clockTolerance: o.clockToleranceSec ?? 30
+    }));
+  } catch (e) {
+    return { error: `invalid_token:${e.code ?? e.message}` };
+  }
+  const jkt = str(payload.cnf?.jkt);
+  let dpop = false;
+  if (jkt) {
+    const proof = ctx.request.headers.get("dpop");
+    if (ctx.scheme !== "dpop" || !proof) return { error: "dpop_proof_required" };
+    const bad = await verifyDpopProof(jose, proof, token, jkt, ctx.request, ctx.replayCache);
+    if (bad) return { error: bad };
+    dpop = true;
+  } else if (o.requireDpop) {
+    return { error: "token_not_dpop_bound" };
+  }
+  if (o.requiredScopes?.length) {
+    const granted = new Set(String(payload.scope ?? payload.scp ?? "").split(/\s+/));
+    const missing = o.requiredScopes.filter((s) => !granted.has(s));
+    if (missing.length) return { error: `missing_scopes:${missing.join(",")}` };
+  }
+  const act = payload.act;
+  const clientId = str(payload.client_id) ?? str(payload.azp);
+  const sub = str(payload.sub);
+  const agentId = str(act?.client_id) ?? str(act?.sub) ?? clientId ?? sub;
+  if (!agentId) return { error: "token_has_no_client_id" };
+  const user = act ? sub : sub && clientId && sub !== clientId ? sub : void 0;
+  const agent = {
+    id: `oauth2:${agentId}`,
+    name: str(payload.agent_name) ?? str(payload.client_name) ?? agentId,
+    vendor: str(payload.agent_vendor) ?? null,
+    claims: { iss: payload.iss, sub, scope: payload.scope ?? payload.scp, ...act ? { act } : {} },
+    dpop
+  };
+  if (user) {
+    const onBehalfOf = { sub: user };
+    if (str(payload.email)) onBehalfOf.email = str(payload.email);
+    if (str(payload.name)) onBehalfOf.name = str(payload.name);
+    agent.onBehalfOf = onBehalfOf;
+  }
+  return agent;
+}
+var PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+function protectedResourceMetadata(o) {
+  return {
+    resource: o.resource,
+    authorization_servers: o.authorizationServers,
+    bearer_methods_supported: ["header"],
+    ...o.scopesSupported ? { scopes_supported: o.scopesSupported } : {},
+    ...o.resourceName ? { resource_name: o.resourceName } : {},
+    ...o.dpop === false ? {} : { dpop_signing_alg_values_supported: ["ES256", "EdDSA", "RS256", "PS256"] }
+  };
+}
+function oauthChallenge(resource, opts = {}) {
+  const meta = `${resource.replace(/\/$/, "")}${PROTECTED_RESOURCE_PATH}`;
+  const parts = [`resource_metadata="${meta}"`];
+  if (opts.error) parts.push(`error="${opts.error}"`);
+  if (opts.scope) parts.push(`scope="${opts.scope}"`);
+  return `Bearer ${parts.join(", ")}`;
+}
+
 // src/server/httpSignatures.ts
 var SignatureError = class extends Error {
   constructor(code, message) {
@@ -756,61 +983,15 @@ var KNOWN_SIGNERS = {
 };
 var GENERIC_AGENT_UA = /\b(bot|crawler|spider|agent|headless|scraper)\b/i;
 var JWT_SHAPE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*$/;
-function bearer(request) {
+function credential(request) {
   const h = request.headers.get("authorization");
-  return h && /^bearer\s+/i.test(h) ? h.replace(/^bearer\s+/i, "").trim() : null;
-}
-function unverifiedJwtIssuer(token) {
-  try {
-    const payload = token.split(".")[1];
-    const json = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
-    const iss = JSON.parse(json).iss;
-    return typeof iss === "string" ? iss : null;
-  } catch {
-    return null;
-  }
-}
-var josePromise;
-var remoteSets = /* @__PURE__ */ new Map();
-async function verifyOAuth2(token, o) {
-  josePromise ??= import('jose');
-  const jose = await josePromise;
-  const keySet = o.jwks ? jose.createLocalJWKSet(o.jwks) : (() => {
-    const uri = o.jwksUri ?? `${o.issuer.replace(/\/$/, "")}/.well-known/jwks.json`;
-    let s = remoteSets.get(uri);
-    if (!s) {
-      s = jose.createRemoteJWKSet(new URL(uri), { cacheMaxAge: 36e5, cooldownDuration: 3e4 });
-      remoteSets.set(uri, s);
-    }
-    return s;
-  })();
-  try {
-    const { payload } = await jose.jwtVerify(token, keySet, {
-      issuer: o.issuer,
-      audience: o.audience,
-      algorithms: o.algorithms ?? ["RS256", "PS256", "ES256", "EdDSA"],
-      clockTolerance: o.clockToleranceSec ?? 30
-    });
-    if (o.requiredScopes?.length) {
-      const granted = new Set(String(payload.scope ?? payload.scp ?? "").split(/\s+/));
-      const missing = o.requiredScopes.filter((s) => !granted.has(s));
-      if (missing.length) return { error: `missing_scopes:${missing.join(",")}` };
-    }
-    const clientId = String(payload.client_id ?? payload.azp ?? payload.sub ?? "");
-    if (!clientId) return { error: "token_has_no_client_id" };
-    return {
-      id: `oauth2:${clientId}`,
-      name: typeof payload.agent_name === "string" ? payload.agent_name : clientId,
-      vendor: typeof payload.agent_vendor === "string" ? payload.agent_vendor : null,
-      method: "oauth2",
-      claims: { sub: payload.sub, scope: payload.scope ?? payload.scp }
-    };
-  } catch (e) {
-    return { error: `invalid_token:${e.code ?? e.message}` };
-  }
+  const m = h?.match(/^(bearer|dpop)\s+(.+)$/i);
+  return m ? { token: m[2].trim(), scheme: m[1].toLowerCase() } : null;
 }
 function createAgentAuth(options = {}) {
-  const wba = options.webBotAuth === false ? null : { replayCache: memoryReplayCache(), ...typeof options.webBotAuth === "object" ? options.webBotAuth : {} };
+  const replayCache = options.replayCache ?? memoryReplayCache();
+  const wba = options.webBotAuth === false ? null : { replayCache, ...typeof options.webBotAuth === "object" ? options.webBotAuth : {} };
+  const issuers = options.oauth2 ? Array.isArray(options.oauth2) ? options.oauth2 : [options.oauth2] : [];
   const crawlers = options.crawlers === false ? null : typeof options.crawlers === "object" ? options.crawlers : {};
   const keyPrefix = options.apiKey?.prefix ?? "agk_";
   async function authenticate(request) {
@@ -839,7 +1020,8 @@ function createAgentAuth(options = {}) {
         claimedName ??= r.agentUrl ? new URL(r.agentUrl).hostname : void 0;
       }
     }
-    const token = bearer(request) ?? request.headers.get("x-agent-key");
+    const cred = credential(request);
+    const token = cred?.token ?? request.headers.get("x-agent-key");
     if (token && options.apiKey && token.startsWith(keyPrefix)) {
       attempted.push("api-key");
       const id = await options.apiKey.verify(token);
@@ -856,12 +1038,23 @@ function createAgentAuth(options = {}) {
         };
       }
       reasons.push("api-key:unknown_or_revoked");
-    } else if (token && options.oauth2 && JWT_SHAPE.test(token)) {
-      const iss = unverifiedJwtIssuer(token);
-      if (iss === options.oauth2.issuer) {
+    } else if (cred && issuers.length && JWT_SHAPE.test(cred.token)) {
+      const iss = unverifiedIssuer(cred.token);
+      const config = issuers.find((i) => i.issuer === iss);
+      if (config) {
         attempted.push("oauth2");
-        const r = await verifyOAuth2(token, options.oauth2);
-        if (!("error" in r)) return { status: "verified", agent: r };
+        const r = await verifyOAuthToken(cred.token, config, { request, scheme: cred.scheme, replayCache });
+        if (!("error" in r)) {
+          const agent = {
+            id: r.id,
+            name: r.name,
+            vendor: r.vendor,
+            method: "oauth2",
+            claims: { ...r.claims, dpop: r.dpop }
+          };
+          if (r.onBehalfOf) agent.onBehalfOf = r.onBehalfOf;
+          return { status: "verified", agent };
+        }
         reasons.push(`oauth2:${r.error}`);
       }
     }
@@ -871,11 +1064,11 @@ function createAgentAuth(options = {}) {
       claimedName ??= claim.name;
       if (crawlers) {
         attempted.push("verified-crawler");
-        const v = await verifyCrawler(claim, clientIp(request, crawlers.clientIp), crawlers.resolver);
+        const v = await verifyCrawler(claim, clientIp(request, crawlers.clientIp), crawlers.resolver, crawlers);
         if (v.status === "verified") {
           return {
             status: "verified",
-            agent: { id: `crawler:${claim.name}`, name: claim.name, vendor: null, method: "verified-crawler", claims: { host: v.host } }
+            agent: { id: `crawler:${claim.name}`, name: claim.name, vendor: null, method: "verified-crawler", claims: { host: v.host, via: v.via } }
           };
         }
         reasons.push(`crawler:${v.reason}`);
@@ -936,6 +1129,7 @@ function toTraceEvent(result, ctx) {
   if (result.status === "none") return null;
   const url = new URL(ctx.request.url);
   const verified = result.status === "verified";
+  const delegated = verified && Boolean(result.agent.onBehalfOf);
   return {
     id: `evt_${crypto.randomUUID()}`,
     siteId: ctx.siteId,
@@ -944,12 +1138,13 @@ function toTraceEvent(result, ctx) {
     type: "auth.identity_presented",
     agent: {
       class: "crawler",
-      trust: verified ? "verified" : "declared",
+      // Unverified claims stay "declared"; a token acting for a signed-in user is "linked".
+      trust: delegated ? "linked" : verified ? "verified" : "declared",
       confidence: verified ? 1 : 0.5,
       vendor: verified ? result.agent.vendor ?? result.agent.name : result.claimedName ?? null,
       userAgent: ctx.request.headers.get("user-agent"),
       detectionVersion: "2026.09",
-      signals: { surface: "server" }
+      signals: { surface: "server", ...verified ? { method: result.agent.method } : {} }
     },
     outcome: verified ? "success" : "error",
     ...verified ? {} : { error: result.reason },
@@ -1000,6 +1195,6 @@ function expressAgentAuth(options = {}) {
   };
 }
 
-export { AGENT_HEADERS, DIRECTORY_PATH, RDNS_DOMAINS, WEB_BOT_AUTH_TAG, classifyUserAgent, clientIp, createAgentAuth, createAgentAuthHandler, expressAgentAuth, generateAgentKey, hashAgentKey, jwkThumbprint, memoryReplayCache, readAgentHeaders, signatureBase, staticKeyVerifier, toTraceEvent, verifyCrawler, verifyWebBotAuth, withAgentHeaders };
-//# sourceMappingURL=chunk-X7NFMFN6.js.map
-//# sourceMappingURL=chunk-X7NFMFN6.js.map
+export { AGENT_HEADERS, DIRECTORY_PATH, PROTECTED_RESOURCE_PATH, PUBLISHED_IP_RANGES, RDNS_DOMAINS, WEB_BOT_AUTH_TAG, classifyUserAgent, clientIp, createAgentAuth, createAgentAuthHandler, expressAgentAuth, generateAgentKey, hashAgentKey, ipInCidr, ipInRanges, jwkThumbprint, memoryReplayCache, oauthChallenge, protectedResourceMetadata, rangesFor, readAgentHeaders, signatureBase, staticKeyVerifier, toTraceEvent, verifyCrawler, verifyOAuthToken, verifyWebBotAuth, withAgentHeaders };
+//# sourceMappingURL=chunk-6QQS26AP.js.map
+//# sourceMappingURL=chunk-6QQS26AP.js.map