fhirstarterjs 1.0.4 → 1.0.6

package/LICENSE.md

@@ -1,24 +1,44 @@
-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>
+# Kopimi License
+
+This software is released under the Kopimi License.
+
+## Permission
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to copy,
+modify, merge, publish, distribute, sublicense, sell, use, study,
+reverse-engineer, decompile, and otherwise deal in the Software without
+restriction, including without limitation for commercial or non-commercial
+purposes.
+
+Commercial use, sale, resale, or distribution for profit must include clear
+attribution to the original author(s) in the distributed copy and in any
+customary public-facing product notices, documentation, credits, or legal
+notices associated with that use.
+
+## Kopimi Propagation
+
+The Software is Kopimi. Copies, substantial portions, and derivative works must
+preserve the freedom to copy, share, modify, remix, and redistribute the
+Software. No copy, substantial portion, or derivative work may be distributed
+under terms that prohibit those freedoms.
+
+License notices, author notices, and Kopimi notices included with the Software
+may not be removed from redistributed copies, substantial portions, or
+derivative works.
+
+Attribution to the original author(s) is appreciated for non-commercial use and
+required for commercial use as described above.
+
+## Disclaimer
+
+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.
+
+This license is itself Kopimi. Copy it, use it, and remix it.
+
+For more information, please refer to <https://kopimi.com>

package/README.md

@@ -1,4 +1,4 @@
-# 🔥 fhirstarterjs
+# 🔥 fhirStarter
 
 SMART on FHIR Backend Services auth lifecycle for any FHIR client.
 
@@ -10,13 +10,13 @@ npm install fhirstarterjs
 
 ## Usage
 
-This example uses the official `fhirclient` package as the FHIR client; `fhirstarterjs` only manages auth.
+This example uses the official `fhirclient` package as the FHIR client; `fhirStarter` only manages auth.
 
 ```ts
 import FHIR from "fhirclient"
-import FHIRStarter from "fhirstarterjs"
+import fhirStarter from "fhirstarterjs"
 
-const auth = new FHIRStarter({
+const auth = new fhirStarter({
    clientId: "your-client-id",
    privateKey: "./privatekey.pem",
    tokenEndpointUrl: "https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token",
@@ -35,7 +35,7 @@ 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.
+`fhirStarter` 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.
 
@@ -68,7 +68,7 @@ const res = await fetch(url, {
 
 ## API
 
-`new FHIRStarter(config)`
+`new fhirStarter(config)`
 
 | Member | Returns | Description |
 |---|---|---|
@@ -90,9 +90,9 @@ Some SMART Backend Services registrations require a public JWKS URL when using `
 
 ```ts
 import { writeFileSync } from "node:fs"
-import FHIRStarter from "fhirstarterjs"
+import fhirStarter from "fhirstarterjs"
 
-const auth = new FHIRStarter({
+const auth = new fhirStarter({
    clientId: "your-client-id",
    privateKey: "./privatekey.pem",
    tokenEndpointUrl: "https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token",

package/dist/fhirstarter.js

@@ -7,7 +7,7 @@ import { readFileSync } from "node:fs";
  * 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 {
+export default class fhirStarter {
     config;
     privateKeyText;
     refreshCallbacks = new Set();
@@ -30,7 +30,7 @@ export default class FHIRStarter {
             throw new Error("AuthConfig: privateKey is required");
         if (!config.tokenEndpointUrl)
             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");
         try {
@@ -40,7 +40,7 @@ export default class FHIRStarter {
             throw new Error(`AuthConfig: tokenEndpointUrl is not a valid URL: ${config.tokenEndpointUrl}`);
         }
         this.config = config;
-        this.privateKeyText = FHIRStarter.resolvePrivateKey(config.privateKey);
+        this.privateKeyText = fhirStarter.resolvePrivateKey(config.privateKey);
     }
     // --- Sync getters ---
     /** The current access token, or `null` if no valid token is cached. */
@@ -108,6 +108,9 @@ export default class FHIRStarter {
             get expires_in() {
                 return auth.expiresIn ?? undefined;
             },
+            get scope() {
+                return auth.cache?.scope;
+            },
         };
     };
     /**
@@ -216,7 +219,7 @@ export default class FHIRStarter {
             }
     };
     refreshAccessToken = async () => {
-        const jwt = await this.buildJwt(), scopes = FHIRStarter.normalizeScopes(this.config.scopes), body = new URLSearchParams({
+        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,
@@ -246,6 +249,7 @@ export default class FHIRStarter {
             accessToken: data.access_token,
             refreshAt,
             expiresAt,
+            ...(typeof data.scope === "string" && { scope: data.scope }),
         };
         this.cache = cache;
         this.notifyRefresh(cache.accessToken);
@@ -272,7 +276,6 @@ export default class FHIRStarter {
         })
             .setProtectedHeader(header)
             .setIssuedAt()
-            .setNotBefore(0)
             .setExpirationTime("5m")
             .sign(privateKey);
     };

package/package.json

@@ -1,16 +1,42 @@
 {
    "name": "fhirstarterjs",
-   "version": "1.0.4",
+   "version": "1.0.6",
    "description": "SMART Backend Services auth lifecycle for any FHIR client",
+   "author": "Joshua Faulkenberry <j@joshuafaulkenberry.com> (https://joshuafaulkenberry.com/)",
+   "license": "Kopimi",
+   "homepage": "https://github.com/FaulkJ/fhirstarter#readme",
+   "repository": {
+      "type": "git",
+      "url": "git+https://github.com/FaulkJ/fhirstarter.git"
+   },
+   "bugs": {
+      "url": "https://github.com/FaulkJ/fhirstarter/issues"
+   },
+   "keywords": [
+      "fhir",
+      "smart",
+      "smart-on-fhir",
+      "backend-services",
+      "oauth",
+      "jwt",
+      "hl7",
+      "healthcare",
+      "ehr",
+      "epic",
+      "fhirclient",
+      "token",
+      "jwks"
+   ],
    "type": "module",
    "main": "./dist/fhirstarter.js",
-   "types": "./ts/fhirstarter.ts",
+   "types": "./types/index.d.ts",
    "exports": {
       ".": {
          "types": "./types/index.d.ts",
          "import": "./dist/fhirstarter.js"
       }
    },
+   "sideEffects": false,
    "files": [
       "dist",
       "ts",
@@ -21,8 +47,6 @@
    "engines": {
       "node": ">=20"
    },
-   "author": "Joshua Faulkenberry <j@joshuafaulkenberry.com> (https://joshuafaulkenberry.com/)",
-   "license": "Kopimi",
    "scripts": {
       "check": "tsc --noEmit",
       "build": "tsc -p tsconfig.build.json",
@@ -32,7 +56,7 @@
       "jose": "^6.2.3"
    },
    "devDependencies": {
-      "@types/node": "^25.9.2",
+      "@types/node": "^25.9.3",
       "typescript": "^6.0.3"
    }
 }

package/ts/fhirstarter.ts

@@ -13,7 +13,7 @@ import { readFileSync } from "node:fs";
  * 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 {
+export default class fhirStarter implements Provider {
    private readonly config: AuthConfig;
    private readonly privateKeyText: string;
    private readonly refreshCallbacks: Set<RefreshCallback> = new Set();
@@ -39,7 +39,7 @@ export default class FHIRStarter implements Provider {
       if (!config.tokenEndpointUrl)
          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");
 
@@ -52,7 +52,7 @@ export default class FHIRStarter implements Provider {
       }
 
       this.config = config;
-      this.privateKeyText = FHIRStarter.resolvePrivateKey(config.privateKey);
+      this.privateKeyText = fhirStarter.resolvePrivateKey(config.privateKey);
    }
 
    // --- Sync getters ---
@@ -127,6 +127,9 @@ export default class FHIRStarter implements Provider {
          get expires_in() {
             return auth.expiresIn ?? undefined;
          },
+         get scope() {
+            return auth.cache?.scope;
+         },
       };
    };
 
@@ -244,7 +247,7 @@ export default class FHIRStarter implements Provider {
 
    private refreshAccessToken = async (): Promise<TokenCache> => {
       const jwt = await this.buildJwt(),
-         scopes = FHIRStarter.normalizeScopes(this.config.scopes),
+         scopes = fhirStarter.normalizeScopes(this.config.scopes),
          body = new URLSearchParams({
             grant_type: "client_credentials",
             client_assertion_type:
@@ -285,6 +288,7 @@ export default class FHIRStarter implements Provider {
             accessToken: data.access_token,
             refreshAt,
             expiresAt,
+            ...(typeof data.scope === "string" && { scope: data.scope }),
          };
 
       this.cache = cache;
@@ -317,7 +321,6 @@ export default class FHIRStarter implements Provider {
       })
          .setProtectedHeader(header)
          .setIssuedAt()
-         .setNotBefore(0)
          .setExpirationTime("5m")
          .sign(privateKey);
    };

package/types/api.d.ts

@@ -21,7 +21,7 @@ declare global {
       keys: import("jose").JWK[]
    }
 
-   /** Auth lifecycle provider implemented by {@link FHIRStarter}. */
+   /** Auth lifecycle provider implemented by {@link fhirStarter}. */
    interface Provider {
       /** Current valid token, or null if no unexpired token is cached. */
       readonly token: string | null
@@ -48,6 +48,7 @@ declare global {
       token_type: "bearer"
       readonly access_token: string | undefined
       readonly expires_in: number | undefined
+      readonly scope: string | undefined
    }
 }
 

package/types/internal.d.ts

@@ -14,6 +14,8 @@ declare global {
       refreshAt: number
       /** Epoch ms — actual token expiry. Never treat as expired before this. */
       expiresAt: number
+      /** Granted scopes returned by the token endpoint, if any. */
+      scope?: string
    }
 
    type RefreshCallback = (token: string) => void