svc-tenders Server Shell Boundary

Purpose

This note records the remaining helper boundary inside services/svc-tenders/src/server.ts after Sprint 20.

The goal is not to force more movement. The goal is to make it obvious which helpers are still legitimate service-shell concerns and which are no longer route-local support.

Labels used here:

• VERIFIED
• REAL
• TRANSITIONAL

Boundary groups still in server.ts

Auth / principal shell helpers

VERIFIED, REAL

These helpers stay in server.ts because they are part of the service HTTP shell's auth contract.

1. requireServiceAuth

• Classification: auth/principal shell helper
• Why it stays: assembles bearer extraction, JWT verification, upstream principal resolution, and request auth context

2. verifyAccessToken

• Classification: auth/principal shell helper
• Why it stays: service-shell token validation tied to runtime JWT config

3. extractBearerToken

• Classification: auth/principal shell helper
• Why it stays: private auth-shell helper used only by requireServiceAuth

4. requireActivePrincipal

• Classification: auth/principal shell helper
• Why it stays: shared route gate over the auth context established by requireServiceAuth

5. resolvePrincipal

• Classification: auth/principal shell helper
• Why it stays: reaches across the auth service boundary to /auth/me, so it is still shell-level integration logic rather than route-local support

6. parseAuthMePrincipal

• Classification: auth/principal shell helper
• Why it stays: private payload-shape guard used only by resolvePrincipal

Low-level shared parser / query helpers

VERIFIED, REAL

These helpers stay in server.ts because they are still reused by multiple support builders and do not yet have a narrower truthful shared home.

1. parsePositiveInt

• Classification: low-level shared parser/query helper
• Why it stays: shared across vacancy, accommodation, tender, auction, Butkhuzi, and KES support assembly

2. parsePositiveNumber

• Classification: low-level shared parser/query helper
• Why it stays: shared numeric parser used outside one route group

3. parseOptionalString

• Classification: low-level shared parser/query helper
• Why it stays: low-level route-shell normalization helper used across multiple support surfaces

4. parseOptionalUpper

• Classification: low-level shared parser/query helper
• Why it stays: low-level parser feeding multiple route-support builders

5. parseOptionalBoolean

• Classification: low-level shared parser/query helper
• Why it stays: shared boolean parser used by both tender and auction support

6. parseOptionalInt

• Classification: low-level shared parser/query helper
• Why it stays: shared parser used by ICPI, Butkhuzi, and KES support assembly

7. clampPositiveInt

• Classification: low-level shared parser/query helper
• Why it stays: shared pagination/limit clamp helper across multiple route groups

8. getFirstQueryValue

• Classification: low-level shared parser/query helper
• Why it stays: foundational low-level helper used by the other parser helpers

KES ingress / security boundary helpers

VERIFIED, REAL

These helpers stay in server.ts because they are ingress controls at the KES route boundary. They are not generic security utilities.

1. ensureThirdPartyKycBoundary

• Classification: KES ingress/security boundary helper
• Why it stays: enforces third-party KYC payload constraints at request ingress using runtime provider mode

2. verifyIncomingSignatureGate

• Classification: KES ingress/security boundary helper
• Why it stays: verifies request payload signatures at the service boundary using runtime key configuration

What moved earlier and why it no longer belongs here

VERIFIED

The following helpers no longer live in server.ts because they had route-support-local homes:

• extractDetails -> services/svc-tenders/src/routes/support/detailExtractionSupport.ts
• resolveIntentId -> services/svc-tenders/src/routes/support/requestIntentSupport.ts
• parseRankingScope -> services/svc-tenders/src/routes/support/rankingScopeSupport.ts
• runMulterSingle bridge -> services/svc-tenders/src/routes/support/declarationUploadSupport.ts
• parseTenderListOptions -> services/svc-tenders/src/routes/support/tenderRouteSupport.ts
• parseAuctionListOptions -> services/svc-tenders/src/routes/support/auctionRouteSupport.ts

These were moved because they were no longer truthful as service-shell helpers.

What remains transitional/shared

VERIFIED, TRANSITIONAL

The remaining transitional/shared area is the low-level parser cluster.

Why it is still transitional:

• it is shared across multiple route-support builders
• it is not route-local
• but it also is not a separate platform module with a clearly better home today

So the honest state is:

• keep it in server.ts
• classify it as low-level route-shell parsing support
• do not force a move for cosmetic neatness

Code-side clarification made in Sprint 20

VERIFIED

Sprint 20 did not force another extraction.

It added explicit section comments in services/svc-tenders/src/server.ts so a reader can immediately distinguish:

• auth/principal shell helpers
• low-level shared parser/query helpers
• KES ingress/security boundary helpers

Current honest verdict

After Sprint 20, the remaining helper surface in server.ts is best understood as:

• auth/principal shell logic
• low-level shared route-shell parsing
• KES ingress/security boundary protection

No obviously route-local helper bodies remain stranded in the file.