Feature/batch passport revocation

[akinboyewaSamson]

closes #110

Description

This PR introduces a batch processing route for passport revocations (POST /api/protocol/passport/revoke-batch). When managing massive agent fleets (e.g., decommission cycles), executing single $N$ serial deletion tasks spikes round-trip overhead. This batch approach executes atomic updates per passport ID while collecting detailed metric classifications.

What was Implemented

• New File Layer: Created src/api/passportBatch.ts to handle isolated array mutations securely.
• Input Validation & Safety Limits:
• Rejects empty arrays, malformed items, or non-array payloads with a 400 status.
• Enforces a hard boundary limit of 1–50 IDs. Collections exceeding 50 entries instantly trigger a 400 response payload: { error: 'batch_too_large', max: 50 }.

State & Processing Pipeline**:

• Active Passports: Transitions status to 'revoked', logs the action dynamically, appends a dedicated structured audit tracking log, and fires off a sequential passport.revoked webhook event.
• Missing Passports: Appends untracked entries directly to the notFound summary catalog.
• Pre-Revoked Passports: Safely skips processed passports, placing their IDs into alreadyRevoked to prevent duplicate writes or double-emitted event triggers.

API Specification

Route

POST /api/protocol/passport/revoke-batch

Request Payload Structure

{
  "passportIds": ["pp_aaa", "pp_bbb", "pp_ccc"],
  "reason": "fleet_decommission"
}

Response Payload Structure (Success 200)

{
  "ok": true,
  "revoked": ["pp_aaa"],
  "notFound": ["pp_bbb"],
  "alreadyRevoked": ["pp_ccc"],
  "total": 1
}

---

Acceptance Criteria Checklist

• Matrix Payload Evaluation (e.g., 2 Valid IDs + 1 Unknown ID $\rightarrow$ revoked: [2], notFound: [1]).
• Boundary Enforcement ($>50$ IDs yields a 400 Bad Request with structured error keys).
• State Idempotency (Already-revoked nodes stream safely into alreadyRevoked without duplicated execution).
• Webhook Lifecycle Pipeline (Each atomic execution triggers a separate passport.revoked hook payload).
• Audit Event Streaming (Dedicated backend audit tracking records structural context metrics for every execution pass).