import type { Application } from 'express'; import { Scopes } from '@BridgemanAccessible/ba-auth'; import Client from '@BridgemanAccessible/ba-auth/client'; import type { OnAuthCallback } from '@BridgemanAccessible/ba-auth/client'; import { logMessage, LogLevel } from '@BridgemanAccessible/ba-logging'; import { App } from '../App.js'; import { Initializer } from '../Initializer.js'; import { getValueFromEnvironmentVariable } from '../utils/env-vars.js'; import type { BridgemanAccessibleAppClaims } from './types/BridgemanAccessibleAppClaims.js'; import type { AppSubscriptionTier } from './types/AppSubscriptionTier.js'; import type { Addon } from './types/addons/Addon.js'; import type { Webhook } from './types/Webhook.js'; interface BasicOAuthAppOptions { // ------------------ // Basic app metadata // ------------------ /** The base URL of the app */ baseAppUrl?: URL, /** The abbreviation of the app */ //appAbbrv?: string, /** The (potentially localized) name of the app */ appName?: string | { /** Localized versions of the app name */ [language: string]: string }, // ----------------------------------------------------------- // Necessary interconnected details (contacts, scopes, etc...) // ----------------------------------------------------------- /** The email addresses of the contacts for the app */ contacts?: string[], /** The "available" scopes (scopes an app token COULD ask for - token scopes would have to ask for this or a subset of this list) */ scopes?: Scopes[], // ----------------------------------------------------- // Optional Mechanical Details (how the OAuth app works) // ----------------------------------------------------- /** The type of vault to use for the keystore */ vault_type?: "azure" | "hashicorp" | "file", /** The default method for authentication */ auth_default_method?: "query" | "form_post" | "PAR", /** Whether to use JWT as the default authentication method */ auth_default_use_JWT?: boolean, /** The default response mode for authentication */ auth_default_response_mode?: 'query' | 'fragment' | 'form_post' // ----------------------------------------------------- // For already registered apps (to stop re-registration) // ----------------------------------------------------- /** The client secret for the app (if this IS set registration WON'T be done. Because re-registering isn't supported) */ client_secret?: string // ---------------------------------- // URL stuff (policies, logo, etc...) // ---------------------------------- /** The URL of the app's logo */ logo_url?: URL, /** The URL of the app's Terms of Service */ tos_url?: URL, /** The URL of the app's Privacy Policy */ policy_url?: URL, // ------------------------------ // Webhooks (async notifications) // ------------------------------ /** The webhooks supported by the app */ //webhooks?: Webhook[], // ------------------------------------------ // Purchasable Stuff (Subscriptions + Addons) // ------------------------------------------ /** If a subscription is required */ //subscriptionRequired?: boolean, /** The subscription tiers available for the app */ //subscriptionTiers?: AppSubscriptionTier[], /** Addons offered by the app */ //addons?: Addon[], }; type OAuthAppOptions = T & BasicOAuthAppOptions; export class OAuthApp extends App { private onAuth: OnAuthCallback; private saveSecret: (secret: string) => void | Promise; private options: OAuthAppOptions; /*private baseAppUrl?: URL; private appAbbrv?: string; private appName?: string | { [language: string]: string }; private contacts?: string[]; private scopes?: Scopes[]; private vault_type?: "azure" | "hashicorp" | "file"; private auth_default_method?: "query" | "form_post" | "PAR"; private auth_default_use_JWT?: boolean; private auth_default_response_mode?: 'query' | 'fragment' | 'form_post'; private client_secret?: string; private logo_url?: URL; private tos_url?: URL; private policy_url?: URL; private webhooks?: Webhook[]; private subscriptionRequired?: boolean; private subscriptionTiers?: AppSubscriptionTier[]; private addons?: Addon[];*/ private client: Client; /** * Create a new OAuth app * * This is a more specialized version of the `App` class that is designed to work with the Bridgeman Accessible OAuth system. * The only required parameters are the `onAuth` and `saveSecret` callbacks which are called when a user logs in. * And when the client secret is generated (and is to be saved) respectively. * The `options` parameter allows for tweaking the OAuth details for the app. * * Note, the following table of environment variables that are used to set the OAuth details if they aren't provided in the `options` parameter: * * | Environment Variable | Is Required | Description | * | -------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- | * | BASE_APP_URL | Required if `options.baseAppUrl` isn't provided | The base URL of the client (app) | * | APP_ABBRV | Required if `options.appAbbrv` isn't provided | The abbreviation of the client (app) | * | APP_NAME | Required if `options.appName` isn't provided | The name of the client (only a single non-localized name is supported) | * | CONTACT_EMAIL | Required if `options.contacts` isn't provided | A comma-separated list of email addresses to list as contacts for the client | * | SCOPES | Required if `options.scopes` isn't provided | A comma-separated list of scopes available to the client | * | VAULT_TYPE | Required if in production (`NODE_ENV` is `production`) | The type of vault to use for the keystore (one of azure, hashicorp, or file) | * | APP_SECRET | Optional (Determines if app should register or not) | The client secret for the app (if this IS set registration WON'T be done) | * | LOGO_URL | Optional (used if `options.logo_url` isn't specified) | The URL of the client's (app's) logo | * | TOS_URL | Optional (used if `options.tos_url` isn't specified) | The URL of the client's terms of service | * | POLICY_URL | Optional (used if `options.policy_url` isn't specified) | The URL of the client's privacy policy | * * @param onAuth The callback to call when a user logs in * @param saveSecret The callback to call to save the secret * @param options The options for the OAuth app * @param options.baseAppUrl The base URL of the app * @param options.appAbbrv The abbreviation of the app (used for user properties associated with the app) * @param options.appName The name of the app * @param options.contacts The email addresses of the contacts for the app * @param options.scopes The scopes an app token COULD ask for (token scopes would have to ask for this or a subset of this list) * @param options.vault_type The type of vault to use for the keystore * @param options.auth_default_method The default method for authentication * @param options.auth_default_use_JWT Whether to use JWT as the default authentication method * @param options.auth_default_response_mode The default response mode for authentication * @param options.client_secret The client secret for the app (if this IS set registration WON'T be done. Because re-registering isn't supported) * @param options.logo_url The URL of the app's logo * @param options.tos_url The URL of the app's terms of service * @param options.policy_url The URL of the app's privacy policy * @param options.webhooks The webhooks supported by the app * @param options.subscriptionRequired If a subscription is required * @param options.subscriptionTiers The subscription tiers available for the app * @param options.addons Addons offered by the app */ constructor( onAuth: OnAuthCallback, saveSecret: (secret: string) => void | Promise, options?: OAuthAppOptions ) { super(); this.onAuth = onAuth; this.saveSecret = saveSecret; this.options = options ?? {} as OAuthAppOptions; /*if(typeof options !== 'undefined') { this.baseAppUrl = options.baseAppUrl; this.appAbbrv = options.appAbbrv; this.appName = options.appName; this.contacts = options.contacts; this.scopes = options.scopes; this.vault_type = options.vault_type; this.auth_default_method = options.auth_default_method; this.auth_default_use_JWT = options.auth_default_use_JWT; this.auth_default_response_mode = options.auth_default_response_mode; this.client_secret = options.client_secret; this.logo_url = options.logo_url; this.tos_url = options.tos_url; this.policy_url = options.policy_url; this.webhooks = options.webhooks; this.subscriptionRequired = options.subscriptionRequired; this.subscriptionTiers = options.subscriptionTiers; this.addons = options.addons; }*/ } /** Returns the OAuthApp's Client instance (which is useful for managing keys, creating resource request, etc...) */ getClient(): Client { return this.client; } /** * Setup the OAuth client * * This is done here because we need the client to be serving/listening for request in order for the auth library stuff to work properly * (mostly, the server needs to be able to get the client's keys which the client needs to be able to serve) * * @param app The app to setup the OAuth client for */ private async setupOAuthClient(app: App) { // If the base URL of the app isn't provided, get it from the environment variable let baseAppUrl = this.options.baseAppUrl; if(typeof baseAppUrl === 'undefined') { baseAppUrl = new URL(getValueFromEnvironmentVariable('BASE_APP_URL', { description: 'app\'s base URL', blank_allowed: false })); } // The app abbreviation (used for user properties associated with the app) let appAbbrv = this.options.client_abbreviation; if(typeof appAbbrv === 'undefined') { appAbbrv = getValueFromEnvironmentVariable('APP_ABBRV', { description: 'app abbreviation', blank_allowed: false }); } logMessage(`Attempting to create/register the app:\n\tApp Base URL: ${baseAppUrl}\n\tApp Abbreviation: ${appAbbrv}\n\tApp Name: ${typeof this.options.appName === 'undefined' ? 'uses APP_NAME environment variable (' + process.env.APP_NAME + ')' : this.options.appName}\n\tScopes: ${typeof this.options.scopes === 'undefined' ? 'uses SCOPES environment variable (' + process.env.SCOPES + ')' : this.options.scopes.join(', ')}`, LogLevel.DEBUG); // Because we need this for registration to work properly. It make sense to put it here app.getInitializer() .getRouter() .addOutsideFrameworkRoute('/.well-known/jwks.json'); this.client = await Client.setup( app.getExpressApp(), baseAppUrl, this.onAuth, this.saveSecret, { client_abbreviation: appAbbrv, subscription_required: this.options.subscriptionRequired ?? false, subscription_tiers: this.options.subscriptionTiers, addons: this.options.addons, webhooks: this.options.webhooks } as TCustomClaims, this.options.appName, this.options.scopes, { contacts: this.options.contacts, logo_url: this.options.logo_url, tos_url: this.options.tos_url, policy_url: this.options.policy_url, vault_type: this.options.vault_type, auth_default_method: this.options.auth_default_method, auth_default_use_JWT: this.options.auth_default_use_JWT, auth_default_response_mode: this.options.auth_default_response_mode, client_secret: this.options.client_secret } ); this.client.getSetupRoutes().forEach((route) => { logMessage(`Adding outside framework route: ${route}`, LogLevel.DEBUG); app.getInitializer().getRouter().addOutsideFrameworkRoute(route); }); } /** * The wrapper method around the `onStart` callback that differentiates the `OAuthApp` from the `App` class. * That is, this (the `OAuthApp` class) sets up the OAuth client before calling the client's `onStart` callback. * As opposed to the `App` class which just calls the `onStart` callback. * * It's done this way so that it's almost entirely transparent the difference between apps that have OAuth and those that don't. * * @param app The Express app object (that is now listening) */ private async onStart(app: App, callback?: (app: OAuthApp) => void | Promise) { try { // Setup the OAuth client. // This is done here because we need the client to be serving/listening for requests for the auth library stuff to work // (mostly because the server needs to be able to get the client's keys which it needs to be able to serve) await this.setupOAuthClient(app); if(typeof callback !== 'undefined') { await callback(this); } } catch(err) { logMessage('Error setting up the BA User Auth', LogLevel.ERROR); logMessage('---------------------------------', LogLevel.ERROR); logMessage(JSON.stringify(err), LogLevel.ERROR); } } /** * The main entry point for the app * * This largely just wraps the `run` method from the parent class (`App`). * However, instead of invoking the provided callback immediately when the client starts. * This initializes the app as an OAuth app first and then calls the callback. * This lets the app just worry about the `onAuth` callback (what happens when a user logs in) and `saveSecret` callback (that saves the generated client secret, if applicable) * And doesn't have to worry about the OAuth details to make this work. * Though it does provide tweaking the OAuth details via options provided to the constructor. */ async run(initializer?: T, callback?: (app: OAuthApp) => void | Promise) { await super.run(initializer, async (app: App) => this.onStart(app, callback)); } }