agentgate-sdk 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# agentgate
+
+The security gateway for AI agents.
+Enforce authentication, rate limiting, and policy controls between
+users and AI agents — in one line of code.
+
+## Install
+
+```bash
+npm install agentgate
+```
+
+## Quickstart
+
+Get your free API key at https://agent-gate-rho.vercel.app/
+
+```typescript
+import { withAgentGate } from "agentgate";
+
+const secured = withAgentGate(myAgent, {
+  apiKey: "ag_your_key_here",
+});
+
+// Use exactly like before — every tool call is now policy-checked
+await secured.executeTool("delete_file", { path: "/etc/passwd" });
+```
+
+## MCP middleware
+
+```typescript
+import { createAgentGateMiddleware } from "agentgate";
+
+const gate = createAgentGateMiddleware({ apiKey: "ag_your_key_here" });
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  return gate(req.params.name, req.params.arguments, () =>
+    myToolHandler(req)
+  );
+});
+```
+
+## Fail-open vs Fail-closed
+
+```typescript
+// Development default — allow if AgentGate unreachable
+withAgentGate(agent, { apiKey: "ag_xxx", onNetworkError: "fail-open" });
+
+// Production recommended — block if AgentGate unreachable
+withAgentGate(agent, { apiKey: "ag_xxx", onNetworkError: "fail-closed" });
+```
+
+## Policy decisions
+
+| Decision | Behaviour |
+| -------- | --------- |
+| ALLOW    | Tool executes normally |
+| DENY     | Tool blocked, error returned to agent |
+| REQUIRE_APPROVAL | Tool paused, human approves in dashboard |
+
+## AgentGate Connect (multi-tenant)
+
+If you are a SaaS platform managing agents for your customers,
+use Connect sub-keys (`agc_` prefix) to enforce per-customer policies.
+
+## Links
+
+Dashboard: https://agent-gate-rho.vercel.app/
+GitHub: https://github.com/wiserautomation/agentgate
+Issues: https://github.com/wiserautomation/agentgate/issues

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+export interface AgentGateResponse {
+    decision: "ALLOW" | "DENY" | "REQUIRE_APPROVAL";
+    reason?: string;
+}
+export interface AgentGateOptions {
+    /**
+     * Your AgentGate API key.
+     * Get one free at https://agent-gate-rho.vercel.app/
+     * Format: ag_xxxxxxxxxxxxxxxx
+     */
+    apiKey: string;
+    /**
+     * Override the AgentGate evaluation endpoint.
+     * Defaults to the hosted AgentGate cloud function.
+     * Set this for self-hosted deployments.
+     */
+    cloudFunctionUrl?: string;
+    /**
+     * What to do when AgentGate is unreachable.
+     * "fail-open"   → allow the action and log a warning (default, good for dev)
+     * "fail-closed" → block the action (recommended for production)
+     */
+    onNetworkError?: "fail-open" | "fail-closed";
+    /**
+     * Custom logger. Defaults to console.
+     * Pass `{ warn: () => {}, error: () => {}, log: () => {} }` to silence.
+     */
+    logger?: Pick<Console, "warn" | "error" | "log">;
+}
+export interface AgentInstance {
+    executeTool: (toolName: string, args: any) => Promise<any> | any;
+    [key: string]: any;
+}
+/**
+ * Wraps any AI agent with AgentGate security enforcement.
+ *
+ * Every tool call is intercepted and evaluated against your policies
+ * before execution. Zero infrastructure required — just an API key.
+ *
+ * @example
+ * // Works with LangChain, OpenAI Agents SDK, CrewAI, AutoGen, raw MCP
+ * import { withAgentGate } from "agentgate";
+ *
+ * const secured = withAgentGate(myAgent, { apiKey: "ag_your_key" });
+ * await secured.executeTool("send_email", { to: "ceo@company.com" }); // checked
+ *
+ * @param agentInstance - Any agent object with an `executeTool` method
+ * @param options - AgentGate configuration (only `apiKey` is required)
+ * @returns The same agent instance, now protected by AgentGate
+ */
+export declare function withAgentGate<T extends AgentInstance>(agentInstance: T, options: AgentGateOptions): T;
+/**
+ * MCP-native middleware for Model Context Protocol servers.
+ *
+ * @example
+ * import { createAgentGateMiddleware } from "agentgate";
+ *
+ * const gate = createAgentGateMiddleware({ apiKey: "ag_your_key" });
+ *
+ * // In your MCP tool handler:
+ * server.setRequestHandler(CallToolRequestSchema, async (req) => {
+ *   return gate(req.params.name, req.params.arguments, () => myToolHandler(req));
+ * });
+ */
+export declare function createAgentGateMiddleware(options: AgentGateOptions): (toolName: string, args: any, next: () => Promise<any>) => Promise<any>;
+export { withAgentGate as withAgentGuard };
+export type { AgentGateOptions as AgentGuardOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,kBAAkB,CAAC;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC7B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC;IAC7C;;;OAGG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,aAAa;IAC1B,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACjE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,aAAa,EACjD,aAAa,EAAE,CAAC,EAChB,OAAO,EAAE,gBAAgB,GAC1B,CAAC,CAmFH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gBAAgB,IAS3D,UAAU,MAAM,EAChB,MAAM,GAAG,EACT,MAAM,MAAM,OAAO,CAAC,GAAG,CAAC,KACzB,OAAO,CAAC,GAAG,CAAC,CAuClB;AAGD,OAAO,EAAE,aAAa,IAAI,cAAc,EAAE,CAAC;AAC3C,YAAY,EAAE,gBAAgB,IAAI,iBAAiB,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAgentGate = withAgentGate;
+exports.withAgentGuard = withAgentGate;
+exports.createAgentGateMiddleware = createAgentGateMiddleware;
+const DEFAULT_CLOUD_FUNCTION_URL = "https://us-central1-agentgate-prod.cloudfunctions.net/evaluateAction";
+const SDK_VERSION = "0.1.0";
+/**
+ * Wraps any AI agent with AgentGate security enforcement.
+ *
+ * Every tool call is intercepted and evaluated against your policies
+ * before execution. Zero infrastructure required — just an API key.
+ *
+ * @example
+ * // Works with LangChain, OpenAI Agents SDK, CrewAI, AutoGen, raw MCP
+ * import { withAgentGate } from "agentgate";
+ *
+ * const secured = withAgentGate(myAgent, { apiKey: "ag_your_key" });
+ * await secured.executeTool("send_email", { to: "ceo@company.com" }); // checked
+ *
+ * @param agentInstance - Any agent object with an `executeTool` method
+ * @param options - AgentGate configuration (only `apiKey` is required)
+ * @returns The same agent instance, now protected by AgentGate
+ */
+function withAgentGate(agentInstance, options) {
+    const { apiKey, cloudFunctionUrl = DEFAULT_CLOUD_FUNCTION_URL, onNetworkError = "fail-open", logger = console, } = options;
+    if (!apiKey || !apiKey.startsWith("ag_")) {
+        throw new Error(`[AgentGate] Invalid API key: "${apiKey}".\n` +
+            `  Get your free key at https://agent-gate-rho.vercel.app/\n` +
+            `  Expected format: ag_xxxxxxxxxxxxxxxx`);
+    }
+    const originalExecuteTool = agentInstance.executeTool.bind(agentInstance);
+    agentInstance.executeTool = async (toolName, args) => {
+        try {
+            const response = await fetch(cloudFunctionUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-AgentGate-SDK": `js-${SDK_VERSION}`,
+                },
+                body: JSON.stringify({ apiKey, toolName, args }),
+            });
+            if (!response.ok) {
+                if (response.status === 401) {
+                    throw new Error(`[AgentGate] Unauthorized. Check your API key at https://agent-gate-rho.vercel.app/`);
+                }
+                if (response.status === 429) {
+                    logger.warn(`[AgentGate] Rate limit exceeded for tool '${toolName}'.`);
+                    return "ERROR: AgentGate rate limit exceeded. Try again shortly.";
+                }
+                if (response.status === 403) {
+                    logger.warn(`[AgentGate] Tool '${toolName}' blocked by policy (HTTP 403).`);
+                    return "ERROR: Action blocked by AgentGate security policy.";
+                }
+                throw new Error(`[AgentGate] Server error ${response.status}`);
+            }
+            const data = (await response.json());
+            switch (data.decision) {
+                case "ALLOW":
+                    return await originalExecuteTool(toolName, args);
+                case "DENY":
+                    logger.warn(`[AgentGate] DENIED '${toolName}'. ${data.reason ? `Reason: ${data.reason}` : ""}`);
+                    return `ERROR: Action blocked by AgentGate. ${data.reason ?? ""}`.trim();
+                case "REQUIRE_APPROVAL":
+                    logger.warn(`[AgentGate] PAUSED '${toolName}'. Human approval required.`);
+                    return "ACTION PAUSED: This action requires human approval. Check your AgentGate dashboard at https://agent-gate-rho.vercel.app/";
+                default:
+                    logger.error("[AgentGate] Unknown decision in response:", data);
+                    return "ERROR: Unknown AgentGate decision.";
+            }
+        }
+        catch (e) {
+            // Re-throw hard errors (bad API key, etc.) — don't silently swallow them
+            if (e instanceof Error && e.message.startsWith("[AgentGate]")) {
+                throw e;
+            }
+            logger.error("[AgentGate] Network error reaching control plane.", e);
+            if (onNetworkError === "fail-closed") {
+                return "ERROR: AgentGate unreachable. Action blocked (fail-closed mode).";
+            }
+            logger.warn("[AgentGate] Proceeding without policy check (fail-open mode). Set onNetworkError: 'fail-closed' in production.");
+            return await originalExecuteTool(toolName, args);
+        }
+    };
+    return agentInstance;
+}
+/**
+ * MCP-native middleware for Model Context Protocol servers.
+ *
+ * @example
+ * import { createAgentGateMiddleware } from "agentgate";
+ *
+ * const gate = createAgentGateMiddleware({ apiKey: "ag_your_key" });
+ *
+ * // In your MCP tool handler:
+ * server.setRequestHandler(CallToolRequestSchema, async (req) => {
+ *   return gate(req.params.name, req.params.arguments, () => myToolHandler(req));
+ * });
+ */
+function createAgentGateMiddleware(options) {
+    const { apiKey, cloudFunctionUrl = DEFAULT_CLOUD_FUNCTION_URL, onNetworkError = "fail-open", logger = console, } = options;
+    return async function agentGateMiddleware(toolName, args, next) {
+        try {
+            const response = await fetch(cloudFunctionUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-AgentGate-SDK": `js-${SDK_VERSION}`,
+                },
+                body: JSON.stringify({ apiKey, toolName, args }),
+            });
+            if (!response.ok) {
+                if (response.status === 403) {
+                    return { error: "Action blocked by AgentGate security policy." };
+                }
+                if (response.status === 429) {
+                    return { error: "AgentGate rate limit exceeded." };
+                }
+                throw new Error(`AgentGate server error: ${response.status}`);
+            }
+            const data = (await response.json());
+            if (data.decision === "ALLOW")
+                return await next();
+            if (data.decision === "DENY") {
+                logger.warn(`[AgentGate] MCP tool '${toolName}' denied. ${data.reason ?? ""}`);
+                return { error: `Blocked by AgentGate. ${data.reason ?? ""}`.trim() };
+            }
+            if (data.decision === "REQUIRE_APPROVAL") {
+                return { error: "Human approval required. Check https://agent-gate-rho.vercel.app/" };
+            }
+        }
+        catch (e) {
+            logger.error("[AgentGate] Middleware error.", e);
+            if (onNetworkError === "fail-closed") {
+                return { error: "AgentGate unreachable. Action blocked." };
+            }
+            return await next();
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "agentgate-sdk",
+  "version": "0.1.0",
+  "description": "The security gateway for AI agents — auth, rate limiting, and policy enforcement in one line.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "security",
+    "mcp",
+    "langchain",
+    "openai",
+    "gateway",
+    "policy",
+    "agentgate"
+  ],
+  "author": "AgentGate",
+  "license": "MIT",
+  "homepage": "https://agent-gate-rho.vercel.app/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wiserautomation/agentgate"
+  },
+  "bugs": {
+    "url": "https://github.com/wiserautomation/agentgate/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  }
+}