feat: enforce provider trust tiers in API gateway (BL-048)

[simonhagger]

Summary

• What changed:
  • Added a provider trust-tier policy engine to the API gateway (apps/desktop-main/src/api-trust-policy.ts): provider classes map to tiers — external-http → remote-low, bundled-http → local-medium, with local-high reserved for future local adapters (BL-049).
  • Tier ceilings constrain request param/header entry counts and value chars, retry attempts, timeout, and response bytes. Operations whose declared configuration exceeds their tier ceiling are blocked fail-closed before dispatch with typed API/POLICY_VIOLATION (non-retryable) and a correlation-ID warning log emitted through the new gateway logger dependency wired to the main-process structured logger.
  • Compliant operations run under effective tier-clamped limits even where they declare no per-operation policy, so runtime requests can never exceed their provider's tier.
  • Provider resolution moved ahead of request validation in invokeApiOperation; unknown providers keep the existing API/OPERATION_NOT_ALLOWED fail-closed behavior.
  • Recorded ADR-0010 in the decision log and marked BL-048 delivered with proof.
• Why this change is needed:
  • BL-048 acceptance: trust regimes constrain allowable operations, headers, payload sizes, and retry behavior by provider class, with violations blocked and logged with correlation IDs.
  • Prepares the gateway for BL-049 external adapters: any new provider must be assigned a tier before it can dispatch.
• Risk level:
  • Medium (gateway dispatch path; existing operations verified tier-compliant, full local gate run green)

Change Groups

• Trust policy engine:
  • New api-trust-policy.ts with tier table, provider→tier mapping, fail-closed resolution, declared-config evaluation, and non-mutating clamping.
• Gateway integration:
  • Pre-validation provider/tier resolution; violation blocking with structured logging; effective-operation clamping applied to validation and dispatch.
• Tests:
  • New api-trust-policy.spec.ts (9 tests) covering tier resolution, fail-closed unknown providers, violation reporting order, ceiling-equality compliance, clamping semantics.
  • Extended api-gateway.spec.ts with trust-tier integration cases: violation block + log assertion, tier-ceiling retries, bundled-http local-medium allowances, unknown-provider block before network.
  • One pre-existing test updated: POST operation declaring retries above the remote-low ceiling is now correctly rejected as a policy violation.

Validation

• pnpm nx run desktop-main:test (84 tests green)
• pnpm lint
• pnpm typecheck
• pnpm unit-test
• pnpm integration-test
• pnpm runtime:smoke
• prettier format checks on touched files

Engineering Checklist

• Conventional Commit title used
• Unit/integration tests added or updated
• A11y impact reviewed (N/A — no UI changes)
• I18n impact reviewed (N/A — no user-facing strings)
• IPC contract changes documented (no wire-format changes; new failure code API/POLICY_VIOLATION flows through the existing typed envelope)
• ADR added/updated for architecture-level decisions (ADR-0010)

Security (Required For Sensitive Changes)

• Security review completed
• Threat model updated or N/A explained
• Confirmed no secrets/sensitive data present in committed files

Security Notes

• Threat model link/update:
  • N/A for this increment.
• N/A rationale:
  • The engine narrows privileged capability: it adds fail-closed ceilings on an existing main-process-enforced boundary and introduces no renderer-visible authority, no new trust boundary, and no credential handling changes.
  • Violations are blocked before any network I/O and logged with correlation IDs for auditability.