fhirstarterjs 1.0.6 → 1.0.8

package/README.md

@@ -81,9 +81,23 @@ const res = await fetch(url, {
 | `tokenResponse()` | `LiveTokenResponse` | Getter-backed token response for `fhirclient` |
 | `onRefresh(callback)` | `() => void` | Subscribe to token updates — returns unsubscribe |
 | `getJwks()` | `Promise<JwkSet>` | Public JWKS derived from the private key |
+| `fhirStarter.thumbprint(privateKey)` | `string` | RFC 7638 JWK Thumbprint (base64url SHA-256) |
 
 `getJwks()` strips private key material — host the output JSON at your registered JWKS URL and pass that URL as `jwksUrl` so the JWT `jku` header is set automatically.
 
+## Thumbprint
+
+Derive a deterministic `kid` from a private key without instantiating the class:
+
+```ts
+import fhirStarter from "fhirstarterjs"
+
+const kid = fhirStarter.thumbprint("./privatekey.pem")
+console.log(kid) // base64url SHA-256 of the canonical RSA public JWK
+```
+
+This implements RFC 7638 — the SHA-256 of the sorted canonical JWK members `{e, kty, n}`, base64url-encoded. Use it as the `keyId` when registering your JWKS.
+
 ## JWKS
 
 Some SMART Backend Services registrations require a public JWKS URL when using `jku`. Generate it from the same private key you use for auth:

package/dist/fhirstarter.js

@@ -1,5 +1,5 @@
 import { importPKCS8, exportJWK, SignJWT, } from "jose";
-import { randomUUID } from "node:crypto";
+import { createHash, createPrivateKey, createPublicKey, randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 /**
  * SMART Backend Services auth provider.
@@ -117,7 +117,7 @@ export default class fhirStarter {
      * Registers a callback that is invoked whenever a new access token is obtained.
      * The callback is called immediately with the current token if one is already cached.
      * @param callback - Receives the new access token string.
-     * @returns An unsubscribe function; call it to stop receiving updates.
+     * @returns An unsubscribe function call it to stop receiving updates.
      */
     onRefresh = (callback) => {
         this.refreshCallbacks.add(callback);
@@ -138,14 +138,14 @@ 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] };
@@ -215,7 +215,7 @@ export default class fhirStarter {
                 callback(token);
             }
             catch {
-                // Ignore callback failures; auth lifecycle must continue.
+                // Ignore callback failures auth lifecycle must continue.
             }
     };
     refreshAccessToken = async () => {
@@ -298,4 +298,19 @@ export default class fhirStarter {
             throw new Error(`AuthConfig: privateKey must be PEM text, a Buffer, or a readable file path: ${trimmed}`);
         }
     }
+    /**
+     * Derives a deterministic key identifier from a private key using an
+     * RFC 7638 JWK Thumbprint (SHA-256 of canonical RSA public JWK members, base64url).
+     *
+     * @param privateKey - RSA PKCS#8 PEM text, a Buffer, or a readable file path.
+     * @returns A base64url-encoded SHA-256 thumbprint string.
+     * @throws If the key is not RSA or cannot be parsed.
+     */
+    static thumbprint(privateKey) {
+        const pem = fhirStarter.resolvePrivateKey(privateKey), key = createPrivateKey(pem);
+        if (key.asymmetricKeyType !== "rsa")
+            throw new Error(`thumbprint: expected RSA key, got ${key.asymmetricKeyType}`);
+        const pub = createPublicKey(key).export({ format: "jwk" }), canonical = JSON.stringify({ e: pub.e, kty: "RSA", n: pub.n });
+        return createHash("sha256").update(canonical).digest("base64url");
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "fhirstarterjs",
-   "version": "1.0.6",
+   "version": "1.0.8",
    "description": "SMART Backend Services auth lifecycle for any FHIR client",
    "author": "Joshua Faulkenberry <j@joshuafaulkenberry.com> (https://joshuafaulkenberry.com/)",
    "license": "Kopimi",
@@ -56,7 +56,7 @@
       "jose": "^6.2.3"
    },
    "devDependencies": {
-      "@types/node": "^25.9.3",
+      "@types/node": "^26.0.1",
       "typescript": "^6.0.3"
    }
 }

package/ts/fhirstarter.ts

@@ -3,9 +3,10 @@ import {
    exportJWK,
    SignJWT,
    type JWTHeaderParameters,
-} from "jose";
-import { randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
+} from "jose"
+import { createHash, createPrivateKey, createPublicKey, randomUUID } from "node:crypto"
+import { readFileSync } from "node:fs"
+import type { PublicKeyInput } from "node:crypto"
 
 /**
  * SMART Backend Services auth provider.
@@ -14,45 +15,45 @@ 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.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");
+         throw new Error("AuthConfig: privateKey is required")
       if (!config.tokenEndpointUrl)
-         throw new Error("AuthConfig: tokenEndpointUrl is required");
+         throw new Error("AuthConfig: tokenEndpointUrl is required")
 
-      const scopes = fhirStarter.normalizeScopes(config.scopes);
+      const scopes = fhirStarter.normalizeScopes(config.scopes)
       if (scopes.length === 0)
-         throw new Error("AuthConfig: at least one scope is required");
+         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}`,
-         );
+         )
       }
 
-      this.config = config;
-      this.privateKeyText = fhirStarter.resolvePrivateKey(config.privateKey);
+      this.config = config
+      this.privateKeyText = fhirStarter.resolvePrivateKey(config.privateKey)
    }
 
    // --- Sync getters ---
@@ -61,20 +62,20 @@ export default class fhirStarter implements Provider {
    get token(): string | null {
       return this.cache && Date.now() < this.cache.expiresAt ?
             this.cache.accessToken
-         :  null;
+         :  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;
+         :  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 ---
@@ -85,30 +86,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 ---
 
@@ -118,38 +119,38 @@ 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;
+            return auth.token ?? undefined
          },
          get expires_in() {
-            return auth.expiresIn ?? undefined;
+            return auth.expiresIn ?? undefined
          },
          get scope() {
-            return auth.cache?.scope;
+            return auth.cache?.scope
          },
-      };
-   };
+      }
+   }
 
    /**
     * Registers a callback that is invoked whenever a new access token is obtained.
     * The callback is called immediately with the current token if one is already cached.
     * @param callback - Receives the new access token string.
-    * @returns An unsubscribe function; call it to stop receiving updates.
+    * @returns An unsubscribe function call it to stop receiving updates.
     */
    onRefresh = (callback: RefreshCallback): (() => void) => {
-      this.refreshCallbacks.add(callback);
-      const current = this.token;
+      this.refreshCallbacks.add(callback)
+      const current = this.token
       if (current)
          try {
-            callback(current);
+            callback(current)
          } catch {
             /* ignore */
          }
-      return () => this.refreshCallbacks.delete(callback);
-   };
+      return () => this.refreshCallbacks.delete(callback)
+   }
 
    // --- Public async ---
 
@@ -160,20 +161,20 @@ export default class fhirStarter implements Provider {
    getJwks = async (): Promise<JwkSet> => {
       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"));
-      if (keyId) jwk.kid = keyId;
-
-      return { keys: [jwk] };
-   };
+         jwk = await exportJWK(privateKey)
+
+      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.
@@ -182,68 +183,68 @@ export default class fhirStarter implements Provider {
     */
    getAccessToken = async (): Promise<string> => {
       if (this.cache && Date.now() < this.cache.refreshAt)
-         return this.cache.accessToken;
-      const staleCache = this.cache;
+         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;
+            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());
+         :  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.
+            // Ignore callback failures auth lifecycle must continue.
          }
-   };
+   }
 
    private refreshAccessToken = async (): Promise<TokenCache> => {
       const jwt = await this.buildJwt(),
@@ -260,24 +261,24 @@ 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;
+      let data: TokenResponse
       try {
-         data = await res.json();
+         data = await res.json()
       } catch {
-         throw new Error("Token response is not valid JSON");
+         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,
          bufferMs = Math.min(60_000, ttlMs / 2),
@@ -289,12 +290,12 @@ export default class fhirStarter implements Provider {
             refreshAt,
             expiresAt,
             ...(typeof data.scope === "string" && { scope: data.scope }),
-         };
+         }
 
-      this.cache = cache;
-      this.notifyRefresh(cache.accessToken);
-      return cache;
-   };
+      this.cache = cache
+      this.notifyRefresh(cache.accessToken)
+      return cache
+   }
 
    private getPrivateKey = async (): Promise<
       Awaited<ReturnType<typeof importPKCS8>>
@@ -302,16 +303,16 @@ export default class fhirStarter implements Provider {
       if (!this.privateKeyObj)
          this.privateKeyObj = await importPKCS8(this.privateKeyText, "RS384", {
             extractable: true,
-         });
-      return this.privateKeyObj;
-   };
+         })
+      return this.privateKeyObj
+   }
 
    private buildJwt = async (): Promise<string> => {
       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,
@@ -322,30 +323,50 @@ export default class fhirStarter implements Provider {
          .setProtectedHeader(header)
          .setIssuedAt()
          .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);
+         :  scopes.split(/\s+/).filter(Boolean)
    }
 
    private static resolvePrivateKey(privateKey: string | Buffer): string {
       if (Buffer.isBuffer(privateKey))
-         return privateKey.toString("utf-8").trim();
+         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}`,
-         );
+         )
       }
    }
+
+   /**
+    * Derives a deterministic key identifier from a private key using an
+    * RFC 7638 JWK Thumbprint (SHA-256 of canonical RSA public JWK members, base64url).
+    *
+    * @param privateKey - RSA PKCS#8 PEM text, a Buffer, or a readable file path.
+    * @returns A base64url-encoded SHA-256 thumbprint string.
+    * @throws If the key is not RSA or cannot be parsed.
+    */
+   static thumbprint(privateKey: string | Buffer): string {
+      const
+         pem = fhirStarter.resolvePrivateKey(privateKey),
+         key = createPrivateKey(pem)
+      if (key.asymmetricKeyType !== "rsa")
+         throw new Error(`thumbprint: expected RSA key, got ${key.asymmetricKeyType}`)
+      const
+         pub = createPublicKey(key as unknown as PublicKeyInput).export({ format: "jwk" }) as { e?: string, n?: string, kty?: string },
+         canonical = JSON.stringify({ e: pub.e, kty: "RSA", n: pub.n })
+      return createHash("sha256").update(canonical).digest("base64url")
+   }
 }