Source: util/config.ts

  1. /**
  2.  * @fileoverview Configuration Object
  3.  */
  5. import assert = require('assert');
  6. import * as https from 'https';
  7. import * as url from 'url';
  8. import { Readable } from 'stream';
  10. // ------------------------------------------------------------------------------
  11. // Requirements
  12. // ------------------------------------------------------------------------------
  13. const merge = require('merge-options'),
  14. 	sdkVersion = require('../../package.json').version;
  16. // ------------------------------------------------------------------------------
  17. // Private
  18. // ------------------------------------------------------------------------------
  20. const nodeVersion = process.version;
  22. /**
  23.  * Configuration for App Auth
  24.  * @typedef {Object} AppAuthConfig
  25.  * @property {string} keyID The ID of the public key used for app auth
  26.  * @property {string|Buffer} privateKey The private key used for app auth
  27.  * @property {string} passphrase The passphrase associated with the private key
  28.  * @property {string} [algorithm=RS256] The signing algorithm to use, "RS256", "RS384", or "RS512"
  29.  * @property {int} [expirationTime=30] Number of seconds the JWT should live for
  30.  * @property {boolean} [verifyTimestamp=false] Whether the timestamp when the auth token is created should be validated
  31.  */
  32. type AppAuthConfig = {
  33. 	keyID: string;
  34. 	privateKey: string | Buffer;
  35. 	passphrase: string;
  36. 	algorithm: 'RS256' | 'RS384' | 'RS512';
  37. 	expirationTime: number;
  38. 	verifyTimestamp: boolean;
  39. };
  41. /**
  42.  * Configuration settings used to initialize and customize the SDK
  43.  *
  44.  * @typedef {Object} UserConfigurationOptions
  45.  * @property {string} clientID Client ID of your Box Application
  46.  * @property {string} clientSecret Client secret of your Box Application
  47.  * @property {string} [apiRootURL] The root URL to Box [Default: 'https://api.box.com']
  48.  * @property {string} [uploadAPIRootURL] The root URL to Box for uploads [Default: 'https://upload.box.com/api']
  49.  * @property {string} [authorizeRootURL] The root URL for the authorization screen [Default: 'https://account.box.com/api']
  50.  * @property {int} [uploadRequestTimeoutMS] Timeout after which an upload request is aborted [Default: 60000]
  51.  * @property {int} [retryIntervalMS] Time between auto-retries of the API call on a temp failure [Default: 2000]
  52.  * @property {int} [numMaxRetries] Max # of times a temporarily-failed request should be retried before propagating a permanent failure [Default: 5]
  53.  * @property {int} [expiredBufferMS] Time before expiration, in milliseconds, when we begin to treat tokens as expired [Default: 3 min.]
  54.  * @property {Object} [request] Request options
  55.  * @property {boolean} [request.strictSSL] Set to false to disable strict SSL checking, which allows using Dev APIs [Default: true]
  56.  * @property {?AppAuthConfig} appAuth Optional configuration for App Auth
  57.  */
  58. type UserConfigurationOptions = {
  59. 	clientID: string;
  60. 	clientSecret: string;
  61. 	apiRootURL: string;
  62. 	uploadAPIRootURL: string;
  63. 	authorizeRootURL: string;
  64. 	uploadRequestTimeoutMS: number;
  65. 	retryIntervalMS: number;
  66. 	numMaxRetries: number;
  67. 	expiredBufferMS: number;
  68. 	request: {
  69. 		agentClass: any /* FIXME */;
  70. 		agentOptions: any /* FIXME */;
  71. 		strictSSL: boolean;
  72. 	};
  73. 	appAuth?: AppAuthConfig;
  74. 	proxy?: {
  75. 		url: string;
  76. 		username: string;
  77. 		password: string;
  78. 	};
  79. };
  81. var defaults = {
  82. 	clientID: null,
  83. 	clientSecret: null,
  84. 	apiRootURL: 'https://api.box.com',
  85. 	uploadAPIRootURL: 'https://upload.box.com/api',
  86. 	authorizeRootURL: 'https://account.box.com/api',
  87. 	apiVersion: '2.0',
  88. 	uploadRequestTimeoutMS: 60000,
  89. 	retryIntervalMS: 2000,
  90. 	numMaxRetries: 5,
  91. 	retryStrategy: null,
  92. 	expiredBufferMS: 180000,
  93. 	appAuth: undefined,
  94. 	iterators: false,
  95. 	enterpriseID: undefined,
  96. 	analyticsClient: null,
  97. 	disableStreamPassThrough: false,
  98. 	proxy: {
  99. 		url: null,
  100. 		username: null,
  101. 		password: null,
  102. 	},
  103. 	request: {
  104. 		// By default, require API SSL cert to be valid
  105. 		strictSSL: true,
  106. 		// Use an agent with keep-alive enabled to avoid performing SSL handshake per connection
  107. 		agentClass: https.Agent,
  108. 		agentOptions: {
  109. 			keepAlive: true,
  110. 		},
  111. 		// Encode requests as JSON. Encode the response as well if JSON is returned.
  112. 		json: true,
  113. 		// Do not encode the response as a string, since the response could be a file. return Buffers instead.
  114. 		encoding: null,
  115. 		// A redirect is usually information we want to handle, so don't automatically follow
  116. 		followRedirect: false,
  117. 		// By default, we attach a version-specific user-agent string to SDK requests
  118. 		headers: {
  119. 			'User-Agent': `Box Node.js SDK v${sdkVersion} (Node ${nodeVersion})`,
  120. 		},
  121. 	},
  122. };
  124. var appAuthDefaults = {
  125. 	algorithm: 'RS256',
  126. 	expirationTime: 30,
  127. 	verifyTimestamp: false,
  128. };
  130. /**
  131.  * Validate the basic Config values needed for the SDK to function
  132.  * @param {UserConfigurationOptions} params The user-supplied config values
  133.  * @returns {void}
  134.  * @throws {AssertionError}
  135.  * @private
  136.  */
  137. function validateBasicParams(params: UserConfigurationOptions) {
  138. 	// Assert that the given params valid, and that required values are present
  139. 	assert(
  140. 		typeof params.clientID === 'string',
  141. 		'"clientID" must be set via init() before using the SDK.'
  142. 	);
  143. 	assert(
  144. 		typeof params.clientSecret === 'string',
  145. 		'"clientSecret" must be set via init() before using the SDK.'
  146. 	);
  147. }
  149. /**
  150.  * Validate app auth-specific Config values
  151.  * @param {Object} appAuth The user-supplied app auth values
  152.  * @returns {void}
  153.  * @throws {AssertionError}
  154.  * @private
  155.  */
  156. function validateAppAuthParams(appAuth: AppAuthConfig) {
  157. 	assert(
  158. 		typeof appAuth.keyID === 'string',
  159. 		'Key ID must be provided in app auth params'
  160. 	);
  161. 	assert(
  162. 		typeof appAuth.privateKey === 'string' ||
  163. 			appAuth.privateKey instanceof Buffer,
  164. 		'Private key must be provided in app auth params'
  165. 	);
  166. 	assert(
  167. 		typeof appAuth.passphrase === 'string' && appAuth.passphrase.length > 0,
  168. 		'Passphrase must be provided in app auth params'
  169. 	);
  171. 	var validAlgorithms = ['RS256', 'RS384', 'RS512'];
  172. 	if (typeof appAuth.algorithm !== 'undefined') {
  173. 		assert(
  174. 			validAlgorithms.indexOf(appAuth.algorithm) > -1,
  175. 			`Algorithm in app auth params must be one of: ${validAlgorithms.join(
  176. 				', '
  177. 			)}`
  178. 		);
  179. 	}
  181. 	if (typeof appAuth.expirationTime !== 'undefined') {
  182. 		assert(
  183. 			Number.isInteger(appAuth.expirationTime) &&
  184. 				appAuth.expirationTime > 0 &&
  185. 				appAuth.expirationTime <= 60,
  186. 			'Valid token expiration time (0 - 60) must be provided in app auth params'
  187. 		);
  188. 	}
  189. }
  191. /**
  192.  * Update the agentClass based on the proxy config values passed in by the user
  193.  * @param {UserConfigurationOptions} params The current Config values
  194.  * @returns {void}
  195.  * @private
  196.  */
  197. function updateRequestAgent(
  198. 	params: UserConfigurationOptions &
  199. 		Required<Pick<UserConfigurationOptions, 'proxy'>>
  200. ) {
  201. 	if (params.proxy.url) {
  202. 		let proxyUrl = params.proxy.url;
  203. 		if (params.proxy.username && params.proxy.password) {
  204. 			proxyUrl = proxyUrl.replace('://', `://${params.proxy.username}:${params.proxy.password}@`);
  205. 		}
  207. 		const ProxyAgent = require('proxy-agent').ProxyAgent;
  208. 		params.request.agentClass = ProxyAgent;
  209. 		params.request.agentOptions = Object.assign({}, 
  210. 			params.request.agentOptions,
  211. 			{
  212. 				getProxyForUrl: (url: string) => proxyUrl
  213. 			}
  214. 		);
  215. 	}
  216. }
  218. /**
  219.  * Deep freeze an object and all nested objects within it. It doesn't go deep on
  220.  * Buffers and Readable streams so can be used on objects containing requests.
  221.  * @param {Object} obj The object to freeze
  222.  * @returns {Object} The frozen object
  223.  */
  224. function deepFreezeWithRequest(obj: any) {
  225. 	Object.freeze(obj);
  227. 	Object.getOwnPropertyNames(obj).forEach(function (name) {
  228. 		const prop = obj[name];
  230. 		if (
  231. 			prop !== null &&
  232. 			typeof prop === 'object' &&
  233. 			obj.hasOwnProperty(name) &&
  234. 			!Object.isFrozen(prop) &&
  235. 			!(prop instanceof Buffer) &&
  236. 			!(prop instanceof Readable)
  237. 		) {
  238. 			deepFreezeWithRequest(obj[name]);
  239. 		}
  240. 	});
  242. 	return obj;
  243. }
  245. // ------------------------------------------------------------------------------
  246. // Public
  247. // ------------------------------------------------------------------------------
  249. /**
  250.  * A Config Object holds the configuration options of the current setup. These are all
  251.  * customizable by the user, and will default if no value is specified in the given params
  252.  * object. The object is frozen on initialization, so that no values can be changed after
  253.  * setup.
  254.  *
  255.  * @param {UserConfigurationOptions} params - The config options set by the user
  256.  * @constructor
  257.  */
  258. class Config {
  259. 	_params: Required<UserConfigurationOptions>;
  260. 	[key: string]: any;
  262. 	constructor(params: UserConfigurationOptions) {
  263. 		validateBasicParams(params);
  264. 		if (typeof params.appAuth === 'object') {
  265. 			validateAppAuthParams(params.appAuth);
  266. 			params.appAuth = merge({}, appAuthDefaults, params.appAuth);
  267. 		}
  269. 		// Ensure that we don't accidentally assign over Config methods
  270. 		assert(
  271. 			!params.hasOwnProperty('extend'),
  272. 			'Config params may not override Config methods'
  273. 		);
  274. 		assert(
  275. 			!params.hasOwnProperty('_params'),
  276. 			'Config params may not override Config methods'
  277. 		);
  279. 		// Set the given params or default value if params property is missing
  280. 		this._params = merge(defaults, params);
  281. 		updateRequestAgent(this._params);
  282. 		Object.assign(this, this._params);
  283. 		// Freeze the object so that configuration options cannot be modified
  284. 		deepFreezeWithRequest(this);
  285. 	}
  287. 	/**
  288. 	 * Extend the current config into a new config with new params overriding old ones
  289. 	 * @param {UserConfigurationOptions} params The override options
  290. 	 * @returns {Config} The extended configuration
  291. 	 */
  292. 	extend(params: UserConfigurationOptions) {
  293. 		var newParams = merge({}, this._params, params);
  294. 		delete newParams.extend;
  295. 		delete newParams._params;
  296. 		return new Config(newParams);
  297. 	}
  298. }
  300. /**
  301.  * @module box-node-sdk/lib/util/config
  302.  * @see {@Link Config}
  303.  */
  304. export = Config;