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 {Promise<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    * Insert or update an almanac entry.
 256    * @param {*} dbCtx
 257    * @param {String} event
 258    * @param {Date=} date
 259    */
 260   async almanacUpsert(dbCtx, event, date) {
 261     this._notImplemented('almanacUpsert', arguments);
 262   }
 263
 264
 265   /**
 266    * Fetch the authentication record for an identifier.
 267    * @param {*} dbCtx
 268    * @param {String} identifier
 269    * @returns {Promise<Authentication>}
 270    */
 271   async authenticationGet(dbCtx, identifier) {
 272     this._notImplemented('authenticationGet', arguments);
 273   }
 274
 275
 276   /**
 277    * Update the authentication record for the identifier that
 278    * correct credentials have been supplied.
 279    * @param {*} dbCtx
 280    * @param {String} identifier
 281    * @returns {Promise<void>}
 282    */
 283   async authenticationSuccess(dbCtx, identifier) {
 284     this._notImplemented('authenticationSuccess', arguments);
 285   }
 286
 287
 288   /**
 289    * Insert or update the credential for an identifier.
 290    * @param {*} dbCtx
 291    * @param {String} identifier
 292    * @param {String} credential
 293    * @returns {Promise<void>}
 294    */
 295   async authenticationUpsert(dbCtx, identifier, credential) {
 296     this._notImplemented('authenticationUpsert', arguments);
 297   }
 298
 299
 300   /**
 301    * Determine if profile url is known to this service.
 302    * @param {*} dbCtx
 303    * @param {String} profile
 304    * @returns {Promise<Boolean>}
 305    */
 306   async profileIsValid(dbCtx, profile) {
 307     this._notImplemented('profileGet', arguments);
 308   }
 309
 310
 311   /**
 312    * Insert a new relationship between a profile endpoint and
 313    * an authenticated identifier.
 314    * @param {*} dbCtx
 315    * @param {String} profile
 316    * @param {String} identifier
 317    * @returns {Promise<void>}
 318    */
 319   async profileIdentifierInsert(dbCtx, profile, identifier) {
 320     this._notImplemented('profileIdentifierInsert', arguments);
 321   }
 322
 323
 324   /**
 325    * Adds a scope to be available for a profile to include on any authorization request.
 326    * @param {*} dbCtx
 327    * @param {String} profile
 328    * @param {String} scope
 329    * @returns {Promise<void>}
 330    */
 331   async profileScopeInsert(dbCtx, profile, scope) {
 332     this._notImplemented('profileScopeInsert', arguments);
 333   }
 334
 335
 336   /**
 337    * @typedef {Object} ScopeDetails
 338    * @property {String} description
 339    * @property {String[]=} profiles
 340    */
 341   /**
 342    * @typedef {Object.<String, Object>} ProfileScopes
 343    * @property {Object.<String, Object>} profile
 344    * @property {Object.<String, ScopeDetails>} profile.scope
 345    */
 346   /**
 347    * @typedef {Object.<String, Object>} ScopeIndex
 348    * @property {ScopeDetails} scope
 349    */
 350   /**
 351    * @typedef {Object} ProfilesScopesReturn
 352    * @property {ProfileScopes} profileScopes
 353    * @property {ScopeIndex} scopeIndex
 354    * @property {String[]} profiles
 355    */
 356   /**
 357    * Returns an object containing:
 358    * - an object with profiles as keys to objects with scopes as keys to scope objects,
 359    *   which each contain a description of the scope and a list of profiles offering it
 360    * - an object with scopes as keys to the same scope objects
 361    * - a list of profiles
 362    * @param {*} dbCtx
 363    * @param {String} identifier
 364    * @returns {Promise<ProfileScopesReturn>}
 365    */
 366   async profilesScopesByIdentifier(dbCtx, identifier) {
 367     this._notImplemented('profilesScopesByIdentifier', arguments);
 368   }
 369
 370
 371   /**
 372    * @typedef ProfileScopesRow
 373    * @property profile
 374    * @property scope
 375    * @property description
 376    * @property application
 377    * @property isPermanent
 378    * @property isManuallyAdded
 379    */
 380   /**
 381    * Convert db row data into associative structures.
 382    * Same behavior is shared by multiple engines.
 383    * @param {ProfileScopesRow[]} profileScopesRows
 384    * @returns {ProfileScopesReturn}
 385    */
 386   static _profilesScopesBuilder(profileScopesRows) {
 387     const scopeIndex = {};
 388     const profileScopes = {};
 389     const profileSet = new Set();
 390
 391     (profileScopesRows || []).forEach(({ profile, scope, description, application, isPermanent, isManuallyAdded }) => {
 392       if (scope && !(scope in scopeIndex)) {
 393         scopeIndex[scope] = { // eslint-disable-line security/detect-object-injection
 394           description,
 395           application,
 396           isPermanent,
 397           isManuallyAdded,
 398           profiles: [],
 399         };
 400       }
 401       if (profile) {
 402         profileSet.add(profile);
 403         if (!(profile in profileScopes)) {
 404           profileScopes[profile] = {}; // eslint-disable-line security/detect-object-injection
 405         }
 406       }
 407       if (profile && scope) {
 408         scopeIndex[scope].profiles.push(profile); // eslint-disable-line security/detect-object-injection
 409         profileScopes[profile][scope] = scopeIndex[scope]; // eslint-disable-line security/detect-object-injection
 410       }
 411     });
 412
 413     return {
 414       profiles: [...profileSet],
 415       profileScopes,
 416       scopeIndex,
 417     };
 418   }
 419
 420
 421   /**
 422    * Sets list of additional scopes available to profile.
 423    * @param {*} dbCtx
 424    * @param {String} profile
 425    * @param {String[]} scopes
 426    * @returns {Promise<void>}
 427    */
 428   async profileScopesSetAll(dbCtx, profile, scopes) {
 429     this._notImplemented('profileScopesSetAll', arguments);
 430   }
 431
 432
 433   /**
 434    * Create (or revoke a duplicate) code as a token entry.
 435    * @param {*} dbCtx
 436    * @param {Object} data
 437    * @param {String} data.codeId
 438    * @param {Date} data.created
 439    * @param {Boolean} data.isToken
 440    * @param {String} data.clientId
 441    * @param {String} data.profile - profile uri
 442    * @param {String} data.identifier
 443    * @param {String[]} data.scopes
 444    * @param {Number|Null} data.lifespanSeconds - null sets expiration to Infinity
 445    * @param {Number|Null} data.refreshLifespanSeconds - null sets refresh to none
 446    * @param {String|Null} data.resource
 447    * @param {Object|Null} data.profileData - profile data from profile uri
 448    * @returns {Promise<Boolean>} whether redemption was successful
 449    */
 450   async redeemCode(dbCtx, { codeId, created, isToken, clientId, profile, identifier, scopes, lifespanSeconds, refreshLifespanSeconds, profileData } = {}) {
 451     this._notImplemented('redeemCode', arguments);
 452   }
 453
 454
 455   /**
 456    * @typedef {Object} RefreshedToken
 457    * @property {Date} expires
 458    * @property {Date} refreshExpires
 459    * @property {String[]=} scopes if scopes were reduced
 460    */
 461   /**
 462    * Redeem a refresh token to renew token codeId.
 463    * @param {*} dbCtx
 464    * @param {String} codeId
 465    * @param {Date} refreshed
 466    * @param {String[]} removeScopes
 467    * @returns {Promise<RefreshedToken>}
 468    */
 469   async refreshCode(dbCtx, codeId, refreshed, removeScopes) {
 470     this._notImplemented('refreshCode', arguments);
 471   }
 472
 473
 474   /**
 475    * Fetch a resource server record.
 476    * @param {*} dbCtx
 477    * @param {String} identifier uuid
 478    * @returns {Promise<Resource>}
 479    */
 480   async resourceGet(dbCtx, resourceId) {
 481     this._notImplemented('resourceGet', arguments);
 482   }
 483
 484
 485   /**
 486    * Create, or update description of, a resourceId.
 487    * @param {*} dbCtx
 488    * @param {String=} resourceId uuid
 489    * @param {String=} secret
 490    * @param {String=} description
 491    * @returns {Promise<void>}
 492    */
 493   async resourceUpsert(dbCtx, resourceId, secret, description) {
 494     this._notImplemented('resourceUpsert', arguments);
 495   }
 496
 497
 498   /**
 499    * Register a scope and its description.
 500    * @param {*} dbCtx
 501    * @param {String} scope
 502    * @param {String} application
 503    * @param {String} description
 504    * @returns {Promise<void>}
 505    */
 506   async scopeUpsert(dbCtx, scope, application, description, manuallyAdded = false) {
 507     this._notImplemented('scopeUpsert', arguments);
 508   }
 509
 510
 511   /**
 512    * Remove a non-permanent scope if it is not currently in use.
 513    * @param {*} dbCtx
 514    * @param {String} scope
 515    * @returns {Promise<Boolean>}
 516    */
 517   async scopeDelete(dbCtx, scope) {
 518     this._notImplemented('scopeDelete', arguments);
 519   }
 520
 521
 522   /**
 523    * @typedef {Number|BigInt} CleanupResult
 524    */
 525   /**
 526    * @typedef {Object} CleanupResult
 527    */
 528   /**
 529    * Remove any non-permanent and non-manually-created scopes not currently in use.
 530    * @param {*} dbCtx
 531    * @param {Number} atLeastMsSinceLast skip cleanup if already executed this recently
 532    * @returns {Promise<CleanupResult>}
 533    */
 534   async scopeCleanup(dbCtx, atLeastMsSinceLast) {
 535     this._notImplemented('scopeClean', arguments);
 536   }
 537
 538
 539   /**
 540    * Forget tokens after they have expired, and redeemed codes after they have expired.
 541    * @param {*} dbCtx
 542    * @param {Number} codeLifespanSeconds
 543    * @param {Number} atLeastMsSinceLast skip cleanup if already executed this recently
 544    * @returns {Promise<CleanupResult>}
 545    */
 546   async tokenCleanup(dbCtx, codeLifespanSeconds, atLeastMsSinceLast) {
 547     this._notImplemented('tokenCleanup', arguments);
 548   }
 549
 550
 551   /**
 552    * Look up a redeemed token by code_id.
 553    * @param {*} dbCtx
 554    * @param {String} codeId
 555    * @returns {Promise<Token>}
 556    */
 557   async tokenGetByCodeId(dbCtx, codeId) {
 558     this._notImplemented('tokenGetByCodeId', arguments);
 559   }
 560
 561
 562   /**
 563    * Sets a redeemed token as revoked.
 564    * @param {*} dbCtx
 565    * @param {String} codeId - uuid
 566    * @returns {Promise<void>}
 567    */
 568   async tokenRevokeByCodeId(dbCtx, codeId) {
 569     this._notImplemented('tokenRevokeByCodeId', arguments);
 570   }
 571
 572
 573   /**
 574    * Revoke the refreshability of a codeId.
 575    * @param {*} dbCtx
 576    * @param {String} codeId - uuid
 577    * @returns {Promise<void>}
 578    */
 579   async tokenRefreshRevokeByCodeId(dbCtx, codeId) {
 580     this._notImplemented('tokenRefreshRevokeByCodeId', arguments);
 581   }
 582
 583
 584   /**
 585    * Get all tokens assigned to identifier.
 586    * @param {*} dbCtx
 587    * @param {String} identifier
 588    * @returns {Promise<Tokens[]>}
 589    */
 590   async tokensGetByIdentifier(dbCtx, identifier) {
 591     this._notImplemented('tokensGetByIdentifier', arguments);
 592   }
 593
 594
 595   /** @typedef {Object} RedeemedTicketData
 596    * @property {String} subject
 597    * @property {String} resource
 598    * @property {String=} iss
 599    * @property {String} ticket
 600    * @property {String} token
 601    */
 602   /**
 603    * Persist details of a redeemed ticket.
 604    * @param {*} dbCtx
 605    * @param {RedeemedTicketData} redeemedData
 606    * @returns {Promise<void>}
 607    */
 608   async ticketRedeemed(dbCtx, redeemedData) {
 609     this._notImplemented('ticketRedeemed', arguments);
 610   }
 611
 612
 613   /**
 614    * Update details of a redeemed ticket that it has been published.
 615    * @param {*} dbCtx
 616    * @param {RedeemedTicketData} redeemedData
 617    * @returns {Promise<void>}
 618    */
 619   async ticketTokenPublished(dbCtx, redeemedData) {
 620     this._notImplemented('ticketTokenPublished', arguments);
 621   }
 622
 623   /**
 624    * Retrieve redeemed tokens which have not yet been published to queue.
 625    * @param {Number} limit
 626    * @returns {Promise<RedeemedData[]>}
 627    */
 628   async ticketTokenGetUnpublished(dbCtx, limit) {
 629     this._notImplemented('ticketTokenGetUnpublished', arguments);
 630   }
 631
 632 }
 633
 634 module.exports = Database;