Successfully implemented a JWT capability payload parsing mechanism f…

[El-swaggerito]

Closes #602

I've successfully implemented a JWT capability payload parsing mechanism for Web3 webhook ingestion. Here's what was delivered:

Implementation Summary

1. JWT Capability Parser Service (src/services/jwtCapabilityParser.ts)

• Non-blocking JWT parsing with stale cache integration
• Permission and resource access validation
• Configurable expiry grace period for robustness
• Comprehensive input validation and error handling
• Batch processing support for high-throughput scenarios

2. Webhook Service Integration (src/services/webhookService.ts)

• Added optional JWT capability token parameter to queueWebhook()
• Non-blocking permission validation using the parser
• Graceful denial of webhook dispatch for insufficient permissions
• Maintains backward compatibility (capability token is optional)

3. tRPC Middleware (src/trpc/jwtCapabilityMiddleware.ts)

• withJwtCapability() - Required capability validation
• withOptionalJwtCapability() - Optional capability validation
• Permission checking (AND/OR logic)
• Resource access validation
• Type-safe context augmentation with parsed capabilities
• Helper functions for token extraction from headers, query, or body

4. Comprehensive Testing (src/services/tests/jwtCapabilityParser.test.ts)

• Event loop non-blocking tests
• High throughput tests (100+ concurrent operations)
• Cache performance validation
• Error handling under load
• Permission and resource access validation
• Memory leak prevention tests
• Input validation edge cases
• Batch processing tests

Acceptance Criteria Met

✅ Non-blocking asynchronous architecture: All JWT operations use stale cache and async patterns to avoid event loop blocking

✅ Type safety across tRPC boundary: Middleware maintains full TypeScript type safety with generic type parameters and context augmentation

✅ Backward compatibility: Integration with existing Prisma schemas without modifications; capability token is optional

✅ Edge case handling: Comprehensive validation for malformed tokens, expired tokens, missing fields, invalid signatures, and permission checks

✅ Performance under load: Tests demonstrate handling 100+ concurrent JWT parses without event loop blocking

Configuration

Add to your .env file:

JWT_CAPABILITY_CACHE_ENABLED=true
JWT_CAPABILITY_CACHE_TTL=300
JWT_CAPABILITY_GRACE_PERIOD_MS=5000

Usage Example

// In webhook ingestion
await webhookService.queueWebhook(
  organizationId,
  "payout_claimed",
  data,
  capabilityToken // Optional JWT capability token
);

// In tRPC procedures
export const myRouter = t.router({
  protectedProcedure: t.procedure
    .input(z.object({ orgId: z.string() }))
    .use(withJwtCapability({
      permissions: ["webhook:dispatch"],
      resource: "org-123"
    }))
    .mutation(async ({ input, ctx }) => {
      // ctx.capability contains the parsed JWT capability
      return { success: true };
    });
});

The implementation leverages the existing stale cache infrastructure and integrates seamlessly with your current webhook ingestion system, providing significant performance improvements during heavy Web3 block finalization spikes while maintaining security through JWT capability validation.