agentkey-ai 1.2.0 → 1.2.1

package/agentkey.js

@@ -20,7 +20,7 @@ const TIMEOUT_MS = 5000;
 
 // Production API. Override with baseUrl only if you self-host.
 export const DEFAULT_BASE_URL = "https://agentkey.base44.app";
-export const VERSION = "1.2.0";
+export const VERSION = "1.2.1";
 const USER_AGENT = `agentkey-sdk-js/${VERSION}`;
 
 // Process-wide flag so the first-run info block prints once per process.

package/cli.mjs

@@ -34,8 +34,67 @@ function step(ok, label, detail, nextStep) {
   return ok;
 }
 
-// Any HTTP response (including 401/400) proves the endpoint is reachable.
-// Only a network-level failure (DNS, timeout, refused) means unreachable.
+// A warning is not a pass mark: doctor prints " ! " and exits non-zero when
+// one appears. Used for the edge-firewall block, a broken setup that must
+// not read as healthy.
+function stepWarn(label, detail, nextStep) {
+  console.log(` ! ${label}${detail ? ` - ${detail}` : ""}`);
+  if (nextStep) console.log(`   → ${nextStep}`);
+  return false;
+}
+
+// The backend host is internal plumbing: output shows a friendly alias, and
+// the raw host appears only when AGENTKEY_DEBUG is set.
+const API_ALIAS = "AgentKey API";
+const displayTarget = (baseUrl) => (process.env.AGENTKEY_DEBUG ? baseUrl : API_ALIAS);
+
+// An edge firewall (e.g. Cloudflare) can block a network or IP outright,
+// answering 403 with an HTML block page while the real API is fine. Detect
+// the block from the body and headers, never the status code alone: a plain
+// 401/400 from the API still proves it is reachable.
+function looksBlocked(headers, bodyText) {
+  const h = (n) => String((headers && headers.get && headers.get(n)) || "");
+  const body = String(bodyText || "");
+  if (h("cf-mitigated").toLowerCase() === "block") return true;
+  if (body.includes("error code: 1010")) return true;
+  if (body.includes("Attention Required") && body.includes("Cloudflare")) return true;
+  if (body.includes("Access denied") && body.includes("Cloudflare")) return true;
+  return false;
+}
+
+// The ray ID to hand support when an edge block is reported.
+function rayIdFrom(headers, bodyText) {
+  const h = String((headers && headers.get && headers.get("cf-ray")) || "");
+  if (h) return h;
+  const m = String(bodyText || "").match(/Ray ID:\s*([0-9a-f-]{8,})/i);
+  return m ? m[1] : "unknown";
+}
+
+function skippedReason(r) {
+  return r.blocked ? "skipped, your network or IP appears blocked" : "skipped, the API is unreachable";
+}
+
+function nextStepFor(r) {
+  if (r.blocked) return `try another network, or contact support with ray ID ${r.rayId || "unknown"}`;
+  return "check the URL (AGENTKEY_BASE_URL overrides it) and your network";
+}
+
+async function authEndpointCheck(baseUrl) {
+  const a = await apiReachable(baseUrl, "/api/functions/authorize");
+  if (!a.reachable) {
+    return step(false, "Authorization endpoint reachable", "unreachable",
+      "authorization checks fail closed until this is reachable");
+  }
+  if (a.blocked) {
+    return stepWarn("Authorization endpoint reachable",
+      `blocked by the edge firewall (HTTP ${a.status})`, nextStepFor(a));
+  }
+  return step(true, "Authorization endpoint reachable");
+}
+
+// Any plain HTTP response (including 401/400) proves the endpoint is
+// reachable; an edge-firewall block does not (see looksBlocked). Only a
+// network-level failure (DNS, timeout, refused) means unreachable.
 async function apiReachable(baseUrl, path, method = "POST") {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
@@ -46,9 +105,13 @@ async function apiReachable(baseUrl, path, method = "POST") {
       body: method === "POST" ? "{}" : undefined,
       signal: controller.signal,
     });
-    return [true, res.status];
+    const text = await res.text().catch(() => "");
+    if (looksBlocked(res.headers, text)) {
+      return { reachable: true, blocked: true, status: res.status, rayId: rayIdFrom(res.headers, text) };
+    }
+    return { reachable: true, blocked: false, status: res.status, rayId: "" };
   } catch {
-    return [false, null];
+    return { reachable: false, blocked: false, status: null, rayId: "" };
   } finally {
     clearTimeout(timeout);
   }
@@ -70,8 +133,11 @@ async function validateRaw(baseUrl, key) {
       const data = JSON.parse(text);
       if (data && typeof data.valid === "boolean") return data;
     } catch {}
-    if (text.includes("error code: 1010") || (text.includes("Attention Required") && text.includes("Cloudflare"))) {
-      return { valid: false, error: "request blocked by the edge WAF (Cloudflare error 1010) - not an authentication failure" };
+    if (looksBlocked(res.headers, text)) {
+      const error = text.includes("error code: 1010")
+        ? "request blocked by the edge WAF (Cloudflare error 1010) - not an authentication failure"
+        : "request blocked by the edge firewall - not an authentication failure";
+      return { valid: false, error, blocked: true, rayId: rayIdFrom(res.headers, text) };
     }
     return { valid: false, error: `API returned HTTP ${res.status}` };
   } catch (e) {
@@ -186,6 +252,8 @@ async function cmdInit() {
       console.log("The key is saved at the config file above. The AGENTKEY_API_KEY");
       console.log("environment variable overrides it; unset yours to use the saved");
       console.log("key. Remove it any time: agentkey logout");
+    } else {
+      console.log("To remove a key saved by init later: agentkey logout");
     }
     console.log("Next:");
     console.log("  1. agentkey doctor");
@@ -195,7 +263,11 @@ async function cmdInit() {
   const detail = String(v.error || v.message || v.reason || "rejected by the API");
   step(false, "API key validated", detail);
   console.log();
-  if (detail.includes("WAF") || detail.includes("1010")) {
+  if (v.blocked && !detail.includes("1010")) {
+    console.log("FAILED: the request was blocked by the edge firewall. This is not an");
+    console.log("authentication failure. Your network or IP may be blocked; try");
+    console.log(`another network, or contact support with this ray ID: ${v.rayId || "unknown"}`);
+  } else if (detail.includes("WAF") || detail.includes("1010")) {
     console.log("FAILED: the request was blocked by the edge WAF. This is not an");
     console.log("authentication failure; a proxy or modified client is likely");
     console.log("stripping the SDK's User-Agent header. Restore it, then run:");
@@ -214,48 +286,48 @@ async function cmdInit() {
 
 async function cmdDoctor() {
   const baseUrl = (process.env.AGENTKEY_BASE_URL || "").trim() || DEFAULT_BASE_URL;
+  const target = displayTarget(baseUrl);
   console.log("AgentKey doctor");
   console.log(RULE);
   console.log();
   let ok = true;
   ok = step(true, "SDK installed", `agentkey-ai ${VERSION}`) && ok;
   const { key, source } = await resolveKey();
-  const [reach, status] = await apiReachable(baseUrl, "/api/functions/validate_api_key", "GET");
-  ok = step(reach, "API reachable", `${baseUrl}${reach ? ` (HTTP ${status})` : " - unreachable"}`,
-    "check the URL (AGENTKEY_BASE_URL overrides it) and your network") && ok;
+  const reach = await apiReachable(baseUrl, "/api/functions/validate_api_key", "GET");
+  if (!reach.reachable) {
+    ok = step(false, "API reachable", `${target} - unreachable`, nextStepFor(reach)) && ok;
+  } else if (reach.blocked) {
+    ok = stepWarn("API reachable", `${target} - blocked by the edge firewall (HTTP ${reach.status})`, nextStepFor(reach)) && ok;
+  } else {
+    ok = step(true, "API reachable", target) && ok;
+  }
+  const usable = reach.reachable && !reach.blocked;
   if (!key) {
     ok = step(false, "Credentials configured", "no API key configured", "run: agentkey init") && ok;
-    if (reach) {
-      ok = step(false, "Credentials valid", "skipped, no key", "run: agentkey init") && ok;
-      const [areach, astatus] = await apiReachable(baseUrl, "/api/functions/authorize");
-      ok = step(areach, "Authorization endpoint reachable", areach ? `HTTP ${astatus}` : "unreachable",
-        "authorization checks fail closed until this is reachable") && ok;
-    } else {
-      // Same host, same fate: no point making more doomed requests.
-      ok = step(false, "Credentials valid", "skipped, the API is unreachable",
-        "check the URL (AGENTKEY_BASE_URL overrides it) and your network") && ok;
+    if (!usable) {
+      ok = step(false, "Credentials valid", skippedReason(reach), nextStepFor(reach)) && ok;
       ok = step(false, "Authorization endpoint reachable", "skipped, same host as the API",
-        "authorization checks fail closed until the API is reachable") && ok;
+        "authorization checks fail closed until the API is usable") && ok;
+    } else {
+      ok = step(false, "Credentials valid", "skipped, no key", "run: agentkey init") && ok;
+      ok = (await authEndpointCheck(baseUrl)) && ok;
     }
   } else {
     const where = source === "environment"
       ? "environment: AGENTKEY_API_KEY"
       : `config file: ${configFilePath()}`;
     ok = step(true, "Credentials configured", where) && ok;
-    if (!reach) {
-      ok = step(false, "Credentials valid", "skipped, the API is unreachable",
-        "check the URL (AGENTKEY_BASE_URL overrides it) and your network") && ok;
+    if (!usable) {
+      ok = step(false, "Credentials valid", skippedReason(reach), nextStepFor(reach)) && ok;
       ok = step(false, "Authorization endpoint reachable", "skipped, same host as the API",
-        "authorization checks fail closed until the API is reachable") && ok;
+        "authorization checks fail closed until the API is usable") && ok;
     } else {
       const v = await validateRaw(baseUrl, key);
       const valid = v.valid === true;
       const detail = valid ? "" : String(v.error || v.message || v.reason || "rejected by the API");
       ok = step(valid, "Credentials valid", detail,
         `run: agentkey init, or create a fresh key at ${DASHBOARD_URL}/connect`) && ok;
-      const [areach, astatus] = await apiReachable(baseUrl, "/api/functions/authorize");
-      ok = step(areach, "Authorization endpoint reachable", areach ? `HTTP ${astatus}` : "unreachable",
-        "authorization checks fail closed until this is reachable") && ok;
+      ok = (await authEndpointCheck(baseUrl)) && ok;
     }
   }
   console.log();
@@ -305,7 +377,6 @@ function onboarding() {
   console.log(`     ${QUICKSTART_URL}`);
   console.log();
   console.log(`Get an API key at ${DASHBOARD_URL} (Connect wizard).`);
-  console.log("agentkey logout deletes the key saved by init.");
   return 0;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentkey-ai",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Authorization and evidence SDK for AI agents: check permissions before every action, record what agents actually did.",
   "type": "module",
   "bin": {