add unit test coverage for agent-service auth-api

[gupta-sahil01]

Task Summary

agent-service/src/api/ currently has no test coverage — none of its four
modules (auth-api.ts, backend-api.ts, workflow-api.ts, execution-api.ts)
has a corresponding .spec.ts. It is the only directory in the service without
any tests; src/agent/tools/ and src/agent/util/ are both covered.

This task covers auth-api.ts only, so the change stays small. The remaining
three modules are HTTP clients that need a stubbed fetch, and are better
handled as a follow-up.

auth-api.ts is the authentication gate for the whole service. Every request
that asks the agent to act on a user's behalf passes through it in
server.ts:187-195:

const userToken = extractBearerToken(headers.authorization);
if (!userToken) throw new Error("Authorization header ... is required");
if (!validateToken(userToken)) throw new Error("Invalid or expired token");
const userInfo = extractUserFromToken(userToken);

The exported functions are pure and dependency-free, so they can be tested
directly with no mocking or network access.

Proposed cases

extractBearerToken

• returns the token from a well-formed Bearer <token> header
• accepts any casing of the scheme (bearer, BEARER)
• returns undefined for a missing header, a non-Bearer scheme, and a
  Bearer header with no token

extractUserFromToken

• maps the backend claim names (userId, sub, email, role, set in
  JwtAuth.jwtClaims) onto UserInfo
• applies the empty-email and REGULAR-role fallbacks when those claims are
  absent
• throws on a token that is not three segments, and on a non-JSON payload

validateToken

• accepts an exp in the future, rejects one in the past
• rejects a malformed token
• pins current behaviour for a token carrying no exp claim (see question
  below)

Open question

validateToken only checks expiry — it never verifies the signature, and
isTokenExpired (auth-api.ts:49) treats a token with no exp claim as
never expiring. Both look intentional, since the Scala backend verifies the
signature properly and JwtAuth.jwtClaims always sets an expiry. I plan to
write the tests against current behaviour and flag it here rather than change
anything. Happy to be corrected if either is actually a gap.

Notes

Tests run with bun test from agent-service/, following the existing style
in src/agent/util/context-utils.spec.ts. No production code changes.

Task Type

• Refactor / Cleanup
• DevOps / Deployment / CI
• Testing / QA
• Documentation
• Performance
• Other

[gupta-sahil01]

/take

[gupta-sahil01]

I want some thoughts on this before I open a PR. @xuang7 ?

[xuang7]

Thanks for the careful write-up. You’re right that this is a real gap and not the intended long-term behavior.

There is an ongoing effort in #5558 that reworks auth-api.ts to delegate validateToken and extractUserFromToken to a new verifyToken function in config/jwt.ts. This should address both the signature-less validation and the current behavior where tokens without an exp field never expire.

To avoid unnecessary churn, please scope this test with the new implementation in mind. Alternatively, you could wait for #5558 to land.