90168f0858
All checks were successful
Publish to Private NPM Registry / publish (push) Successful in 33s
309 lines
No EOL
15 KiB
TypeScript
309 lines
No EOL
15 KiB
TypeScript
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 extends BridgemanAccessibleAppClaims> = T & BasicOAuthAppOptions;
|
|
|
|
export class OAuthApp<TCustomClaims extends BridgemanAccessibleAppClaims> extends App {
|
|
private onAuth: OnAuthCallback;
|
|
private saveSecret: (secret: string) => void | Promise<void>;
|
|
|
|
private options: OAuthAppOptions<TCustomClaims>;
|
|
/*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<TCustomClaims>;
|
|
|
|
/**
|
|
* 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<void>,
|
|
options?: OAuthAppOptions<TCustomClaims>
|
|
) {
|
|
super();
|
|
this.onAuth = onAuth;
|
|
this.saveSecret = saveSecret;
|
|
this.options = options ?? {} as OAuthAppOptions<TCustomClaims>;
|
|
|
|
/*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<TCustomClaims> {
|
|
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<TCustomClaims>(
|
|
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<TCustomClaims>) => void | Promise<void>) {
|
|
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<T extends Initializer>(initializer?: T, callback?: (app: OAuthApp<TCustomClaims>) => void | Promise<void>) {
|
|
await super.run(initializer, async (app: App) => this.onStart(app, callback));
|
|
}
|
|
} |