KES Shared Shell Contract

Purpose

This document defines the smallest truthful shared-shell contract KES still depends on after host extraction and compatibility-layer removal.

It is not a target-state fantasy. It reflects current code truth.

Gateway behavior

Current gateway surface:

• kes-orchestrator.ts

Current seam:

• KES_ORCHESTRATOR_SERVICE_URL ?? TENDERS_SERVICE_URL

Classification:

• must remain shared

Why:

• the gateway route family is already the stable public HTTP contract
• extraction should preserve that seam instead of rebuilding client-facing routing

Auth behavior

Current runtime-local auth ingress:

• buildRequireServiceAuth(...) in auth.ts

Current identity resolution:

• upstream /auth/me resolution from svc-auth

Classification:

• must remain shared

Why:

• KES still relies on the same bearer-token verification and shared principal resolution contract as the rest of the backend shell

Shared auth / identity expectations

Current expectations:

• bearer token required for all KES writes
• principal context arrives through shared auth shell behavior
• role/permission detail is not redefined inside KES itself

Classification:

• must remain shared

Why:

• KES does not currently own a separate auth model

KYC / signature shared-ingress expectations

Current helpers:

• ensureThirdPartyKycBoundary(...)
• verifyIncomingSignatureGate(...)

Current location:

• server.ts
• adapted through kesRouteSupport.ts

Classification:

• can be wrapped later

Why:

• they are KES-facing ingress rules
• but their semantics are still shared shell policy today
• payment request currently needs both KYC-boundary enforcement and signature verification
• payment approve/settle currently need signature verification only

Parser / helper expectations

Current shared parser helpers:

• parsePositiveInt
• parseOptionalInt
• parseOptionalString
• parseOptionalUpper
• clampPositiveInt

Classification:

• can move into KES later

Why:

• these are simple query/body normalization helpers
• they are now runtime-local to svc-kes, but they remain part of a broader shared-shell contract because they preserve existing gateway/auth semantics

Kafka / outbox / projection shared-infra expectations

Current shared infra:

• gateway mutation-event producer
• proxy mutation event consumer
• outbox relay
• domain-event consumer
• idempotency store
• DLQ replay tooling

Classification:

• must remain shared for now

Why:

• KES is the strongest product consumer of this backbone
• but these pieces still behave like shared Kvary event infrastructure rather than a clean KES-local package
• later extraction work should decide whether they move, not host-retirement cleanup

What remains shared on purpose

• gateway route family
• auth ingress
• principal resolution via /auth/me
• KYC boundary helper
• signature verification helper
• event-backbone infrastructure

What can move later

• deeper KYC/signature ownership if the team wants KES-local ingress policy
• any remaining parser/helper conventions that should stop being shared by convention
• shared backbone workers if the team later wants full KES-local event ownership

What still blocks runtime/bootstrap prep

• runtime/bootstrap prep is no longer blocked by the shell contract
• only later full-independence work remains: shared ingress ownership decisions and shared backbone transfer