feat: Breaking changes to SmartAuthProvider

src/index.ts

@@ -15,6 +15,7 @@ export {
   SmartAuthRedirectQuerystring,
   SmartAuthUrlQuerystring,
   getAccessTokenFromClientCredentialFlow,
+  GrantFlow
 } from "./smart-auth/index.js";
 
 export {

src/smart-auth/README.md

@@ -32,19 +32,19 @@ const fastify = Fastify();
 // Our Smart Health ID Provider config
 const smartAuthProviderExample: SmartAuthProvider = {
   name: "idp",
-  scope: ["launch"],
   client: {
     id: "123",
     secret: "somesecret",
   },
   auth: {
+    grantFlow: "authorization_code",
+    scope: ["launch"],
     tokenHost: "http://external.localhost",
     authorizePath: "/smart/oauth/authorize",
+    redirect: {
+      host: "http://localhost:3000",
+    }
   },
-  redirect: {
-    host: "http://localhost:3000",
-  },
-  iss: "http://external.localhost/issuer",
 };
 
 // Initialize the plugin with our Smart Health ID Provider config
@@ -68,16 +68,22 @@ fastify.listen(3000)
 
 ## Features
 
+### SMART App Launch + Client Credentials
+
+SMART Auth profiles can be configured for both the Authorization Code grant flow (i.e. standard SMART App Launch) and, separately, for the Client Credentials grant flow introduced in some SMART + FHIR systems even though it is not standard.
+
+The rest of this document will assume the perspective of the SMART App Launch flow. See more config details in [Smart Health ID Provider Config](#Smart-Health-ID-Provider-Config). 
+
 ### Routes
 
-By default, the above example will scaffold an authorization URL in the format:
+By default, the above example in [Usage](#Usage) will scaffold an authorization URL from the `const smartAuthProviderExample` configuration object in this format:
 
-`/{prefix}/{SmartAuthProvider.name}/auth`
+`/{prefix}/{smartAuthProviderExample.name}/auth`
 
-* Prefix by default is `smart` - you can customize in the SmartAuthProvider config 
-* `SmartAuthProvider.name` is the id field of the config
+* Prefix by default is `smart` - you can customize in `const smartAuthProviderExample`
+* `smartAuthProviderExample.name` is the id field of the config
 
-For the above example the authorization URL will be:
+For the above example in [Usage](#Usage) the authorization URL will be:
 
 `/smart/smartHealthIdProvider/auth`
 
@@ -187,43 +193,62 @@ generateAuthorizationUri(
 The supported configuration for the provider config is just a TypeScript interface:
 
 ```typescript
-export type SmartAuthProvider = {
+export interface SmartAuthProvider {
   /** A name to label the provider */
   name: string;
-  /** @todo this could be typed to the FHIR spec */
-  scope: string[];
   /** Client registration */
   client: {
     id: string;
     secret: string;
-  }
-  /** Auth related config */
-  auth?: {
-    /** An optional prefix to add to every route path */
-    pathPrefix?: string;
-    /** Optional params to append to the authorization redirect */
-    authorizeParams?: Record<string, any>;
-    /** String used to set the host to request the tokens to. Required. */
-    tokenHost: string;
-    /** String path to request an access token. Default to /oauth/token. */
-    tokenPath?: string;
-    /** String path to revoke an access token. Default to /oauth/revoke. */
-    revokePath?: string;
-    /** String used to set the host to request an "authorization code". Default to the value set on auth.tokenHost. */
-    authorizeHost?: string;
-    /** String path to request an authorization code. Default to /oauth/authorize. */
-    authorizePath?: string;
   };
+  /** Auth related config */
+  auth: AuthCodeConfig | ClientCredentialsConfig;
+}
+```
+
+SMART Auth profiles can be configured for both the Authorization Code grant flow (i.e. as in CARIN BlueButton 2.0's SMART support) and, separately, for the Client Credentials grant flow introduced in some SMART + FHIR systems even though it is not standard.
+
+These are typed this way:
+
+```typescript
+interface SmartAuthConfig {
+  /** Supported grant flow */
+  grantFlow: GrantFlow;
+  /** String used to set the host to request the tokens to. Required. */
+  tokenHost: string;
+  /** String path to request an access token. Default to /oauth/token. */
+  tokenPath?: string;
+  /** Optional params to post to the token exchange */
+  tokenParams?: Record<string, any>;
+}
+
+interface ClientCredentialsConfig extends SmartAuthConfig {
+  grantFlow: "client_credentials"
+};
+
+interface AuthCodeConfig extends SmartAuthConfig {
+  grantFlow: "authorization_code"
+  scope: SmartAuthScope[];
+  /** An optional prefix to add to every route path */
+  pathPrefix?: string;
+  /** Optional params to append to the authorization redirect */
+  authorizeParams?: Record<string, any>;
+  /** String used to set the host to request an "authorization code". Default to the value set on auth.tokenHost. */
+  authorizeHost?: string;
+  /** String path to request an authorization code. Default to /oauth/authorize. */
+  authorizePath?: string;
+  /** String path to revoke an access token. Default to /oauth/revoke. */
+  revokePath?: string;
+  /** Where should users (with the auth code) be redirected to? */
   redirect: {
     /** A required host name for the auth code exchange redirect path. */
     host: string;
     /** An optional authorize path override. */
     path?: string;
   };
-  /** The default host name for the authorization service. Used to redirect users to the authorization URL. */
-  iss: string;
-}
+};
 ```
+
 ### Redirect/Callback 
 
 By default, you need to define a redirect/callback path for your provider. This plugin is flexible about what you can do in this route.

src/smart-auth/index.test.ts

@@ -1,7 +1,7 @@
 import { fastify as app } from "../../test/fixtures/authServer"
+import { ClientCredentialsExample } from "../../test/smart-auth/idp"
 
 import {
-  SmartAuthProvider,
   getAccessTokenFromClientCredentialFlow,
 } from './index';
 
@@ -73,24 +73,8 @@ describe("a provider with a weird name", () => {
 })
 
 describe("getAccessTokenFromClientCredentialFlow", () => {
-  const stubSmartAuthProvider = {
-    name: 'smart-stub',
-    scope: ['fhirUser'],
-    client: {
-      id: 'foo',
-      secret: 'bar',
-    },
-    auth: {
-      tokenHost: 'http://localhost/token',
-    },
-    redirect: {
-      host: 'http://localhost:3000/smart/smart-stub/auth',
-    },
-    iss: '',
-  } as SmartAuthProvider;
-
   it("returns an access token", async () => {
-    const token = await getAccessTokenFromClientCredentialFlow(stubSmartAuthProvider);
+    const token = await getAccessTokenFromClientCredentialFlow(ClientCredentialsExample);
     expect(ClientCredentials).toHaveBeenCalled();
     expect(token).toEqual('faketoken');
   });

src/smart-auth/index.ts

@@ -20,43 +20,56 @@ type Resources = `${"patient" | "user"}/${FHIRResourceList | "*"}.${"read" | "wr
 
 export type SmartAuthScope = LaunchContext | Profile | Refresh | Resources
 
-export type SmartAuthProvider = {
+export type GrantFlow = "authorization_code" | "client_credentials"
+
+export interface SmartAuthProvider {
   /** A name to label the provider */
   name: string;
-  scope: SmartAuthScope[];
   /** Client registration */
   client: {
     id: string;
     secret: string;
-  }
-  /** Auth related config */
-  auth: {
-    /** An optional prefix to add to every route path */
-    pathPrefix?: string;
-    /** Optional params to append to the authorization redirect */
-    authorizeParams?: Record<string, any>;
-    /** String used to set the host to request an "authorization code". Default to the value set on auth.tokenHost. */
-    authorizeHost?: string;
-    /** String path to request an authorization code. Default to /oauth/authorize. */
-    authorizePath?: string;
-    /** Optional params to post to the token exchange */
-    tokenParams?: Record<string, any>;
-    /** String used to set the host to request the tokens to. Required. */
-    tokenHost: string;
-    /** String path to request an access token. Default to /oauth/token. */
-    tokenPath?: string;
-    /** String path to revoke an access token. Default to /oauth/revoke. */
-    revokePath?: string;
   };
+  /** Auth related config */
+  auth: AuthCodeConfig | ClientCredentialsConfig;
+}
+
+interface SmartAuthConfig {
+  /** Supported grant flow */
+  grantFlow: GrantFlow;
+  /** String used to set the host to request the tokens to. Required. */
+  tokenHost: string;
+  /** String path to request an access token. Default to /oauth/token. */
+  tokenPath?: string;
+  /** Optional params to post to the token exchange */
+  tokenParams?: Record<string, any>;
+}
+
+interface ClientCredentialsConfig extends SmartAuthConfig {
+  grantFlow: "client_credentials"
+};
+
+interface AuthCodeConfig extends SmartAuthConfig {
+  grantFlow: "authorization_code"
+  scope: SmartAuthScope[];
+  /** An optional prefix to add to every route path */
+  pathPrefix?: string;
+  /** Optional params to append to the authorization redirect */
+  authorizeParams?: Record<string, any>;
+  /** String used to set the host to request an "authorization code". Default to the value set on auth.tokenHost. */
+  authorizeHost?: string;
+  /** String path to request an authorization code. Default to /oauth/authorize. */
+  authorizePath?: string;
+  /** String path to revoke an access token. Default to /oauth/revoke. */
+  revokePath?: string;
+  /** Where should users (with the auth code) be redirected to? */
   redirect: {
     /** A required host name for the auth code exchange redirect path. */
     host: string;
     /** An optional authorize path override. */
     path?: string;
   };
-  /** The default host name for the authorization service. Used to redirect users to the authorization URL. */
-  iss: string;
-}
+};
 
 export interface SmartAuthNamespace {
   authorizationCodeFlow: AuthorizationCode;
@@ -100,7 +113,11 @@ export interface SmartAuthUrlQuerystring {
   Querystring?: {
     scope?: SmartAuthScope[]
   }
-} 
+}
+
+function supports(provider: SmartAuthProvider, flow: GrantFlow): boolean {
+  return provider.auth.grantFlow === flow
+}
 
 const defaultState = randomBytes(10).toString('hex')
 
@@ -119,14 +136,17 @@ function routeCase(value: string): string {
 }
 
 const oauthPlugin: FastifyPluginCallback<SmartAuthProvider> = function (http, options, next) {
-  const { name, auth, client, scope: defaultScope, redirect } = options
+  const { name, client } = options;
+  supports(options, "authorization_code");
+  const auth =  options.auth as AuthCodeConfig;
+  const { scope: defaultScope, redirect } = auth;
 
   const prefix                = auth?.pathPrefix || "/smart";
   const tokenParams           = auth?.tokenParams || {}
   const tokenHost             = auth.tokenHost;
   const authorizeParams       = auth?.authorizeParams || {}
   const authorizeRedirectPath = `${prefix}/${routeCase(name)}/auth`
-  const redirectPath          = redirect.path || `${prefix}/${routeCase(name)}/redirect`
+  const redirectPath          = redirect?.path || `${prefix}/${routeCase(name)}/redirect`
   const redirectUri           = `${redirect.host}${redirectPath}`
 
   function generateAuthorizationUri(scope?: SmartAuthScope[]) {
@@ -209,6 +229,10 @@ export const getAccessTokenFromClientCredentialFlow = async (
   smartAuthProvider: SmartAuthProvider,
   scope?: string[]
 ): Promise<AccessToken | undefined> => {
+  if (!supports(smartAuthProvider, "client_credentials")) {
+    throw new Error(`SmartAuthProvider ${smartAuthProvider.name} does not support client_credentials - client_credentials must be explicitly set as a suppoedGrantFlow`)
+  }
+
   const clientCredentialsOptions = {
     client: smartAuthProvider.client,
     auth: {
@@ -218,12 +242,13 @@ export const getAccessTokenFromClientCredentialFlow = async (
   };
 
   const client = new ClientCredentials(clientCredentialsOptions);
-  const tokenParams = {
-    scope: scope || smartAuthProvider.scope,
-  };
-
+  const params = {
+    scope,
+    ...smartAuthProvider.auth.tokenParams
+  }
+
   try {
-    return await client.getToken(tokenParams);
+    return await client.getToken(params);
   } catch (error: any) {
     console.log('Access Token error', error.message);
   }

test/fixtures/authServer.ts

@@ -1,4 +1,4 @@
-import { smartAuthProviderExample, badNameProviderExample } from "../smart-auth/idp";
+import { AuthorizationCodeExample, badNameExample } from "../smart-auth/idp";
 import Fastify from "fastify";
 import {
   SmartAuth,
@@ -15,8 +15,8 @@ declare module 'fastify' {
 
 export const fastify = Fastify();
 
-fastify.register(SmartAuth, { prefix: '/smart', ...smartAuthProviderExample }) 
-fastify.register(SmartAuth, { prefix: '/smart', ...badNameProviderExample }) 
+fastify.register(SmartAuth, { prefix: '/smart', ...AuthorizationCodeExample }) 
+fastify.register(SmartAuth, { prefix: '/smart', ...badNameExample }) 
 
 fastify.get<Querystring>("/smart/idp/redirect", QuerystringAjvSchema, async function (request, reply) {
   const response = await this.idp.getAccessTokenFromAuthorizationCodeFlow(request)