git.squeep.com Git - squeep-indie-auther/blob - src/db/abstract.js

   1 /* eslint-disable no-unused-vars */
   2 'use strict';
   3
   4 const common = require('../common');
   5 const DatabaseErrors = require('./errors');
   6 const svh = require('./schema-version-helper');
   7 const uuid = require('uuid');
   8
   9 const _fileScope = common.fileScope(__filename);
  10
  11 class Database {
  12   constructor(logger, options) {
  13     this.logger = logger;
  14     this.options = options;
  15   }
  16
  17
  18   /**
  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.
  24   */
  25   async initialize() {
  26     const _scope = _fileScope('initialize');
  27
  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 });
  34     } else {
  35       this.logger.error(_scope, 'schema not supported', { currentSchema, schemaVersionsSupported: this.schemaVersionsSupported });
  36       throw new DatabaseErrors.MigrationNeeded();
  37     }
  38   }
  39
  40
  41   /**
  42    * @typedef {Object} SchemaVersionObject
  43    * @property {Number} major
  44    * @property {Number} minor
  45    * @property {Number} patch
  46    */
  47   /**
  48    * Query the current schema version.
  49    * This is a standalone query function, as it is called before statements are loaded.
  50    * @returns {SchemaVersionObject}
  51    */
  52   async _currentSchema() {
  53     this._notImplemented('_currentSchema', arguments);
  54   }
  55
  56
  57   /**
  58    * Perform db connection health-check, if applicable.
  59    * Throw something if a database situation should pull us out of a load-balancer.
  60    */
  61   async healthCheck() {
  62     this._notImplemented('healthCheck', arguments);
  63   }
  64
  65
  66   /**
  67    * Wrap a function call in a database context.
  68    * @param {Function} fn fn(ctx)
  69    */
  70   async context(fn) {
  71     this._notImplemented('context', arguments);
  72   }
  73
  74   /**
  75    * Wrap a function call in a transaction context.
  76    * @param {*} dbCtx
  77    * @param {Function} fn fn(txCtx)
  78    */
  79   async transaction(dbCtx, fn) {
  80     this._notImplemented('transaction', arguments);
  81   }
  82
  83
  84   /**
  85    * Basic type checking of object properties.
  86    *
  87    * Types may be any of the built-in types:
  88    * - boolean
  89    * - bigint (also allowed with 'number')
  90    * - function
  91    * - number (this will also allow 'bigint')
  92    * - object
  93    * - string
  94    * - symbol
  95    * - undefined
  96    *
  97    * Types may also be any of the following:
  98    * - array
  99    * - buffer
 100    * - date
 101    * - infinites
 102    * - null
 103    * - uuid
 104    * @param {Object} object
 105    * @param {String[]} properties
 106    * @param {String[]} types
 107    */
 108   _ensureTypes(object, properties, types) {
 109     const _scope = _fileScope('_ensureTypes');
 110
 111     if (!(object && properties && types)) {
 112       this.logger.error(_scope, 'undefined argument', { object, properties, types });
 113       throw new DatabaseErrors.DataValidation();
 114     }
 115
 116     const supportedTypes = [
 117       'array',
 118       'bigint',
 119       'boolean',
 120       'buffer',
 121       'date',
 122       'function',
 123       'infinites',
 124       'null',
 125       'number',
 126       'object',
 127       'string',
 128       'symbol',
 129       'undefined',
 130       'uuid',
 131     ];
 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();
 136       }
 137     });
 138
 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);
 154       }
 155     });
 156   }
 157
 158
 159   /**
 160    * @typedef {Object} Authentication
 161    * @property {String} identifier
 162    * @property {String=} credential
 163    * @property {Date} created
 164    * @property {Date=} lastAuthentication
 165    */
 166   /**
 167    * @param {Authentication} authentication
 168    */
 169   _validateAuthentication(authentication) {
 170     [
 171       [['identifier'], ['string']],
 172       [['credential'], ['string', 'null']],
 173       [['created'], ['date']],
 174       [['lastAuthentication'], ['date', 'infinites']],
 175     ].forEach(([properties, types]) => this._ensureTypes(authentication, properties, types));
 176   }
 177
 178
 179   /**
 180    * @typedef {Object} Resource
 181    * @property {String} resourceId - uuid
 182    * @property {String} secret
 183    * @property {String} description
 184    * @property {Date} created
 185    */
 186   /**
 187    * @param {Resource} resource
 188    */
 189   _validateResource(resource) {
 190     [
 191       [['resourceId', 'secret', 'description'], ['string']],
 192       [['resourceId'], ['uuid']],
 193       [['created'], ['date']],
 194     ].forEach(([properties, types]) => this._ensureTypes(resource, properties, types));
 195   }
 196
 197
 198   /**
 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
 214    */
 215   /**
 216    * @param {Token} token
 217    */
 218   _validateToken(token) {
 219     [
 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']);
 229   }
 230
 231
 232   /**
 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
 238    */
 239   _notImplemented(method, args) {
 240     this.logger.error(_fileScope(method), 'abstract method called', Array.from(args));
 241     throw new DatabaseErrors.NotImplemented(method);
 242   }
 243
 244
 245   /**
 246    * Get all the almanac entries.
 247    * @param {*} dbCtx
 248    */
 249   async almanacGetAll(dbCtx) {
 250     this._notImplemented('almanacGetAll', arguments);
 251   }
 252
 253
 254   /**
 255    * Fetch the authentication record for an identifier.
 256    * @param {*} dbCtx
 257    * @param {String} identifier
 258    * @returns {Promise<Authentication>}
 259    */
 260   async authenticationGet(dbCtx, identifier) {
 261     this._notImplemented('authenticationGet', arguments);
 262   }
 263
 264
 265   /**
 266    * Update the authentication record for the identifier that
 267    * correct credentials have been supplied.
 268    * @param {*} dbCtx
 269    * @param {String} identifier
 270    * @returns {Promise<void>}
 271    */
 272   async authenticationSuccess(dbCtx, identifier) {
 273     this._notImplemented('authenticationSuccess', arguments);
 274   }
 275
 276
 277   /**
 278    * Insert or update the credential for an identifier.
 279    * @param {*} dbCtx
 280    * @param {String} identifier
 281    * @param {String} credential
 282    * @returns {Promise<void>}
 283    */
 284   async authenticationUpsert(dbCtx, identifier, credential) {
 285     this._notImplemented('authenticationUpsert', arguments);
 286   }
 287
 288
 289   /**
 290    * Determine if profile url is known to this service.
 291    * @param {*} dbCtx
 292    * @param {String} profile
 293    * @returns {Promise<Boolean>}
 294    */
 295   async profileIsValid(dbCtx, profile) {
 296     this._notImplemented('profileGet', arguments);
 297   }
 298
 299
 300   /**
 301    * Insert a new relationship between a profile endpoint and
 302    * an authenticated identifier.
 303    * @param {*} dbCtx
 304    * @param {String} profile
 305    * @param {String} identifier
 306    * @returns {Promise<void>}
 307    */
 308   async profileIdentifierInsert(dbCtx, profile, identifier) {
 309     this._notImplemented('profileIdentifierInsert', arguments);
 310   }
 311
 312
 313   /**
 314    * Adds a scope to be available for a profile to include on any authorization request.
 315    * @param {*} dbCtx
 316    * @param {String} profile
 317    * @param {String} scope
 318    * @returns {Promise<void>}
 319    */
 320   async profileScopeInsert(dbCtx, profile, scope) {
 321     this._notImplemented('profileScopeInsert', arguments);
 322   }
 323
 324
 325   /**
 326    * @typedef {Object} ScopeDetails
 327    * @property {String} description
 328    * @property {String[]=} profiles
 329    */
 330   /**
 331    * @typedef {Object.<String, Object>} ProfileScopes
 332    * @property {Object.<String, Object>} profile
 333    * @property {Object.<String, ScopeDetails>} profile.scope
 334    */
 335   /**
 336    * @typedef {Object.<String, Object>} ScopeIndex
 337    * @property {ScopeDetails} scope
 338    */
 339   /**
 340    * @typedef {Object} ProfilesScopesReturn
 341    * @property {ProfileScopes} profileScopes
 342    * @property {ScopeIndex} scopeIndex
 343    * @property {String[]} profiles
 344    */
 345   /**
 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
 351    * @param {*} dbCtx
 352    * @param {String} identifier
 353    * @returns {Promise<ProfileScopesReturn>}
 354    */
 355   async profilesScopesByIdentifier(dbCtx, identifier) {
 356     this._notImplemented('profilesScopesByIdentifier', arguments);
 357   }
 358
 359
 360   /**
 361    * @typedef ProfileScopesRow
 362    * @property profile
 363    * @property scope
 364    * @property description
 365    * @property application
 366    * @property isPermanent
 367    * @property isManuallyAdded
 368    */
 369   /**
 370    * Convert db row data into associative structures.
 371    * Same behavior is shared by multiple engines.
 372    * @param {ProfileScopesRow[]} profileScopesRows
 373    * @returns {ProfileScopesReturn}
 374    */
 375   static _profilesScopesBuilder(profileScopesRows) {
 376     const scopeIndex = {};
 377     const profileScopes = {};
 378     const profileSet = new Set();
 379
 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
 383           description,
 384           application,
 385           isPermanent,
 386           isManuallyAdded,
 387           profiles: [],
 388         };
 389       }
 390       if (profile) {
 391         profileSet.add(profile);
 392         if (!(profile in profileScopes)) {
 393           profileScopes[profile] = {}; // eslint-disable-line security/detect-object-injection
 394         }
 395       }
 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
 399       }
 400     });
 401
 402     return {
 403       profiles: [...profileSet],
 404       profileScopes,
 405       scopeIndex,
 406     };
 407   }
 408
 409
 410   /**
 411    * Sets list of additional scopes available to profile.
 412    * @param {*} dbCtx
 413    * @param {String} profile
 414    * @param {String[]} scopes
 415    * @returns {Promise<void>}
 416    */
 417   async profileScopesSetAll(dbCtx, profile, scopes) {
 418     this._notImplemented('profileScopesSetAll', arguments);
 419   }
 420
 421
 422   /**
 423    * Create (or revoke a duplicate) code as a token entry.
 424    * @param {*} dbCtx
 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
 438    */
 439   async redeemCode(dbCtx, { codeId, created, isToken, clientId, profile, identifier, scopes, lifespanSeconds, refreshLifespanSeconds, profileData } = {}) {
 440     this._notImplemented('redeemCode', arguments);
 441   }
 442
 443
 444   /**
 445    * @typedef {Object} RefreshedToken
 446    * @property {Date} expires
 447    * @property {Date} refreshExpires
 448    * @property {String[]=} scopes if scopes were reduced
 449    */
 450   /**
 451    * Redeem a refresh token to renew token codeId.
 452    * @param {*} dbCtx
 453    * @param {String} codeId
 454    * @param {Date} refreshed
 455    * @param {String[]} removeScopes
 456    * @returns {Promise<RefreshedToken>}
 457    */
 458   async refreshCode(dbCtx, codeId, refreshed, removeScopes) {
 459     this._notImplemented('refreshCode', arguments);
 460   }
 461
 462
 463   /**
 464    * Fetch a resource server record.
 465    * @param {*} dbCtx
 466    * @param {String} identifier uuid
 467    * @returns {Promise<Resource>}
 468    */
 469   async resourceGet(dbCtx, resourceId) {
 470     this._notImplemented('resourceGet', arguments);
 471   }
 472
 473
 474   /**
 475    * Create, or update description of, a resourceId.
 476    * @param {*} dbCtx
 477    * @param {String=} resourceId uuid
 478    * @param {String=} secret
 479    * @param {String=} description
 480    * @returns {Promise<void>}
 481    */
 482   async resourceUpsert(dbCtx, resourceId, secret, description) {
 483     this._notImplemented('resourceUpsert', arguments);
 484   }
 485
 486
 487   /**
 488    * Register a scope and its description.
 489    * @param {*} dbCtx
 490    * @param {String} scope
 491    * @param {String} application
 492    * @param {String} description
 493    * @returns {Promise<void>}
 494    */
 495   async scopeUpsert(dbCtx, scope, application, description, manuallyAdded = false) {
 496     this._notImplemented('scopeUpsert', arguments);
 497   }
 498
 499
 500   /**
 501    * Remove a non-permanent scope if it is not currently in use.
 502    * @param {*} dbCtx
 503    * @param {String} scope
 504    * @returns {Promise<Boolean>}
 505    */
 506   async scopeDelete(dbCtx, scope) {
 507     this._notImplemented('scopeDelete', arguments);
 508   }
 509
 510
 511   /**
 512    * @typedef {Number|BigInt} CleanupResult
 513    */
 514   /**
 515    * @typedef {Object} CleanupResult
 516    */
 517   /**
 518    * Remove any non-permanent and non-manually-created scopes not currently in use.
 519    * @param {*} dbCtx
 520    * @param {Number} atLeastMsSinceLast skip cleanup if already executed this recently
 521    * @returns {Promise<CleanupResult>}
 522    */
 523   async scopeCleanup(dbCtx, atLeastMsSinceLast) {
 524     this._notImplemented('scopeClean', arguments);
 525   }
 526
 527
 528   /**
 529    * Forget tokens after they have expired, and redeemed codes after they have expired.
 530    * @param {*} dbCtx
 531    * @param {Number} codeLifespanSeconds
 532    * @param {Number} atLeastMsSinceLast skip cleanup if already executed this recently
 533    * @returns {Promise<CleanupResult>}
 534    */
 535   async tokenCleanup(dbCtx, codeLifespanSeconds, atLeastMsSinceLast) {
 536     this._notImplemented('tokenCleanup', arguments);
 537   }
 538
 539
 540   /**
 541    * Look up a redeemed token by code_id.
 542    * @param {*} dbCtx
 543    * @param {String} codeId
 544    * @returns {Promise<Token>}
 545    */
 546   async tokenGetByCodeId(dbCtx, codeId) {
 547     this._notImplemented('tokenGetByCodeId', arguments);
 548   }
 549
 550
 551   /**
 552    * Sets a redeemed token as revoked.
 553    * @param {*} dbCtx
 554    * @param {String} codeId - uuid
 555    * @returns {Promise<void>}
 556    */
 557   async tokenRevokeByCodeId(dbCtx, codeId) {
 558     this._notImplemented('tokenRevokeByCodeId', arguments);
 559   }
 560
 561
 562   /**
 563    * Revoke the refreshability of a codeId.
 564    * @param {*} dbCtx
 565    * @param {String} codeId - uuid
 566    * @returns {Promise<void>}
 567    */
 568   async tokenRefreshRevokeByCodeId(dbCtx, codeId) {
 569     this._notImplemented('tokenRefreshRevokeByCodeId', arguments);
 570   }
 571
 572
 573   /**
 574    * Get all tokens assigned to identifier.
 575    * @param {*} dbCtx
 576    * @param {String} identifier
 577    * @returns {Promise<Tokens[]>}
 578    */
 579   async tokensGetByIdentifier(dbCtx, identifier) {
 580     this._notImplemented('tokensGetByIdentifier', arguments);
 581   }
 582
 583 }
 584
 585 module.exports = Database;