@hivemagnus/ardent 1.1.5 → 1.1.8

package/README.md

@@ -149,8 +149,23 @@ a2a:
   peers_file: peers.yaml
   skill: { id: research, name: Research, description: Sourced answers, tags: [research] }
   hermes_compat: false
+  rate_limit:                            # all optional; these are the defaults
+    enabled: true
+    ip_requests_per_minute: 600          # every HTTP request, before authentication
+    ip_burst: 120
+    peer_requests_per_minute: 300        # after authentication, per peer (also gRPC)
+    peer_burst: 60
+    max_concurrent_tasks_per_peer: 16    # queued and running tasks
+    trusted_proxies: []                  # proxies whose X-Forwarded-For is believed
 ```
 
+A limited request is answered with `429` and `Retry-After`. The client address
+is the socket address unless the connecting address is listed in
+`trusted_proxies` (addresses or CIDR ranges). Behind a reverse proxy, all clients
+otherwise share the proxy's address and one bucket, so list the proxy there.
+gRPC requests count against the peer limit and the task cap; the address limit
+covers HTTP only. Limits are kept in memory, per process.
+
 Peers are listed in `peers.yaml` with the environment variables holding their
 inbound and outbound bearer tokens. An ordinary peer task can reach only the
 public news tools. A peer that sends a validated team mission envelope gets

package/dist/a2a-idempotency.d.ts

@@ -1,13 +1,15 @@
 import { Message, type SendMessageRequest, type StreamResponse, type Task } from '@a2a-js/sdk';
 import { DefaultRequestHandler, type ServerCallContext } from '@a2a-js/sdk/server';
 import type Database from 'better-sqlite3';
+import type { PeerTaskGate } from './a2a-rate-limit.js';
 import type { SqliteA2ATaskStore } from './a2a-store.js';
 /** Binds transport retries to the original task before invoking the executor. */
 export declare class IdempotentA2AHandler extends DefaultRequestHandler {
     #private;
     readonly db: Database.Database;
     readonly durableStore: SqliteA2ATaskStore;
-    constructor(db: Database.Database, durableStore: SqliteA2ATaskStore, ...args: ConstructorParameters<typeof DefaultRequestHandler>);
+    readonly taskGate: PeerTaskGate;
+    constructor(db: Database.Database, durableStore: SqliteA2ATaskStore, taskGate: PeerTaskGate, ...args: ConstructorParameters<typeof DefaultRequestHandler>);
     sendMessage(params: SendMessageRequest, context: ServerCallContext): Promise<Task | Message>;
     sendMessageStream(params: SendMessageRequest, context: ServerCallContext): AsyncGenerator<StreamResponse, void, undefined>;
 }

package/dist/a2a-idempotency.js

@@ -9,10 +9,12 @@ const terminal = new Set([TaskState.TASK_STATE_COMPLETED, TaskState.TASK_STATE_F
 export class IdempotentA2AHandler extends DefaultRequestHandler {
     db;
     durableStore;
-    constructor(db, durableStore, ...args) {
+    taskGate;
+    constructor(db, durableStore, taskGate, ...args) {
         super(...args);
         this.db = db;
         this.durableStore = durableStore;
+        this.taskGate = taskGate;
     }
     #scope(context) {
         if (!context.user?.isAuthenticated || !context.user.userName)
@@ -37,6 +39,25 @@ export class IdempotentA2AHandler extends DefaultRequestHandler {
             return { prior: inserted.changes === 0, tenant, caller, messageId };
         })();
     }
+    /**
+     * Runs before #claim: a refusal must not leave a receipt, or the peer's retry
+     * of this message would wait on an admission that never happened. Retries of
+     * known messages and team control messages start no new work and take no slot.
+     */
+    #admit(params, context) {
+        const { tenant, caller } = this.#scope(context);
+        const messageId = params.message?.messageId;
+        if (!messageId || 'hermesTeamControl' in (params.message?.metadata ?? {}) || this.taskGate.holds(caller, messageId)
+            || this.db.prepare('SELECT 1 FROM a2a_request_receipts WHERE tenant=? AND caller=? AND message_id=?').get(tenant, caller, messageId))
+            return null;
+        if (!this.taskGate.acquire(caller, messageId))
+            throw new UnsupportedOperationError('Peer task limit reached; retry after a running task finishes');
+        return { caller, messageId };
+    }
+    #release(slot) {
+        if (slot)
+            this.taskGate.release(slot.caller, slot.messageId);
+    }
     #bind(receipt, taskId) {
         this.db.prepare('UPDATE a2a_request_receipts SET task_id=? WHERE tenant=? AND caller=? AND message_id=? AND (task_id IS NULL OR task_id=?)')
             .run(taskId, receipt.tenant, receipt.caller, receipt.messageId, taskId);
@@ -58,29 +79,53 @@ export class IdempotentA2AHandler extends DefaultRequestHandler {
     async sendMessage(params, context) {
         if ('hermesTeamReport' in (params.message?.metadata ?? {}))
             throw new RequestMalformedError('Report intake is not supported by this profile');
-        const receipt = this.#claim(params, context);
-        if (receipt.prior)
-            return this.#original(receipt, context);
-        const result = await super.sendMessage(params, context);
-        if ('id' in result)
-            this.#bind(receipt, result.id);
-        return result;
+        const slot = this.#admit(params, context);
+        try {
+            const receipt = this.#claim(params, context);
+            if (receipt.prior) {
+                this.#release(slot);
+                return await this.#original(receipt, context);
+            }
+            const result = await super.sendMessage(params, context);
+            if ('id' in result)
+                this.#bind(receipt, result.id);
+            return result;
+        }
+        catch (error) {
+            this.#release(slot);
+            throw error;
+        }
     }
     async *sendMessageStream(params, context) {
         if ('hermesTeamReport' in (params.message?.metadata ?? {}))
             throw new UnsupportedOperationError('Report intake requires a terminal SendMessage receipt');
-        const receipt = this.#claim(params, context);
+        const slot = this.#admit(params, context);
+        let receipt;
+        try {
+            receipt = this.#claim(params, context);
+        }
+        catch (error) {
+            this.#release(slot);
+            throw error;
+        }
         if (receipt.prior) {
+            this.#release(slot);
             const task = await this.#original(receipt, context);
             yield { payload: { $case: 'task', value: task } };
             if (task.status && !terminal.has(task.status.state))
                 yield* this.resubscribe({ tenant: context.tenant ?? '', id: task.id }, context);
             return;
         }
-        for await (const event of super.sendMessageStream(params, context)) {
-            if (event.payload?.$case === 'task')
-                this.#bind(receipt, event.payload.value.id);
-            yield event;
+        try {
+            for await (const event of super.sendMessageStream(params, context)) {
+                if (event.payload?.$case === 'task')
+                    this.#bind(receipt, event.payload.value.id);
+                yield event;
+            }
+        }
+        catch (error) {
+            this.#release(slot);
+            throw error;
         }
     }
 }

package/dist/a2a-push-inbox.d.ts

@@ -1,6 +1,12 @@
 import type Database from 'better-sqlite3';
 import { type StreamResponse } from '@a2a-js/sdk';
+import { z } from 'zod';
 import type { PeerConfig } from './a2a-peers.js';
+declare const Outbound: z.ZodObject<{
+    id: z.ZodString;
+    peer_id: z.ZodString;
+    task_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
 export declare class A2APushInbox {
     readonly db: Database.Database;
     readonly peers: PeerConfig[];
@@ -13,6 +19,8 @@ export declare class A2APushInbox {
     };
     bind(id: string, taskId: string): void;
     markFailed(id: string): void;
+    /** Checks the callback token alone, so an unauthorized sender cannot make the server parse its body. */
+    authorize(peerId: string, token: string | undefined): z.infer<typeof Outbound>;
     accept(peerId: string, token: string | undefined, raw: unknown): {
         duplicate: boolean;
         outboundId: string;
@@ -20,3 +28,4 @@ export declare class A2APushInbox {
     };
     events(outboundId: string): StreamResponse[];
 }
+export {};

package/dist/a2a-push-inbox.js

@@ -46,7 +46,8 @@ export class A2APushInbox {
         this.db.prepare("UPDATE a2a_outbound_calls SET task_id=?,state='bound',updated_ms=? WHERE id=?").run(taskId, Date.now(), id);
     }
     markFailed(id) { this.db.prepare("UPDATE a2a_outbound_calls SET state='failed',updated_ms=? WHERE id=?").run(Date.now(), id); }
-    accept(peerId, token, raw) {
+    /** Checks the callback token alone, so an unauthorized sender cannot make the server parse its body. */
+    authorize(peerId, token) {
         if (!token || token.length > 256 || !this.peers.some(peer => peer.enabled && peer.id === peerId))
             throw new Error('A2A push is unauthorized');
         const row = this.db.prepare('SELECT id,peer_id,task_id FROM a2a_outbound_calls WHERE token_hash=?').get(digest(token));
@@ -55,6 +56,10 @@ export class A2APushInbox {
         const call = Outbound.parse(row);
         if (call.peer_id !== peerId)
             throw new Error('A2A push is unauthorized');
+        return call;
+    }
+    accept(peerId, token, raw) {
+        const call = this.authorize(peerId, token);
         const event = StreamCodec.fromJSON(raw);
         const payload = event.payload;
         if (!payload)

package/dist/a2a-rate-limit.d.ts

@@ -0,0 +1,52 @@
+import { type AgentExecutor, type ExecutionEventBus, type RequestContext } from '@a2a-js/sdk/server';
+import type { Request, RequestHandler, Response } from 'express';
+export type TakeResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    retryAfterSeconds: number;
+};
+export interface BucketLimits {
+    perMinute: number;
+    burst: number;
+    maxKeys?: number;
+    now?: () => number;
+}
+/** Answers from memory only, and keeps at most maxKeys buckets so many clients cannot grow it. */
+export declare class TokenBucketLimiter {
+    #private;
+    constructor(limits: BucketLimits);
+    take(key: string): TakeResult;
+}
+/** One bucket per client: an IPv4-mapped address is its IPv4 address, and IPv6 clients share a /64. */
+export declare function clientKey(address: string | undefined): string;
+export declare function tooManyRequests(res: Response, retryAfterSeconds: number, error?: string): void;
+export declare function limitRequests(limiter: TokenBucketLimiter, key: (req: Request, res: Response) => string): RequestHandler;
+/** Admitted peer tasks, from before the SDK creates the task until the executor settles it. */
+export declare class PeerTaskGate {
+    #private;
+    readonly maxPerPeer: number;
+    constructor(maxPerPeer: number);
+    isFull(peer: string): boolean;
+    holds(peer: string, key: string): boolean;
+    acquire(peer: string, key: string): boolean;
+    release(peer: string, key: string): void;
+}
+/** Frees a task's slot when its execution ends, however it ends. */
+export declare class GatedA2AExecutor implements AgentExecutor {
+    readonly inner: AgentExecutor;
+    readonly gate: PeerTaskGate;
+    constructor(inner: AgentExecutor, gate: PeerTaskGate);
+    execute(request: RequestContext, bus: ExecutionEventBus): Promise<void>;
+    cancelTask(taskId: string, bus: ExecutionEventBus): Promise<void>;
+}
+/** How long a peer at its task cap should wait; tasks have no fixed duration to report instead. */
+export declare const TASK_CAP_RETRY_SECONDS = 5;
+/**
+ * Answers an HTTP 429 before the transports turn the handler's refusal into an
+ * application error. The handler still enforces the cap atomically and for gRPC.
+ * Team control messages stay allowed so a peer at its cap can still cancel work.
+ */
+export declare function jsonRpcTaskCap(gate: PeerTaskGate, peerOf: (res: Response) => string): RequestHandler;
+/** The REST body is not parsed yet here; cancel has its own route and stays available. */
+export declare function restTaskCap(gate: PeerTaskGate, peerOf: (res: Response) => string): RequestHandler;

package/dist/a2a-rate-limit.js

@@ -0,0 +1,136 @@
+/** Bounds on the A2A surface: per-client and per-peer token buckets and a per-peer task cap. */
+import { isIPv4, isIPv6 } from 'node:net';
+import { z } from 'zod';
+/** Answers from memory only, and keeps at most maxKeys buckets so many clients cannot grow it. */
+export class TokenBucketLimiter {
+    #buckets = new Map();
+    #perMs;
+    #burst;
+    #maxKeys;
+    #now;
+    constructor(limits) {
+        this.#perMs = limits.perMinute / 60_000;
+        this.#burst = limits.burst;
+        this.#maxKeys = limits.maxKeys ?? 10_000;
+        this.#now = limits.now ?? Date.now;
+    }
+    take(key) {
+        const now = this.#now();
+        const bucket = this.#buckets.get(key) ?? { tokens: this.#burst, updated: now };
+        bucket.tokens = Math.min(this.#burst, bucket.tokens + Math.max(0, now - bucket.updated) * this.#perMs);
+        bucket.updated = now;
+        // Reinsert so the Map's order runs from least to most recently used.
+        this.#buckets.delete(key);
+        this.#buckets.set(key, bucket);
+        if (this.#buckets.size > this.#maxKeys) {
+            const oldest = this.#buckets.keys().next();
+            if (!oldest.done)
+                this.#buckets.delete(oldest.value);
+        }
+        if (bucket.tokens < 1)
+            return { allowed: false, retryAfterSeconds: Math.max(1, Math.ceil((1 - bucket.tokens) / this.#perMs / 1000)) };
+        bucket.tokens -= 1;
+        return { allowed: true };
+    }
+}
+/** One bucket per client: an IPv4-mapped address is its IPv4 address, and IPv6 clients share a /64. */
+export function clientKey(address) {
+    if (!address)
+        return 'unknown';
+    const bare = address.split('%')[0] ?? address;
+    const mapped = bare.toLowerCase().startsWith('::ffff:') ? bare.slice(7) : bare;
+    if (isIPv4(mapped) || !isIPv6(bare))
+        return mapped;
+    const [head = '', tail = ''] = bare.toLowerCase().split('::');
+    const before = head ? head.split(':') : [];
+    const after = tail ? tail.split(':') : [];
+    const groups = [...before, ...new Array(Math.max(0, 8 - before.length - after.length)).fill('0'), ...after];
+    return `${groups.slice(0, 4).map(group => group.replace(/^0+(?=.)/, '')).join(':')}::/64`;
+}
+export function tooManyRequests(res, retryAfterSeconds, error = 'Too many A2A requests') {
+    res.status(429).set({ 'Retry-After': String(retryAfterSeconds), 'Cache-Control': 'no-store' }).json({ error });
+}
+export function limitRequests(limiter, key) {
+    return (req, res, next) => {
+        const result = limiter.take(key(req, res));
+        if (result.allowed) {
+            next();
+            return;
+        }
+        tooManyRequests(res, result.retryAfterSeconds);
+    };
+}
+/** Admitted peer tasks, from before the SDK creates the task until the executor settles it. */
+export class PeerTaskGate {
+    maxPerPeer;
+    #active = new Map();
+    constructor(maxPerPeer) {
+        this.maxPerPeer = maxPerPeer;
+    }
+    isFull(peer) { return (this.#active.get(peer)?.size ?? 0) >= this.maxPerPeer; }
+    holds(peer, key) { return this.#active.get(peer)?.has(key) ?? false; }
+    acquire(peer, key) {
+        const active = this.#active.get(peer) ?? new Set();
+        if (!active.has(key) && active.size >= this.maxPerPeer)
+            return false;
+        active.add(key);
+        this.#active.set(peer, active);
+        return true;
+    }
+    release(peer, key) {
+        const active = this.#active.get(peer);
+        if (!active?.delete(key))
+            return;
+        if (active.size === 0)
+            this.#active.delete(peer);
+    }
+}
+/** Frees a task's slot when its execution ends, however it ends. */
+export class GatedA2AExecutor {
+    inner;
+    gate;
+    constructor(inner, gate) {
+        this.inner = inner;
+        this.gate = gate;
+    }
+    async execute(request, bus) {
+        try {
+            await this.inner.execute(request, bus);
+        }
+        finally {
+            const peer = request.context.user?.userName;
+            if (peer)
+                this.gate.release(peer, request.userMessage.messageId);
+        }
+    }
+    cancelTask(taskId, bus) { return this.inner.cancelTask(taskId, bus); }
+}
+const SendRpc = z.object({ method: z.string(), params: z.object({ message: z.object({ metadata: z.record(z.string(), z.unknown()).nullish() }).nullish() }).nullish() });
+const SEND_METHODS = new Set(['SendMessage', 'SendStreamingMessage', 'message/send', 'message/stream']);
+/** How long a peer at its task cap should wait; tasks have no fixed duration to report instead. */
+export const TASK_CAP_RETRY_SECONDS = 5;
+/**
+ * Answers an HTTP 429 before the transports turn the handler's refusal into an
+ * application error. The handler still enforces the cap atomically and for gRPC.
+ * Team control messages stay allowed so a peer at its cap can still cancel work.
+ */
+export function jsonRpcTaskCap(gate, peerOf) {
+    return (req, res, next) => {
+        const rpc = SendRpc.safeParse(req.body);
+        if (rpc.success && SEND_METHODS.has(rpc.data.method) && !('hermesTeamControl' in (rpc.data.params?.message?.metadata ?? {})) && gate.isFull(peerOf(res))) {
+            tooManyRequests(res, TASK_CAP_RETRY_SECONDS, 'Peer task limit reached');
+            return;
+        }
+        next();
+    };
+}
+/** The REST body is not parsed yet here; cancel has its own route and stays available. */
+export function restTaskCap(gate, peerOf) {
+    return (req, res, next) => {
+        if (req.method === 'POST' && /\/message:(?:send|stream)$/.test(req.path) && gate.isFull(peerOf(res))) {
+            tooManyRequests(res, TASK_CAP_RETRY_SECONDS, 'Peer task limit reached');
+            return;
+        }
+        next();
+    };
+}

package/dist/a2a-server.d.ts

@@ -6,6 +6,8 @@ import { SafeA2APushSender } from './a2a-push.js';
 import { A2APushInbox } from './a2a-push-inbox.js';
 import type { ArdentRuntime } from './runtime.js';
 import { hermesTeamCard } from './hermes-compat.js';
+import { IdempotentA2AHandler } from './a2a-idempotency.js';
+import { PeerTaskGate, TokenBucketLimiter } from './a2a-rate-limit.js';
 export type A2ASurface = {
     app: Express;
     grpcServer: GrpcServer;
@@ -14,6 +16,8 @@ export type A2ASurface = {
     grpcListenPort: number;
     pushSender: SafeA2APushSender;
     pushInbox: A2APushInbox;
+    handler: IdempotentA2AHandler;
+    taskGate: PeerTaskGate;
 };
 /** Refresh only discovery freshness; the reviewed runtime identity and digests stay pinned to this process. */
 export declare function freshHermesTeamCard(source: Awaited<ReturnType<typeof hermesTeamCard>>, now?: number): {
@@ -33,5 +37,10 @@ export declare function freshHermesTeamCard(source: Awaited<ReturnType<typeof he
         tags: string[];
     }>;
 };
+/** gRPC bypasses Express, so its authenticated calls spend the same per-peer tokens here. */
+export declare function limitedGrpcUser(peer: string | undefined, bucket: TokenBucketLimiter | undefined): {
+    isAuthenticated: boolean;
+    userName: string;
+};
 export declare function createA2ASurface(runtime: ArdentRuntime, config: ArdentConfig, env?: NodeJS.ProcessEnv): Promise<A2ASurface>;
 export declare function startA2AGrpc(surface: A2ASurface, host?: string): Promise<void>;

package/dist/a2a-server.js

@@ -15,6 +15,7 @@ import { hermesTeamCard } from './hermes-compat.js';
 import { IdempotentA2AHandler } from './a2a-idempotency.js';
 import { hermesAlias } from './a2a-hermes-alias.js';
 import { ARDENT_VERSION } from './version.js';
+import { clientKey, GatedA2AExecutor, jsonRpcTaskCap, limitRequests, PeerTaskGate, restTaskCap, TokenBucketLimiter } from './a2a-rate-limit.js';
 import { TeamArtifacts } from './team-artifacts.js';
 /** Refresh only discovery freshness; the reviewed runtime identity and digests stay pinned to this process. */
 export function freshHermesTeamCard(source, now = Date.now()) {
@@ -26,6 +27,12 @@ export function freshHermesTeamCard(source, now = Date.now()) {
     return { ...source, metadata: { hermesTeam: { ...team,
                 discovery: { ...team.discovery, observedAt, expiresAt: observedAt + 300 } } } };
 }
+/** gRPC bypasses Express, so its authenticated calls spend the same per-peer tokens here. */
+export function limitedGrpcUser(peer, bucket) {
+    if (peer && bucket && !bucket.take(peer).allowed)
+        throw new Error('Too many A2A requests');
+    return { isAuthenticated: Boolean(peer), userName: peer ?? '' };
+}
 export async function createA2ASurface(runtime, config, env = process.env) {
     const publicAddress = resolveReference(config.a2a.public_url, env);
     if (!publicAddress)
@@ -77,7 +84,9 @@ export async function createA2ASurface(runtime, config, env = process.env) {
     const pushInbox = new A2APushInbox(runtime.store.db, peers, publicAddress);
     const artifactTransfers = new TeamArtifacts(runtime, config, env);
     const taskStore = new SqliteA2ATaskStore(runtime.store.db);
-    const handler = new IdempotentA2AHandler(runtime.store.db, taskStore, card, taskStore, new ArdentA2AExecutor(runtime, env), undefined, pushStore, pushSender, async (context) => {
+    const limits = config.a2a.rate_limit;
+    const taskGate = new PeerTaskGate(limits.enabled ? limits.max_concurrent_tasks_per_peer : Number.MAX_SAFE_INTEGER);
+    const handler = new IdempotentA2AHandler(runtime.store.db, taskStore, taskGate, card, taskStore, new GatedA2AExecutor(new ArdentA2AExecutor(runtime, env), taskGate), undefined, pushStore, pushSender, async (context) => {
         const peerId = context.user?.userName;
         if (!context.user?.isAuthenticated || !peerId || !peers.some(peer => peer.id === peerId && peer.enabled))
             throw new Error('Authenticated configured peer required');
@@ -88,14 +97,29 @@ export async function createA2ASurface(runtime, config, env = process.env) {
         };
     });
     const app = express();
-    app.get('/team/artifacts/:id', async (req, res) => {
+    // Off by default: without an explicit proxy list req.ip is the socket address and X-Forwarded-For is ignored.
+    if (limits.trusted_proxies.length)
+        app.set('trust proxy', limits.trusted_proxies);
+    const pass = (_req, _res, next) => next();
+    const peerOf = (res) => String(res.locals.peer);
+    const peerBucket = new TokenBucketLimiter({ perMinute: limits.peer_requests_per_minute, burst: limits.peer_burst });
+    const peerLimit = limits.enabled ? limitRequests(peerBucket, (_req, res) => peerOf(res)) : pass;
+    const requirePeer = (message) => (req, res, next) => {
         const peer = authenticate(req.header('Authorization'));
         if (!peer) {
-            res.status(401).json({ error: 'Authenticated A2A peer required' });
+            res.status(401).json({ error: message });
             return;
         }
+        res.locals.peer = peer;
+        next();
+    };
+    // First in the chain: every route below, authenticated or not, is limited by client address.
+    if (limits.enabled)
+        app.use(limitRequests(new TokenBucketLimiter({ perMinute: limits.ip_requests_per_minute, burst: limits.ip_burst }), req => clientKey(req.ip)));
+    app.get('/team/artifacts/:id', requirePeer('Authenticated A2A peer required'), peerLimit, async (req, res) => {
+        const peer = peerOf(res);
         try {
-            const result = await artifactTransfers.serve(peer, req.params.id ?? '', String(req.query.context ?? ''));
+            const result = await artifactTransfers.serve(peer, String(req.params.id ?? ''), String(req.query.context ?? ''));
             if (result.status !== 200 || !result.bytes || !result.descriptor) {
                 res.status(result.status).json({ error: result.status === 410 ? 'Artifact export revoked or expired' : 'Artifact unavailable' });
                 return;
@@ -110,9 +134,22 @@ export async function createA2ASurface(runtime, config, env = process.env) {
             res.status(503).json({ error: 'Artifact export state is unavailable' });
         }
     });
-    app.post('/a2a/push/:peerId', express.json({ limit: '2mb', type: ['application/json', 'application/a2a+json'] }), (req, res) => {
+    const pushToken = (req, res, next) => {
+        const peerId = String(req.params.peerId ?? '');
+        try {
+            pushInbox.authorize(peerId, req.header('X-A2A-Notification-Token'));
+        }
+        catch {
+            res.status(401).json({ error: 'A2A push is unauthorized' });
+            return;
+        }
+        res.locals.peer = `push:${peerId}`;
+        next();
+    };
+    // The token is checked before up to 2 MB of JSON is parsed.
+    app.post('/a2a/push/:peerId', pushToken, peerLimit, express.json({ limit: '2mb', type: ['application/json', 'application/a2a+json'] }), (req, res) => {
         try {
-            const result = pushInbox.accept(req.params.peerId ?? '', req.header('X-A2A-Notification-Token'), req.body);
+            const result = pushInbox.accept(String(req.params.peerId ?? ''), req.header('X-A2A-Notification-Token'), req.body);
             res.status(202).json({ accepted: true, duplicate: result.duplicate });
         }
         catch (error) {
@@ -135,49 +172,39 @@ export async function createA2ASurface(runtime, config, env = process.env) {
     });
     app.use(`/${AGENT_CARD_PATH}`, legacyAgentCardRouter({ agentCardProvider: handler }));
     if (teamCard)
-        app.get('/.well-known/hermes-team-card.json', (req, res) => {
-            if (!authenticate(req.header('Authorization'))) {
-                res.status(401).json({ error: 'Authenticated configured peer required' });
-                return;
-            }
+        app.get('/.well-known/hermes-team-card.json', requirePeer('Authenticated configured peer required'), peerLimit, (_req, res) => {
             const encoded = AgentCard.toJSON(card);
             if (!encoded || typeof encoded !== 'object' || Array.isArray(encoded))
                 throw new Error('A2A Agent Card encoding failed');
             res.set('Cache-Control', 'private, no-store').json({ ...encoded, ...freshHermesTeamCard(teamCard) });
         });
-    const auth = (req, res, next) => {
-        if (!authenticate(req.header('Authorization'))) {
-            res.status(401).json({ error: 'Authenticated A2A peer required' });
-            return;
-        }
-        next();
-    };
+    const auth = requirePeer('Authenticated A2A peer required');
+    const jsonRpcCap = jsonRpcTaskCap(taskGate, peerOf);
     const userBuilder = async (req) => {
         const id = authenticate(req.header('Authorization'));
         return { isAuthenticated: Boolean(id), userName: id ?? '' };
     };
     const aliases = config.a2a.hermes_compat ? hermesAlias : (_req, _res, next) => next();
     if (config.a2a.bindings.includes('jsonrpc'))
-        app.use('/a2a/jsonrpc', auth, express.json({ limit: '1mb' }), aliases, jsonRpcHandler({ requestHandler: handler, userBuilder, legacyCompat: { enabled: true } }));
+        app.use('/a2a/jsonrpc', auth, peerLimit, express.json({ limit: '1mb' }), aliases, jsonRpcCap, jsonRpcHandler({ requestHandler: handler, userBuilder, legacyCompat: { enabled: true } }));
     if (config.a2a.bindings.includes('http-json'))
-        app.use('/a2a/rest', auth, restHandler({ requestHandler: handler, userBuilder }));
+        app.use('/a2a/rest', auth, peerLimit, restTaskCap(taskGate, peerOf), restHandler({ requestHandler: handler, userBuilder }));
     // Hermes Agent's team router posts to the peer origin itself. Keep that
     // optional compatibility route separate from the advertised v1 interface.
     if (config.a2a.hermes_compat && config.a2a.bindings.includes('jsonrpc')) {
         const rootCompat = express.Router();
         rootCompat.use((req, _res, next) => { if (!req.header('A2A-Version'))
             req.headers['a2a-version'] = '1.0'; next(); });
-        rootCompat.use(auth, express.json({ limit: '1mb' }), hermesAlias, jsonRpcHandler({ requestHandler: handler, userBuilder, legacyCompat: { enabled: true } }));
+        rootCompat.use(auth, peerLimit, express.json({ limit: '1mb' }), hermesAlias, jsonRpcCap, jsonRpcHandler({ requestHandler: handler, userBuilder, legacyCompat: { enabled: true } }));
         app.use('/', (req, res, next) => req.path === '/' ? rootCompat(req, res, next) : next());
     }
     const grpcServer = new GrpcServer();
     if (config.a2a.bindings.includes('grpc'))
         grpcServer.addService(A2AService, grpcService({ requestHandler: handler, userBuilder: async (call) => {
                 const raw = call.metadata.get('authorization')[0];
-                const id = authenticate(typeof raw === 'string' ? raw : undefined);
-                return { isAuthenticated: Boolean(id), userName: id ?? '' };
+                return limitedGrpcUser(authenticate(typeof raw === 'string' ? raw : undefined), limits.enabled ? peerBucket : undefined);
             } }));
-    return { app, grpcServer, card, grpcAddress, grpcListenPort: listenPort + 1, pushSender, pushInbox };
+    return { app, grpcServer, card, grpcAddress, grpcListenPort: listenPort + 1, pushSender, pushInbox, handler, taskGate };
 }
 export async function startA2AGrpc(surface, host = '127.0.0.1') {
     await new Promise((resolve, reject) => {

package/dist/config.d.ts

@@ -96,6 +96,15 @@ export declare const ConfigSchema: z.ZodObject<{
         listen_port: z.ZodOptional<z.ZodNumber>;
         peers_file: z.ZodDefault<z.ZodString>;
         hermes_compat: z.ZodDefault<z.ZodBoolean>;
+        rate_limit: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            ip_requests_per_minute: z.ZodDefault<z.ZodNumber>;
+            ip_burst: z.ZodDefault<z.ZodNumber>;
+            peer_requests_per_minute: z.ZodDefault<z.ZodNumber>;
+            peer_burst: z.ZodDefault<z.ZodNumber>;
+            max_concurrent_tasks_per_peer: z.ZodDefault<z.ZodNumber>;
+            trusted_proxies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
         skill: z.ZodOptional<z.ZodObject<{
             id: z.ZodString;
             name: z.ZodString;

package/dist/config.js

@@ -43,7 +43,8 @@ const MattermostChannel = z.object({ enabled: z.boolean().default(false), base_u
 /** A plugin module specifier: an npm package name, or an absolute path / file URL to an ES module. */
 const pluginSpecifier = z.string().min(1).max(500).refine(value => /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:\/[A-Za-z0-9._-]+)*$/.test(value) || value.startsWith('/') || value.startsWith('file://'), 'Expected an npm package name, an absolute path, or a file:// URL');
 const magnusControlDefault = { enabled: false, base_url: '${ARDENT_MAGNUS_API_URL}', token_env: 'ARDENT_MAGNUS_READ_TOKEN' };
-const a2aDefault = { enabled: false, protocol_version: '1.0', bindings: ['jsonrpc', 'http-json'], public_url: '${ARDENT_A2A_PUBLIC_URL}', listen_host: '127.0.0.1', peers_file: 'peers.yaml', hermes_compat: false };
+const a2aRateLimitDefault = { enabled: true, ip_requests_per_minute: 600, ip_burst: 120, peer_requests_per_minute: 300, peer_burst: 60, max_concurrent_tasks_per_peer: 16, trusted_proxies: [] };
+const a2aDefault = { rate_limit: a2aRateLimitDefault, enabled: false, protocol_version: '1.0', bindings: ['jsonrpc', 'http-json'], public_url: '${ARDENT_A2A_PUBLIC_URL}', listen_host: '127.0.0.1', peers_file: 'peers.yaml', hermes_compat: false };
 const researchDefault = { enabled: false, searxng_url: '${ARDENT_SEARXNG_URL}', firecrawl_url: '${ARDENT_FIRECRAWL_URL}', firecrawl_token_env: 'FIRECRAWL_API_KEY' };
 export const ConfigSchema = z.object({
     schema_version: z.literal(1),
@@ -62,6 +63,8 @@ export const ConfigSchema = z.object({
     a2a: z.object({ enabled: z.boolean().default(false), protocol_version: z.literal('1.0').default('1.0'), bindings: z.array(z.enum(['jsonrpc', 'http-json', 'grpc'])).min(1).default(['jsonrpc', 'http-json']), public_url: urlReference.default('${ARDENT_A2A_PUBLIC_URL}'), listen_host: z.string().min(1).default('127.0.0.1'), listen_port: z.number().int().min(1).max(65534).optional(), peers_file: z.string().regex(/^[A-Za-z0-9._-]+\.yaml$/).default('peers.yaml'),
         /** Serve Hermes Agent team-card discovery and slash-style JSON-RPC method aliases. */
         hermes_compat: z.boolean().default(false),
+        /** Request and task limits. `trusted_proxies` lists the reverse proxies whose X-Forwarded-For is believed; by default none is. */
+        rate_limit: z.object({ enabled: z.boolean().default(true), ip_requests_per_minute: z.number().int().min(1).max(1_000_000).default(600), ip_burst: z.number().int().min(1).max(1_000_000).default(120), peer_requests_per_minute: z.number().int().min(1).max(1_000_000).default(300), peer_burst: z.number().int().min(1).max(1_000_000).default(60), max_concurrent_tasks_per_peer: z.number().int().min(1).max(100_000).default(16), trusted_proxies: z.array(z.string().min(1).max(64)).max(64).default([]) }).strict().default(a2aRateLimitDefault),
         /** Agent Card skill advertised to peers. */
         skill: z.object({ id: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/), name: z.string().min(1).max(100), description: z.string().min(1).max(500), tags: z.array(z.string().min(1).max(40)).max(10).default([]), example: z.string().min(1).max(300).optional() }).strict().optional() }).strict().default(a2aDefault),
     channels: z.object({ telegram: TelegramChannel.default(TelegramChannel.parse({})), mattermost: MattermostChannel.default(MattermostChannel.parse({})) }).strict().default({ telegram: TelegramChannel.parse({}), mattermost: MattermostChannel.parse({}) }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/ardent",
-  "version": "1.1.5",
+  "version": "1.1.8",
   "description": "Headless TypeScript agent runtime with A2A, scheduled jobs, skills, chat channels, and a plugin API",
   "keywords": [
     "agent",