1 /* eslint-disable no-unused-vars */
4 const common
= require('../common');
5 const DatabaseErrors
= require('./errors');
6 const svh
= require('./schema-version-helper');
7 const uuid
= require('uuid');
9 const _fileScope
= common
.fileScope(__filename
);
12 constructor(logger
, options
) {
14 this.options
= options
;
19 * Perform tasks needed to prepare database for use. Ensure this is called
20 * after construction, and before any other database activity.
21 * At the minimum, this will validate a compatible schema is present and usable.
22 * Some engines will also perform other initializations or async actions which
23 * are easier handled outside the constructor.
26 const _scope
= _fileScope('initialize');
28 const currentSchema
= await
this._currentSchema();
29 const current
= svh
.schemaVersionObjectToNumber(currentSchema
);
30 const min
= svh
.schemaVersionObjectToNumber(this.schemaVersionsSupported
.min
);
31 const max
= svh
.schemaVersionObjectToNumber(this.schemaVersionsSupported
.max
);
32 if (current
>= min
&& current
<= max
) {
33 this.logger
.debug(_scope
, 'schema supported', { currentSchema
, schemaVersionsSupported: this.schemaVersionsSupported
});
35 this.logger
.error(_scope
, 'schema not supported', { currentSchema
, schemaVersionsSupported: this.schemaVersionsSupported
});
36 throw new DatabaseErrors
.MigrationNeeded();
42 * @typedef {Object} SchemaVersionObject
43 * @property {Number} major
44 * @property {Number} minor
45 * @property {Number} patch
48 * Query the current schema version.
49 * This is a standalone query function, as it is called before statements are loaded.
50 * @returns {SchemaVersionObject}
52 async
_currentSchema() {
53 this._notImplemented('_currentSchema', arguments
);
58 * Perform db connection health-check, if applicable.
59 * Throw something if a database situation should pull us out of a load-balancer.
62 this._notImplemented('healthCheck', arguments
);
67 * Wrap a function call in a database context.
68 * @param {Function} fn fn(ctx)
71 this._notImplemented('context', arguments
);
75 * Wrap a function call in a transaction context.
77 * @param {Function} fn fn(txCtx)
79 async
transaction(dbCtx
, fn
) {
80 this._notImplemented('transaction', arguments
);
85 * Basic type checking of object properties.
87 * Types may be any of the built-in types:
89 * - bigint (also allowed with 'number')
91 * - number (this will also allow 'bigint')
97 * Types may also be any of the following:
104 * @param {Object} object
105 * @param {String[]} properties
106 * @param {String[]} types
108 _ensureTypes(object
, properties
, types
) {
109 const _scope
= _fileScope('_ensureTypes');
111 if (!(object
&& properties
&& types
)) {
112 this.logger
.error(_scope
, 'undefined argument', { object
, properties
, types
});
113 throw new DatabaseErrors
.DataValidation();
116 const supportedTypes
= [
132 types
.forEach((t
) => {
133 if (!supportedTypes
.includes(t
)) {
134 this.logger
.error(_scope
, 'unsupported type', { object
, properties
, types
, unsupportedType: t
});
135 throw new DatabaseErrors
.DataValidation();
139 properties
.forEach((p
) => {
140 // eslint-disable-next-line security/detect-object-injection
141 const pObj
= object
[p
];
142 const pType
= typeof pObj
;
143 if (!types
.includes(pType
)
144 && !(types
.includes('array') && Array
.isArray(pObj
))
145 && !(types
.includes('buffer') && pObj
instanceof Buffer
)
146 && !(types
.includes('date') && pObj
instanceof Date
)
147 && !(types
.includes('infinites') && Math
.abs(pObj
) === Infinity
)
148 && !(types
.includes('null') && pObj
=== null)
149 && !(types
.includes('number') && pType
=== 'bigint')
150 && !(types
.includes('uuid') && uuid
.validate(pObj
))) {
151 const reason
= `'${p}' is '${pType}', but must be ${types.length > 1 ? 'one of ' : ''}'${types}'`;
152 this.logger
.error(_scope
, reason
, {});
153 throw new DatabaseErrors
.DataValidation(reason
);
160 * @typedef {Object} Authentication
161 * @property {String} identifier
162 * @property {String=} credential
163 * @property {Date} created
164 * @property {Date=} lastAuthentication
167 * @param {Authentication} authentication
169 _validateAuthentication(authentication
) {
171 [['identifier'], ['string']],
172 [['credential'], ['string', 'null']],
173 [['created'], ['date']],
174 [['lastAuthentication'], ['date', 'infinites']],
175 ].forEach(([properties
, types
]) => this._ensureTypes(authentication
, properties
, types
));
180 * @typedef {Object} Resource
181 * @property {String} resourceId - uuid
182 * @property {String} secret
183 * @property {String} description
184 * @property {Date} created
187 * @param {Resource} resource
189 _validateResource(resource
) {
191 [['resourceId', 'secret', 'description'], ['string']],
192 [['resourceId'], ['uuid']],
193 [['created'], ['date']],
194 ].forEach(([properties
, types
]) => this._ensureTypes(resource
, properties
, types
));
199 * @typedef {Object} Token
200 * @property {String} codeId - uuid
201 * @property {String} profile
202 * @property {Date} created
203 * @property {Date=} expires
204 * @property {Date=} refreshExpires
205 * @property {Date=} refreshed
206 * @property {*=} duration
207 * @property {*=} refreshDuration
208 * @property {Number|BigInt=} refresh_count
209 * @property {Boolean} is_revoked
210 * @property {Boolean} is_token
211 * @property {String} client_id
212 * @property {String[]} scopes
213 * @property {Object=} profileData
216 * @param {Token} token
218 _validateToken(token
) {
220 [['codeId', 'profile', 'clientId'], ['string']],
221 [['codeId'], ['uuid']],
222 [['created'], ['date']],
223 [['expires', 'refreshExpires', 'refreshed'], ['date', 'null']],
224 [['isToken', 'isRevoked'], ['boolean']],
225 [['scopes'], ['array']],
226 [['profileData'], ['object', 'null']],
227 ].forEach(([properties
, types
]) => this._ensureTypes(token
, properties
, types
));
228 this._ensureTypes(token
.scopes
, Object
.keys(token
.scopes
), ['string']);
233 * Interface methods need implementations. Ensure the db-interaction
234 * methods on the base class call this, so they may be overridden by
235 * implementation classes.
236 * @param {String} method
237 * @param {arguments} args
239 _notImplemented(method
, args
) {
240 this.logger
.error(_fileScope(method
), 'abstract method called', Array
.from(args
));
241 throw new DatabaseErrors
.NotImplemented(method
);
246 * Get all the almanac entries.
249 async
almanacGetAll(dbCtx
) {
250 this._notImplemented('almanacGetAll', arguments
);
255 * Fetch the authentication record for an identifier.
257 * @param {String} identifier
258 * @returns {Promise<Authentication>}
260 async
authenticationGet(dbCtx
, identifier
) {
261 this._notImplemented('authenticationGet', arguments
);
266 * Update the authentication record for the identifier that
267 * correct credentials have been supplied.
269 * @param {String} identifier
270 * @returns {Promise<void>}
272 async
authenticationSuccess(dbCtx
, identifier
) {
273 this._notImplemented('authenticationSuccess', arguments
);
278 * Insert or update the credential for an identifier.
280 * @param {String} identifier
281 * @param {String} credential
282 * @returns {Promise<void>}
284 async
authenticationUpsert(dbCtx
, identifier
, credential
) {
285 this._notImplemented('authenticationUpsert', arguments
);
290 * Determine if profile url is known to this service.
292 * @param {String} profile
293 * @returns {Promise<Boolean>}
295 async
profileIsValid(dbCtx
, profile
) {
296 this._notImplemented('profileGet', arguments
);
301 * Insert a new relationship between a profile endpoint and
302 * an authenticated identifier.
304 * @param {String} profile
305 * @param {String} identifier
306 * @returns {Promise<void>}
308 async
profileIdentifierInsert(dbCtx
, profile
, identifier
) {
309 this._notImplemented('profileIdentifierInsert', arguments
);
314 * Adds a scope to be available for a profile to include on any authorization request.
316 * @param {String} profile
317 * @param {String} scope
318 * @returns {Promise<void>}
320 async
profileScopeInsert(dbCtx
, profile
, scope
) {
321 this._notImplemented('profileScopeInsert', arguments
);
326 * @typedef {Object} ScopeDetails
327 * @property {String} description
328 * @property {String[]=} profiles
331 * @typedef {Object.<String, Object>} ProfileScopes
332 * @property {Object.<String, Object>} profile
333 * @property {Object.<String, ScopeDetails>} profile.scope
336 * @typedef {Object.<String, Object>} ScopeIndex
337 * @property {ScopeDetails} scope
340 * @typedef {Object} ProfilesScopesReturn
341 * @property {ProfileScopes} profileScopes
342 * @property {ScopeIndex} scopeIndex
343 * @property {String[]} profiles
346 * Returns an object containing:
347 * - an object with profiles as keys to objects with scopes as keys to scope objects,
348 * which each contain a description of the scope and a list of profiles offering it
349 * - an object with scopes as keys to the same scope objects
350 * - a list of profiles
352 * @param {String} identifier
353 * @returns {Promise<ProfileScopesReturn>}
355 async
profilesScopesByIdentifier(dbCtx
, identifier
) {
356 this._notImplemented('profilesScopesByIdentifier', arguments
);
361 * @typedef ProfileScopesRow
364 * @property description
365 * @property application
366 * @property isPermanent
367 * @property isManuallyAdded
370 * Convert db row data into associative structures.
371 * Same behavior is shared by multiple engines.
372 * @param {ProfileScopesRow[]} profileScopesRows
373 * @returns {ProfileScopesReturn}
375 static _profilesScopesBuilder(profileScopesRows
) {
376 const scopeIndex
= {};
377 const profileScopes
= {};
378 const profileSet
= new Set();
380 (profileScopesRows
|| []).forEach(({ profile
, scope
, description
, application
, isPermanent
, isManuallyAdded
}) => {
381 if (scope
&& !(scope
in scopeIndex
)) {
382 scopeIndex
[scope
] = { // eslint-disable-line security/detect-object-injection
391 profileSet
.add(profile
);
392 if (!(profile
in profileScopes
)) {
393 profileScopes
[profile
] = {}; // eslint-disable-line security/detect-object-injection
396 if (profile
&& scope
) {
397 scopeIndex
[scope
].profiles
.push(profile
); // eslint-disable-line security/detect-object-injection
398 profileScopes
[profile
][scope
] = scopeIndex
[scope
]; // eslint-disable-line security/detect-object-injection
403 profiles: [...profileSet
],
411 * Sets list of additional scopes available to profile.
413 * @param {String} profile
414 * @param {String[]} scopes
415 * @returns {Promise<void>}
417 async
profileScopesSetAll(dbCtx
, profile
, scopes
) {
418 this._notImplemented('profileScopesSetAll', arguments
);
423 * Create (or revoke a duplicate) code as a token entry.
425 * @param {Object} data
426 * @param {String} data.codeId
427 * @param {Date} data.created
428 * @param {Boolean} data.isToken
429 * @param {String} data.clientId
430 * @param {String} data.profile - profile uri
431 * @param {String} data.identifier
432 * @param {String[]} data.scopes
433 * @param {Number|Null} data.lifespanSeconds - null sets expiration to Infinity
434 * @param {Number|Null} data.refreshLifespanSeconds - null sets refresh to none
435 * @param {String|Null} data.resource
436 * @param {Object|Null} data.profileData - profile data from profile uri
437 * @returns {Promise<Boolean>} whether redemption was successful
439 async
redeemCode(dbCtx
, { codeId
, created
, isToken
, clientId
, profile
, identifier
, scopes
, lifespanSeconds
, refreshLifespanSeconds
, profileData
} = {}) {
440 this._notImplemented('redeemCode', arguments
);
445 * @typedef {Object} RefreshedToken
446 * @property {Date} expires
447 * @property {Date} refreshExpires
448 * @property {String[]=} scopes if scopes were reduced
451 * Redeem a refresh token to renew token codeId.
453 * @param {String} codeId
454 * @param {Date} refreshed
455 * @param {String[]} removeScopes
456 * @returns {Promise<RefreshedToken>}
458 async
refreshCode(dbCtx
, codeId
, refreshed
, removeScopes
) {
459 this._notImplemented('refreshCode', arguments
);
464 * Fetch a resource server record.
466 * @param {String} identifier uuid
467 * @returns {Promise<Resource>}
469 async
resourceGet(dbCtx
, resourceId
) {
470 this._notImplemented('resourceGet', arguments
);
475 * Create, or update description of, a resourceId.
477 * @param {String=} resourceId uuid
478 * @param {String=} secret
479 * @param {String=} description
480 * @returns {Promise<void>}
482 async
resourceUpsert(dbCtx
, resourceId
, secret
, description
) {
483 this._notImplemented('resourceUpsert', arguments
);
488 * Register a scope and its description.
490 * @param {String} scope
491 * @param {String} application
492 * @param {String} description
493 * @returns {Promise<void>}
495 async
scopeUpsert(dbCtx
, scope
, application
, description
, manuallyAdded
= false) {
496 this._notImplemented('scopeUpsert', arguments
);
501 * Remove a non-permanent scope if it is not currently in use.
503 * @param {String} scope
504 * @returns {Promise<Boolean>}
506 async
scopeDelete(dbCtx
, scope
) {
507 this._notImplemented('scopeDelete', arguments
);
512 * @typedef {Number|BigInt} CleanupResult
515 * @typedef {Object} CleanupResult
518 * Remove any non-permanent and non-manually-created scopes not currently in use.
520 * @param {Number} atLeastMsSinceLast skip cleanup if already executed this recently
521 * @returns {Promise<CleanupResult>}
523 async
scopeCleanup(dbCtx
, atLeastMsSinceLast
) {
524 this._notImplemented('scopeClean', arguments
);
529 * Forget tokens after they have expired, and redeemed codes after they have expired.
531 * @param {Number} codeLifespanSeconds
532 * @param {Number} atLeastMsSinceLast skip cleanup if already executed this recently
533 * @returns {Promise<CleanupResult>}
535 async
tokenCleanup(dbCtx
, codeLifespanSeconds
, atLeastMsSinceLast
) {
536 this._notImplemented('tokenCleanup', arguments
);
541 * Look up a redeemed token by code_id.
543 * @param {String} codeId
544 * @returns {Promise<Token>}
546 async
tokenGetByCodeId(dbCtx
, codeId
) {
547 this._notImplemented('tokenGetByCodeId', arguments
);
552 * Sets a redeemed token as revoked.
554 * @param {String} codeId - uuid
555 * @returns {Promise<void>}
557 async
tokenRevokeByCodeId(dbCtx
, codeId
) {
558 this._notImplemented('tokenRevokeByCodeId', arguments
);
563 * Revoke the refreshability of a codeId.
565 * @param {String} codeId - uuid
566 * @returns {Promise<void>}
568 async
tokenRefreshRevokeByCodeId(dbCtx
, codeId
) {
569 this._notImplemented('tokenRefreshRevokeByCodeId', arguments
);
574 * Get all tokens assigned to identifier.
576 * @param {String} identifier
577 * @returns {Promise<Tokens[]>}
579 async
tokensGetByIdentifier(dbCtx
, identifier
) {
580 this._notImplemented('tokensGetByIdentifier', arguments
);
585 module
.exports
= Database
;