agents-scope 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# agent-scope
+
+A security layer that ensures agents can only use the tools they're explicitly allowed to access.
+
+## Install
+
+```bash
+bun add agent-scope
+```
+
+## Usage
+
+```ts
+import { createAgentScope } from "agent-scope";
+
+const scope = createAgentScope({
+  agents: [
+    { id: "researcher", permissions: ["read_doc"] },
+    { id: "admin", permissions: ["read_doc", "admin_delete_user"] },
+  ],
+});
+
+// pass the tool and tool_id
+const secureTool = scope.agent("researcher").secureTool(tool, "read_doc");
+```
+
+**Any attempt by the research agent to execute `admin_delete_user` will be blocked.**

package/dist/core.d.ts

@@ -0,0 +1,34 @@
+interface AgentConfig {
+    id: string;
+    permissions: string[];
+}
+interface AgentScopeConfig {
+    agents: AgentConfig[];
+}
+export declare class UnknownAgentError extends Error {
+    constructor(agentId: string);
+}
+export declare class UnknownToolError extends Error {
+    constructor(message: string);
+}
+export declare class PermissionDeniedError extends Error {
+    constructor(agentId: string, toolId: string);
+}
+export declare class ToolExecutionMethodNotFoundError extends Error {
+    constructor();
+}
+interface Tool {
+    name?: string;
+    id?: string;
+    invoke?: (...args: any[]) => any;
+    func?: (...args: any[]) => any;
+    execute?: (...args: any[]) => any;
+    [key: string]: any;
+}
+export declare function createAgentScope(config: AgentScopeConfig): {
+    agent(agentId: string): {
+        secureTool<T extends Tool>(tool: T, toolId?: string): T;
+    };
+};
+export declare const createAgentAuth: typeof createAgentScope;
+export {};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { createAgentScope, createAgentAuth, UnknownAgentError, UnknownToolError, PermissionDeniedError, ToolExecutionMethodNotFoundError, } from "./core";

package/dist/index.js

@@ -0,0 +1,111 @@
+// core.ts
+function validateAgentScopeConfig(config) {
+  if (!config || typeof config !== "object") {
+    throw new Error("AgentScope: config must be an object.");
+  }
+  if (!Array.isArray(config.agents)) {
+    throw new Error("AgentScope: `agents` must be an array.");
+  }
+  const seenAgentIds = new Set;
+  for (let i = 0;i < config.agents.length; i++) {
+    const agent = config.agents[i];
+    if (!agent || typeof agent !== "object") {
+      throw new Error(`AgentScope: agents[${i}] must be an object.`);
+    }
+    if (typeof agent.id !== "string" || agent.id.trim().length === 0) {
+      throw new Error(`AgentScope: agents[${i}].id must be a non-empty string.`);
+    }
+    if (seenAgentIds.has(agent.id)) {
+      throw new Error(`AgentScope: duplicate agent id '${agent.id}'.`);
+    }
+    seenAgentIds.add(agent.id);
+    if (!Array.isArray(agent.permissions)) {
+      throw new Error(`AgentScope: agents[${i}].permissions must be an array.`);
+    }
+    for (let j = 0;j < agent.permissions.length; j++) {
+      const permission = agent.permissions[j];
+      if (typeof permission !== "string" || permission.trim().length === 0) {
+        throw new Error(`AgentScope: agents[${i}].permissions[${j}] must be a non-empty string.`);
+      }
+    }
+  }
+}
+
+class UnknownAgentError extends Error {
+  constructor(agentId) {
+    super(`Agent with ID ${agentId} not found.`);
+    this.name = "UnknownAgentError";
+  }
+}
+
+class UnknownToolError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnknownToolError";
+  }
+}
+
+class PermissionDeniedError extends Error {
+  constructor(agentId, toolId) {
+    super(`Agent with ID ${agentId} has no tool permission with name ${toolId}`);
+    this.name = "PermissionDeniedError";
+  }
+}
+
+class ToolExecutionMethodNotFoundError extends Error {
+  constructor() {
+    super("AgentScope: Could not find an execution function (invoke/func/execute/_call) on tool.");
+    this.name = "ToolExecutionMethodNotFoundError";
+  }
+}
+function createAgentScope(config) {
+  validateAgentScopeConfig(config);
+  const knownToolIds = new Set(config.agents.flatMap((agent) => agent.permissions));
+  return {
+    agent(agentId) {
+      const currentAgent = config.agents.find((v) => v.id === agentId);
+      if (!currentAgent) {
+        throw new UnknownAgentError(agentId);
+      }
+      return {
+        secureTool(tool, toolId) {
+          const toolWithFallback = tool;
+          const method = typeof tool.invoke === "function" ? "invoke" : typeof tool.func === "function" ? "func" : typeof tool.execute === "function" ? "execute" : typeof toolWithFallback._call === "function" ? "_call" : null;
+          if (!method) {
+            throw new ToolExecutionMethodNotFoundError;
+          }
+          const resolvedToolId = toolId ?? tool.name ?? tool.id;
+          if (!resolvedToolId) {
+            throw new UnknownToolError("AgentScope: Missing tool id. Pass toolId explicitly or set tool.name/tool.id.");
+          }
+          if (!knownToolIds.has(resolvedToolId)) {
+            throw new UnknownToolError(`AgentScope: Unknown tool id '${resolvedToolId}' is denied by default.`);
+          }
+          const sourceTool = tool;
+          const executor = sourceTool[method];
+          const original = executor.bind(tool);
+          const wrappedTool = Object.create(Object.getPrototypeOf(tool));
+          Object.defineProperties(wrappedTool, Object.getOwnPropertyDescriptors(tool));
+          const mutableWrappedTool = wrappedTool;
+          mutableWrappedTool[method] = async (...args) => {
+            const isValidTool = currentAgent.permissions.includes(resolvedToolId);
+            if (!isValidTool) {
+              throw new PermissionDeniedError(agentId, resolvedToolId);
+            }
+            return original(...args);
+          };
+          return wrappedTool;
+        }
+      };
+    }
+  };
+}
+var createAgentAuth = createAgentScope;
+export {
+  createAgentScope,
+  createAgentAuth,
+  UnknownToolError,
+  UnknownAgentError,
+  ToolExecutionMethodNotFoundError,
+  PermissionDeniedError
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "agents-scope",
+  "version": "0.1.0",
+  "description": "Framework-agnostic tool authorization for AI agents.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Muhammad-Owais-Warsi/agent-scope.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Muhammad-Owais-Warsi/agent-scope/issues"
+  },
+  "homepage": "https://github.com/Muhammad-Owais-Warsi/agent-scope#readme",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build:js": "bun build ./index.ts --outfile ./dist/index.js --format esm --target node",
+    "build:types": "bunx tsc -p tsconfig.build.json",
+    "build": "bun run clean && bun run build:js && bun run build:types",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}