agent-authority 0.1.0

package/dist/a2a.js

@@ -0,0 +1,117 @@
+import { Behalf } from "./behalf.js";
+import { permits } from "./capability.js";
+import { AuthorizationError } from "./errors.js";
+/**
+ * A2A (agent-to-agent) HTTP transport.
+ *
+ * The in-process `withBehalf` middleware secures tool calls inside one agent;
+ * this secures calls *between* agents over the wire. A caller attaches its
+ * mandate to an outgoing request (optionally attenuating it first, so the callee
+ * receives strictly less authority); the callee verifies the mandate and its
+ * whole delegation chain — offline, with only the issuer's public key — and
+ * authorizes the action before doing any work. The verifiable chain travels with
+ * the request, so a compromised hop still can't widen scope.
+ *
+ * Zero dependencies: built on `node:http` types and the global `fetch`.
+ */
+/** Header carrying the serialized mandate on an A2A request. */
+export const MANDATE_HEADER = "x-behalf-mandate";
+/** Header carrying the caller's proof of possession (anti-truncation / replay). */
+export const PROOF_HEADER = "x-behalf-proof";
+/** Header carrying the caller's declared action (the proof is bound to it). */
+export const ACTION_HEADER = "x-behalf-action";
+/**
+ * Build the headers that carry a mandate to a downstream agent: the serialized
+ * (optionally attenuated) token, the caller's declared action, and a fresh proof
+ * of possession bound to that action and the exact chain. The callee verifies
+ * all three, so a truncated, intercepted, or repurposed token is useless.
+ */
+export function present(mandate, opts) {
+    const outgoing = opts.attenuate ? mandate.attenuate(opts.attenuate) : mandate;
+    const proof = outgoing.prove(opts.action, { agentKeys: opts.agentKeys });
+    return {
+        [MANDATE_HEADER]: outgoing.serialize(),
+        [ACTION_HEADER]: opts.action,
+        [PROOF_HEADER]: Buffer.from(JSON.stringify(proof), "utf8").toString("base64url"),
+    };
+}
+/** `fetch` wrapper that attaches (and optionally attenuates) a mandate. */
+export function behalfFetch(input, mandate, init = {}, presentOpts = { action: "" }) {
+    const headers = { ...init.headers, ...present(mandate, presentOpts) };
+    return fetch(input, { ...init, headers });
+}
+function headerValue(headers, name) {
+    if (typeof headers.get === "function") {
+        return headers.get(name) ?? undefined;
+    }
+    const raw = headers[name];
+    return Array.isArray(raw) ? raw[0] : raw;
+}
+/**
+ * Verify + authorize an incoming A2A request. Returns the verified Mandate, or
+ * throws {@link AuthorizationError} if it is missing, untrusted, or out of scope.
+ * Framework-agnostic: pass any header bag (node:http or fetch `Headers`).
+ */
+export async function authorizeIncoming(engine, headers, capability) {
+    const raw = headerValue(headers, MANDATE_HEADER);
+    if (!raw)
+        throw new AuthorizationError(capability, "no mandate presented");
+    const proofRaw = headerValue(headers, PROOF_HEADER);
+    if (!proofRaw)
+        throw new AuthorizationError(capability, "no possession proof presented");
+    const declaredAction = headerValue(headers, ACTION_HEADER);
+    if (!declaredAction)
+        throw new AuthorizationError(capability, "no declared action presented");
+    let proof;
+    try {
+        proof = JSON.parse(Buffer.from(proofRaw, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new AuthorizationError(capability, "malformed possession proof");
+    }
+    // The caller's declared action (which the proof is bound to) must satisfy what
+    // this route requires — so it can't prove a benign action and perform another.
+    if (!permits(capability, declaredAction)) {
+        throw new AuthorizationError(capability, `declared action "${declaredAction}" exceeds route`);
+    }
+    const mandate = engine.import(raw);
+    // Verifies the chain, the proof of possession (bound to declaredAction), scope,
+    // expiry, and revocation; audits under the concrete declared action.
+    await engine.authorize(mandate.token, declaredAction, proof);
+    return mandate;
+}
+/**
+ * A connect/express/node:http-style middleware that authorizes each request
+ * before it reaches your handler. On success the verified mandate is attached as
+ * `req.mandate` and `next()` is called; on failure it writes 403 and returns.
+ */
+export function guard(opts) {
+    const engine = opts.engine ?? Behalf.default;
+    return async (req, res, next) => {
+        const capability = opts.capability(req);
+        if (capability === undefined) {
+            next?.();
+            return true;
+        }
+        try {
+            req.mandate = await authorizeIncoming(engine, req.headers, capability);
+            next?.();
+            return true;
+        }
+        catch (e) {
+            const reason = e instanceof AuthorizationError ? e.reason : String(e);
+            if (opts.onDenied) {
+                opts.onDenied(req, res, reason);
+            }
+            else {
+                res.statusCode = 403;
+                res.setHeader("content-type", "application/json");
+                res.end(JSON.stringify({ error: "forbidden", reason }));
+            }
+            return false;
+        }
+    };
+}
+/** The symmetric in-process A2A binding (re-exported for continuity). */
+export { withBehalfA2A } from "./mcp.js";
+//# sourceMappingURL=a2a.js.map

package/dist/a2a.js.map

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

package/dist/audit.d.ts

@@ -0,0 +1,12 @@
+import type { AuditEntry, AuditFields, AuditIntegrity } from "./types.js";
+export declare const GENESIS: string;
+/**
+ * Seal a new entry onto the chain after `prev` (or `null` for the first entry).
+ * Pure and O(1): the caller supplies the previous entry, so there is no need to
+ * re-read the whole log per record. The store that owns the log is the single
+ * writer, which keeps the hash chain race-free.
+ */
+export declare function seal(prev: AuditEntry | null, fields: AuditFields): AuditEntry;
+/** Replay the hash chain to confirm nothing was tampered with. */
+export declare function verify(entries: AuditEntry[]): AuditIntegrity;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1E,eAAO,MAAM,OAAO,QAAiB,CAAC;AAiBtC;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,EAAE,MAAM,EAAE,WAAW,GAAG,UAAU,CAe7E;AAED,kEAAkE;AAClE,wBAAgB,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,cAAc,CAS5D"}

package/dist/audit.js

@@ -0,0 +1,52 @@
+import { sha256Hex } from "./crypto.js";
+export const GENESIS = "0".repeat(64);
+/** Canonical body (everything that is hashed, excluding the hash itself). */
+function body(e) {
+    return JSON.stringify({
+        seq: e.seq,
+        ts: e.ts,
+        mandateId: e.mandateId,
+        issuer: e.issuer ?? "",
+        chain: e.chain,
+        action: e.action,
+        decision: e.decision,
+        reason: e.reason ?? "",
+        prevHash: e.prevHash,
+    });
+}
+/**
+ * Seal a new entry onto the chain after `prev` (or `null` for the first entry).
+ * Pure and O(1): the caller supplies the previous entry, so there is no need to
+ * re-read the whole log per record. The store that owns the log is the single
+ * writer, which keeps the hash chain race-free.
+ */
+export function seal(prev, fields) {
+    const seq = prev ? prev.seq + 1 : 0;
+    const prevHash = prev ? prev.hash : GENESIS;
+    const partial = {
+        seq,
+        ts: Date.now(),
+        mandateId: fields.mandateId,
+        issuer: fields.issuer,
+        chain: fields.chain,
+        action: fields.action,
+        decision: fields.decision,
+        reason: fields.reason,
+        prevHash,
+    };
+    return { ...partial, hash: sha256Hex(prevHash + body(partial)) };
+}
+/** Replay the hash chain to confirm nothing was tampered with. */
+export function verify(entries) {
+    let prevHash = GENESIS;
+    for (const e of entries) {
+        if (e.prevHash !== prevHash)
+            return { ok: false, brokenAt: e.seq };
+        const expected = sha256Hex(prevHash + body(e));
+        if (expected !== e.hash)
+            return { ok: false, brokenAt: e.seq };
+        prevHash = e.hash;
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,MAAM,CAAC,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAEtC,6EAA6E;AAC7E,SAAS,IAAI,CAAC,CAA2B;IACvC,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE;QACtB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE;QACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;KACrB,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CAAC,IAAuB,EAAE,MAAmB;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;IAC5C,MAAM,OAAO,GAA6B;QACxC,GAAG;QACH,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;QACd,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,QAAQ;KACT,CAAC;IACF,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;AACnE,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,MAAM,CAAC,OAAqB;IAC1C,IAAI,QAAQ,GAAG,OAAO,CAAC;IACvB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;QACnE,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,IAAI,QAAQ,KAAK,CAAC,CAAC,IAAI;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;QAC/D,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC;IACpB,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/behalf.d.ts

@@ -0,0 +1,173 @@
+import { type KeyPair } from "./crypto.js";
+import { type AuditStore, type RevocationStore, type RateStore } from "./store.js";
+import { Mandate, type Engine } from "./mandate.js";
+import { type SealKeyPair } from "./seal.js";
+import { BehalfError } from "./errors.js";
+import type { AttenuateOptions, AuditCheckpoint, AuditEntry, AuditIntegrity, GrantOptions, MandateToken, Proof } from "./types.js";
+import type { KeyObject } from "node:crypto";
+export interface BehalfConfig {
+    /** Issuer keypair. Auto-generated if omitted (so the engine can grant). */
+    rootKeyPair?: KeyPair;
+    /**
+     * This engine's agent-identity keypair (SVID-style). When set, in-process
+     * `authorize` automatically proves possession of it, satisfying any
+     * `agentKey` caveat bound to `agentPublicKey`. Distribute `agentPublicKey`
+     * to whoever grants you a mandate so they can bind it.
+     */
+    agentKey?: KeyPair;
+    /** Additional trusted issuer public keys (base64url SPKI) for foreign mandates. */
+    trust?: string[];
+    revocations?: RevocationStore;
+    audit?: AuditStore;
+    /** Rate-limit accounting. Use a shared store to enforce one cap across agents. */
+    rate?: RateStore;
+    /** Max age (ms) of a possession proof accepted at authorize. Default 5 min. */
+    proofSkewMs?: number;
+    /**
+     * Require a verifier-issued single-use nonce (see `challenge()`) on every
+     * possession proof — eliminates replay within the freshness window at the
+     * cost of a challenge round-trip. Default false.
+     */
+    requireNonce?: boolean;
+    /** Override the clock — handy for tests. */
+    now?: () => number;
+}
+/**
+ * The Behalf engine: holds the issuer keypair and the revocation / audit stores,
+ * and implements the five verbs. Use the default singleton via the static
+ * facade (`Behalf.grant`, ...) or construct an isolated instance with
+ * `createBehalf()`. A verify-only engine (no grant) is made with
+ * `createBehalf({ trust: [issuerPublicKey] })` and a generated throwaway key.
+ */
+export declare class Behalf implements Engine {
+    private readonly rootKeyPair;
+    private readonly agentKey?;
+    private readonly trusted;
+    private readonly revocations;
+    private readonly auditStore;
+    private readonly rateStore;
+    private readonly proofSkewMs;
+    private readonly requireNonce;
+    /** Outstanding single-use challenges: nonce → expiry (ms). */
+    private readonly nonces;
+    private readonly now;
+    constructor(config?: BehalfConfig);
+    /**
+     * Issue a single-use challenge nonce. The holder binds it into its possession
+     * proof (`prove(action, { nonce })`); `authorize` consumes it, so that proof
+     * can never be replayed — even within the freshness window.
+     */
+    challenge(): string;
+    /** This engine's issuer public key (base64url SPKI). Share it with verifiers. */
+    get publicKey(): string;
+    /**
+     * This engine's agent-identity public key (base64url), or undefined if none is
+     * configured. Hand it to a granter so they can `bindAgent` a mandate to you;
+     * only an engine holding the matching private key can then authorize it.
+     */
+    get agentPublicKey(): string | undefined;
+    /** GRANT — a principal authorizes an agent: scoped, capped, short-lived. */
+    grant(opts: GrantOptions): Mandate;
+    /** ATTENUATE — narrow a mandate for a sub-agent. Never widens. */
+    attenuate(token: MandateToken, delegationKey: KeyObject | undefined, opts: AttenuateOptions): Mandate;
+    /**
+     * Mint a possession proof for `token` using `delegationKey` (the holder's
+     * terminal key). Throws if the key is absent — you cannot act on a mandate you
+     * only hold the public token for.
+     */
+    provePossession(token: MandateToken, delegationKey: KeyObject, action: string, nonce?: string, agentKeys?: KeyObject[]): Proof;
+    /** Holder path: `mandate.authorize()` routes here, minting a PoP from its key. */
+    authorizeAsHolder(token: MandateToken, action: string, delegationKey: KeyObject | undefined): Promise<void>;
+    /**
+     * AUTHORIZE — verify a token, prove the presenter possesses the chain's
+     * terminal key, then check a concrete action. The `proof` is required: it
+     * binds the presenter to the exact (untruncated) chain and a fresh timestamp,
+     * which is what closes trailing-block truncation and stops a serialized token
+     * from being a reusable bearer credential. Produce one with `provePossession`
+     * (or, across the wire, `agent-authority/a2a`'s `present`).
+     */
+    authorize(token: MandateToken, action: string, proof?: Proof): Promise<void>;
+    /**
+     * INSPECT — advisory check of signature, revocation, expiry, and scope WITHOUT
+     * a possession proof. Use for "would this token allow X?" tooling (CLI,
+     * dashboards, `check_authority`). It does NOT prove the caller holds the
+     * mandate, does not consume rate budget, and writes no audit record — never
+     * gate a real action on it; use `authorize` for that.
+     */
+    inspect(token: MandateToken, action: string): Promise<{
+        allowed: boolean;
+        reason?: string;
+    }>;
+    /** Shared signature + revocation + expiry + scope check (no PoP, no side effects). */
+    private evaluate;
+    /** REVOKE — kill a mandate (and, transitively, everything downstream). */
+    revoke(id: string): Promise<void>;
+    /** AUDIT — fetch the hash-chained audit trail for a mandate's chain. */
+    audit(id: string): Promise<AuditEntry[]>;
+    /** Verify the integrity of the entire audit log. */
+    verifyAuditLog(): Promise<AuditIntegrity>;
+    /**
+     * Sign an anchor over the audit log's current head (C4). Store checkpoints
+     * somewhere the log's writer can't reach (another host, object storage, a
+     * ledger): a later `verifyAuditCheckpoint` then detects tail-deletion and
+     * full-chain rewrites, which the unkeyed hash chain alone cannot.
+     */
+    checkpointAudit(): Promise<AuditCheckpoint>;
+    /**
+     * Verify the log against a previously-taken checkpoint: the checkpoint's
+     * signature must verify under a trusted key, the chain must replay, and the
+     * entry at `checkpoint.seq` must still carry exactly the anchored hash.
+     */
+    verifyAuditCheckpoint(checkpoint: AuditCheckpoint): Promise<AuditIntegrity & {
+        reason?: string;
+    }>;
+    /**
+     * Rotate the issuer key with overlap: returns a NEW engine with a fresh
+     * keypair that shares this engine's stores/config and still trusts every
+     * previously trusted key (including the old one), so existing mandates keep
+     * verifying while new grants are signed by the new key. Distribute the new
+     * `publicKey` to verifiers, wait out the longest outstanding mandate expiry,
+     * then end the overlap with `untrustKey(oldPublicKey)`.
+     */
+    rotate(): Behalf;
+    /** Currently trusted issuer public keys (own key included). */
+    get trustedKeys(): string[];
+    /** Trust an additional issuer key (e.g. a peer's, or a pre-staged next key). */
+    trustKey(publicKey: string): void;
+    /** End a rotation overlap. Refuses to remove this engine's own key. */
+    untrustKey(publicKey: string): boolean;
+    /**
+     * Re-hydrate a Mandate from a serialized string. Accepts both forms:
+     * - `serialize()` (public token) → inspect/verify only; cannot authorize,
+     *   prove, or attenuate (no delegation key).
+     * - `serializeWithKey()` (token + delegation key) → a full holder credential
+     *   that can authorize, prove, and attenuate.
+     */
+    import(serialized: string): Mandate;
+    /**
+     * Decrypt and import a sealed holder credential (see
+     * `mandate.sealForRecipient`) using the recipient's X25519 sealing keypair.
+     * Equivalent to `import(unseal(sealed, recipient))`.
+     */
+    importSealed(sealed: string, recipient: SealKeyPair): Mandate;
+    /**
+     * Throws {@link IntegrityError} if the issuer is untrusted or the Ed25519
+     * signature chain does not verify. Pure public-key checks — no secrets.
+     */
+    verifySignature(token: MandateToken): void;
+    private static _default;
+    static get default(): Behalf;
+    /** Replace the default instance (e.g. to inject a persistent store). */
+    static configure(config: BehalfConfig): Behalf;
+    static grant(opts: GrantOptions): Mandate;
+    static revoke(id: string): Promise<void>;
+    static audit(id: string): Promise<AuditEntry[]>;
+    static import(serialized: string): Mandate;
+}
+/** Thrown when attenuating a mandate that has no in-memory delegation key. */
+export declare class BehalfDelegationError extends BehalfError {
+    constructor();
+}
+/** Construct an isolated engine (own key + stores). */
+export declare function createBehalf(config?: BehalfConfig): Behalf;
+//# sourceMappingURL=behalf.d.ts.map

package/dist/behalf.d.ts.map

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