fhirstarterjs 1.0.2 → 1.0.3

package/dist/fhirstarter.js

@@ -1,4 +1,4 @@
-import { importPKCS8, exportJWK, SignJWT } from "jose";
+import { importPKCS8, exportJWK, SignJWT, } from "jose";
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 /**
@@ -25,7 +25,8 @@ export default class FHIRStarter {
     constructor(config) {
         if (!config.clientId)
             throw new Error("AuthConfig: clientId is required");
-        if (!config.privateKey || (Buffer.isBuffer(config.privateKey) && config.privateKey.length === 0))
+        if (!config.privateKey ||
+            (Buffer.isBuffer(config.privateKey) && config.privateKey.length === 0))
             throw new Error("AuthConfig: privateKey is required");
         if (!config.tokenEndpointUrl)
             throw new Error("AuthConfig: tokenEndpointUrl is required");
@@ -44,14 +45,14 @@ export default class FHIRStarter {
     // --- Sync getters ---
     /** The current access token, or `null` if no valid token is cached. */
     get token() {
-        return this.cache && Date.now() < this.cache.expiresAt
-            ? this.cache.accessToken
+        return this.cache && Date.now() < this.cache.expiresAt ?
+            this.cache.accessToken
             : null;
     }
     /** Seconds until the cached token expires, or `null` if no valid token is cached. */
     get expiresIn() {
-        return this.cache && Date.now() < this.cache.expiresAt
-            ? Math.ceil((this.cache.expiresAt - Date.now()) / 1000)
+        return this.cache && Date.now() < this.cache.expiresAt ?
+            Math.ceil((this.cache.expiresAt - Date.now()) / 1000)
             : null;
     }
     /** Ready-to-use `Authorization` header value (e.g. `"Bearer <token>"`), or `null` if no valid token is cached. */
@@ -101,8 +102,12 @@ export default class FHIRStarter {
         const auth = this;
         return {
             token_type: "bearer",
-            get access_token() { return auth.token ?? undefined; },
-            get expires_in() { return auth.expiresIn ?? undefined; },
+            get access_token() {
+                return auth.token ?? undefined;
+            },
+            get expires_in() {
+                return auth.expiresIn ?? undefined;
+            },
         };
     };
     /**
@@ -118,7 +123,9 @@ export default class FHIRStarter {
             try {
                 callback(current);
             }
-            catch { /* ignore */ }
+            catch {
+                /* ignore */
+            }
         return () => this.refreshCallbacks.delete(callback);
     };
     // --- Public async ---
@@ -129,8 +136,13 @@ export default class FHIRStarter {
     getJwks = async () => {
         const { keyId } = this.config, privateKey = await this.getPrivateKey(), jwk = await exportJWK(privateKey);
         // Public key only — strip private components
-        delete jwk.d, delete jwk.p, delete jwk.q, delete jwk.dp, delete jwk.dq, delete jwk.qi;
-        jwk.alg = "RS384", jwk.use = "sig";
+        (delete jwk.d,
+            delete jwk.p,
+            delete jwk.q,
+            delete jwk.dp,
+            delete jwk.dq,
+            delete jwk.qi);
+        ((jwk.alg = "RS384"), (jwk.use = "sig"));
         if (keyId)
             jwk.kid = keyId;
         return { keys: [jwk] };
@@ -179,8 +191,8 @@ export default class FHIRStarter {
             return;
         if (this.refreshTimer)
             clearTimeout(this.refreshTimer);
-        const delay = !this.cache || this.refreshFailed
-            ? this.refreshRetryMs
+        const delay = !this.cache || this.refreshFailed ?
+            this.refreshRetryMs
             : Math.max(1_000, this.cache.refreshAt - Date.now());
         this.refreshTimer = setTimeout(async () => {
             try {
@@ -230,14 +242,20 @@ export default class FHIRStarter {
             throw new Error("Token response missing access_token");
         if (typeof data.expires_in !== "number" || data.expires_in <= 0)
             throw new Error("Token response has invalid expires_in");
-        const ttlMs = data.expires_in * 1000, bufferMs = Math.min(60_000, ttlMs / 2), now = Date.now(), expiresAt = now + ttlMs, refreshAt = expiresAt - bufferMs, cache = { accessToken: data.access_token, refreshAt, expiresAt };
+        const ttlMs = data.expires_in * 1000, bufferMs = Math.min(60_000, ttlMs / 2), now = Date.now(), expiresAt = now + ttlMs, refreshAt = expiresAt - bufferMs, cache = {
+            accessToken: data.access_token,
+            refreshAt,
+            expiresAt,
+        };
         this.cache = cache;
         this.notifyRefresh(cache.accessToken);
         return cache;
     };
     getPrivateKey = async () => {
         if (!this.privateKeyObj)
-            this.privateKeyObj = await importPKCS8(this.privateKeyText, "RS384");
+            this.privateKeyObj = await importPKCS8(this.privateKeyText, "RS384", {
+                extractable: true,
+            });
         return this.privateKeyObj;
     };
     buildJwt = async () => {
@@ -260,7 +278,9 @@ export default class FHIRStarter {
     };
     // --- Static helpers ---
     static normalizeScopes(scopes) {
-        return Array.isArray(scopes) ? scopes.filter(Boolean) : scopes.split(/\s+/).filter(Boolean);
+        return Array.isArray(scopes) ?
+            scopes.filter(Boolean)
+            : scopes.split(/\s+/).filter(Boolean);
     }
     static resolvePrivateKey(privateKey) {
         if (Buffer.isBuffer(privateKey))

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "fhirstarterjs",
-   "version": "1.0.2",
+   "version": "1.0.3",
    "description": "SMART Backend Services auth lifecycle for any FHIR client",
    "type": "module",
    "main": "./dist/fhirstarter.js",
@@ -11,7 +11,13 @@
          "import": "./dist/fhirstarter.js"
       }
    },
-   "files": ["dist", "ts", "types", "README.md", "LICENSE.md"],
+   "files": [
+      "dist",
+      "ts",
+      "types",
+      "README.md",
+      "LICENSE.md"
+   ],
    "engines": {
       "node": ">=20"
    },
@@ -29,4 +35,4 @@
       "@types/node": "^25.9.2",
       "typescript": "^6.0.3"
    }
-}
+}

package/ts/fhirstarter.ts

@@ -1,6 +1,11 @@
-import { importPKCS8, exportJWK, SignJWT, type JWTHeaderParameters } from "jose"
-import { randomUUID } from "node:crypto"
-import { readFileSync } from "node:fs"
+import {
+   importPKCS8,
+   exportJWK,
+   SignJWT,
+   type JWTHeaderParameters,
+} from "jose";
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
 
 /**
  * SMART Backend Services auth provider.
@@ -9,60 +14,67 @@ import { readFileSync } from "node:fs"
  * using a private RSA key and the JWT Bearer client-assertion flow (RFC 7523).
  */
 export default class FHIRStarter implements Provider {
-   private readonly config: AuthConfig
-   private readonly privateKeyText: string
-   private readonly refreshCallbacks: Set<RefreshCallback> = new Set()
-   private cache: TokenCache | null = null
-   private refreshPromise: Promise<string> | null = null
-   private refreshTimer: ReturnType<typeof setTimeout> | null = null
-   private privateKeyObj: Awaited<ReturnType<typeof importPKCS8>> | null = null
-   private started = false
-   private refreshFailed = false
-   private refreshRetryMs = 5_000
+   private readonly config: AuthConfig;
+   private readonly privateKeyText: string;
+   private readonly refreshCallbacks: Set<RefreshCallback> = new Set();
+   private cache: TokenCache | null = null;
+   private refreshPromise: Promise<string> | null = null;
+   private refreshTimer: ReturnType<typeof setTimeout> | null = null;
+   private privateKeyObj: Awaited<ReturnType<typeof importPKCS8>> | null = null;
+   private started = false;
+   private refreshFailed = false;
+   private refreshRetryMs = 5_000;
 
    /**
     * @param config - Auth configuration including client ID, private key, token endpoint, and scopes.
     * @throws If any required field is missing, blank, or invalid.
     */
    constructor(config: AuthConfig) {
-      if (!config.clientId) throw new Error("AuthConfig: clientId is required")
-      if (!config.privateKey || (Buffer.isBuffer(config.privateKey) && config.privateKey.length === 0))
-         throw new Error("AuthConfig: privateKey is required")
-      if (!config.tokenEndpointUrl) throw new Error("AuthConfig: tokenEndpointUrl is required")
-
-      const scopes = FHIRStarter.normalizeScopes(config.scopes)
-      if (scopes.length === 0) throw new Error("AuthConfig: at least one scope is required")
+      if (!config.clientId) throw new Error("AuthConfig: clientId is required");
+      if (
+         !config.privateKey ||
+         (Buffer.isBuffer(config.privateKey) && config.privateKey.length === 0)
+      )
+         throw new Error("AuthConfig: privateKey is required");
+      if (!config.tokenEndpointUrl)
+         throw new Error("AuthConfig: tokenEndpointUrl is required");
+
+      const scopes = FHIRStarter.normalizeScopes(config.scopes);
+      if (scopes.length === 0)
+         throw new Error("AuthConfig: at least one scope is required");
 
       try {
-         new URL(config.tokenEndpointUrl)
+         new URL(config.tokenEndpointUrl);
       } catch {
-         throw new Error(`AuthConfig: tokenEndpointUrl is not a valid URL: ${config.tokenEndpointUrl}`)
+         throw new Error(
+            `AuthConfig: tokenEndpointUrl is not a valid URL: ${config.tokenEndpointUrl}`,
+         );
       }
 
-      this.config = config
-      this.privateKeyText = FHIRStarter.resolvePrivateKey(config.privateKey)
+      this.config = config;
+      this.privateKeyText = FHIRStarter.resolvePrivateKey(config.privateKey);
    }
 
    // --- Sync getters ---
 
    /** The current access token, or `null` if no valid token is cached. */
    get token(): string | null {
-      return this.cache && Date.now() < this.cache.expiresAt
-         ? this.cache.accessToken
-         : null
+      return this.cache && Date.now() < this.cache.expiresAt ?
+            this.cache.accessToken
+         :  null;
    }
 
    /** Seconds until the cached token expires, or `null` if no valid token is cached. */
    get expiresIn(): number | null {
-      return this.cache && Date.now() < this.cache.expiresAt
-         ? Math.ceil((this.cache.expiresAt - Date.now()) / 1000)
-         : null
+      return this.cache && Date.now() < this.cache.expiresAt ?
+            Math.ceil((this.cache.expiresAt - Date.now()) / 1000)
+         :  null;
    }
 
    /** Ready-to-use `Authorization` header value (e.g. `"Bearer <token>"`), or `null` if no valid token is cached. */
    get authorizationHeader(): string | null {
-      const token = this.token
-      return token ? `Bearer ${token}` : null
+      const token = this.token;
+      return token ? `Bearer ${token}` : null;
    }
 
    // --- Lifecycle ---
@@ -73,30 +85,30 @@ export default class FHIRStarter implements Provider {
     * @throws If the initial token acquisition fails.
     */
    start = async (): Promise<void> => {
-      if (this.started) return
-      this.started = true
-      this.refreshRetryMs = 5_000
-      this.refreshFailed = false
+      if (this.started) return;
+      this.started = true;
+      this.refreshRetryMs = 5_000;
+      this.refreshFailed = false;
       try {
-         await this.getAccessToken()
+         await this.getAccessToken();
       } catch (err) {
-         this.started = false
-         throw err
+         this.started = false;
+         throw err;
       }
-      this.scheduleRefresh()
-   }
+      this.scheduleRefresh();
+   };
 
    /**
     * Stops the background refresh timer.
     * Any in-flight refresh will still complete, but no new timers will be scheduled.
     */
    stop = (): void => {
-      this.started = false
+      this.started = false;
       if (this.refreshTimer) {
-         clearTimeout(this.refreshTimer)
-         this.refreshTimer = null
+         clearTimeout(this.refreshTimer);
+         this.refreshTimer = null;
       }
-   }
+   };
 
    // --- Token adapters ---
 
@@ -106,13 +118,17 @@ export default class FHIRStarter implements Provider {
     * Useful for libraries that hold a reference to a token response object.
     */
    tokenResponse = (): LiveTokenResponse => {
-      const auth = this
+      const auth = this;
       return {
          token_type: "bearer",
-         get access_token() { return auth.token ?? undefined },
-         get expires_in() { return auth.expiresIn ?? undefined },
-      }
-   }
+         get access_token() {
+            return auth.token ?? undefined;
+         },
+         get expires_in() {
+            return auth.expiresIn ?? undefined;
+         },
+      };
+   };
 
    /**
     * Registers a callback that is invoked whenever a new access token is obtained.
@@ -121,11 +137,16 @@ export default class FHIRStarter implements Provider {
     * @returns An unsubscribe function; call it to stop receiving updates.
     */
    onRefresh = (callback: RefreshCallback): (() => void) => {
-      this.refreshCallbacks.add(callback)
-      const current = this.token
-      if (current) try { callback(current) } catch { /* ignore */ }
-      return () => this.refreshCallbacks.delete(callback)
-   }
+      this.refreshCallbacks.add(callback);
+      const current = this.token;
+      if (current)
+         try {
+            callback(current);
+         } catch {
+            /* ignore */
+         }
+      return () => this.refreshCallbacks.delete(callback);
+   };
 
    // --- Public async ---
 
@@ -134,18 +155,22 @@ export default class FHIRStarter implements Provider {
     * Private key material (`d`, `p`, `q`, etc.) is stripped before returning.
     */
    getJwks = async (): Promise<JwkSet> => {
-      const
-         { keyId } = this.config,
+      const { keyId } = this.config,
          privateKey = await this.getPrivateKey(),
-         jwk = await exportJWK(privateKey)
+         jwk = await exportJWK(privateKey);
 
       // Public key only — strip private components
-      delete jwk.d, delete jwk.p, delete jwk.q, delete jwk.dp, delete jwk.dq, delete jwk.qi
-      jwk.alg = "RS384", jwk.use = "sig"
-      if (keyId) jwk.kid = keyId
-
-      return { keys: [jwk] }
-   }
+      (delete jwk.d,
+         delete jwk.p,
+         delete jwk.q,
+         delete jwk.dp,
+         delete jwk.dq,
+         delete jwk.qi);
+      ((jwk.alg = "RS384"), (jwk.use = "sig"));
+      if (keyId) jwk.kid = keyId;
+
+      return { keys: [jwk] };
+   };
 
    /**
     * Returns a valid access token, refreshing if the cached token is at or past its refresh threshold.
@@ -153,74 +178,77 @@ export default class FHIRStarter implements Provider {
     * @throws If no cached token is available and the refresh request fails.
     */
    getAccessToken = async (): Promise<string> => {
-      if (this.cache && Date.now() < this.cache.refreshAt) return this.cache.accessToken
-      const staleCache = this.cache
+      if (this.cache && Date.now() < this.cache.refreshAt)
+         return this.cache.accessToken;
+      const staleCache = this.cache;
       try {
-         return await this.doRefresh()
+         return await this.doRefresh();
       } catch (err) {
          // Graceful degradation: if the token is not actually expired yet, return it
-         if (staleCache && Date.now() < staleCache.expiresAt) return staleCache.accessToken
-         throw err
+         if (staleCache && Date.now() < staleCache.expiresAt)
+            return staleCache.accessToken;
+         throw err;
       }
-   }
+   };
 
    // --- Private ---
 
    // Single-flight refresh — shared by getAccessToken and the proactive timer
    private doRefresh = (): Promise<string> => {
-      if (this.refreshPromise) return this.refreshPromise
+      if (this.refreshPromise) return this.refreshPromise;
       this.refreshPromise = this.refreshAccessToken()
          .then((cache) => {
-            this.refreshPromise = null
-            this.refreshFailed = false
-            this.refreshRetryMs = 5_000
-            if (this.started) this.scheduleRefresh()
-            return cache.accessToken
+            this.refreshPromise = null;
+            this.refreshFailed = false;
+            this.refreshRetryMs = 5_000;
+            if (this.started) this.scheduleRefresh();
+            return cache.accessToken;
          })
          .catch((err) => {
-            this.refreshPromise = null
-            throw err
-         })
-      return this.refreshPromise
-   }
+            this.refreshPromise = null;
+            throw err;
+         });
+      return this.refreshPromise;
+   };
 
    private scheduleRefresh = (): void => {
-      if (!this.started) return
-      if (this.refreshTimer) clearTimeout(this.refreshTimer)
+      if (!this.started) return;
+      if (this.refreshTimer) clearTimeout(this.refreshTimer);
 
-      const delay = !this.cache || this.refreshFailed
-         ? this.refreshRetryMs
-         : Math.max(1_000, this.cache.refreshAt - Date.now())
+      const delay =
+         !this.cache || this.refreshFailed ?
+            this.refreshRetryMs
+         :  Math.max(1_000, this.cache.refreshAt - Date.now());
 
       this.refreshTimer = setTimeout(async () => {
          try {
-            await this.doRefresh()
+            await this.doRefresh();
          } catch {
-            this.refreshFailed = true
-            this.refreshRetryMs = Math.min(this.refreshRetryMs * 2, 60_000)
-            this.scheduleRefresh()
+            this.refreshFailed = true;
+            this.refreshRetryMs = Math.min(this.refreshRetryMs * 2, 60_000);
+            this.scheduleRefresh();
          }
-      }, delay)
+      }, delay);
 
-      this.refreshTimer.unref?.()
-   }
+      this.refreshTimer.unref?.();
+   };
 
    private notifyRefresh = (token: string): void => {
       for (const callback of this.refreshCallbacks)
          try {
-            callback(token)
+            callback(token);
          } catch {
             // Ignore callback failures; auth lifecycle must continue.
          }
-   }
+   };
 
    private refreshAccessToken = async (): Promise<TokenCache> => {
-      const
-         jwt = await this.buildJwt(),
+      const jwt = await this.buildJwt(),
          scopes = FHIRStarter.normalizeScopes(this.config.scopes),
          body = new URLSearchParams({
             grant_type: "client_credentials",
-            client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+            client_assertion_type:
+               "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
             client_assertion: jwt,
             scope: scopes.join(" "),
          }),
@@ -229,48 +257,57 @@ export default class FHIRStarter implements Provider {
             headers: { "Content-Type": "application/x-www-form-urlencoded" },
             body,
             signal: AbortSignal.timeout(30_000),
-         })
+         });
 
       if (!res.ok) {
-         const text = await res.text().catch(() => "(no body)")
-         throw new Error(`Token request failed (${res.status}): ${text}`)
+         const text = await res.text().catch(() => "(no body)");
+         throw new Error(`Token request failed (${res.status}): ${text}`);
       }
 
-      let data: TokenResponse
-      try { data = await res.json() }
-      catch { throw new Error("Token response is not valid JSON") }
+      let data: TokenResponse;
+      try {
+         data = await res.json();
+      } catch {
+         throw new Error("Token response is not valid JSON");
+      }
 
       if (!data.access_token || typeof data.access_token !== "string")
-         throw new Error("Token response missing access_token")
+         throw new Error("Token response missing access_token");
       if (typeof data.expires_in !== "number" || data.expires_in <= 0)
-         throw new Error("Token response has invalid expires_in")
+         throw new Error("Token response has invalid expires_in");
 
-      const
-         ttlMs = data.expires_in * 1000,
+      const ttlMs = data.expires_in * 1000,
          bufferMs = Math.min(60_000, ttlMs / 2),
          now = Date.now(),
          expiresAt = now + ttlMs,
          refreshAt = expiresAt - bufferMs,
-         cache: TokenCache = { accessToken: data.access_token, refreshAt, expiresAt }
-
-      this.cache = cache
-      this.notifyRefresh(cache.accessToken)
-      return cache
-   }
-
-   private getPrivateKey = async (): Promise<Awaited<ReturnType<typeof importPKCS8>>> => {
+         cache: TokenCache = {
+            accessToken: data.access_token,
+            refreshAt,
+            expiresAt,
+         };
+
+      this.cache = cache;
+      this.notifyRefresh(cache.accessToken);
+      return cache;
+   };
+
+   private getPrivateKey = async (): Promise<
+      Awaited<ReturnType<typeof importPKCS8>>
+   > => {
       if (!this.privateKeyObj)
-         this.privateKeyObj = await importPKCS8(this.privateKeyText, "RS384")
-      return this.privateKeyObj
-   }
+         this.privateKeyObj = await importPKCS8(this.privateKeyText, "RS384", {
+            extractable: true,
+         });
+      return this.privateKeyObj;
+   };
 
    private buildJwt = async (): Promise<string> => {
-      const
-         { clientId, tokenEndpointUrl, keyId, jwksUrl } = this.config,
+      const { clientId, tokenEndpointUrl, keyId, jwksUrl } = this.config,
          privateKey = await this.getPrivateKey(),
-         header: JWTHeaderParameters = { alg: "RS384", typ: "JWT" }
-      if (keyId) header.kid = keyId
-      if (jwksUrl) header.jku = jwksUrl
+         header: JWTHeaderParameters = { alg: "RS384", typ: "JWT" };
+      if (keyId) header.kid = keyId;
+      if (jwksUrl) header.jku = jwksUrl;
 
       return new SignJWT({
          iss: clientId,
@@ -282,25 +319,30 @@ export default class FHIRStarter implements Provider {
          .setIssuedAt()
          .setNotBefore("now")
          .setExpirationTime("5m")
-         .sign(privateKey)
-   }
+         .sign(privateKey);
+   };
 
    // --- Static helpers ---
 
    private static normalizeScopes(scopes: string | string[]): string[] {
-      return Array.isArray(scopes) ? scopes.filter(Boolean) : scopes.split(/\s+/).filter(Boolean)
+      return Array.isArray(scopes) ?
+            scopes.filter(Boolean)
+         :  scopes.split(/\s+/).filter(Boolean);
    }
 
    private static resolvePrivateKey(privateKey: string | Buffer): string {
-      if (Buffer.isBuffer(privateKey)) return privateKey.toString("utf-8").trim()
+      if (Buffer.isBuffer(privateKey))
+         return privateKey.toString("utf-8").trim();
 
-      const trimmed = privateKey.trim()
-      if (trimmed.includes("-----BEGIN")) return trimmed
+      const trimmed = privateKey.trim();
+      if (trimmed.includes("-----BEGIN")) return trimmed;
 
       try {
-         return readFileSync(trimmed, "utf-8").trim()
+         return readFileSync(trimmed, "utf-8").trim();
       } catch {
-         throw new Error(`AuthConfig: privateKey must be PEM text, a Buffer, or a readable file path: ${trimmed}`)
+         throw new Error(
+            `AuthConfig: privateKey must be PEM text, a Buffer, or a readable file path: ${trimmed}`,
+         );
       }
    }
 }