ICPI Shared Shell Contract

Purpose

This document defines what intentionally remains shared when ICPI leaves svc-tenders.

It describes the contract ICPI should continue to rely on, not the parts that should move with ICPI.

1. Gateway Behavior

Gateway ownership remains in services/api/src/routes/icpi.ts.

Current behavior that should remain unchanged:

• GET /api/v1/icpi/prices
• GET /api/v1/icpi/suggest
• GET /api/v1/icpi/latest/:itemCode
• GET /api/v1/icpi/estimate
• POST /api/v1/icpi/upsert

Gateway route behavior today:

• forwards request method and query string
• forwards Authorization when present
• forwards x-request-id when present
• treats JSON responses as pass-through JSON
• returns 502 icpi_service_unavailable or 504 icpi_service_timeout on upstream failure

This is a stable shared shell seam and should stay outside the ICPI extraction package.

2. Gateway Auth Behavior

Protected ICPI writes stay behind services/api/src/auth/middleware.ts requireGatewayAuth.

Current shared behavior:

• verify bearer token with shared gateway JWT config
• resolve principal through shared auth service /auth/me
• reject missing or invalid auth before proxying

This should remain shared because it is public-facade auth behavior, not ICPI business logic.

3. Service URL / Env Contract

Current gateway target contract:

• ICPI_SERVICE_URL ?? TENDERS_SERVICE_URL ?? "http://localhost:4020"
• ICPI_PROXY_TIMEOUT_MS with current default 15000

Post-extraction expectation:

• ICPI_SERVICE_URL should point to the new ICPI runtime
• TENDERS_SERVICE_URL remains a fallback only during staged migration or rollback

4. Service-Side Auth Ingress Behavior

ICPI currently depends on service-side auth ingress equivalent to requireServiceAuth in services/svc-tenders/src/server.ts.

Current behavior that must remain compatible after extraction:

• extract bearer token from Authorization
• verify JWT using shared JWT_SECRET
• resolve principal through AUTH_SERVICE_URL/auth/me
• attach auth context to the request before route logic runs

This behavior may move into an ICPI-local runtime shell, but the contract with shared auth/identity remains intentionally shared.

5. Shared Auth / Identity Expectations

These dependencies remain shared on purpose:

• shared JWT verification rules
• shared auth service availability
• shared /auth/me principal payload expectations

These are backbone platform dependencies, not reasons to keep ICPI inside svc-tenders.

6. What Does Not Belong In The Shared Shell

The following should move with ICPI and should not remain shared:

• ICPI contracts
• ICPI validation
• ICPI query parsing
• ICPI repository/persistence code
• ICPI direct route registration
• ICPI persistence migrations

7. Contract Summary

The intended post-extraction contract is:

• gateway owns public route façade and gateway auth
• auth/identity services remain shared platform infrastructure
• ICPI owns everything behind that façade except the shared auth dependency itself