feat: jwt sub

Author: zhengzheng-jason

src/wrapper/ReferralExchangeJwtClient.ts

@@ -10,6 +10,7 @@ export declare namespace ReferralExchangeJwtClient {
     export interface Options extends Omit<ReferralExchangeClient.Options, "fetcher" | "apiKey"> {
         privateKey: string;
         apiKeyName: string;
+        subject?: string;
         tokenCache?: TokenCacheOptions;
     }
 
@@ -20,8 +21,8 @@ export declare namespace ReferralExchangeJwtClient {
 
 export class ReferralExchangeJwtClient extends ReferralExchangeClient {
     constructor(options: ReferralExchangeJwtClient.Options) {
-        const { privateKey, apiKeyName, tokenCache, ...baseOptions } = options;
-        const signer = new JwtSigner({ privateKey, issuer: apiKeyName, tokenCache });
+        const { privateKey, apiKeyName, subject, tokenCache, ...baseOptions } = options;
+        const signer = new JwtSigner({ privateKey, issuer: apiKeyName, subject, tokenCache });
         const fetcher = createJwtFetcher(signer);
         super({
             ...baseOptions,
@@ -33,19 +34,22 @@ export class ReferralExchangeJwtClient extends ReferralExchangeClient {
 interface JwtSignerConfig {
     privateKey: string;
     issuer: string;
+    subject?: string;
     tokenCache?: ReferralExchangeJwtClient.TokenCacheOptions;
 }
 
 class JwtSigner {
     private readonly privateKey: string;
     private readonly issuer: string;
+    private readonly subject?: string;
     private readonly cacheEnabled: boolean;
     private readonly refreshBufferSeconds: number;
     private cachedToken: { token: string; expiresAtEpochSeconds: number } | undefined;
 
-    constructor({ privateKey, issuer, tokenCache }: JwtSignerConfig) {
+    constructor({ privateKey, issuer, subject, tokenCache }: JwtSignerConfig) {
         this.privateKey = privateKey;
         this.issuer = issuer;
+        this.subject = subject;
         const cacheEnabled = tokenCache != null;
         this.cacheEnabled = cacheEnabled;
         this.refreshBufferSeconds = cacheEnabled ? clampRefreshBufferSeconds(tokenCache.refreshBufferSeconds) : 0;
@@ -73,6 +77,7 @@ class JwtSigner {
         return createSignedJwt({
             privateKey: this.privateKey,
             issuer: this.issuer,
+            subject: this.subject,
         });
     }
 }
@@ -93,9 +98,10 @@ function createJwtFetcher(signer: JwtSigner): FetchFunction {
 interface CreateSignedJwtArgs {
     privateKey: string;
     issuer: string;
+    subject?: string;
 }
 
-function createSignedJwt({ privateKey, issuer }: CreateSignedJwtArgs): {
+function createSignedJwt({ privateKey, issuer, subject }: CreateSignedJwtArgs): {
     token: string;
     expiresAtEpochSeconds: number;
 } {
@@ -109,6 +115,7 @@ function createSignedJwt({ privateKey, issuer }: CreateSignedJwtArgs): {
             algorithm: "ES256",
             issuer,
             expiresIn: JWT_TTL_SECONDS,
+            subject,
         },
     );
 

tests/unit/wrapper/ReferralExchangeJwtClient.test.ts

@@ -57,6 +57,29 @@ describe("ReferralExchangeJwtClient", () => {
         );
     });
 
+    it("includes subject claim when provided", async () => {
+        signMock.mockReturnValue("token-1");
+
+        const client = new ReferralExchangeJwtClient({
+            privateKey: "fake-private-key",
+            apiKeyName: "issuer",
+            subject: "user-123",
+        });
+
+        const fetcher = ((client as any)._options.fetcher) as (args: typeof requestArgs) => Promise<unknown>;
+
+        await fetcher(requestArgs);
+
+        expect(signMock).toHaveBeenCalledWith(
+            {},
+            "fake-private-key",
+            expect.objectContaining({
+                issuer: "issuer",
+                subject: "user-123",
+            }),
+        );
+    });
+
     it("reuses cached tokens until the refresh buffer elapses", async () => {
         signMock.mockReturnValueOnce("token-1").mockReturnValueOnce("token-2");