@samirosamsam/aim 0.1.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "aim",
+  "interface": {
+    "displayName": "AIM"
+  },
+  "plugins": [
+    {
+      "name": "aim",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "aim",
+  "version": "0.1.0",
+  "description": "Install deterministic Codex guardrails from natural-language block rules.",
+  "author": {
+    "name": "AIM"
+  },
+  "repository": "https://github.com/tototozip/AIM",
+  "license": "MIT",
+  "keywords": ["agents", "codex", "iam", "mcp", "permissions"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "AIM",
+    "shortDescription": "Block matching Codex tool calls with local guardrails.",
+    "longDescription": "AIM helps Codex turn natural-language block requests into local PreToolUse guardrails for Bash, file edits, and MCP tool calls.",
+    "developerName": "AIM",
+    "category": "Productivity",
+    "capabilities": ["Write"],
+    "defaultPrompt": [
+      "Block this Codex action.",
+      "Install deterministic guardrails for this repo."
+    ]
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIM contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# AIM
+
+Minimal command-first prototype for **Agent Identity & Access Management**.
+
+AIM keeps the first surface small: Codex uses a plugin skill to install a local `PreToolUse` hook, turn natural-language "block this" requirements into policy rows, and deny matching Codex tool calls before they execute. There is no local server and no UI.
+
+## Install
+
+Run the public CLI without installing:
+
+```bash
+npx -y @samirosamsam/aim@latest demo
+```
+
+Install the CLI globally:
+
+```bash
+npm install -g @samirosamsam/aim
+aim demo
+```
+
+Install the Codex plugin from this repo:
+
+```bash
+codex plugin marketplace add tototozip/AIM --ref main
+codex plugin add aim@aim
+```
+
+Then start a new Codex thread and invoke `@aim`.
+
+## Codex Guardrail
+
+Install or refresh the local Codex hook:
+
+```bash
+npx -y @samirosamsam/aim@latest setup
+```
+
+If Codex says hooks need review, run `/hooks`, inspect the AIM hook, and trust it.
+
+Add a deterministic guardrail from natural language:
+
+```bash
+npx -y @samirosamsam/aim@latest rule add 'empêche git push'
+npx -y @samirosamsam/aim@latest rule add 'empêche de modifier package.json'
+npx -y @samirosamsam/aim@latest rule add 'empêche les calls GitHub qui ajoutent des collaborators'
+```
+
+Codex then calls the AIM hook before supported tool calls. A blocked Bash call returns the Codex `PreToolUse` deny shape:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "AIM blocked Bash: Block write on bash/git push*."
+  }
+}
+```
+
+## Run
+
+```bash
+npm test
+node ./bin/aim.js demo
+```
+
+## CLI
+
+Draft grants without writing policy:
+
+```bash
+npx -y @samirosamsam/aim@latest compile 'Block Notion read access to "workspace/shared/legal/*"' --json
+```
+
+Capture a concrete MCP call as a resource/action rule:
+
+```bash
+npx -y @samirosamsam/aim@latest capture \
+  --provider github \
+  --tool list_repository_collaborators \
+  --args '{"owner":"tototozip","repo":"AIM"}' \
+  --effect deny \
+  --agent 'spiffe://local/agent/demo/codex' \
+  --connection 'github:prod' \
+  --json
+```
+
+Append grants to a policy file:
+
+```bash
+npx -y @samirosamsam/aim@latest add 'Allow Notion read access to "workspace/shared/*"' \
+  --policy aim.policy.json \
+  --agent 'spiffe://local/agent/demo/codex' \
+  --json
+```
+
+Append a captured MCP rule to a policy file:
+
+```bash
+npx -y @samirosamsam/aim@latest capture \
+  --provider github \
+  --tool list_branches \
+  --args '{"owner":"tototozip","repo":"AIM"}' \
+  --effect allow \
+  --policy aim.policy.json \
+  --agent 'spiffe://local/agent/demo/codex' \
+  --connection 'github:prod' \
+  --json
+```
+
+Check a representative MCP call:
+
+```bash
+npx -y @samirosamsam/aim@latest check \
+  --policy aim.policy.json \
+  --agent 'spiffe://local/agent/demo/codex' \
+  --connection 'notion:prod' \
+  --tool 'pages.read' \
+  --resource 'workspace/shared/legal/term-sheet' \
+  --access read \
+  --json
+```
+
+Authorize using raw MCP call args:
+
+```bash
+npx -y @samirosamsam/aim@latest authorize \
+  --policy aim.policy.json \
+  --agent 'spiffe://local/agent/demo/codex' \
+  --connection 'github:prod' \
+  --provider github \
+  --tool list_branches \
+  --args '{"owner":"tototozip","repo":"AIM"}' \
+  --json
+```
+
+## Codex Plugin
+
+This repo is shaped as a Codex plugin:
+
+- `.codex-plugin/plugin.json` declares the plugin package.
+- `skills/aim/SKILL.md` teaches Codex to install the hook and add rules with the local `aim` command instead of inventing grant JSON manually.
+- `hooks/hooks.json` bundles the `PreToolUse` hook for plugin installs.
+- `bin/aim.js` is the command surface.
+
+The current prototype implements prompt-to-guardrail compilation, Codex `PreToolUse` blocking for Bash, `apply_patch`, and MCP tool calls, MCP-call capture, JSON policy writes, deny-overrides precedence, and decision audit rows. It intentionally skips the real MCP proxy, token vault, OAuth, Cedar, and hosted control plane.

package/bin/aim.js

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import {
+  addGrantDraft,
+  compileCodexRulePrompt,
+  compileGrantPrompt,
+  createPolicy,
+  deriveMcpCall,
+  draftGrantFromCall,
+  evaluateCodexHook,
+  evaluatePolicyCall,
+} from "../src/engine.js";
+
+const args = parseArgs(process.argv.slice(2));
+const command = args._.shift();
+
+try {
+  if (!command || command === "help" || args.help) {
+    printHelp();
+  } else if (command === "compile") {
+    compileCommand(args);
+  } else if (command === "add") {
+    addCommand(args);
+  } else if (command === "rule") {
+    ruleCommand(args);
+  } else if (command === "setup") {
+    setupCommand(args);
+  } else if (command === "hook") {
+    hookCommand(args);
+  } else if (command === "capture") {
+    captureCommand(args);
+  } else if (command === "check") {
+    checkCommand(args);
+  } else if (command === "authorize") {
+    authorizeCommand(args);
+  } else if (command === "demo") {
+    demoCommand(args);
+  } else {
+    fail(`Unknown command: ${command}`, 1, args.json);
+  }
+} catch (error) {
+  fail(error.message, 1, args.json);
+}
+
+function ruleCommand(args) {
+  const subcommand = args._.shift();
+  if (subcommand === "add") {
+    ruleAddCommand(args);
+  } else if (subcommand === "list") {
+    ruleListCommand(args);
+  } else {
+    fail("Usage: aim rule add <intent> [--json] or aim rule list [--json]", 1, args.json);
+  }
+}
+
+function ruleAddCommand(args) {
+  const prompt = promptFrom(args);
+  const policyPath = policyPathFrom(args);
+  const policy = readPolicy(policyPath);
+  const result = compileCodexRulePrompt(prompt, { agentUid: args.agent ?? "codex" });
+
+  if (result.questions.length > 0 && !args.force) {
+    writeOutput({
+      error: "Refusing to write ambiguous Codex guardrail.",
+      questions: result.questions,
+      drafts: result.drafts,
+    }, args, true);
+    process.exitCode = 2;
+    return;
+  }
+
+  const grants = result.drafts.map((draft) =>
+    addGrantDraft(policy, draft, {
+      agentUid: args.agent ?? "codex",
+      grantedBy: args["granted-by"] ?? "aim",
+      connectionId: args.connection,
+    }),
+  );
+  writePolicy(policyPath, policy);
+  writeOutput({ policy: resolve(policyPath), grants, questions: result.questions }, args);
+}
+
+function ruleListCommand(args) {
+  const policyPath = policyPathFrom(args);
+  writeOutput({ policy: resolve(policyPath), grants: readPolicy(policyPath).grants }, args);
+}
+
+function setupCommand(args) {
+  const codexHome = codexHomeFrom(args);
+  const policyPath = policyPathFrom(args, codexHome);
+  const hooksPath = join(codexHome, "hooks.json");
+  const commandPrefix = args.command ?? "npx -y @samirosamsam/aim@latest";
+  const hookCommand = `${commandPrefix} hook pre-tool-use --policy ${quote(policyPath)}`;
+  const hooksConfig = readJson(hooksPath, { hooks: {} });
+  hooksConfig.hooks ??= {};
+  hooksConfig.hooks.PreToolUse = (hooksConfig.hooks.PreToolUse ?? [])
+    .filter((entry) => !(entry.hooks ?? []).some((hook) => String(hook.command ?? "").includes("aim") && String(hook.command ?? "").includes("pre-tool-use")));
+  hooksConfig.hooks.PreToolUse.push({
+    matcher: args.matcher ?? ".*",
+    hooks: [{
+      type: "command",
+      command: hookCommand,
+      timeout: Number(args.timeout ?? 5),
+      statusMessage: "AIM checking tool call",
+    }],
+  });
+
+  if (!existsSync(policyPath)) writePolicy(policyPath, createPolicy());
+  writeJson(hooksPath, hooksConfig);
+  writeOutput({ codexHome, hooks: resolve(hooksPath), policy: resolve(policyPath), command: hookCommand }, args);
+}
+
+function hookCommand(args) {
+  const subcommand = args._.shift();
+  if (subcommand !== "pre-tool-use") fail("Usage: aim hook pre-tool-use [--policy <file>]", 1, args.json);
+  const policy = readPolicy(policyPathFrom(args));
+  const input = JSON.parse(readFileSync(0, "utf8") || "{}");
+  const result = evaluateCodexHook(policy, input, { agentUid: args.agent ?? "codex" });
+
+  if (result.decision === "deny") {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: `AIM blocked ${input.tool_name ?? "tool"}: ${result.reason}`,
+      },
+    }, null, 2));
+    return;
+  }
+
+  if (args.json) writeOutput(result, args);
+}
+
+function compileCommand(args) {
+  const prompt = promptFrom(args);
+  const result = compileGrantPrompt(prompt, { agentUid: args.agent ?? "" });
+  const drafts = applyDraftOverrides(result.drafts, args);
+  writeOutput({ intent: prompt, drafts, questions: result.questions }, args);
+}
+
+function addCommand(args) {
+  const prompt = promptFrom(args);
+  const policyPath = requireFlag(args, "policy");
+  const agentUid = requireFlag(args, "agent");
+  const policy = readPolicy(policyPath);
+  const result = compileGrantPrompt(prompt, { agentUid });
+  const drafts = applyDraftOverrides(result.drafts, args);
+
+  if (result.questions.length > 0 && !args.force) {
+    writeOutput({
+      error: "Refusing to write ambiguous grants. Answer questions or pass --force.",
+      questions: result.questions,
+      drafts,
+    }, args, true);
+    process.exitCode = 2;
+    return;
+  }
+
+  const grants = drafts.map((draft) =>
+    addGrantDraft(policy, draft, {
+      agentUid,
+      grantedBy: args["granted-by"] ?? "codex",
+      connectionId: args.connection,
+    }),
+  );
+  writePolicy(policyPath, policy);
+  writeOutput({ policy: resolve(policyPath), grants }, args);
+}
+
+function captureCommand(args) {
+  const call = callFromArgs(args);
+  const draft = draftGrantFromCall(call, {
+    effect: args.effect ?? "deny",
+    strictTool: Boolean(args["strict-tool"]),
+    reason: args.reason,
+  });
+  const questions = draft.resourcePattern === "*" ? ["Pass --resource or more MCP args before writing this rule."] : [];
+
+  if (args.policy) {
+    if (questions.length > 0 && !args.force) {
+      writeOutput({ error: "Refusing to write ambiguous MCP rule.", questions, draft }, args, true);
+      process.exitCode = 2;
+      return;
+    }
+    const policy = readPolicy(args.policy);
+    const grant = addGrantDraft(policy, draft, {
+      agentUid: requireFlag(args, "agent"),
+      grantedBy: args["granted-by"] ?? "codex",
+      connectionId: args.connection,
+    });
+    writePolicy(args.policy, policy);
+    writeOutput({ policy: resolve(args.policy), call, grants: [grant], questions }, args);
+    return;
+  }
+
+  writeOutput({ call, drafts: [draft], questions }, args);
+}
+
+function checkCommand(args) {
+  const policyPath = requireFlag(args, "policy");
+  const decision = evaluatePolicyCall(readPolicy(policyPath), {
+    agentUid: requireFlag(args, "agent"),
+    connectionId: requireFlag(args, "connection"),
+    tool: requireFlag(args, "tool"),
+    resource: requireFlag(args, "resource"),
+    access: args.access ?? "read",
+    params: args.params ? JSON.parse(args.params) : {},
+  });
+  writeOutput({ policy: resolve(policyPath), decision }, args);
+}
+
+function authorizeCommand(args) {
+  const policyPath = requireFlag(args, "policy");
+  const call = callFromArgs(args);
+  const decision = evaluatePolicyCall(readPolicy(policyPath), call);
+  writeOutput({ policy: resolve(policyPath), call, decision }, args);
+}
+
+function demoCommand(args) {
+  const policy = createPolicy();
+  const agentUid = "spiffe://local/agent/demo/codex";
+  const allow = compileGrantPrompt('Allow Notion read access to "workspace/shared/*"', { agentUid }).drafts[0];
+  const deny = compileGrantPrompt('Block Notion read access to "workspace/shared/legal/*"', { agentUid }).drafts[0];
+  const allowGrant = addGrantDraft(policy, allow, { agentUid, grantedBy: "demo" });
+  const denyGrant = addGrantDraft(policy, deny, { agentUid, grantedBy: "demo" });
+  const allowed = evaluatePolicyCall(policy, {
+    agentUid,
+    connectionId: "notion:prod",
+    tool: "pages.read",
+    resource: "workspace/shared/roadmap",
+    access: "read",
+  });
+  const denied = evaluatePolicyCall(policy, {
+    agentUid,
+    connectionId: "notion:prod",
+    tool: "pages.read",
+    resource: "workspace/shared/legal/term-sheet",
+    access: "read",
+  });
+  writeOutput({ grants: [allowGrant, denyGrant], decisions: [allowed, denied] }, args);
+}
+
+function applyDraftOverrides(drafts, args) {
+  return drafts.map((draft) => ({
+    ...draft,
+    agentUid: args.agent ?? draft.agentUid,
+    connectionId: args.connection ?? draft.connectionId,
+  }));
+}
+
+function callFromArgs(args) {
+  return deriveMcpCall({
+    agentUid: requireFlag(args, "agent"),
+    connectionId: requireFlag(args, "connection"),
+    provider: args.provider,
+    tool: requireFlag(args, "tool"),
+    args: args.args ? JSON.parse(args.args) : {},
+    access: args.access,
+    resource: args.resource,
+  });
+}
+
+function promptFrom(args) {
+  const prompt = args.prompt ?? args._.join(" ");
+  if (!prompt.trim()) throw new Error("Missing intent prompt.");
+  return prompt;
+}
+
+function readPolicy(path) {
+  const absolute = resolve(expandHome(path));
+  if (!existsSync(absolute)) return createPolicy();
+  return createPolicy(JSON.parse(readFileSync(absolute, "utf8")));
+}
+
+function writePolicy(path, policy) {
+  const absolute = resolve(expandHome(path));
+  mkdirSync(dirname(absolute), { recursive: true });
+  writeFileSync(absolute, `${JSON.stringify(policy, null, 2)}\n`);
+}
+
+function readJson(path, fallback) {
+  const absolute = resolve(expandHome(path));
+  if (!existsSync(absolute)) return fallback;
+  return JSON.parse(readFileSync(absolute, "utf8"));
+}
+
+function writeJson(path, value) {
+  const absolute = resolve(expandHome(path));
+  mkdirSync(dirname(absolute), { recursive: true });
+  writeFileSync(absolute, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function writeOutput(payload, args, stderr = false) {
+  const text = args.json ? JSON.stringify(payload, null, 2) : humanize(payload);
+  (stderr ? console.error : console.log)(text);
+}
+
+function humanize(payload) {
+  if (payload.error) {
+    return `${payload.error}\n${(payload.questions ?? []).map((q) => `- ${q}`).join("\n")}`;
+  }
+  if (payload.decision) {
+    return `${payload.decision.decision}: ${payload.decision.reason}`;
+  }
+  if (payload.grants) {
+    return payload.grants.map(formatGrant).join("\n");
+  }
+  if (payload.hooks) {
+    return `AIM hook installed\npolicy: ${payload.policy}\nhooks: ${payload.hooks}`;
+  }
+  if (!payload.drafts) return JSON.stringify(payload, null, 2);
+  return [
+    ...(payload.questions ?? []).map((question) => `QUESTION ${question}`),
+    ...payload.drafts.map(formatGrant),
+  ].join("\n");
+}
+
+function formatGrant(grant) {
+  return [
+    grant.effect.toUpperCase(),
+    grant.access,
+    grant.connectionId,
+    grant.toolPattern,
+    grant.resourcePattern,
+  ].join(" ");
+}
+
+function requireFlag(args, name) {
+  if (!args[name]) throw new Error(`Missing --${name}.`);
+  return args[name];
+}
+
+function codexHomeFrom(args) {
+  return resolve(expandHome(args["codex-home"] ?? process.env.CODEX_HOME ?? join(homedir(), ".codex")));
+}
+
+function policyPathFrom(args, codexHome = codexHomeFrom(args)) {
+  return resolve(expandHome(args.policy ?? join(codexHome, "aim", "policy.json")));
+}
+
+function expandHome(path) {
+  const text = String(path);
+  return text === "~" || text.startsWith("~/") ? join(homedir(), text.slice(2)) : text;
+}
+
+function quote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function parseArgs(argv) {
+  const parsed = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      parsed._.push(arg);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith("--")) {
+      parsed[key] = true;
+    } else {
+      parsed[key] = next;
+      i += 1;
+    }
+  }
+  return parsed;
+}
+
+function fail(message, code = 1, asJson = false) {
+  console.error(asJson ? JSON.stringify({ error: message }, null, 2) : message);
+  process.exit(code);
+}
+
+function printHelp() {
+  console.log(`AIM command
+
+Usage:
+  aim compile "<intent>" [--agent <uid>] [--connection <id>] [--json]
+  aim setup [--codex-home <dir>] [--policy <file>] [--json]
+  aim rule add "<intent>" [--codex-home <dir>] [--policy <file>] [--json]
+  aim rule list [--codex-home <dir>] [--policy <file>] [--json]
+  aim hook pre-tool-use [--policy <file>]
+  aim add "<intent>" --policy <file> --agent <uid> [--connection <id>] [--granted-by <id>] [--json]
+  aim capture --provider <name> --tool <name> --args <json> --effect allow|deny|approval --agent <uid> --connection <id> [--policy <file>] [--json]
+  aim authorize --policy <file> --agent <uid> --connection <id> --provider <name> --tool <name> --args <json> [--json]
+  aim check --policy <file> --agent <uid> --connection <id> --tool <name> --resource <path> [--access read|write|delete] [--json]
+  aim demo [--json]
+`);
+}

package/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y @samirosamsam/aim@latest hook pre-tool-use",
+            "timeout": 5,
+            "statusMessage": "AIM checking tool call"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@samirosamsam/aim",
+  "version": "0.1.0",
+  "description": "AIM CLI for installing deterministic Codex tool-call guardrails.",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "aim": "bin/aim.js"
+  },
+  "files": [
+    ".agents/plugins/marketplace.json",
+    ".codex-plugin/plugin.json",
+    "bin/",
+    "hooks/",
+    "skills/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepublishOnly": "npm test",
+    "test": "node test/engine.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tototozip/AIM.git"
+  },
+  "keywords": [
+    "agents",
+    "codex",
+    "iam",
+    "mcp",
+    "permissions"
+  ],
+  "author": "AIM",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}