suaveplan/openspec/archive/2026-05-12-enterprise-network-governance/tasks.md

Tasks: enterprise-network-governance

Change ID: enterprise-network-governance Package: @suaveplan/network-governance Target path: universal/network/network-governance Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/logger, @suaveplan/rules

---

1. Scaffold

• Create universal/network/network-governance/ with src/, tests/, and all feature subdirectories.
• Write package.json at version 0.1.0: "sideEffects": false, exports map, deps per proposal.md.
• Write tsconfig.json, vitest.config.ts, scripts.

---

2. Types and error codes

• Define all public types in src/types/common.ts: NetworkPolicy, RateLimitPolicy, AccessControlPolicy, QuotaPolicy, CapabilityPolicy, GovernanceRequest, GovernanceDecision, AuditEntry, GovernanceEvent, GovernanceEngineOptions.
• Write src/types/common.md (≥200 words, simple + advanced examples).
• Define error codes in src/error-codes.ts.
• Write Zod schemas for all policy types in src/types/schemas.ts + src/types/schemas.md.

---

3. Policy implementations (src/policies/)

3a. Rate limit policy

• Implement evaluateRateLimitPolicy(policy, request, store, clock):
  • Sliding-window counter keyed by policy.keyBy field from request.
  • Increment counter; if count > maxRequests, return deny with throttleMs until window resets.
  • Use injectable Clock for window bounds.
• Write rate-limit.test.ts + rate-limit.md.

3b. Access control policy

• Implement evaluateAccessControlPolicy(policy, request):
  • Check denylist first (explicit deny overrides).
  • Check allowlist next (explicit allow).
  • If requireAuth and no peerId/userId, deny.
• Write access-control.test.ts + access-control.md.

3c. Quota policy

• Implement evaluateQuotaPolicy(policy, request, store, clock):
  • Track active connection count per key; deny if maxConnections exceeded.
  • Reset on resetIntervalMs using injectable Clock.
• Write quota.test.ts + quota.md.

3d. Capability policy

• Implement evaluateCapabilityPolicy(policy, request):
  • Check if request capabilities includes ALL policy.requiredCapabilities.
  • If policy.target is set, only apply when request.target matches the pattern (exact or glob).
• Write capability.test.ts + capability.md.

---

4. Governance engine (src/core/engine/)

• Implement createGovernanceEngine(options?):
  • Stores policies in a sorted array (descending by priority).
  • Maintains audit log as bounded ring buffer (auditLogSize, default 1000).
• Implement engine.addPolicy(policy) — validates with Zod; inserts in priority order.
• Implement engine.removePolicy(id).
• Implement engine.evaluate(request, signal?):
  • Check signal.aborted.
  • Iterate policies in priority order; evaluate via the appropriate evaluator.
  • First deny → short-circuit (deny wins over allow at same priority).
  • Collect appliedPolicies.
  • Write to audit log.
  • Emit event-bus event per decision type.
  • OTel: span governance.evaluate, counter governance.decisions_total (attribute: allowed).
• Implement engine.getAuditLog(limit?).
• Write engine.test.ts (≤500 lines): allow, deny, throttle, multi-policy, priority ordering, audit log.
• Write engine.md (≥200 words).

---

5. Property-based tests (tests/property.test.ts)

• Deny always wins when a deny policy matches, regardless of allow policies.
• Rate-limit counter is monotonically non-decreasing per key within a window.

---

6. Docs and verify

• All per-file .md files per layout in proposal.md.
• universal/network/network-governance/README.md.
• bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-governance — all green, 100%.
• bun scripts/publish.ts --package @suaveplan/network-governance.
• Update CLAUDE.md. Archive change folder.