@behalfid/cli 0.1.0

package/dist/commands/permissions.js

@@ -0,0 +1,74 @@
+import { Command } from "commander";
+import { apiRequest, resolveApiKey, resolveBaseUrl } from "../lib/client.js";
+import { isJsonMode, printJson, printKv, printSuccess, runAction } from "../lib/output.js";
+export function permissionsCommand() {
+    const cmd = new Command("permissions").description("manage agent permissions");
+    cmd
+        .command("create <agentId>")
+        .description("create a permission for an agent (requires agent API key)")
+        .requiredOption("-a, --action <action>", "action to permit (e.g. purchase, access_data, schedule)")
+        .option("-r, --resource <resource>", "resource or vendor (e.g. amazon.com, gmail.com)")
+        .option("-s, --scope <scope>", "plain-English scope description")
+        .option("-d, --description <desc>", "permission description")
+        .option("--template <template>", "template: purchase, access_data, create_content, schedule, custom")
+        .option("--max-amount <n>", "maximum transaction amount (for purchase permissions)")
+        .option("--expires <date>", "expiry date (ISO 8601, e.g. 2027-01-01)")
+        .option("--allowed <actions>", "comma-separated allowed actions")
+        .option("--blocked <actions>", "comma-separated blocked actions")
+        .option("--requires-approval", "require human approval before acting")
+        .option("-k, --api-key <key>", "agent API key (overrides config)")
+        .action(runAction(async (agentId, opts) => {
+        const apiKey = opts.apiKey ?? resolveApiKey();
+        if (!apiKey)
+            throw new Error("An agent API key is required. Set it with `behalf config set api-key <key>` or pass --api-key.");
+        const baseUrl = resolveBaseUrl();
+        const body = { agentId, action: opts.action };
+        if (opts.resource)
+            body.resource = opts.resource;
+        if (opts.scope)
+            body.scope = opts.scope;
+        if (opts.description)
+            body.description = opts.description;
+        if (opts.template)
+            body.template = opts.template;
+        if (opts.requiresApproval)
+            body.requiresApproval = true;
+        if (opts.allowed)
+            body.allowedActions = opts.allowed.split(",").map(s => s.trim()).filter(Boolean);
+        if (opts.blocked)
+            body.blockedActions = opts.blocked.split(",").map(s => s.trim()).filter(Boolean);
+        if (opts.maxAmount || opts.expires || opts.resource) {
+            const constraints = {};
+            if (opts.maxAmount)
+                constraints.maxAmount = Number(opts.maxAmount);
+            if (opts.expires)
+                constraints.expiresAt = new Date(opts.expires).toISOString();
+            if (opts.resource)
+                constraints.allowedVendors = [opts.resource];
+            body.constraints = constraints;
+        }
+        const data = await apiRequest("/api/permissions", {
+            method: "POST", body, apiKey, baseUrl,
+        });
+        if (isJsonMode())
+            printJson(data);
+        else
+            printKv({ permissionId: data.permissionId, status: data.status });
+    }));
+    cmd
+        .command("revoke <permissionId>")
+        .description("revoke a permission (requires agent API key)")
+        .option("-k, --api-key <key>", "agent API key (overrides config)")
+        .action(runAction(async (permissionId, opts) => {
+        const apiKey = opts.apiKey ?? resolveApiKey();
+        if (!apiKey)
+            throw new Error("An agent API key is required. Set it with `behalf config set api-key <key>` or pass --api-key.");
+        const baseUrl = resolveBaseUrl();
+        const data = await apiRequest(`/api/permissions/${encodeURIComponent(permissionId)}/revoke`, { method: "POST", apiKey, baseUrl });
+        if (isJsonMode())
+            printJson(data);
+        else
+            printSuccess(`Permission ${permissionId} revoked.`);
+    }));
+    return cmd;
+}

package/dist/commands/run.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+export declare function runCommand(): Command;
+export declare function claudeCommand(): Command;
+export declare function codexCommand(): Command;

package/dist/commands/run.js

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { Command } from "commander";
+import { resolveBaseUrl } from "../lib/client.js";
+import { readConfig } from "../lib/config.js";
+import { generateContextMd, generateMcpJson } from "../lib/context-generator.js";
+import { fetchAndCacheDetail, readCachedDetail } from "../lib/passport-cache.js";
+import { runAction } from "../lib/output.js";
+import { mkdirSync } from "node:fs";
+const TOOLS = {
+    claude: {
+        binary: "claude",
+        contextFiles: ["CLAUDE.md"],
+        injectLine: "@.behalf/context.md",
+    },
+    codex: {
+        binary: "codex",
+        contextFiles: ["AGENTS.md"],
+        injectLine: "@.behalf/context.md",
+    },
+    cursor: {
+        binary: "cursor",
+        contextFiles: [".cursorrules"],
+        injectLine: "@.behalf/context.md",
+    },
+};
+async function launchTool(toolKey, extraArgs) {
+    const tool = TOOLS[toolKey];
+    if (!tool)
+        throw new Error(`Unknown tool "${toolKey}". Supported: ${Object.keys(TOOLS).join(", ")}`);
+    const config = readConfig();
+    const agentId = config.agentId ?? process.env.BEHALFID_AGENT_ID;
+    const baseUrl = resolveBaseUrl();
+    if (!agentId) {
+        throw new Error("Agent ID not configured.\nRun: behalf config set agent-id <agentId>");
+    }
+    const cwd = process.cwd();
+    const behalfDir = join(cwd, ".behalf");
+    const contextFile = join(behalfDir, "context.md");
+    const mcpJsonPath = join(cwd, ".mcp.json");
+    // Fetch or refresh permissions
+    let detail = readCachedDetail(agentId);
+    if (!detail) {
+        process.stderr.write("Fetching BehalfID permissions… ");
+        try {
+            detail = await fetchAndCacheDetail(agentId, baseUrl, false);
+            process.stderr.write("done.\n");
+        }
+        catch (err) {
+            process.stderr.write(`failed (${err instanceof Error ? err.message : String(err)}).\n`);
+            process.stderr.write("Continuing without live permissions. Run `behalf mcp init` to populate the cache.\n");
+        }
+    }
+    // Write .behalf/context.md
+    if (detail) {
+        if (!existsSync(behalfDir))
+            mkdirSync(behalfDir, { recursive: true });
+        writeFileSync(contextFile, generateContextMd(detail));
+    }
+    // Write .mcp.json (merge with existing)
+    let existingMcp = null;
+    if (existsSync(mcpJsonPath)) {
+        try {
+            existingMcp = JSON.parse(readFileSync(mcpJsonPath, "utf-8"));
+        }
+        catch { /* ignore */ }
+    }
+    writeFileSync(mcpJsonPath, generateMcpJson(existingMcp ?? undefined));
+    // Inject include into tool config files (idempotent)
+    for (const fileName of tool.contextFiles) {
+        const filePath = join(cwd, fileName);
+        if (!existsSync(filePath))
+            continue;
+        const content = readFileSync(filePath, "utf-8");
+        if (!content.includes(tool.injectLine)) {
+            writeFileSync(filePath, content + `\n\n${tool.injectLine}\n`);
+        }
+    }
+    // Launch the tool
+    const result = spawnSync(tool.binary, extraArgs, { stdio: "inherit" });
+    process.exit(result.status ?? 0);
+}
+function toolCommand(toolKey, description) {
+    return new Command(toolKey)
+        .description(description)
+        .allowUnknownOption(true)
+        .passThroughOptions(true)
+        .argument("[args...]", `arguments to pass to ${toolKey}`)
+        .action(runAction(async (args) => {
+        await launchTool(toolKey, args);
+    }));
+}
+export function runCommand() {
+    return new Command("run")
+        .description("launch an AI tool with BehalfID enforcement active")
+        .allowUnknownOption(true)
+        .passThroughOptions(true)
+        .argument("<tool>", `tool to launch: ${Object.keys(TOOLS).join(", ")}`)
+        .argument("[args...]", "arguments to pass through to the tool")
+        .action(runAction(async (toolKey, args) => {
+        await launchTool(toolKey, args);
+    }));
+}
+export function claudeCommand() { return toolCommand("claude", "launch Claude Code with BehalfID enforcement"); }
+export function codexCommand() { return toolCommand("codex", "launch Codex CLI with BehalfID enforcement"); }

package/dist/commands/verify.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function verifyCommand(): Command;

package/dist/commands/verify.js

@@ -0,0 +1,37 @@
+import { Command } from "commander";
+import { apiRequest, resolveApiKey, resolveBaseUrl } from "../lib/client.js";
+import { isJsonMode, printJson, printKv, runAction } from "../lib/output.js";
+export function verifyCommand() {
+    return new Command("verify")
+        .description("verify whether an agent may perform an action")
+        .argument("<agentId>", "agent ID")
+        .requiredOption("-a, --action <action>", "action to verify (e.g. purchase, access_data)")
+        .option("-v, --vendor <vendor>", "vendor or resource (e.g. amazon.com, gmail.com)")
+        .option("-r, --resource <resource>", "alias for --vendor")
+        .option("--amount <n>", "transaction amount (for purchase actions)")
+        .option("-k, --api-key <key>", "agent API key (overrides config)")
+        .action(runAction(async (agentId, opts) => {
+        const apiKey = opts.apiKey ?? resolveApiKey();
+        if (!apiKey)
+            throw new Error("An agent API key is required. Set it with `behalf config set api-key <key>` or pass --api-key.");
+        const baseUrl = resolveBaseUrl();
+        const body = { agentId, action: opts.action };
+        const vendor = opts.vendor ?? opts.resource;
+        if (vendor)
+            body.vendor = vendor;
+        if (opts.amount)
+            body.amount = Number(opts.amount);
+        const data = await apiRequest("/api/verify", {
+            method: "POST", body, apiKey, baseUrl,
+        });
+        if (isJsonMode()) {
+            printJson(data);
+            return;
+        }
+        console.log(`\n${data.allowed ? "✓ ALLOWED" : "✗ DENIED"}`);
+        printKv({ requestId: data.requestId, reason: data.reason, risk: data.risk });
+        console.log("");
+        if (!data.allowed)
+            process.exit(1);
+    }));
+}

package/dist/commands/whoami.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function whoamiCommand(): Command;

package/dist/commands/whoami.js

@@ -0,0 +1,49 @@
+import { Command } from "commander";
+import { readConfig, readSession } from "../lib/config.js";
+import { apiRequest, resolveBaseUrl } from "../lib/client.js";
+import { isJsonMode, printJson, printKv, runAction } from "../lib/output.js";
+export function whoamiCommand() {
+    return new Command("whoami")
+        .description("show current authentication status")
+        .action(runAction(async function () {
+        const config = readConfig();
+        const session = readSession();
+        const baseUrl = resolveBaseUrl();
+        let user = null;
+        if (session) {
+            try {
+                const data = await apiRequest("/api/auth/me", { baseUrl });
+                user = data.user;
+            }
+            catch {
+                // session may be expired
+            }
+        }
+        if (isJsonMode()) {
+            printJson({
+                loggedIn: !!user,
+                email: user?.email ?? null,
+                userId: user?.userId ?? null,
+                apiKey: config.apiKey ? `${config.apiKey.slice(0, 15)}…` : null,
+                baseUrl: config.baseUrl ?? null,
+            });
+            return;
+        }
+        if (user) {
+            printKv({
+                email: user.email,
+                userId: user.userId,
+                "api key": config.apiKey ? `${config.apiKey.slice(0, 15)}…` : "(not set)",
+                "base url": baseUrl,
+            });
+        }
+        else {
+            console.log("Not logged in.");
+            if (config.apiKey) {
+                console.log(`API key: ${config.apiKey.slice(0, 15)}…`);
+            }
+            console.log(`Base URL: ${baseUrl}`);
+            console.log('\nRun `behalf login` to authenticate.');
+        }
+    }));
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { setJsonMode } from "./lib/output.js";
+import { configCommand } from "./commands/config.js";
+import { initCommand } from "./commands/init.js";
+import { loginCommand } from "./commands/login.js";
+import { logoutCommand } from "./commands/logout.js";
+import { whoamiCommand } from "./commands/whoami.js";
+import { agentsCommand } from "./commands/agents.js";
+import { permissionsCommand } from "./commands/permissions.js";
+import { verifyCommand } from "./commands/verify.js";
+import { logsCommand } from "./commands/logs.js";
+import { passportCommand } from "./commands/passport.js";
+import { healthCommand } from "./commands/health.js";
+import { mcpCommand } from "./commands/mcp.js";
+import { runCommand, claudeCommand, codexCommand } from "./commands/run.js";
+const rawArgs = process.argv.slice(2);
+const jsonMode = rawArgs.includes("--json");
+if (jsonMode)
+    setJsonMode(true);
+const filteredArgs = rawArgs.filter(a => a !== "--json");
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const { version } = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
+const program = new Command();
+program
+    .name("behalf")
+    .description("Official CLI for BehalfID — agent permission management and enforcement")
+    .version(version)
+    .addHelpText("after", `
+Examples:
+  behalf init                                     interactive setup wizard
+  behalf login                                    log in to your account
+  behalf agents create --name "My Bot" --save     create agent and save credentials
+  behalf mcp init                                 set up BehalfID enforcement in this directory
+  behalf claude                                   launch Claude Code with enforcement active
+  behalf verify agent_xxx --action purchase -v amazon.com --amount 25
+  behalf permissions create agent_xxx --action purchase -r amazon.com --max-amount 50
+  behalf logs agent_xxx                           view recent verification logs
+`);
+program.enablePositionalOptions();
+program.addCommand(initCommand());
+program.addCommand(configCommand());
+program.addCommand(loginCommand());
+program.addCommand(logoutCommand());
+program.addCommand(whoamiCommand());
+program.addCommand(agentsCommand());
+program.addCommand(permissionsCommand());
+program.addCommand(verifyCommand());
+program.addCommand(logsCommand());
+program.addCommand(passportCommand());
+program.addCommand(healthCommand());
+program.addCommand(mcpCommand());
+program.addCommand(runCommand());
+program.addCommand(claudeCommand());
+program.addCommand(codexCommand());
+program.parseAsync(["", "", ...filteredArgs]).catch(err => {
+    if (jsonMode) {
+        console.error(JSON.stringify({ error: err.message }));
+    }
+    else {
+        console.error(`Error: ${err.message}`);
+    }
+    process.exit(1);
+});

package/dist/lib/client.d.ts

@@ -0,0 +1,13 @@
+export declare const DEFAULT_BASE_URL = "https://behalfid.com";
+export type RequestOptions = {
+    method?: "GET" | "POST" | "PATCH" | "DELETE";
+    body?: unknown;
+    apiKey?: string;
+    baseUrl?: string;
+    skipAuth?: boolean;
+    onHeaders?: (headers: Headers) => void;
+};
+export declare function resolveBaseUrl(override?: string): string;
+export declare function resolveApiKey(override?: string): string | undefined;
+export declare function originOf(baseUrl: string): string;
+export declare function apiRequest<T = unknown>(path: string, opts?: RequestOptions): Promise<T>;

package/dist/lib/client.js

@@ -0,0 +1,62 @@
+import { readConfig, readSession } from "./config.js";
+export const DEFAULT_BASE_URL = "https://behalfid.com";
+export function resolveBaseUrl(override) {
+    const config = readConfig();
+    return (override ??
+        process.env.BEHALFID_BASE_URL ??
+        config.baseUrl ??
+        DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+export function resolveApiKey(override) {
+    const config = readConfig();
+    return override ?? process.env.BEHALFID_API_KEY ?? config.apiKey;
+}
+export function originOf(baseUrl) {
+    try {
+        return new URL(baseUrl).origin;
+    }
+    catch {
+        return baseUrl;
+    }
+}
+export async function apiRequest(path, opts = {}) {
+    const baseUrl = resolveBaseUrl(opts.baseUrl);
+    const apiKey = opts.skipAuth ? undefined : opts.apiKey ?? resolveApiKey();
+    const session = opts.skipAuth ? null : readSession();
+    const headers = {
+        Accept: "application/json",
+        Origin: originOf(baseUrl),
+    };
+    if (apiKey)
+        headers.Authorization = `Bearer ${apiKey}`;
+    if (session)
+        headers.Cookie = session;
+    if (opts.body !== undefined)
+        headers["Content-Type"] = "application/json";
+    let response;
+    try {
+        response = await fetch(`${baseUrl}${path}`, {
+            method: opts.method ?? "GET",
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+        });
+    }
+    catch {
+        throw new Error("Network request failed. Check your connection and base URL.");
+    }
+    if (opts.onHeaders)
+        opts.onHeaders(response.headers);
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+        const message = typeof body === "object" &&
+            body !== null &&
+            "error" in body &&
+            typeof body.error === "string"
+            ? body.error
+            : `Request failed with status ${response.status}.`;
+        throw new Error(message);
+    }
+    if (body === null)
+        throw new Error("Expected JSON response.");
+    return body;
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,13 @@
+export type Config = {
+    apiKey?: string;
+    agentId?: string;
+    baseUrl?: string;
+};
+export declare function readConfig(): Config;
+export declare function writeConfig(config: Config): void;
+export declare function patchConfig(patch: Partial<Config>): void;
+export declare function readSession(): string | null;
+export declare function writeSession(cookie: string): void;
+export declare function clearSession(): void;
+export declare const CONFIG_FILE_PATH: string;
+export declare const CONFIG_DIR_PATH: string;

package/dist/lib/config.js

@@ -0,0 +1,48 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const CONFIG_DIR = join(homedir(), ".behalf");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+const SESSION_FILE = join(CONFIG_DIR, "session");
+function ensureDir() {
+    if (!existsSync(CONFIG_DIR))
+        mkdirSync(CONFIG_DIR, { recursive: true });
+}
+export function readConfig() {
+    if (!existsSync(CONFIG_FILE))
+        return {};
+    try {
+        return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfig(config) {
+    ensureDir();
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+}
+export function patchConfig(patch) {
+    writeConfig({ ...readConfig(), ...patch });
+}
+export function readSession() {
+    if (!existsSync(SESSION_FILE))
+        return null;
+    try {
+        const val = readFileSync(SESSION_FILE, "utf-8").trim();
+        return val || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSession(cookie) {
+    ensureDir();
+    writeFileSync(SESSION_FILE, cookie, { mode: 0o600 });
+}
+export function clearSession() {
+    if (existsSync(SESSION_FILE))
+        writeFileSync(SESSION_FILE, "", { mode: 0o600 });
+}
+export const CONFIG_FILE_PATH = CONFIG_FILE;
+export const CONFIG_DIR_PATH = CONFIG_DIR;

package/dist/lib/context-generator.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDetail } from "./passport-cache.js";
+export declare function generateContextMd(detail: AgentDetail, updatedAt?: string): string;
+export declare function generateMcpJson(existing?: Record<string, unknown>): string;

package/dist/lib/context-generator.js

@@ -0,0 +1,70 @@
+function formatConstraints(p) {
+    const lines = [];
+    if (p.constraints?.maxAmount)
+        lines.push(`max $${p.constraints.maxAmount}`);
+    if (p.constraints?.allowedVendors?.length)
+        lines.push(`vendors: ${p.constraints.allowedVendors.join(", ")}`);
+    if (p.constraints?.expiresAt)
+        lines.push(`expires: ${p.constraints.expiresAt.slice(0, 10)}`);
+    return lines;
+}
+export function generateContextMd(detail, updatedAt) {
+    const { agent, permissions } = detail;
+    const active = permissions.filter(p => p.status === "active");
+    const timestamp = updatedAt ?? new Date().toISOString().slice(0, 16).replace("T", " ");
+    const lines = [
+        `<!-- BehalfID Agent Context — auto-generated by \`behalf mcp init\` -->`,
+        `<!-- Run \`behalf mcp init --refresh\` to update -->`,
+        ``,
+        `## BehalfID Agent: ${agent.name}`,
+        ``,
+        `You are operating as BehalfID agent **\`${agent.agentId}\`** ("${agent.name}").`,
+        ``,
+        `The \`behalfid\` MCP server is active in this session.`,
+        ``,
+        `**ENFORCEMENT RULE: Before executing any action that touches an external service,`,
+        `you MUST call the \`verify_action\` tool from the \`behalfid\` MCP server.**`,
+        `If \`verify_action\` returns \`"allowed": false\`, stop immediately and tell the user`,
+        `why the action was blocked. Never bypass or skip this check.`,
+        ``,
+    ];
+    if (active.length === 0) {
+        lines.push(`### Permissions`, ``, `No active permissions. All external actions will be denied.`, ``);
+    }
+    else {
+        lines.push(`### Active Permissions`, ``);
+        for (const p of active) {
+            const constraints = formatConstraints(p);
+            const constraintStr = constraints.length ? ` (${constraints.join(", ")})` : "";
+            lines.push(`- **${p.action}**${p.resource ? ` → \`${p.resource}\`` : ""}${constraintStr}${p.scope ? `: ${p.scope}` : ""}`);
+            if (p.allowedActions?.length) {
+                lines.push(`  - Allowed: ${p.allowedActions.map(a => `"${a}"`).join(", ")}`);
+            }
+            if (p.blockedActions?.length) {
+                lines.push(`  - Blocked: ${p.blockedActions.map(a => `"${a}"`).join(", ")}`);
+            }
+            if (p.requiresApproval) {
+                lines.push(`  - ⚠ Requires human approval before proceeding`);
+            }
+        }
+        lines.push(``);
+    }
+    lines.push(`### How to call \`verify_action\``, ``, `\`\`\``, `verify_action(action: string, vendor?: string, amount?: number)`, `// action: "purchase" | "access_data" | "browse_web" | "schedule" | "create_content" | ...`, `// vendor: the service or domain being accessed (e.g. "amazon.com", "gmail.com")`, `// amount: only for purchase actions`, `\`\`\``, ``, `---`, `*Updated ${timestamp} · Agent \`${agent.agentId}\` · [BehalfID](https://behalfid.com)*`);
+    return lines.join("\n");
+}
+export function generateMcpJson(existing) {
+    const base = existing ?? {};
+    const servers = base.mcpServers ?? {};
+    const updated = {
+        ...base,
+        mcpServers: {
+            ...servers,
+            behalfid: {
+                type: "stdio",
+                command: "behalf",
+                args: ["mcp", "start"],
+            },
+        },
+    };
+    return JSON.stringify(updated, null, 2) + "\n";
+}

package/dist/lib/mcp-server.d.ts

@@ -0,0 +1,5 @@
+export declare function startMcpServer(config: {
+    agentId: string;
+    apiKey: string;
+    baseUrl: string;
+}): Promise<void>;