# OpenSpec Change: network-plugin-middleware

- **Change ID**: network-plugin-middleware
- **Package**: `@suaveplan/network-plugin-middleware` (new)
- **Status**: PROPOSED
- **Type**: new-package
- **Date**: 2026-04-29

## Why

The network stack processes thousands of messages per second across multiple plugins. Without a unified interception layer, each plugin must independently handle cross-cutting concerns: logging, validation, rate limiting, transformation, and security. This leads to duplicated code, inconsistent behavior, and missed enforcement. A middleware pipeline provides a single, ordered chain where every message (incoming and outgoing) passes through configurable interceptors before reaching its destination.

This plugin implements a **priority-ordered middleware chain** for the network layer, inspired by Express/Koa middleware patterns but adapted for peer-to-peer message flow.

## What changes

- **ADDED**: `MiddlewarePlugin` class implementing `NetworkPlugin`.
- **ADDED**: `MiddlewareManager` — registers, orders, and executes middleware components. Supports runtime add/remove/enable/disable. Orders middleware by priority bands:
  - `CRITICAL` (0–99) — security validation, message integrity, system health filters
  - `HIGH` (100–199) — encryption/decryption, authentication, rate limiting
  - `NORMAL` (200–299) — logging, metrics collection, transformations
  - `LOW` (300–399) — content enrichment, non-critical validations, debug info
  - `BACKGROUND` (400+) — performance monitoring, analytics, diagnostics
- **ADDED**: `LoggingMiddleware` — records message details with configurable body inclusion, max body size, and custom formatters. Logs to `NetworkBus` topic `middleware:logged` for aggregation.
- **ADDED**: `ValidationMiddleware` — schema-based message validation using Zod. Supports per-`MessageType` schemas. Strict mode rejects invalid messages; lenient mode logs warnings but forwards.
- **ADDED**: `TransformationMiddleware` — modifies message structure per type. Example: compress large payloads, strip debug fields in production, inject trace context.
- **ADDED**: `MetricsMiddleware` — collects per-message metrics: size, processing time, queue wait time. Publishes `middleware:metrics` on bus for `network-plugin-monitor`.
- **ADDED**: `ThrottlingMiddleware` — rate limiting with token-bucket algorithm. Supports global limits, per-peer limits, per-type limits, and burst allowances. Uses `@suaveplan/rate-limiter`.
- **ADDED**: `SecurityMiddleware` — automatic encryption/signing per policy. Intercepts outgoing messages and applies crypto transforms based on message type and destination tier.
- **ADDED**: `I18nMiddleware` — locale-aware message handling. Injects locale metadata, handles RTL text, standardizes timestamps.
- **ADDED**: `NETWORK_MW_CODES` — frozen error registry.

## Middleware chain execution

```yaml
OUTGOING: Application → MiddlewareManager → (CRITICAL → HIGH → NORMAL → LOW → BACKGROUND) → Transport
INCOMING: Transport → MiddlewareManager → (CRITICAL → HIGH → NORMAL → LOW → BACKGROUND) → Application

If any middleware returns null, the message is DROPPED.
If any middleware throws, the error policy applies: continue | stop | retry.
```

## Out of scope

- Application-specific middleware → applications register custom middleware via the plugin API.
- Message routing logic → handled by `network-core` `MessageRouter`.
- Transport-specific transforms → handled by `network-plugin-protocol` pipeline.

## Source mapping

This derives from `docs/old-network-planning/PHASE_9.md` §Middleware System and `PLAN_ENHANCED.md` §Phase 9.

| Requirement | Source lines | Notes |
|---|---|---|
| Priority-based ordering | `PHASE_9.md` §Middleware Priority Levels | verbatim: 5 priority bands |
| Logging middleware | `PHASE_9.md` §Logging Middleware | reworded; uses `NetworkBus` |
| Validation middleware | `PHASE_9.md` §Validation Middleware | reworded; uses Zod |
| Transformation middleware | `PHASE_9.md` §Transformation Middleware | reworded |
| Metrics middleware | `PHASE_9.md` §Metrics Middleware | reworded; publishes to bus |
| Throttling middleware | `PHASE_9.md` §Throttling Middleware | reworded; uses `@suaveplan/rate-limiter` |
| Direction handling | `PHASE_9.md` §Middleware Chain Execution | verbatim: incoming vs outgoing |
| Chain interruption | `PHASE_9.md` §Chain Execution | verbatim: null → drop |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| `SecurityMiddleware` | Required for automatic per-policy crypto application |
| `I18nMiddleware` | Required for locale-aware message handling across global peers |
| Runtime add/remove/enable/disable | Required for dynamic middleware configuration without restart |

## Verification approach

- `src/manager/manager.spec-conformance.test.ts` — pins registration, ordering, enable/disable, removal.
- `src/logging/logging.spec-conformance.test.ts` — pins body inclusion, formatting, max size.
- `src/validation/validation.spec-conformance.test.ts` — pins schema validation, strict/lenient modes.
- `src/transformation/transformation.spec-conformance.test.ts` — pins message modification, type-specific transforms.
- `src/metrics/metrics.spec-conformance.test.ts` — pins size/timing collection, bus publication.
- `src/throttling/throttling.spec-conformance.test.ts` — pins global/per-peer/per-type limits, burst handling.
- `src/security/security.spec-conformance.test.ts` — pins automatic crypto application per policy.
- `src/i18n/i18n.spec-conformance.test.ts` — pins locale injection, RTL handling.
- `src/chain/chain.spec-conformance.test.ts` — pins null-drop, error-policy, direction isolation.
- `src/error-codes.spec-conformance.test.ts` — frozen registry.
- `tests/dep-graph.test.ts` — pins no direct import of transport or protocol packages.

## Migration impact

None — additive only. Middleware is opt-in; existing message flow continues unchanged if no middleware is registered.