Skip to content

fix(web-shared): validate internal service endpoints before each request - #11158

Open
iscekic wants to merge 6 commits into
mainfrom
drain/internal-service-url-check
Open

iscekic wants to merge 6 commits into
mainfrom
drain/internal-service-url-check

Conversation

@iscekic

@iscekic iscekic commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Evidence

Evidence: demonstrated — a real-socket harness drove the worker admin client, the notifications worker client, the gateway metrics emitter and the bouncer client from this head against a local HTTP listener. An accepted endpoint delivered its request at the single-separator path with its credential header; an endpoint outside the rule produced the client's existing unconfigured result and the listener received nothing.

Change

  • packages/web-shared/src/lib/internal-service-url.ts exports parseInternalServiceUrl. An endpoint is used only when its value is an absolute https URL, or an http URL on a loopback hostname (localhost, 127.0.0.1, [::1]).
  • The same module exports parseInternalServiceEndpoint, which resolves a request path against the parsed endpoint. Only an absolute path on that endpoint is used, so a request URL always derives from the value the rule accepted. The worker admin client, the notifications worker client (dispatch and glanceable refresh), benchmark profile registration, both auto-routing decision fetchers and the bouncer client build their request URL through it, so a request URL is never assembled by concatenation and an accepted value that ends in a separator still produces one separator.
  • The bouncer client reports its unconfigured case as a tagged result, so post and deliverWireBody keep their existing values (null, and bouncer_not_configured) without a second configuration check.
  • packages/web-shared/src/lib/ai-gateway/usage-publisher.ts uses the shared rule instead of its private copy, so one implementation serves every internal client. The existing publisher suite is the differential: behaviour is unchanged.
  • The rule now runs in every client of the package that sends to a configured service endpoint: the O11Y metrics emitter, the worker admin client, benchmark profile registration, both auto-routing decision fetchers, the primary-region usage record client, the Claude payer-state read, the Enkrypt usage handoff, the notifications worker client, and the bouncer client.
  • A value outside the rule counts as unconfigured. Each caller keeps its current failure result: no request, and the existing value (null, { kind: 'unavailable' }, the 500 unconfigured body, bouncer_not_configured, or its existing thrown error).
  • The notifications worker client reports an unset variable and a configured value outside the rule as two different logged reasons.

Verification

The harness starts a listener bound to 0.0.0.0, drives the clients from this head, and reports what the listener received and which credential headers arrived. The accepted endpoint is the loopback address; the endpoint outside the rule is this machine's non-loopback address, so both cases use a real socket. Each configured endpoint ran in its own process, because the endpoints are read once at module load.

scenario configured endpoint request reached listener path the listener saw result
worker admin satisfies the rule, loopback, one trailing separator yes /admin/x 200
worker admin does not satisfy the rule no — 500 unconfigured error
notifications dispatch satisfies the rule, loopback, one trailing separator yes /internal/v1/dispatch accepted
notifications dispatch does not satisfy the rule no — refused, unsupported-endpoint reason logged
notifications refresh does not satisfy the rule no — refused, unsupported-endpoint reason logged
O11Y metrics satisfies the rule, loopback, one trailing separator yes /ingest/api-metrics deferred send delivered
O11Y metrics does not satisfy the rule no — no deferred send
bouncer: credit event, usage event, decide, charge decide, signup decide, release satisfies the rule, loopback, one trailing separator yes /api/v2/credit-event, /api/v1/usage-event, /api/v1/decide, /api/v1/charge-decide, /api/v1/signup-decide, /api/v1/release delivered: true; each caller returned its parsed verdict
bouncer: the same six calls does not satisfy the rule no — bouncer_not_configured, and null from each verdict caller

The bouncer case ran in its own two processes with --conditions=react-server, so the client's server-only guard resolves in a plain script instead of a bundler.

Test suites, from the repository root:

  • pnpm --filter web exec jest internal-service-url worker-admin-fetch api-metrics.server auto-routing-benchmark-admin auto-routing-decision auto-routing-admin-client usage-record-client payer-state usage-region notifications-worker-client bouncer/client usage-publisher — 13 suites, 383 tests, all passing.
  • pnpm --filter web exec jest packages/web-shared/src/lib/bouncer/client.test.ts packages/web-shared/src/lib/internal-service-url.test.ts — 2 suites, 119 tests, all passing. These pin the bouncer request URL for an accepted endpoint, including one that ends in a separator, and pin that a value outside the rule sends nothing.
  • pnpm --filter @kilocode/web-shared run typecheck — clean.
  • pnpm -w exec oxlint --config .oxlintrc.json packages/web-shared/src/lib — clean.

Production prerequisites

  • Confirm that every deployed value of O11Y_SERVICE_URL and of each worker admin endpoint that these clients call is an https URL.

Proxy answers

The owner's proxy gave these answers in the owner's place.

  1. Question: Scope: five other clients in the same package reach their configured service endpoints through the same code path. The approved brief names only the metrics emitter and the worker admin client. What should this pull request do?
    Answer: Also harden the sibling sites
    Confidence: 0.60 · Precedent: Fix the root cause and the class of the issue on every affected surface: session 00eb2a1d3e4b, "if anything repeats the same mistake over and over again, fix the class"; a related bug in the same PR's area belongs in that PR (session a2f7aef14d65, "fix in the existing pr").

Add one shared endpoint rule (an absolute https URL, or http on a loopback hostname) and
apply it in every internal client before it sends. A value that fails the rule counts as
unconfigured, so each caller keeps its existing failure result and sends no request.
@iscekic iscekic added drain Work item from the findings drain janitor:trust Janitor finding: trust boundary hardening labels Nov 16, 2026
@kilo-code-bot

kilo-code-bot Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

The bouncer client now derives its request URL from parseInternalServiceEndpoint and reports an unconfigured endpoint through a tagged PostResult, and every caller behaviour is preserved because the removed pre-checks were duplicated inside postWithResult; I found no defect in the changed lines.

Assumptions: [INFERENCE] The deployed BOUNCER_URL value was not verifiable from the repository; all current paths passed to postWithResult start with a single / and the URL is an origin, so the helper's absolute-path requirement and origin-based resolution change nothing for them, and a configured value carrying a path prefix would now be dropped.

Files Reviewed (3 files)
  • packages/web-shared/src/lib/bouncer/client.ts
  • packages/web-shared/src/lib/bouncer/client.test.ts
  • packages/web-shared/src/lib/internal-service-url.ts
Previous Review Summaries (3 snapshots, latest commit 0cf0229)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 0cf0229)

Status: No Issues Found | Recommendation: Merge

Executive Summary

The follow-up commit adds an absolute-path guard and an origin-equality check to parseInternalServiceEndpoint, so a request path can no longer resolve onto a host other than the endpoint the rule accepted; every current caller passes an absolute path, so no caller behavior regresses and I found no defects in the changed lines.

Assumptions: [INFERENCE] Deployed values of the worker/notifications URLs were not verifiable from the repository; the guard only rejects paths that do not begin with a single /, so any caller that later passes a relative path would now be treated as unconfigured. [INFERENCE] packages/web-shared/src/lib/bouncer/client.ts:466 still builds its URL by concatenation, but that path is unchanged by this increment and outside its scope.

Files Reviewed (2 files)
  • packages/web-shared/src/lib/internal-service-url.ts
  • packages/web-shared/src/lib/internal-service-url.test.ts

Previous review (commit c236f97)

Status: No Issues Found | Recommendation: Merge

Executive Summary

The follow-up commit routes every request path through parseInternalServiceEndpoint, so a configured endpoint ending in a separator now yields a single separator and rejected endpoints keep each caller's existing unconfigured result; the added tests cover the trailing-separator and rejected-value paths, and I found no defects in the changed code.

Assumptions: [INFERENCE] The helper treats each configured service URL as an origin: new URL(path, base) drops any path component of a deployed value (e.g. https://host/base now yields https://host/decide instead of https://host/base/decide). This matches the prior O11Y client's new URL('/ingest/api-metrics', baseUrl) and every committed example value is origin-only (apps/web/.env.development.local.example, ENVIRONMENT.md), but production values could not be verified from the repository. [INFERENCE] packages/web-shared/src/lib/bouncer/client.ts:466 still concatenates \${BOUNCER_URL}${path}``; that line is unchanged by this increment and out of scope, so it is noted only as an observation.

Files Reviewed (9 files)
  • packages/web-shared/src/lib/internal-service-url.ts
  • packages/web-shared/src/lib/internal-service-url.test.ts
  • packages/web-shared/src/lib/ai-gateway/worker-admin-fetch.ts
  • packages/web-shared/src/lib/ai-gateway/worker-admin-fetch.test.ts
  • packages/web-shared/src/lib/ai-gateway/auto-routing-benchmark-admin-client.ts
  • packages/web-shared/src/lib/ai-gateway/auto-routing-benchmark-admin-client.test.ts
  • packages/web-shared/src/lib/ai-gateway/auto-routing-decision.ts
  • packages/web-shared/src/lib/notifications-worker-client.ts
  • packages/web-shared/src/lib/notifications-worker-client.test.ts

Previous review (commit b238ca4)

Status: No Issues Found | Recommendation: Merge

Executive Summary

The new shared endpoint rule is applied consistently across every changed client, each caller keeps its existing unconfigured result and sends no request, and the added tests cover both accepted and rejected endpoint shapes; I found no defects in the changed code.

Assumptions: [INFERENCE] Production values of O11Y_SERVICE_URL, APP_URL, BOUNCER_URL, and the worker URLs are https (or loopback in local fixtures), per the PR's production prerequisite; deployment configuration was not verifiable from the repository. [INFERENCE] One path in unchanged code, apps/web/src/lib/o11y-client.ts, still sends X-O11Y-ADMIN-TOKEN to O11Y_SERVICE_URL without this rule; it is outside the package scope this PR hardens.

Files Reviewed (21 files)
  • packages/web-shared/src/lib/internal-service-url.ts
  • packages/web-shared/src/lib/internal-service-url.test.ts
  • packages/web-shared/src/lib/ai-gateway/worker-admin-fetch.ts
  • packages/web-shared/src/lib/ai-gateway/worker-admin-fetch.test.ts
  • packages/web-shared/src/lib/ai-gateway/usage-publisher.ts
  • packages/web-shared/src/lib/ai-gateway/usage-record-client.ts
  • packages/web-shared/src/lib/ai-gateway/usage-record-client.test.ts
  • packages/web-shared/src/lib/ai-gateway/auto-routing-decision.ts
  • packages/web-shared/src/lib/ai-gateway/auto-routing-decision.test.ts
  • packages/web-shared/src/lib/ai-gateway/auto-routing-benchmark-admin-client.ts
  • packages/web-shared/src/lib/ai-gateway/auto-routing-benchmark-admin-client.test.ts
  • packages/web-shared/src/lib/ai-gateway/claude-billing/payer-state.ts
  • packages/web-shared/src/lib/ai-gateway/claude-billing/payer-state.test.ts
  • packages/web-shared/src/lib/ai-gateway/enkrypt-guardrail/usage-primary-region.ts
  • packages/web-shared/src/lib/ai-gateway/enkrypt-guardrail/usage-region.test.ts
  • packages/web-shared/src/lib/ai-gateway/o11y/api-metrics.server.ts
  • packages/web-shared/src/lib/ai-gateway/o11y/api-metrics.server.test.ts
  • packages/web-shared/src/lib/bouncer/client.ts
  • packages/web-shared/src/lib/bouncer/client.test.ts
  • packages/web-shared/src/lib/notifications-worker-client.ts
  • packages/web-shared/src/lib/notifications-worker-client.test.ts

Reviewed by deepseek-flash-latest · Input: 63.9K · Output: 8.3K · Cached: 591.4K

Review guidance: REVIEW.md from base branch main

@iscekic iscekic added merge:human Substantive functional risk requires human review. needs:prod-action Prod prerequisite (env var, secret, firewall rule, config) needed before merge labels Nov 16, 2026

@eshurakov eshurakov left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bot - No critical issues found. Two minor, actionable notes:

  1. packages/web-shared/src/lib/ai-gateway/worker-admin-fetch.ts:26 validates the endpoint with parseInternalServiceUrl but then discards the parsed URL and still builds the request by string concatenation (`${workerUrl}${path}`). An accepted value with a trailing slash or a path (e.g. https://worker.example.com/) yields https://worker.example.com//admin/x. Build the request from the parsed URL so a validated value cannot produce a malformed endpoint.

  2. packages/web-shared/src/lib/notifications-worker-client.ts:55 and :251 report "NOTIFICATIONS_WORKER_URL is not configured" when the variable is set but falls outside the new rule. That is now a different failure than an unset value; logging an explicit unsupported-endpoint reason (as usage-record-client and the Enkrypt handoff already do) would let operators tell the two apart.

@iscekic iscekic removed the merge:human Substantive functional risk requires human review. label Nov 16, 2026
@iscekic

iscekic commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator Author

bot: Both notes are addressed in c236f97.

  1. parseInternalServiceEndpoint in packages/web-shared/src/lib/internal-service-url.ts resolves a request path against the endpoint value that has already passed the endpoint rule. The worker admin client, the notifications worker client (dispatch and glanceable refresh), benchmark profile registration and both auto-routing decision fetchers build their request URL through it. A configured endpoint that ends in a separator resolves to a request path with one separator: https://worker.example.com/ with /admin/x requests https://worker.example.com/admin/x.
  2. The notifications worker client reports an unset variable and a value outside the endpoint rule as two separate reasons. An unset variable logs NOTIFICATIONS_WORKER_URL is not configured; a value outside the rule logs NOTIFICATIONS_WORKER_URL is not an https or loopback http endpoint. Both the dispatch and the glanceable refresh path report this way, and neither sends a request.

Tests: worker-admin-fetch.test.ts asserts the single-separator request for an endpoint that ends in a separator; internal-service-url.test.ts covers the resolver for accepted and rejected values; notifications-worker-client.test.ts asserts the two distinct reasons with no request sent; auto-routing-benchmark-admin-client.test.ts asserts the registration path for an endpoint that ends in a separator.

@iscekic iscekic added the merge:human Substantive functional risk requires human review. label Nov 16, 2026

@eshurakov eshurakov left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bot - Minor hardening gap in parseInternalServiceEndpoint: it validates the base URL but then resolves path with new URL(path, base), so a path that is not a single-slash-absolute reference still escapes the validated host. parseInternalServiceEndpoint("https://worker.example.com", "//evil.example.org/admin") returns https://evil.example.org/admin, which would send the Bearer INTERNAL_API_SECRET to that host. Every current caller passes a hardcoded path, so this is not exploitable today, but the helper exists to guarantee the request URL derives from the accepted base. Reject any path that does not start with exactly one / (or url-encode/throw) before resolving, and add a //host case to internal-service-url.test.ts.

`parseInternalServiceEndpoint` now accepts a request path only when it is
absolute on the endpoint that passed the transport rule, and it checks that
the resolved URL keeps that endpoint's origin. A path outside that form counts
as unconfigured, so every caller keeps its existing failure result and sends
nothing. Tests cover the accepted form and the rejected forms.
@iscekic iscekic removed the merge:human Substantive functional risk requires human review. label Nov 16, 2026
@iscekic

iscekic commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator Author

bot: Fixed in 0cf0229.

parseInternalServiceEndpoint now accepts a request path only when it is absolute on the endpoint that passed the transport rule, and it checks that the resolved URL keeps that endpoint's origin. A path outside that form counts as unconfigured, so every caller returns its existing failure result and sends nothing.

packages/web-shared/src/lib/internal-service-url.test.ts covers the accepted form and the rejected forms, so the guard cannot regress silently.

Verification at 0cf0229:

  • pnpm --filter web exec jest internal-service-url worker-admin-fetch notifications-worker-client api-metrics.server — 4 suites, 69 tests passing.
  • pnpm --filter @kilocode/web-shared run typecheck — clean.
  • oxfmt --list-different and oxlint on both changed files — clean.
  • A real-socket harness drove the real worker admin client against a loopback endpoint: the accepted path delivered exactly one request with its authorization header, and each rejected path delivered nothing to either listener and returned the unconfigured result.

@iscekic iscekic added the merge:human Substantive functional risk requires human review. label Nov 16, 2026

@eshurakov eshurakov left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bot - Reviewed the shared endpoint-validation change; no critical issues found. One actionable, non-blocking finding:

  • packages/web-shared/src/lib/bouncer/client.ts postWithResult still assembles the request URL as ${BOUNCER_URL}${path}. The new guards in post and deliverWireBody validate BOUNCER_URL through parseInternalServiceUrl but never normalize it, so a configured value with a trailing separator (e.g. https://bouncer.kiloapps.io/) produces https://bouncer.kiloapps.io//api/v1/decide, which the worker may not route. Build the URL with parseInternalServiceEndpoint(BOUNCER_URL, path) (as the worker admin and notifications clients now do) or strip the trailing separator, so the change's "never assembled by concatenation" guarantee actually covers the bouncer client.

The bouncer request URL now comes from the shared endpoint helper, as it already
does in the worker admin and notifications clients, so the URL derives from the
value the transport rule accepted. The unconfigured case is a tagged result, so
each caller keeps its existing failure value without a second configuration
check. Both helpers accept a null value, because the configured bouncer value is
null when it is unset.
@iscekic iscekic removed the merge:human Substantive functional risk requires human review. label Nov 16, 2026
@iscekic

iscekic commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator Author

bot: Addressed the review remark on packages/web-shared/src/lib/bouncer/client.ts.

postWithResult now resolves its request URL with parseInternalServiceEndpoint(BOUNCER_URL, path) and hands that URL to fetch, so the bouncer client builds every request from the value the shared transport rule accepted, as the worker admin and notifications clients already do. PostResult is a tagged union, so post and deliverWireBody keep their existing results (null, and bouncer_not_configured) without a duplicate configuration check. Both helpers in internal-service-url.ts accept string | null | undefined, because the configured bouncer value is null when it is unset.

Verification on 0de630f:

  • pnpm --filter @kilocode/web-shared typecheck — exit 0.
  • pnpm --filter web exec jest packages/web-shared/src/lib/bouncer/client.test.ts packages/web-shared/src/lib/internal-service-url.test.ts — 2 suites, 119 tests passing, including the new case where a configured endpoint that ends in a separator still produces one separator, and the case where a value the rule refuses sends nothing.
  • oxlint on the three changed files and oxfmt --list-different — clean.
  • A real-socket harness drove the six bouncer calls with a configured endpoint that ends in a separator. The listener received /api/v2/credit-event, /api/v1/usage-event twice, /api/v1/decide, /api/v1/charge-decide, /api/v1/signup-decide and /api/v1/release, each with the credential header, and every caller returned its parsed verdict. With an endpoint the rule refuses, the listener received nothing and the callers returned bouncer_not_configured or null.

@iscekic iscekic added the merge:human Substantive functional risk requires human review. label Nov 16, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

drain Work item from the findings drain janitor:trust Janitor finding: trust boundary hardening merge:human Substantive functional risk requires human review. needs:prod-action Prod prerequisite (env var, secret, firewall rule, config) needed before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants