fhirstarterjs 1.0.0

package/LICENSE.md

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -0,0 +1,128 @@
+# 🔥 fhirstarterjs
+
+SMART on FHIR Backend Services auth lifecycle for any FHIR client.
+
+## Install
+
+```sh
+npm install fhirstarterjs
+```
+
+## Usage
+
+This example uses the official `fhirclient` package as the FHIR client; `fhirstarterjs` only manages auth.
+
+```ts
+import FHIR from "fhirclient"
+import FHIRStarter from "fhirstarterjs"
+
+const auth = new FHIRStarter({
+   clientId: "your-client-id",
+   privateKey: "./privatekey.pem",
+   tokenEndpointUrl: "https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token",
+   scopes: ["system/Patient.rs", "system/Observation.rs"],
+})
+
+await auth.start()
+
+const client = FHIR.client({
+   serverUrl: "https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4",
+   tokenResponse: auth.tokenResponse(),
+})
+
+const bundle = await client.request("Patient?family=Smith")
+```
+
+`auth.start()` fetches the first token and starts the proactive refresh loop. `auth.tokenResponse()` returns a live getter-backed object — `fhirclient` reads `access_token` dynamically per request, so it always picks up the latest token.
+
+`fhirstarterjs` does not fetch FHIR resources and does not bundle a FHIR client. It manages the auth lifecycle; the FHIR client does the rest.
+
+`privateKey` can be PEM text, a `Buffer` from `readFileSync`, or a path to a PKCS#8 PEM file.
+
+## TypeScript types
+
+If needed, you can import the public types directly from the shipped type folder:
+
+```ts
+import type { AuthConfig, JwkSet, LiveTokenResponse, Provider } from "fhirstarterjs/types/api"
+```
+
+## Other FHIR clients
+
+For clients with a bearer token setter (e.g. `fhir-kit-client`):
+
+```ts
+const unsubscribe = auth.onRefresh((token) => {
+   client.bearerToken = token
+})
+```
+
+For raw `fetch` or any other HTTP client:
+
+```ts
+const token = await auth.getAccessToken()
+const res = await fetch(url, {
+   headers: { Authorization: `Bearer ${token}` },
+})
+```
+
+## API
+
+`new FHIRStarter(config)`
+
+| Member | Returns | Description |
+|---|---|---|
+| `start()` | `Promise<void>` | Fetch first token and begin proactive refresh loop |
+| `stop()` | `void` | Clear the refresh timer |
+| `token` | `string \| null` | Current valid token, or null if expired |
+| `expiresIn` | `number \| null` | Seconds until actual expiry, or null |
+| `authorizationHeader` | `string \| null` | `Bearer <token>` or null |
+| `getAccessToken()` | `Promise<string>` | Async valid token with lazy refresh |
+| `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 |
+
+`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.
+
+## 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:
+
+```ts
+import { writeFileSync } from "node:fs"
+import FHIRStarter from "fhirstarterjs"
+
+const auth = new FHIRStarter({
+   clientId: "your-client-id",
+   privateKey: "./privatekey.pem",
+   tokenEndpointUrl: "https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token",
+   scopes: ["system/Patient.rs"],
+   keyId: "my-key-id",
+   jwksUrl: "https://example.com/.well-known/jwks.json",
+})
+
+// No need to call auth.start() — getJwks() only needs the private key.
+const jwks = await auth.getJwks()
+writeFileSync("./jwks.json", JSON.stringify(jwks, null, 3))
+```
+
+Host `jwks.json` at the exact URL you register with your authorization server, then pass that URL as `jwksUrl`. If you set `keyId`, the generated key includes `kid`, and signed JWTs use the same `kid` header.
+
+## Compatibility
+
+`tokenResponse()` is designed for `fhirclient.request()`. If a client copies the token at construction time rather than reading it per-request, use `onRefresh()` to update or recreate that client instead. If `fhirclient` clears its internal state after a 401, recreate the client instance with `auth.tokenResponse()`.
+
+## Scripts
+
+| Command | What |
+|---|---|
+| `npm run check` | `tsc --noEmit` |
+| `npm run build` | Compile to `dist/` (JS only — no `.d.ts`) |
+
+## Notes
+
+- Call `auth.start()` to fetch the first token and begin the proactive refresh loop — call `auth.stop()` during shutdown in long-running processes
+- Tokens are cached with separate refresh and expiry timestamps — if a refresh fails but the token is not yet expired, the old token remains usable
+- Concurrent callers share a single in-flight token refresh
+- JWT assertions are signed RS384, expire after 5 minutes
+- Requires Node 20+, a PKCS#8 RSA key, and SMART Backend Services scopes

package/dist/fhirstarter.js

@@ -0,0 +1,278 @@
+import { importPKCS8, exportJWK, SignJWT } from "jose";
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+/**
+ * SMART Backend Services auth provider.
+ *
+ * Manages client-credentials token acquisition and proactive refresh
+ * using a private RSA key and the JWT Bearer client-assertion flow (RFC 7523).
+ */
+export default class FHIRStarter {
+    config;
+    privateKeyText;
+    refreshCallbacks = new Set();
+    cache = null;
+    refreshPromise = null;
+    refreshTimer = null;
+    privateKeyObj = null;
+    started = false;
+    refreshFailed = false;
+    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) {
+        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);
+        }
+        catch {
+            throw new Error(`AuthConfig: tokenEndpointUrl is not a valid URL: ${config.tokenEndpointUrl}`);
+        }
+        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() {
+        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)
+            : null;
+    }
+    /** Ready-to-use `Authorization` header value (e.g. `"Bearer <token>"`), or `null` if no valid token is cached. */
+    get authorizationHeader() {
+        const token = this.token;
+        return token ? `Bearer ${token}` : null;
+    }
+    // --- Lifecycle ---
+    /**
+     * Acquires an initial token and starts the proactive background refresh timer.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     * @throws If the initial token acquisition fails.
+     */
+    start = async () => {
+        if (this.started)
+            return;
+        this.started = true;
+        this.refreshRetryMs = 5_000;
+        this.refreshFailed = false;
+        try {
+            await this.getAccessToken();
+        }
+        catch (err) {
+            this.started = false;
+            throw err;
+        }
+        this.scheduleRefresh();
+    };
+    /**
+     * Stops the background refresh timer.
+     * Any in-flight refresh will still complete, but no new timers will be scheduled.
+     */
+    stop = () => {
+        this.started = false;
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    };
+    // --- Token adapters ---
+    /**
+     * Returns a live `LiveTokenResponse` object whose `access_token` and `expires_in`
+     * properties are always read from the current cache.
+     * Useful for libraries that hold a reference to a token response object.
+     */
+    tokenResponse = () => {
+        const auth = this;
+        return {
+            token_type: "bearer",
+            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.
+     * 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.
+     */
+    onRefresh = (callback) => {
+        this.refreshCallbacks.add(callback);
+        const current = this.token;
+        if (current)
+            try {
+                callback(current);
+            }
+            catch { /* ignore */ }
+        return () => this.refreshCallbacks.delete(callback);
+    };
+    // --- Public async ---
+    /**
+     * Returns the public JWKS derived from the configured private key.
+     * Private key material (`d`, `p`, `q`, etc.) is stripped before returning.
+     */
+    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";
+        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.
+     * Falls back to a not-yet-expired stale token if the refresh request fails.
+     * @throws If no cached token is available and the refresh request fails.
+     */
+    getAccessToken = async () => {
+        if (this.cache && Date.now() < this.cache.refreshAt)
+            return this.cache.accessToken;
+        const staleCache = this.cache;
+        try {
+            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;
+        }
+    };
+    // --- Private ---
+    // Single-flight refresh — shared by getAccessToken and the proactive timer
+    doRefresh = () => {
+        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;
+        })
+            .catch((err) => {
+            this.refreshPromise = null;
+            throw err;
+        });
+        return this.refreshPromise;
+    };
+    scheduleRefresh = () => {
+        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());
+        this.refreshTimer = setTimeout(async () => {
+            try {
+                await this.doRefresh();
+            }
+            catch {
+                this.refreshFailed = true;
+                this.refreshRetryMs = Math.min(this.refreshRetryMs * 2, 60_000);
+                this.scheduleRefresh();
+            }
+        }, delay);
+        this.refreshTimer.unref?.();
+    };
+    notifyRefresh = (token) => {
+        for (const callback of this.refreshCallbacks)
+            try {
+                callback(token);
+            }
+            catch {
+                // Ignore callback failures; auth lifecycle must continue.
+            }
+    };
+    refreshAccessToken = async () => {
+        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: jwt,
+            scope: scopes.join(" "),
+        }), res = await fetch(this.config.tokenEndpointUrl, {
+            method: "POST",
+            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}`);
+        }
+        let data;
+        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");
+        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 };
+        this.cache = cache;
+        this.notifyRefresh(cache.accessToken);
+        return cache;
+    };
+    getPrivateKey = async () => {
+        if (!this.privateKeyObj)
+            this.privateKeyObj = await importPKCS8(this.privateKeyText, "RS384");
+        return this.privateKeyObj;
+    };
+    buildJwt = async () => {
+        const { clientId, tokenEndpointUrl, keyId, jwksUrl } = this.config, privateKey = await this.getPrivateKey(), header = { alg: "RS384", typ: "JWT" };
+        if (keyId)
+            header.kid = keyId;
+        if (jwksUrl)
+            header.jku = jwksUrl;
+        return new SignJWT({
+            iss: clientId,
+            sub: clientId,
+            aud: tokenEndpointUrl,
+            jti: randomUUID(), // unique per RFC 7523 §3
+        })
+            .setProtectedHeader(header)
+            .setIssuedAt()
+            .setNotBefore("now")
+            .setExpirationTime("5m")
+            .sign(privateKey);
+    };
+    // --- Static helpers ---
+    static normalizeScopes(scopes) {
+        return Array.isArray(scopes) ? scopes.filter(Boolean) : scopes.split(/\s+/).filter(Boolean);
+    }
+    static resolvePrivateKey(privateKey) {
+        if (Buffer.isBuffer(privateKey))
+            return privateKey.toString("utf-8").trim();
+        const trimmed = privateKey.trim();
+        if (trimmed.includes("-----BEGIN"))
+            return trimmed;
+        try {
+            return readFileSync(trimmed, "utf-8").trim();
+        }
+        catch {
+            throw new Error(`AuthConfig: privateKey must be PEM text, a Buffer, or a readable file path: ${trimmed}`);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+   "name": "fhirstarterjs",
+   "version": "1.0.0",
+   "description": "SMART Backend Services auth lifecycle for any FHIR client",
+   "type": "module",
+   "main": "./dist/fhirstarter.js",
+   "types": "./ts/fhirstarter.ts",
+   "exports": {
+      ".": {
+         "types": "./ts/fhirstarter.ts",
+         "import": "./dist/fhirstarter.js"
+      },
+      "./types/api": {
+         "types": "./types/api.d.ts"
+      },
+      "./types/internal": {
+         "types": "./types/internal.d.ts"
+      }
+   },
+   "files": ["dist", "ts", "types", "README.md", "LICENSE.md"],
+   "engines": {
+      "node": ">=20"
+   },
+   "author": "Joshua Faulkenberry <j@joshuafaulkenberry.com> (https://joshuafaulkenberry.com/)",
+   "license": "Kopimi",
+   "scripts": {
+      "check": "tsc --noEmit",
+      "build": "tsc -p tsconfig.build.json",
+      "prepack": "npm run build"
+   },
+   "dependencies": {
+      "jose": "^6.2.3"
+   },
+   "devDependencies": {
+      "@types/node": "^25.9.2",
+      "typescript": "^6.0.3"
+   }
+}

package/ts/fhirstarter.ts

@@ -0,0 +1,306 @@
+import { importPKCS8, exportJWK, SignJWT, type JWTHeaderParameters } from "jose"
+import { randomUUID } from "node:crypto"
+import { readFileSync } from "node:fs"
+
+/**
+ * SMART Backend Services auth provider.
+ *
+ * Manages client-credentials token acquisition and proactive refresh
+ * 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
+
+   /**
+    * @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")
+
+      try {
+         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)
+   }
+
+   // --- 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
+   }
+
+   /** 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
+   }
+
+   /** 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
+   }
+
+   // --- Lifecycle ---
+
+   /**
+    * Acquires an initial token and starts the proactive background refresh timer.
+    * Safe to call multiple times — subsequent calls are no-ops.
+    * @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
+      try {
+         await this.getAccessToken()
+      } catch (err) {
+         this.started = false
+         throw err
+      }
+      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
+      if (this.refreshTimer) {
+         clearTimeout(this.refreshTimer)
+         this.refreshTimer = null
+      }
+   }
+
+   // --- Token adapters ---
+
+   /**
+    * Returns a live `LiveTokenResponse` object whose `access_token` and `expires_in`
+    * properties are always read from the current cache.
+    * Useful for libraries that hold a reference to a token response object.
+    */
+   tokenResponse = (): LiveTokenResponse => {
+      const auth = this
+      return {
+         token_type: "bearer",
+         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.
+    * 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.
+    */
+   onRefresh = (callback: RefreshCallback): (() => void) => {
+      this.refreshCallbacks.add(callback)
+      const current = this.token
+      if (current) try { callback(current) } catch { /* ignore */ }
+      return () => this.refreshCallbacks.delete(callback)
+   }
+
+   // --- Public async ---
+
+   /**
+    * Returns the public JWKS derived from the configured private key.
+    * Private key material (`d`, `p`, `q`, etc.) is stripped before returning.
+    */
+   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] }
+   }
+
+   /**
+    * Returns a valid access token, refreshing if the cached token is at or past its refresh threshold.
+    * Falls back to a not-yet-expired stale token if the refresh request fails.
+    * @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
+      try {
+         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
+      }
+   }
+
+   // --- Private ---
+
+   // Single-flight refresh — shared by getAccessToken and the proactive timer
+   private doRefresh = (): Promise<string> => {
+      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
+         })
+         .catch((err) => {
+            this.refreshPromise = null
+            throw err
+         })
+      return this.refreshPromise
+   }
+
+   private scheduleRefresh = (): void => {
+      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())
+
+      this.refreshTimer = setTimeout(async () => {
+         try {
+            await this.doRefresh()
+         } catch {
+            this.refreshFailed = true
+            this.refreshRetryMs = Math.min(this.refreshRetryMs * 2, 60_000)
+            this.scheduleRefresh()
+         }
+      }, delay)
+
+      this.refreshTimer.unref?.()
+   }
+
+   private notifyRefresh = (token: string): void => {
+      for (const callback of this.refreshCallbacks)
+         try {
+            callback(token)
+         } catch {
+            // Ignore callback failures; auth lifecycle must continue.
+         }
+   }
+
+   private refreshAccessToken = async (): Promise<TokenCache> => {
+      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: jwt,
+            scope: scopes.join(" "),
+         }),
+         res = await fetch(this.config.tokenEndpointUrl, {
+            method: "POST",
+            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}`)
+      }
+
+      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")
+      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: 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
+   }
+
+   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
+
+      return new SignJWT({
+         iss: clientId,
+         sub: clientId,
+         aud: tokenEndpointUrl,
+         jti: randomUUID(), // unique per RFC 7523 §3
+      })
+         .setProtectedHeader(header)
+         .setIssuedAt()
+         .setNotBefore("now")
+         .setExpirationTime("5m")
+         .sign(privateKey)
+   }
+
+   // --- Static helpers ---
+
+   private static normalizeScopes(scopes: string | string[]): string[] {
+      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()
+
+      const trimmed = privateKey.trim()
+      if (trimmed.includes("-----BEGIN")) return trimmed
+
+      try {
+         return readFileSync(trimmed, "utf-8").trim()
+      } catch {
+         throw new Error(`AuthConfig: privateKey must be PEM text, a Buffer, or a readable file path: ${trimmed}`)
+      }
+   }
+}

package/types/api.d.ts

@@ -0,0 +1,54 @@
+declare global {
+   /** Configuration required to authenticate using SMART Backend Services. */
+   interface AuthConfig {
+      /** App client_id registered with your FHIR authorization server */
+      clientId: string
+      /** RSA private key as PEM text, a Buffer, or a path to a PKCS#8 PEM file */
+      privateKey: string | Buffer
+      /** OAuth 2.0 token endpoint URL */
+      tokenEndpointUrl: string
+      /** SMART scopes to request — space-delimited string or array */
+      scopes: string | string[]
+      /** Key ID — set when using a registered JWKS URL */
+      keyId?: string
+      /** JWK Set URL registered with your authorization server — included as `jku` in JWT header */
+      jwksUrl?: string
+   }
+
+   /** Standard JWK Set structure — suitable for hosting at a public URL. */
+   interface JwkSet {
+      /** Array of JSON Web Keys. */
+      keys: import("jose").JWK[]
+   }
+
+   /** Auth lifecycle provider implemented by {@link FHIRStarter}. */
+   interface Provider {
+      /** Current valid token, or null if no unexpired token is cached. */
+      readonly token: string | null
+      /** Seconds until actual token expiry, or null if no valid token is cached. */
+      readonly expiresIn: number | null
+      /** `Bearer <token>` string, or null if no valid token is cached. */
+      readonly authorizationHeader: string | null
+      /** Fetch the first token and begin the proactive refresh loop. Safe to call once. */
+      start(): Promise<void>
+      /** Clear the proactive refresh timer. */
+      stop(): void
+      /** Returns a valid access token. Refreshes if past the refresh window; degrades gracefully on failure. */
+      getAccessToken(): Promise<string>
+      /** Returns a getter-backed token response object for use with official `fhirclient`. */
+      tokenResponse(): LiveTokenResponse
+      /** Subscribe to token refreshes. Returns an unsubscribe function. */
+      onRefresh(callback: (token: string) => void): () => void
+      /** Returns the public JWKS derived from the private key. */
+      getJwks(): Promise<JwkSet>
+   }
+
+   /** Getter-backed token response shape compatible with `fhirclient`'s request path. */
+   interface LiveTokenResponse {
+      token_type: "bearer"
+      readonly access_token: string | undefined
+      readonly expires_in: number | undefined
+   }
+}
+
+export { AuthConfig, JwkSet, Provider, LiveTokenResponse }

package/types/internal.d.ts

@@ -0,0 +1,22 @@
+declare global {
+   /** Shape of the OAuth 2.0 token endpoint response. */
+   interface TokenResponse {
+      access_token: string
+      token_type: string
+      expires_in: number
+      scope?: string
+   }
+
+   /** In-memory cache entry for a fetched access token. */
+   interface TokenCache {
+      accessToken: string
+      /** Epoch ms — when to attempt proactive refresh (before actual expiry). */
+      refreshAt: number
+      /** Epoch ms — actual token expiry. Never treat as expired before this. */
+      expiresAt: number
+   }
+
+   type RefreshCallback = (token: string) => void
+}
+
+export { TokenResponse, TokenCache, RefreshCallback }