agent-authority 0.1.0

package/dist/capability.js

@@ -0,0 +1,176 @@
+import { CapabilityParseError } from "./errors.js";
+const OP_RE = "<=|>=|<|>|=";
+const MAIN_RE = new RegExp(`^([^:\\s]+):([^<>=\\s]+)(?:(${OP_RE})([0-9]*\\.?[0-9]+))?$`);
+const RATE_RE = new RegExp(`^rate(${OP_RE})([0-9]*\\.?[0-9]+)(?:\\/([smhd]))?$`);
+/** Parse a capability string into structured form. Throws on malformed input. */
+export function parse(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        throw new CapabilityParseError(raw, "empty");
+    }
+    if (trimmed === "*") {
+        return { raw: trimmed, wildcard: true, verb: "*", resource: "*" };
+    }
+    const parts = trimmed.split(/\s+/);
+    const main = parts[0];
+    const m = MAIN_RE.exec(main);
+    if (!m) {
+        throw new CapabilityParseError(raw, 'expected "<verb>:<resource>" optionally with a constraint');
+    }
+    const cap = {
+        raw: trimmed,
+        wildcard: false,
+        verb: m[1],
+        resource: m[2],
+    };
+    if (m[3]) {
+        cap.amount = { op: m[3], value: Number(m[4]) };
+    }
+    for (const extra of parts.slice(1)) {
+        const r = RATE_RE.exec(extra);
+        if (!r) {
+            throw new CapabilityParseError(raw, `unrecognized constraint "${extra}"`);
+        }
+        cap.rate = { op: r[1], value: Number(r[2]), per: r[3] ?? "h" };
+    }
+    return cap;
+}
+/** Window length in milliseconds for a rate unit. */
+export function windowMs(per) {
+    switch (per) {
+        case "s":
+            return 1000;
+        case "m":
+            return 60_000;
+        case "h":
+            return 3_600_000;
+        case "d":
+            return 86_400_000;
+    }
+}
+function applyOp(value, op, limit) {
+    switch (op) {
+        case "<=":
+            return value <= limit;
+        case ">=":
+            return value >= limit;
+        case "<":
+            return value < limit;
+        case ">":
+            return value > limit;
+        case "=":
+            return value === limit;
+    }
+}
+/** Does grant's resource path cover the request's? Segment-prefix + wildcard. */
+function resourceCovers(grant, request) {
+    if (grant === "*" || grant === request)
+        return true;
+    if (grant.endsWith("/*")) {
+        const base = grant.slice(0, -2);
+        return request === base || request.startsWith(base + "/");
+    }
+    // Bare prefix segment: "repo" covers "repo/acme-app".
+    return request.startsWith(grant + "/");
+}
+/**
+ * Does the `grant` capability permit the `request` action?
+ *
+ * The request is the concrete action being attempted (e.g. `spend:usd=20`); the
+ * grant is the authority held (e.g. `spend:usd<=50`). Rate limits are *not*
+ * evaluated here — they require call history and are enforced by the engine.
+ */
+export function satisfies(grant, request) {
+    if (grant.wildcard)
+        return true;
+    if (request.wildcard)
+        return false; // can't request unbounded against a bounded grant
+    if (grant.verb !== request.verb)
+        return false;
+    if (!resourceCovers(grant.resource, request.resource))
+        return false;
+    if (grant.amount) {
+        // The grant imposes a quantitative cap; the request must name an amount
+        // that falls within it.
+        if (!request.amount)
+            return false;
+        if (!applyOp(request.amount.value, grant.amount.op, grant.amount.value)) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Convenience: parse both sides then check satisfaction. */
+export function permits(grant, request) {
+    return satisfies(parse(grant), parse(request));
+}
+/**
+ * Is every capability in `child` covered by some capability in `parent`?
+ * Used to reject widening at attenuation time (the chain enforces it too, but
+ * this gives a clear, early error).
+ */
+export function isNarrowing(parent, child) {
+    const parents = parent.map(parse);
+    for (const c of child) {
+        const childCap = parse(c);
+        const covered = parents.some((p) => coversCapability(p, childCap));
+        if (!covered)
+            return { ok: false, offending: c };
+    }
+    return { ok: true };
+}
+/**
+ * Is `child`'s quantitative bound a genuine tightening of `grant`'s, in the same
+ * direction? An upper bound (`<=`/`<`) may only be narrowed by another upper
+ * bound or an exact value within it; a lower bound (`>=`/`>`) likewise; `=` must
+ * match. This rejects direction flips like narrowing `usd<=50` to `usd>=10`.
+ */
+function amountNarrows(grant, child) {
+    const isUpper = (op) => op === "<=" || op === "<";
+    const isLower = (op) => op === ">=" || op === ">";
+    if (grant.op === "=")
+        return child.op === "=" && child.value === grant.value;
+    if (isUpper(grant.op)) {
+        if (!isUpper(child.op) && child.op !== "=")
+            return false;
+        return applyOp(child.value, grant.op, grant.value);
+    }
+    if (isLower(grant.op)) {
+        if (!isLower(child.op) && child.op !== "=")
+            return false;
+        return applyOp(child.value, grant.op, grant.value);
+    }
+    return false;
+}
+/**
+ * Does grant cover a *narrower capability* (not a concrete action)? This is the
+ * attenuation check: e.g. `spend:usd<=50` covers `spend:usd<=20` but not
+ * `spend:usd<=80`, and `read:calendar` covers `read:calendar`.
+ */
+function coversCapability(grant, child) {
+    if (grant.wildcard)
+        return true;
+    if (child.wildcard)
+        return false;
+    if (grant.verb !== child.verb)
+        return false;
+    if (!resourceCovers(grant.resource, child.resource))
+        return false;
+    if (grant.amount) {
+        if (!child.amount)
+            return false; // child must also be bounded
+        // The child must narrow in the SAME direction as the grant — a `<=` cap may
+        // only be tightened by another upper bound (or `=`), never flipped to `>=`.
+        if (!amountNarrows(grant.amount, child.amount))
+            return false;
+    }
+    if (grant.rate) {
+        if (!child.rate)
+            return false;
+        if (child.rate.value / windowMs(child.rate.per) > grant.rate.value / windowMs(grant.rate.per)) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { createBehalf } from "./behalf.js";
+import { newKeyPair, exportPublicKey, exportPrivateKey, importPublicKey, importPrivateKey, } from "./crypto.js";
+import { FileRevocationStore, FileAuditStore } from "./persist.js";
+import { AuthorizationError } from "./errors.js";
+import { lint } from "./lint.js";
+import { generateQuickstart, findSurface, listSurfaces, } from "./quickstart.js";
+/**
+ * `agent-authority` CLI — grant, inspect, authorize, revoke, and audit mandates from the
+ * terminal. State (issuer keypair, revocation list, audit log) lives under
+ * $BEHALF_HOME (default ~/.behalf), so mandates issued in one invocation can be
+ * checked and revoked in the next.
+ */
+const HOME = process.env.BEHALF_HOME ?? join(homedir(), ".behalf");
+const KEY_FILE = join(HOME, "key.json");
+const REV_FILE = join(HOME, "revocations.json");
+const AUDIT_FILE = join(HOME, "audit.jsonl");
+function loadEngine() {
+    if (!existsSync(HOME))
+        mkdirSync(HOME, { recursive: true });
+    let keyPair;
+    if (existsSync(KEY_FILE)) {
+        const { priv, pub } = JSON.parse(readFileSync(KEY_FILE, "utf8"));
+        keyPair = { privateKey: importPrivateKey(priv, pub), publicKey: importPublicKey(pub) };
+    }
+    else {
+        keyPair = newKeyPair();
+        writeFileSync(KEY_FILE, JSON.stringify({
+            priv: exportPrivateKey(keyPair.privateKey),
+            pub: exportPublicKey(keyPair.publicKey),
+        }), "utf8");
+    }
+    return createBehalf({
+        rootKeyPair: keyPair,
+        revocations: new FileRevocationStore(REV_FILE),
+        audit: new FileAuditStore(AUDIT_FILE),
+    });
+}
+/** Tiny flag parser: collects --flag value, repeats into arrays, _ for positionals. */
+function parseArgs(argv) {
+    const out = { _: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const key = a.slice(2);
+            const val = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "true";
+            const existing = out[key];
+            if (existing === undefined)
+                out[key] = val;
+            else if (Array.isArray(existing))
+                existing.push(val);
+            else
+                out[key] = [existing, val];
+        }
+        else {
+            out._.push(a);
+        }
+    }
+    return out;
+}
+function asArray(v) {
+    if (v === undefined)
+        return [];
+    return Array.isArray(v) ? v : [v];
+}
+const USAGE = `agent-authority — agent authority CLI
+
+Usage:
+  agent-authority pubkey
+  agent-authority grant --principal <id> --agent <id> --can <cap> [--can <cap> ...] --expires <dur>
+  agent-authority inspect <mandate>
+  agent-authority authorize <mandate> <action>
+  agent-authority revoke <mandate-id>
+  agent-authority audit <mandate-id>
+  agent-authority lint <cap> [<cap> ...]
+  agent-authority quickstart <surface>   (e.g. claude-code, cursor, copilot, gpt, gemini)
+  agent-authority quickstart --list      (list every surface; any AI is configurable)
+
+State dir: ${HOME}  (override with $BEHALF_HOME)`;
+/** Commands that need no key store or engine: lint, quickstart. */
+function runStateless(cmd, args) {
+    if (cmd === "lint") {
+        const caps = args._;
+        if (caps.length === 0) {
+            console.error("lint requires at least one capability");
+            return 2;
+        }
+        const findings = lint(caps);
+        for (const f of findings) {
+            console.log(`${f.level.toUpperCase().padEnd(5)} ${f.capability}  ${f.message}`);
+        }
+        const hasProblem = findings.some((f) => f.level !== "info");
+        console.log(`\n${findings.length} finding(s)`);
+        return hasProblem ? 1 : 0;
+    }
+    // quickstart
+    const extra = loadCustomSurfaces(args.surfaces);
+    if (args.list !== undefined || args._[0] === "list") {
+        for (const s of listSurfaces(extra))
+            console.log(`${s.id.padEnd(16)} ${s.name}`);
+        return 0;
+    }
+    const id = args._[0];
+    if (!id) {
+        console.error("quickstart requires a surface id, or --list. e.g. agent-authority quickstart claude-code");
+        return 2;
+    }
+    const surface = findSurface(id, extra);
+    if (!surface) {
+        console.error(`unknown surface "${id}". Run: agent-authority quickstart --list`);
+        return 2;
+    }
+    const command = args.local !== undefined ? "node" : args.command ?? undefined;
+    const cliArgs = args.local !== undefined ? ["dist/mcp-server.js"] : asArray(args.arg);
+    const env = {};
+    for (const e of asArray(args.env)) {
+        const i = e.indexOf("=");
+        if (i > 0)
+            env[e.slice(0, i)] = e.slice(i + 1);
+    }
+    const qs = generateQuickstart(surface, {
+        name: args.name ?? undefined,
+        command,
+        args: cliArgs.length ? cliArgs : undefined,
+        env: Object.keys(env).length ? env : undefined,
+    });
+    console.log(args.format === "json" ? JSON.stringify(qs, null, 2) : qs.text);
+    return 0;
+}
+function loadCustomSurfaces(file) {
+    if (!file)
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return Array.isArray(parsed) ? parsed : [parsed];
+    }
+    catch (e) {
+        console.error(`could not read surfaces file "${file}": ${e.message}`);
+        return [];
+    }
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    if (!cmd || cmd === "help" || cmd === "--help") {
+        console.log(USAGE);
+        return 0;
+    }
+    const args = parseArgs(rest);
+    // Commands that don't touch mandate state shouldn't create the key store.
+    if (cmd === "lint" || cmd === "quickstart") {
+        return runStateless(cmd, args);
+    }
+    const engine = loadEngine();
+    switch (cmd) {
+        case "pubkey": {
+            console.log(engine.publicKey);
+            return 0;
+        }
+        case "grant": {
+            const principal = args.principal;
+            const agent = args.agent;
+            const can = asArray(args.can);
+            const expiresIn = args.expires ?? "1h";
+            if (!principal || !agent || can.length === 0) {
+                console.error("grant requires --principal, --agent, and at least one --can");
+                return 2;
+            }
+            // Warn (on stderr, so stdout stays a clean mandate) about loose scopes.
+            for (const f of lint(can)) {
+                process.stderr.write(`[lint:${f.level}] ${f.capability}: ${f.message}\n`);
+            }
+            const m = engine.grant({ principal, agent, can, expiresIn });
+            if (args.public !== undefined) {
+                // Presentation-only token (cannot authorize — no delegation key).
+                console.log(m.serialize());
+            }
+            else {
+                process.stderr.write("note: output is a HOLDER credential (includes the delegation key) — treat it as a secret.\n" +
+                    "      Use --public for the presentation-only token.\n");
+                console.log(m.serializeWithKey());
+            }
+            return 0;
+        }
+        case "inspect": {
+            const m = engine.import(args._[0]);
+            try {
+                engine.verifySignature(m.token);
+                const scope = m.token.blocks
+                    .flatMap((b) => b.caveats)
+                    .filter((c) => c.t === "cap")
+                    .map((c) => c.can);
+                console.log(JSON.stringify({
+                    valid: true,
+                    id: m.id,
+                    principal: m.principal,
+                    agent: m.agent,
+                    expiresAt: m.expiresAt ? new Date(m.expiresAt).toISOString() : undefined,
+                    chain: m.chain,
+                    scope,
+                }, null, 2));
+                return 0;
+            }
+            catch (e) {
+                console.log(JSON.stringify({ valid: false, reason: e.message }, null, 2));
+                return 1;
+            }
+        }
+        case "authorize": {
+            const [mandate, action] = args._;
+            if (!mandate || !action) {
+                console.error("authorize requires <mandate> <action>");
+                return 2;
+            }
+            const m = engine.import(mandate);
+            if (m.canDelegate) {
+                // Holder credential: full authorize with proof of possession.
+                try {
+                    await m.authorize(action);
+                    console.log(`ALLOW  ${action}`);
+                    return 0;
+                }
+                catch (e) {
+                    const reason = e instanceof AuthorizationError ? e.reason : String(e);
+                    console.log(`DENY   ${action}  (${reason})`);
+                    return 1;
+                }
+            }
+            // Public token only: advisory scope check (possession not proven).
+            const result = await engine.inspect(m.token, action);
+            if (result.allowed) {
+                console.log(`ALLOW  ${action}  (advisory; possession not checked)`);
+                return 0;
+            }
+            console.log(`DENY   ${action}  (${result.reason})`);
+            return 1;
+        }
+        case "revoke": {
+            const id = args._[0];
+            if (!id) {
+                console.error("revoke requires <mandate-id>");
+                return 2;
+            }
+            await engine.revoke(id);
+            console.log(`revoked ${id}`);
+            return 0;
+        }
+        case "audit": {
+            const id = args._[0];
+            if (!id) {
+                console.error("audit requires <mandate-id>");
+                return 2;
+            }
+            const trail = await engine.audit(id);
+            for (const e of trail) {
+                const ts = new Date(e.ts).toISOString();
+                console.log(`${ts}  ${e.decision.toUpperCase().padEnd(5)}  ${e.action}${e.reason ? `  (${e.reason})` : ""}`);
+            }
+            console.log(`\n${trail.length} record(s)`);
+            return 0;
+        }
+        default:
+            console.error(`unknown command "${cmd}"\n\n${USAGE}`);
+            return 2;
+    }
+}
+main().then((code) => process.exit(code), (e) => {
+    console.error(e);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/control-plane.d.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { type AuditStore, type RevocationStore, type RateStore, type ConsentStore, type PolicyStore } from "./store.js";
+export type { ConsentRecord } from "./types.js";
+/**
+ * The Behalf control plane (Phase 2 / open-core hosted surface).
+ *
+ * It centralizes the three things that benefit from being shared across agents
+ * and processes: revocation propagation (revoke once, everyone sees it), audit
+ * retention (one tamper-evident log of every decision), and a consent/policy
+ * surface (just-in-time human approval + named tool→capability policies). It's a
+ * thin HTTP service over the same pluggable stores the library already uses, so
+ * it can be backed by the in-memory defaults or the file stores for durability.
+ *
+ * Agents talk to it through `HttpRevocationStore` / `HttpAuditStore` (see
+ * `behalf/remote`), so the five-verb API and enforcement are unchanged — only
+ * where revocation/audit live moves.
+ */
+export interface ControlPlaneOptions {
+    revocations?: RevocationStore;
+    audit?: AuditStore;
+    rate?: RateStore;
+    /** Consent record storage. Defaults to in-memory; use a file store to persist. */
+    consents?: ConsentStore;
+    /** Named-policy storage. Defaults to in-memory; use a file store to persist. */
+    policies?: PolicyStore;
+    /**
+     * Multi-tenant mode: require audit queries to name an `?issuer=`, and refuse
+     * the unscoped "all entries" list (and omit it from the dashboard). Keeps one
+     * tenant from reading another's audit through a shared control plane.
+     */
+    tenantScoped?: boolean;
+    /**
+     * Per-tenant bearer tokens: a map of `token -> issuer public key`. A tenant
+     * token may only read/write audit for its own issuer (any `?issuer=` is
+     * ignored, cross-issuer writes are refused) and gets a private policy
+     * namespace. Combine with `token` (an admin credential with full, unscoped
+     * access). When either is set, every request must authenticate.
+     */
+    tenants?: Record<string, string>;
+    /**
+     * Pending consent requests older than this are marked "expired" (a terminal
+     * deny for the consent provider). Disabled when unset.
+     */
+    consentTtlMs?: number;
+    /** Admin credential — full, unscoped access. */
+    token?: string;
+}
+export interface ControlPlane {
+    /** Raw request listener — handy for tests without binding a socket. */
+    handler: (req: IncomingMessage, res: ServerResponse) => void;
+    /** Bind to a port; resolves with the chosen port (0 picks a free one). */
+    listen(port?: number): Promise<number>;
+    close(): Promise<void>;
+}
+export declare function createControlPlane(options?: ControlPlaneOptions): ControlPlane;
+//# sourceMappingURL=control-plane.d.ts.map

package/dist/control-plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-plane.d.ts","sourceRoot":"","sources":["../src/control-plane.ts"],"names":[],"mappings":";AACA,OAAO,EAAgB,KAAK,eAAe,EAAE,KAAK,cAAc,EAAe,MAAM,WAAW,CAAC;AAGjG,OAAO,EAML,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;IAC7D,0EAA0E;IAC1E,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CA6OlF"}