@idevelopers/agentlock 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "agentlock-marketplace",
+  "description": "Local marketplace for AgentLock, a permission firewall for AI coding agents and MCP tools.",
+  "owner": {
+    "name": "iDevelopers"
+  },
+  "plugins": [
+    {
+      "name": "agentlock",
+      "description": "Local permission firewall for AI coding agents and MCP tools",
+      "author": {
+        "name": "iDevelopers"
+      },
+      "category": "development",
+      "source": "./",
+      "version": "0.1.0",
+      "homepage": "https://www.npmjs.com/package/@idevelopers/agentlock"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "agentlock",
+  "version": "0.1.0",
+  "description": "Local permission firewall for AI coding agents and MCP tools",
+  "author": {
+    "name": "iDevelopers",
+    "url": "https://github.com/manish-1988"
+  },
+  "repository": "https://www.npmjs.com/package/@idevelopers/agentlock",
+  "license": "MIT"
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "agentlock": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@idevelopers/agentlock"
+      ]
+    }
+  }
+}

package/README.md

@@ -0,0 +1,114 @@
+# AgentLock
+
+Stop AI coding agents from touching secrets, running unsafe commands, or overusing MCP tools without explicit policy.
+
+AgentLock is a local MCP server plus Claude Code and Codex plugin packaging. It gives each agent task a permission capsule for files, shell commands, secret reads, network egress, MCP tools, and actions that require approval.
+
+## Install
+
+Install the MCP server directly from npm in Claude Code:
+
+```text
+claude mcp add agentlock -- npx -y @idevelopers/agentlock
+```
+
+Or install the Claude Code plugin from the public installer marketplace:
+
+```text
+/plugin marketplace add https://github.com/manish-1988/agentlock-installer
+/plugin install agentlock@agentlock-marketplace
+```
+
+For local source development from this private repository:
+
+```sh
+npm install
+npm run build
+node dist/index.js
+```
+
+Polar handles paid licenses; npm distributes the runtime package. The public installer repository contains only plugin metadata and points Claude/Codex at `npx -y @idevelopers/agentlock`.
+
+## Free, Pro, Team
+
+Free is the local AgentLock scanner and starter policy generator. The source repository remains private; the public installer repository only contains plugin metadata that points to the public npm runtime.
+
+| Capability | Free | Pro | Team |
+| --- | --- | --- | --- |
+| Local AI-agent/MCP risk scan | Yes | Yes | Yes |
+| Starter policy generation | Yes | Yes | Yes |
+| Action checks against policy | No | Yes | Yes |
+| Guarded command execution | No | Yes | Yes |
+| Redacted local audit log | No | Yes | Yes |
+| Shared policies, signed bundles, seats | No | No | Yes |
+
+Pro is intended for `$19/dev/month` or local INR equivalent. Team is intended for `$99/team/month` with seats.
+
+The AgentLock live checkout URL is added after the Polar product is created. Until then, set `AGENTLOCK_CHECKOUT_URL` locally during sandbox or live payment validation.
+
+## Policy
+
+Create `agentlock.policy.json` in your repo. Start from `agentlock.policy.example.json` or call `agentlock_generate_policy`.
+
+```json
+{
+  "version": 1,
+  "defaultCapsule": "default",
+  "capsules": [
+    {
+      "id": "default",
+      "allowedFiles": ["**"],
+      "deniedFiles": [".env", ".env.*", "~/.aws/**", "~/.ssh/**"],
+      "allowedCommands": ["npm test", "npm run", "git status", "git diff"],
+      "deniedCommands": ["rm", "sudo", "npm publish", "git push"],
+      "approvalRequired": ["secret-read", "package-publish", "git-push"]
+    }
+  ]
+}
+```
+
+For smoke tests or nonstandard filenames, point AgentLock at a specific policy:
+
+```sh
+export AGENTLOCK_POLICY=agentlock.policy.example.json
+```
+
+## Tools
+
+- `agentlock_scan_environment`: free local risk scan for secret-adjacent files and agent/MCP config.
+- `agentlock_generate_policy`: free starter permission capsule generator.
+- `agentlock_check_action`: Pro policy decision for file, command, network, and MCP actions.
+- `agentlock_run_guarded_command`: Pro command runner using `child_process.spawn` with `shell:false`.
+- `agentlock_audit_log`: Pro redacted local audit log.
+- `agentlock_activate_license`: store and verify a Polar license key.
+
+## License Activation
+
+AgentLock uses Polar license keys and caches successful validation in `~/.agentlock/license.json` with a 72-hour offline grace window for Pro and Team licenses.
+
+For sandbox checks, set both values:
+
+```sh
+export POLAR_ENVIRONMENT=sandbox
+export POLAR_ORGANIZATION_ID="your_sandbox_org_id"
+export AGENTLOCK_CHECKOUT_URL="your_sandbox_checkout_url"
+```
+
+Then call `agentlock_activate_license` with the Polar license key. By default the activation label is `agentlock-local`; override it with `AGENTLOCK_ACTIVATION_LABEL` if you want a more specific device label in Polar.
+
+## Security
+
+AgentLock runs locally and does not upload files or secrets to an AgentLock server. The scanner reports file presence and risky surfaces, not secret values. Reports, command output tails, and audit entries are redacted.
+
+Guarded commands run with `shell:false` and a sanitized environment that strips secret-like variables. Treat `agentlock.policy.json` like a CI or firewall file: review it before trusting an agent task.
+
+## Development
+
+```sh
+npm install
+npm run build
+npx vitest run
+npm pack --dry-run
+```
+
+The package binary is `agentlock`, mapped to `dist/index.js`.

package/agentlock.policy.example.json

@@ -0,0 +1,84 @@
+{
+  "version": 1,
+  "defaultCapsule": "default",
+  "audit": {
+    "enabled": true
+  },
+  "capsules": [
+    {
+      "id": "default",
+      "allowedFiles": [
+        "**"
+      ],
+      "deniedFiles": [
+        ".env",
+        ".env.*",
+        "**/.env",
+        "**/.env.*",
+        "**/.npmrc",
+        "~/.npmrc",
+        "~/.aws/**",
+        "~/.ssh/**",
+        "~/.config/gcloud/**",
+        "~/.docker/config.json",
+        "~/.kube/config",
+        "**/*secret*",
+        "**/*credential*",
+        "**/*token*",
+        "**/Cookies"
+      ],
+      "allowedCommands": [
+        "node",
+        "npm test",
+        "npm run",
+        "npm install",
+        "npx vitest",
+        "pnpm test",
+        "pnpm run",
+        "yarn test",
+        "git status",
+        "git diff",
+        "git log",
+        "git show",
+        "rg",
+        "ls",
+        "pwd",
+        "cat package.json"
+      ],
+      "deniedCommands": [
+        "rm",
+        "sudo",
+        "chmod",
+        "chown",
+        "dd",
+        "mkfs",
+        "kill",
+        "pkill",
+        "npm publish",
+        "pnpm publish",
+        "yarn npm publish",
+        "git push",
+        "wrangler deploy",
+        "vercel deploy",
+        "firebase deploy",
+        "gcloud app deploy",
+        "terraform apply",
+        "terraform destroy"
+      ],
+      "allowedDomains": [],
+      "deniedDomains": [],
+      "allowedMcpServers": [],
+      "allowedMcpTools": [],
+      "approvalRequired": [
+        "destructive-command",
+        "secret-read",
+        "network-egress",
+        "package-publish",
+        "git-push",
+        "cloud-deploy",
+        "database-command",
+        "mcp-tool"
+      ]
+    }
+  ]
+}

package/codex-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "agentlock",
+  "version": "0.1.0",
+  "description": "Local permission firewall for AI coding agents and MCP tools",
+  "author": "iDevelopers",
+  "license": "MIT",
+  "mcpServers": {
+    "agentlock": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@idevelopers/agentlock"
+      ]
+    }
+  },
+  "skills": [
+    "skills/agentlock-workflow/SKILL.md"
+  ],
+  "commands": [
+    "commands/scan.md",
+    "commands/check.md",
+    "commands/guard.md"
+  ]
+}

package/commands/check.md

@@ -0,0 +1,6 @@
+---
+description: Check an action against AgentLock policy
+argument-hint: "[action-json]"
+---
+
+Run `agentlock_check_action` with the provided action JSON. If the decision is `block`, stop. If the decision is `needs_approval`, ask for explicit user approval before retrying with `approved: true`.

package/commands/guard.md

@@ -0,0 +1,6 @@
+---
+description: Run a shell command through AgentLock policy enforcement
+argument-hint: "[command and args]"
+---
+
+Run `agentlock_run_guarded_command` with the command and arguments. Inspect the policy evaluation before trusting any command result.

package/commands/scan.md

@@ -0,0 +1,6 @@
+---
+description: Scan the current repo for AI-agent secret and MCP risk surfaces
+argument-hint: ""
+---
+
+Run `agentlock_scan_environment` for the current repository with home checks enabled. Summarize the risk categories and recommend creating `agentlock.policy.json` from `agentlock_generate_policy`.

package/dist/audit/log.js

@@ -0,0 +1,32 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { auditLogPath } from "../util/paths.js";
+import { redactValue } from "../util/redact.js";
+export async function appendAuditEntry(entry, logPath = auditLogPath()) {
+    await mkdir(path.dirname(logPath), { recursive: true });
+    const redacted = redactValue(entry);
+    await writeFile(logPath, `${JSON.stringify(redacted)}\n`, {
+        encoding: "utf8",
+        flag: "a",
+    });
+}
+export async function readAuditEntries(limit = 50, logPath = auditLogPath()) {
+    try {
+        const raw = await readFile(logPath, "utf8");
+        return raw
+            .trim()
+            .split("\n")
+            .filter(Boolean)
+            .slice(-limit)
+            .map((line) => JSON.parse(line));
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/config/policy.js

@@ -0,0 +1,47 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { ZodError } from "zod";
+import { policySchema } from "./schema.js";
+import { generatePolicy } from "../enforcement/generate_policy.js";
+export async function loadPolicy(cwd = process.cwd()) {
+    const policyPath = process.env.AGENTLOCK_POLICY
+        ? path.resolve(cwd, process.env.AGENTLOCK_POLICY)
+        : path.join(cwd, "agentlock.policy.json");
+    try {
+        const raw = await readFile(policyPath, "utf8");
+        return {
+            policy: parsePolicy(raw, policyPath),
+            source: "file",
+            path: policyPath,
+        };
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return {
+                policy: generatePolicy({ mode: "balanced" }),
+                source: "default",
+            };
+        }
+        throw error;
+    }
+}
+export function parsePolicy(raw, policyPath = "agentlock.policy.json") {
+    try {
+        return policySchema.parse(JSON.parse(raw));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error(`Invalid JSON in ${policyPath}: ${error.message}`);
+        }
+        if (error instanceof ZodError) {
+            const details = error.issues
+                .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+                .join("; ");
+            throw new Error(`Invalid AgentLock policy at ${policyPath}: ${details}`);
+        }
+        throw error;
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/config/schema.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+export const actionTypeSchema = z.enum([
+    "file_read",
+    "file_write",
+    "command",
+    "network",
+    "mcp_tool",
+]);
+export const approvalCategorySchema = z.enum([
+    "destructive-command",
+    "secret-read",
+    "network-egress",
+    "package-publish",
+    "git-push",
+    "cloud-deploy",
+    "database-command",
+    "mcp-tool",
+]);
+export const permissionCapsuleSchema = z.object({
+    id: z.string().min(1),
+    allowedFiles: z.array(z.string()).default(["**"]),
+    deniedFiles: z.array(z.string()).default([]),
+    allowedCommands: z.array(z.string()).default([]),
+    deniedCommands: z.array(z.string()).default([]),
+    allowedDomains: z.array(z.string()).default([]),
+    deniedDomains: z.array(z.string()).default([]),
+    allowedMcpServers: z.array(z.string()).default([]),
+    allowedMcpTools: z.array(z.string()).default([]),
+    approvalRequired: z.array(approvalCategorySchema).default([]),
+});
+export const policySchema = z.object({
+    version: z.literal(1),
+    defaultCapsule: z.string().min(1).default("default"),
+    audit: z
+        .object({
+        enabled: z.boolean().default(true),
+    })
+        .default({ enabled: true }),
+    capsules: z.array(permissionCapsuleSchema).min(1),
+});
+export const actionSchema = z.object({
+    type: actionTypeSchema,
+    capsuleId: z.string().min(1).optional(),
+    path: z.string().min(1).optional(),
+    command: z.string().min(1).optional(),
+    args: z.array(z.string()).default([]),
+    domain: z.string().min(1).optional(),
+    mcpServer: z.string().min(1).optional(),
+    mcpTool: z.string().min(1).optional(),
+    approved: z.boolean().default(false),
+});

package/dist/enforcement/classify.js

@@ -0,0 +1,51 @@
+import { isLikelySecretPath } from "./secrets.js";
+export function classifyCommand(command, args) {
+    const line = commandLine(command, args);
+    const categories = new Set();
+    if (/(^|\s)(rm|sudo|chmod|chown|dd|mkfs|kill|pkill)(\s|$)/.test(line)) {
+        categories.add("destructive-command");
+    }
+    if (/(^|\s)(npm|pnpm)\s+publish(\s|$)/.test(line) || /(^|\s)yarn\s+npm\s+publish(\s|$)/.test(line)) {
+        categories.add("package-publish");
+    }
+    if (/(^|\s)git\s+push(\s|$)/.test(line)) {
+        categories.add("git-push");
+    }
+    if (/(^|\s)(wrangler|vercel|firebase|serverless)\s+deploy(\s|$)/.test(line) ||
+        /(^|\s)gcloud\s+(app\s+deploy|run\s+deploy)(\s|$)/.test(line) ||
+        /(^|\s)terraform\s+(apply|destroy)(\s|$)/.test(line)) {
+        categories.add("cloud-deploy");
+    }
+    if (/(^|\s)(psql|mysql|mongosh|redis-cli)(\s|$)/.test(line) ||
+        /(^|\s)prisma\s+migrate\s+(deploy|reset)(\s|$)/.test(line)) {
+        categories.add("database-command");
+    }
+    if (/(^|\s)(curl|wget)(\s|$)/.test(line) || extractDomains(args).length > 0) {
+        categories.add("network-egress");
+    }
+    if (/(^|\s)(cat|head|tail|less|more|grep|rg)(\s|$)/.test(line) && args.some(isLikelySecretPath)) {
+        categories.add("secret-read");
+    }
+    return {
+        categories: [...categories],
+        domains: extractDomains(args),
+    };
+}
+export function commandLine(command, args) {
+    return [command, ...args].join(" ").trim();
+}
+export function extractDomains(values) {
+    const domains = new Set();
+    for (const value of values) {
+        try {
+            const url = new URL(value);
+            domains.add(url.hostname.toLowerCase());
+        }
+        catch {
+            if (/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(value)) {
+                domains.add(value.toLowerCase());
+            }
+        }
+    }
+    return [...domains];
+}

package/dist/enforcement/evaluator.js

@@ -0,0 +1,126 @@
+import { normalizeForPolicy } from "../util/paths.js";
+import { classifyCommand, commandLine } from "./classify.js";
+import { matchesAny } from "./match.js";
+import { isLikelySecretPath } from "./secrets.js";
+export function evaluateAction(policy, action, cwd = process.cwd()) {
+    const capsule = selectCapsule(policy, action.capsuleId);
+    const reasons = [];
+    const categories = new Set();
+    if (action.type === "command") {
+        evaluateCommand(capsule, action.command ?? "", action.args, action.approved, reasons, categories);
+    }
+    if (action.type === "file_read" || action.type === "file_write") {
+        evaluateFile(capsule, action, cwd, reasons, categories);
+    }
+    if (action.type === "network") {
+        evaluateDomains(capsule, action.domain ? [action.domain] : [], reasons, categories);
+        categories.add("network-egress");
+    }
+    if (action.type === "mcp_tool") {
+        evaluateMcp(capsule, action, reasons, categories);
+        categories.add("mcp-tool");
+    }
+    if (reasons.some((reason) => reason.startsWith("blocked:"))) {
+        return {
+            decision: "block",
+            capsuleId: capsule.id,
+            reasons,
+            categories: [...categories],
+        };
+    }
+    const approvalReasons = [...categories]
+        .filter((category) => capsule.approvalRequired.includes(category))
+        .map((category) => `approval required: ${category}`);
+    if (approvalReasons.length > 0 && !action.approved) {
+        return {
+            decision: "needs_approval",
+            capsuleId: capsule.id,
+            reasons: [...reasons, ...approvalReasons],
+            categories: [...categories],
+        };
+    }
+    return {
+        decision: "allow",
+        capsuleId: capsule.id,
+        reasons: reasons.length > 0 ? reasons : ["allowed by capsule policy"],
+        categories: [...categories],
+    };
+}
+function selectCapsule(policy, capsuleId) {
+    const selectedId = capsuleId ?? policy.defaultCapsule;
+    const capsule = policy.capsules.find((candidate) => candidate.id === selectedId) ??
+        policy.capsules.find((candidate) => candidate.id === policy.defaultCapsule);
+    if (!capsule) {
+        throw new Error(`AgentLock policy does not contain capsule ${selectedId}`);
+    }
+    return capsule;
+}
+function evaluateCommand(capsule, command, args, approved, reasons, categories) {
+    if (!command) {
+        reasons.push("blocked: command is required");
+        return;
+    }
+    const line = commandLine(command, args);
+    const classification = classifyCommand(command, args);
+    let approvedDeniedCommand = false;
+    for (const category of classification.categories) {
+        categories.add(category);
+    }
+    evaluateDomains(capsule, classification.domains, reasons, categories);
+    if (matchesAny(line, capsule.deniedCommands) || matchesAny(command, capsule.deniedCommands)) {
+        const canApprove = [...categories].some((category) => capsule.approvalRequired.includes(category));
+        reasons.push(canApprove && approved ? `approved denied-pattern command: ${line}` : `blocked: denied command ${line}`);
+        if (!approved) {
+            return;
+        }
+        approvedDeniedCommand = canApprove;
+    }
+    if (!approvedDeniedCommand && capsule.allowedCommands.length > 0 && !matchesAny(line, capsule.allowedCommands) && !matchesAny(command, capsule.allowedCommands)) {
+        reasons.push(`blocked: command is not in allowedCommands: ${line}`);
+    }
+}
+function evaluateFile(capsule, action, cwd, reasons, categories) {
+    if (!action.path) {
+        reasons.push("blocked: path is required");
+        return;
+    }
+    const policyPath = normalizeForPolicy(action.path, cwd);
+    if (isLikelySecretPath(policyPath) && action.type === "file_read") {
+        categories.add("secret-read");
+    }
+    if (matchesAny(policyPath, capsule.deniedFiles)) {
+        const canApprove = categories.has("secret-read") && capsule.approvalRequired.includes("secret-read");
+        if (canApprove) {
+            reasons.push(action.approved ? `approved denied-pattern file: ${policyPath}` : `approval required: denied-pattern file ${policyPath}`);
+            return;
+        }
+        reasons.push(`blocked: denied file ${policyPath}`);
+        if (!action.approved) {
+            return;
+        }
+    }
+    if (capsule.allowedFiles.length > 0 && !matchesAny(policyPath, capsule.allowedFiles)) {
+        reasons.push(`blocked: file is not in allowedFiles: ${policyPath}`);
+    }
+}
+function evaluateDomains(capsule, domains, reasons, categories) {
+    const extracted = domains.length > 0 ? domains : [];
+    for (const domain of extracted) {
+        categories.add("network-egress");
+        if (matchesAny(domain, capsule.deniedDomains)) {
+            reasons.push(`blocked: denied domain ${domain}`);
+        }
+        if (capsule.allowedDomains.length > 0 && !matchesAny(domain, capsule.allowedDomains)) {
+            reasons.push(`blocked: domain is not in allowedDomains: ${domain}`);
+        }
+    }
+}
+function evaluateMcp(capsule, action, reasons, _categories) {
+    if (capsule.allowedMcpServers.length > 0 && (!action.mcpServer || !matchesAny(action.mcpServer, capsule.allowedMcpServers))) {
+        reasons.push(`blocked: MCP server is not allowed: ${action.mcpServer ?? "<missing>"}`);
+    }
+    const toolName = action.mcpTool ? `${action.mcpServer ?? "*"}.${action.mcpTool}` : undefined;
+    if (capsule.allowedMcpTools.length > 0 && (!toolName || !matchesAny(toolName, capsule.allowedMcpTools) && !matchesAny(action.mcpTool ?? "", capsule.allowedMcpTools))) {
+        reasons.push(`blocked: MCP tool is not allowed: ${toolName ?? "<missing>"}`);
+    }
+}

package/dist/enforcement/generate_policy.js

@@ -0,0 +1,73 @@
+import { defaultSecretPathPatterns } from "./secrets.js";
+const approvalRequired = [
+    "destructive-command",
+    "secret-read",
+    "network-egress",
+    "package-publish",
+    "git-push",
+    "cloud-deploy",
+    "database-command",
+    "mcp-tool",
+];
+export function generatePolicy(options) {
+    const allowedCommands = options.mode === "strict"
+        ? ["npm test", "npm run test", "npm run lint", "npm run typecheck"]
+        : [
+            "node",
+            "npm test",
+            "npm run",
+            "npm install",
+            "npx vitest",
+            "pnpm test",
+            "pnpm run",
+            "yarn test",
+            "git status",
+            "git diff",
+            "git log",
+            "git show",
+            "rg",
+            "ls",
+            "pwd",
+            "cat package.json",
+        ];
+    return {
+        version: 1,
+        defaultCapsule: "default",
+        audit: {
+            enabled: true,
+        },
+        capsules: [
+            {
+                id: "default",
+                allowedFiles: options.mode === "strict" ? ["src/**", "test/**", "package.json"] : ["**"],
+                deniedFiles: defaultSecretPathPatterns(),
+                allowedCommands: options.mode === "relaxed" ? [] : allowedCommands,
+                deniedCommands: [
+                    "rm",
+                    "sudo",
+                    "chmod",
+                    "chown",
+                    "dd",
+                    "mkfs",
+                    "kill",
+                    "pkill",
+                    "npm publish",
+                    "pnpm publish",
+                    "yarn npm publish",
+                    "git push",
+                    "wrangler deploy",
+                    "vercel deploy",
+                    "firebase deploy",
+                    "gcloud app deploy",
+                    "terraform apply",
+                    "terraform destroy",
+                ],
+                allowedDomains: [],
+                deniedDomains: [],
+                allowedMcpServers: [],
+                allowedMcpTools: [],
+                approvalRequired,
+            },
+        ],
+    };
+}