agentkey-ai 1.2.0 → 1.3.0

package/README.md

@@ -35,39 +35,74 @@ The CLI never prints your key. `agentkey init` saves a pasted key to a local con
 2. Open the Connect wizard (or Agents, then create an agent).
 3. Generate an API key. It is shown once. Run `agentkey init` to save it to the local config file, or export it as `AGENTKEY_API_KEY`. Never hard-code it.
 
-## First authorization (Python)
+## First authorization (guided)
+
+Run this right after `agentkey init` (or with `AGENTKEY_API_KEY` exported). It performs ONE real, least-privilege authorization: `sandbox.send_test`, an isolated test capability every new agent ships with. It can only ever return allow or deny; it never performs a real external side effect, never touches a real tool, and grants nothing beyond that single permission. The decision is made by the real policy engine and recorded as hash-chained evidence.
+
+Python:
 
 ```python
 from agentkey import AgentKeyClient
 
-ak = AgentKeyClient(api_key="agent_live_xxxxx")  # production API by default
+ak = AgentKeyClient()  # reads AGENTKEY_API_KEY, or the config file from `agentkey init`
+
+result = ak.check_permission(action="send_test", resource="sandbox")
 
-result = ak.check_permission(action="send_email", resource="gmail", arguments={"to": "x@company.com"})
-if result["allowed"]:
-    send_email(...)  # your code
+print("session_id:       ", result.get("session_id"))
+decision = "ALLOW" if result.get("allowed") else ("APPROVAL REQUIRED" if result.get("approval_required") else "DENY")
+print("decision:         ", decision, "-", result.get("reason"))
+if result.get("event_id"):
+    print("evidence_event_id:", result["event_id"])
+    print()
+    print("YOU'RE DONE - your first real authorization was decided by the policy")
+    print("engine and recorded as verifiable evidence. See it in the dashboard:")
+    print("https://agentkey.us/sessions/" + str(result.get("session_id")))
 else:
-    print("Blocked:", result["reason"], "approval_required:", result.get("approval_required", False))
+    reason = str(result.get("reason") or "")
+    if "Invalid API key" in reason:
+        print("Your key is invalid - create one at https://agentkey.us/connect")
+    elif "No permission configured" in reason:
+        print("This agent has no sandbox.send_test permission yet. Add one in the")
+        print("dashboard (Agents -> Permissions): resource 'sandbox', action")
+        print("'send_test', decision allow - then run this again.")
+    else:
+        print("Denied by policy:", reason)
 ```
 
-## First authorization (JavaScript / TypeScript)
+JavaScript / TypeScript (save as `first-authorization.mjs`, run with `node first-authorization.mjs`):
 
 ```js
 import { AgentKeyClient } from "agentkey-ai";
 
-const ak = new AgentKeyClient({ apiKey: "agent_live_xxxxx" }); // production API by default
+const ak = new AgentKeyClient(); // reads AGENTKEY_API_KEY, or the config file from `npx agentkey init`
 
-const result = await ak.checkPermission({
-  action: "send_email",
-  resource: "gmail",
-  arguments: { to: "x@company.com" },
-});
-if (result.allowed) {
-  await sendEmail(); // your code
+const result = await ak.checkPermission({ action: "send_test", resource: "sandbox" });
+
+console.log("session_id:       ", result.session_id);
+const decision = result.allowed ? "ALLOW" : (result.approval_required ? "APPROVAL REQUIRED" : "DENY");
+console.log("decision:         ", decision, "-", result.reason);
+if (result.event_id) {
+  console.log("evidence_event_id:", result.event_id);
+  console.log();
+  console.log("YOU'RE DONE - your first real authorization was decided by the policy");
+  console.log("engine and recorded as verifiable evidence. See it in the dashboard:");
+  console.log("https://agentkey.us/sessions/" + result.session_id);
 } else {
-  console.log("Blocked:", result.reason, "approval_required:", result.approval_required ?? false);
+  const reason = String(result.reason || "");
+  if (reason.includes("Invalid API key")) {
+    console.log("Your key is invalid - create one at https://agentkey.us/connect");
+  } else if (reason.includes("No permission configured")) {
+    console.log("This agent has no sandbox.send_test permission yet. Add one in the");
+    console.log("dashboard (Agents -> Permissions): resource 'sandbox', action");
+    console.log("'send_test', decision allow - then run this again.");
+  } else {
+    console.log("Denied by policy:", reason);
+  }
 }
 ```
 
+A wrong, expired, or revoked key fails closed exactly like any other call (`allowed: false`); the scripts above tell you which case you are in.
+
 ## Decisions: allow, deny, ask
 
 `check_permission` / `checkPermission` evaluates the permissions you configured for the agent:

package/agentkey.js

@@ -19,8 +19,8 @@ const FAIL_CLOSED = { allowed: false, reason: "agentkey_unreachable", fail_close
 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 DEFAULT_BASE_URL = "https://agentkey.us";
+export const VERSION = "1.3.0";
 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.3.0",
   "description": "Authorization and evidence SDK for AI agents: check permissions before every action, record what agents actually did.",
   "type": "module",
   "bin": {
@@ -36,5 +36,5 @@
     "llm"
   ],
   "license": "MIT",
-  "homepage": "https://agentkey.base44.app"
-}
+  "homepage": "https://agentkey.us"
+}