feat: jwt sub (#6)

* feat: jwt sub

* chore: dev version for testing

* fix: only add sub when provide

* chore: test dev version

Author: zhengzheng-jason

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@opengovsg/refx-ts-sdk",
-    "version": "0.0.0-develop-alpha-1763450943",
+    "version": "0.0.0-develop-alpha-1763535866",
     "private": false,
     "repository": "https://github.com/opengovsg/refer-ts-sdk",
     "main": "./index.js",

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,24 +98,27 @@ 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;
 } {
     const issuedAt = Math.floor(Date.now() / 1000);
     const expiresAtEpochSeconds = issuedAt + JWT_TTL_SECONDS;
+    const signOptions: jwt.SignOptions = {
+        algorithm: "ES256",
+        issuer,
+        expiresIn: JWT_TTL_SECONDS,
+    };
+
+    // Only add the claim if a value is provided(not null or undefined) 
+    if (subject != null) {
+        signOptions.subject = subject;
+    }
 
-    const token = jwt.sign(
-        {},
-        privateKey,
-        {
-            algorithm: "ES256",
-            issuer,
-            expiresIn: JWT_TTL_SECONDS,
-        },
-    );
+    const token = jwt.sign({}, privateKey, signOptions);
 
     return {
         token,

tests/unit/wrapper/ReferralExchangeJwtClient.test.ts

@@ -57,6 +57,51 @@ describe("ReferralExchangeJwtClient", () => {
         );
     });
 
+    it("omits subject claim when not provided", async () => {
+        signMock.mockReturnValue("token-1");
+
+        const client = new ReferralExchangeJwtClient({
+            privateKey: "fake-private-key",
+            apiKeyName: "issuer",
+        });
+
+        const fetcher = ((client as any)._options.fetcher) as (args: typeof requestArgs) => Promise<unknown>;
+
+        await fetcher(requestArgs);
+
+        const [, , options] = signMock.mock.calls[0];
+        expect(options).toEqual(
+            expect.objectContaining({
+                issuer: "issuer",
+                algorithm: "ES256",
+            }),
+        );
+        expect(options).not.toHaveProperty("subject");
+    });
+
+    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");