feat: jwt client

[zhengzheng-jason]

Problem

After refactoring RefX auth model from a static API key to dynamic JWT token, we need to implement this JWT signing logic in SDK so less effort needed at the caller side.

Closes REFX-590

Solution

Reference: https://buildwithfern.com/learn/sdks/generators/typescript/dynamic-authentication

By referencing Fern documentation, this PR extended the default client to implement a ReferralExchangeJwtClient with customised fetcher. The customised fetcher can help sign a JWT token and then utilised the default fetcher to finish up the call. This extended client uses jwtwebtoken to sign the JWT hence added this new dependency.

why do we need a src/browser/jsonwebtoken-stub.ts

jsonwebtoken uses Node-only crypto module and can fail yarn & yarn test because it checks browser compatibility, as by design(Fern) the SDK should be able to be used in web env as well. However, this JWT client should only be used in server hence added a stub so browser bundles stay lean and predictable. The stub throws a descriptive error at runtime to make it clear the JWT client isn’t meant for browsers, while Node builds continue to use the real library.

why add .fernignore

To avoid the extended client being overridden by auto generation

Tests

Published an alpha version in NPM and tested the SDK in HAS locally. Tested the new client calls RefX successfully. In RefX server we can see it passed the new auth guard.

Deploy Notes

NA

[linear]

REFX-590 Implement JWT signing logic in SDK

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​types/​jsonwebtoken@​9.0.10
	@​types/​readable-stream@​4.0.22 ⏵ 4.0.18
	readable-stream@​4.7.0 ⏵ 4.6.0	+1			-1
	ts-loader@​9.5.4 ⏵ 9.5.1	+1			-1
	jsonwebtoken@​9.0.2
	webpack@​5.102.1 ⏵ 5.97.1	+1
	ts-jest@​29.4.5 ⏵ 29.1.1	+1			+2

View full report

[EYLeong]

if we ignore index.ts does this mean in the future if we for e.g. create a new error type it won't automatically be included by fern?

[zhengzheng-jason]

good point lemme discuss with Fern side

[zhengzheng-jason]

confirmed with Fern that src/index.ts won't be touched by codegen. I changed to use wildcard for error types.

[EYLeong]

nit: can turn this into a constant, maybe TOKEN_CACHE_BUFFER_SECONDS or something

Wonder if the performance benefit is worth the possibility of returning expired tokens. When we call SmartCMS now we don't cache the JWTs im pretty sure. ofc we call them less often than for eg HAS calls RefX

[zhengzheng-jason]

The current implementation signs a new token if the last token valid time is less than 1s, hence the client itself should not return expired token. However, this means the returned token TTL can vary from 1s ~ 15s. In case of the network, if the request spend more than 1s reaching RefX server, the token with 1s TTL might be expired.
To mitigate that, we might change the refresh buffer to be 5s, meaning returned token TTL can vary from 5s - 15s, giving more buffer to tolerate bad network.
Lemme know your thoughts!

[EYLeong]

Yeah I was worried about 1s of network latency. 5s is safer for sure, but at some point I started wondering what the sweet spot is or if we should even do this optimisation HAHAH. But yeah honestly I don’t think network is likely to take 5s

[zhengzheng-jason]

got it yeah I double checked data dog and HAS -> RefX is roughly <100 request per min, i.e. <1.6 QPS. Even with Bright it's still very small scale hence performance impact should be very minor.
I will make the cached token configurable so we can start with no cache and fine tune it if we really hit a certain scale in NRP.