api/utils/rights

Module for validation functions that manage access rights to application data. Divided in parts access for Global Admins, Admins and Users.

Description:

  • Module for validation functions that manage access rights to application data. Divided in parts access for Global Admins, Admins and Users.

Source:

Members

(inner) PERMISSION_TYPES

Description:

  • Access types in a permission object, in their canonical order.

Source:

Access types in a permission object, in their canonical order.

Methods

(static) credentialRef(tokenId) → {string|null}

Description:

  • A non-secret reference to a token: what may be stored or compared where the token itself, a bearer credential, must not appear - on params.member.

Source:
Parameters:
Name Type Description
tokenId string

auth_tokens _id (the token string)
Returns:

the reference, or null for a missing id

Type
string | null

(static) dbUserHasAccessToCollection(params, collection, app_id, callback) → {function}

Description:

  • Check user has access to collection

Source:
Parameters:
Name Type Description
params object

params object
collection string

collection will be checked for access
app_id string

app_id to which to restrict access
callback function

callback method includes boolean variable as argument
Returns:

returns callback

Type
function

(static) getBaseAppFilter(member, dbName, collectionName, featureopt) → {object}

Description:

  • Creates filter object to filter by member allowed collections

Source:
Parameters:
Name Type Attributes Description
member object

members object from params
dbName string

database name as string
collectionName string

collection Name
feature string | Array.<string> <optional>

when given, only apps the member holds this feature's read right on (any of them, for a list) are in scope, instead of every app they belong to
Returns:

filter object

Type
object

(static) getExportAppFilter(member, dbName, collectionName) → {object|null}

Description:

  • App scope of a DB export from the collections shared by all apps (drill_events, events_data). A global admin is not scoped.

Source:
Parameters:
Name Type Description
member object

member object
dbName string

name of the database
collectionName string

name of the collection
Returns:

the base app filter, or null when the export is not scoped

Type
object | null

(static) getPermissionApps(permission) → {Array.<string>}

Description:

  • Every app id referenced by a permission object.

Source:
Parameters:
Name Type Description
permission object

permission object ({_:{a,u}, c/r/u/d:{appId:...}})
Returns:

list of app ids

Type
Array.<string>

(static) getSharedCollectionExportFeatures(dbName, collectionName) → {Array.<string>|null}

Description:

  • Features whose read right lets a member export a collection shared by all apps (/o/export/db). These collections are not per-app collections, so dbUserHasAccessToCollection never grants them: the export needs the read right of one of these features on at least one app, and its rows are scoped to those apps. drill_events is also exported by the drill API and the user profile timeline.

Source:
Parameters:
Name Type Description
dbName string

database name
collectionName string

collection name
Returns:

feature names, or null when the collection is not a shared one

Type
Array.<string> | null

(static) getUserAppsWithReadRight(member, feature) → {Array.<string>}

Description:

  • Apps of a member on which they hold the read right of at least one of the features

Source:
Parameters:
Name Type Description
member object

members object from params
feature string | Array.<string>

feature name, or a list of names any of which grants the read
Returns:

app ids

Type
Array.<string>

(static) hasAdminAccess(member, app_id, type) → {boolean}

Description:

  • Is user has admin access on selected app?

Source:
Parameters:
Name Type Description
member object

member object from params
app_id string

id value of related app
type string

type of access (c, r, u, d)
Returns:

isAdmin - is that user has admin access on that app?

Type
boolean

(static) hasDashboardAccess(member, operation) → {boolean}

Description:

  • Whether a member may use custom dashboards for an operation.

    A member reached through its own api_key or an unrestricted token (a dashboard session) is the owner and is decided by dashboard ownership and sharing alone. A scoped credential, marked by applyTokenScope with its dashboard_grant, needs the operation in that grant; with it, it has the owner's whole dashboard access.

Source:
Parameters:
Name Type Description
member object

params.member, bounded by applyTokenScope
operation string

c, r, u or d
Returns:

true if the member may use dashboards for this operation

Type
boolean

(static) intersectPermission(member, tokenPermission) → {object}

Description:

  • Bound a member by a token's permissions, returning a member that holds only what both allow.

    The subset check at creation time bounds a token to its creator, but the owner's own permissions can be reduced afterwards, so the intersection is recomputed on every request. The returned member never carries global_admin: that is precisely the authority a scoped token was narrowed away from, and leaving it set would let every global_admin check bypass the scope.

Source:
Parameters:
Name Type Description
member object

member document for the token owner
tokenPermission object

permission object stored on the token
Returns:

a copy of the member holding only the intersection

Type
object

(static) isPermissionSubset(childPermission, ceiling) → {boolean}

Description:

  • Whether one permission set grants nothing beyond what a ceiling principal already holds.

    This is what bounds a grant to the credential that creates it: a token may only pass on authority it holds itself. The ceiling is the member for an api_key or an unrestricted session, and the parent token's own permissions when a token creates a token - so a token scoped to app A cannot produce a child that reaches app B, even though their common owner can.

Source:
Parameters:
Name Type Description
childPermission object

permission object being granted
ceiling object

principal that must already hold everything the child grants
Returns:

true if childPermission is a subset of the ceiling's authority

Type
boolean

(static) isScopedCredential(params) → {boolean}

Description:

  • Whether the credential that authenticated this request is narrower than its owner.

    True for a token carrying token_permission, and for a token restricted by the legacy app/endpoint scope. False for an api_key (the member itself) and for an unrestricted token such as a dashboard session token. Used to keep credential management - which hands out and revokes the owner's other credentials - to credentials that are not themselves narrowed.

Source:
Parameters:
Name Type Description
params params

params object
Returns:

true if a scoped credential authenticated the request

Type
boolean

(static) scopeQueryToApps(appFilter, query) → {object}

Description:

  • Restrict a query to an app scope. The query is kept as given and both must hold. Apply it last, after /drill/preprocess_query, right before the read: a listener rewrites the query in place and must not be able to reshape the scope.

Source:
Parameters:
Name Type Description
appFilter object

app scope from getExportAppFilter, or null
query object

query to restrict
Returns:

the restricted query

Type
object

(static) validateAppAdmin(params, callback, callbackParamopt) → {Promise}

Description:

  • Validate user for admin access for specific app by api_key (required parameter for the request). User must exist, must not be locked, must pass plugin validation (if any). If user does not pass validation, it outputs error to request. In case validation passes, provided callback is called. Additionally populates params with member information.

Source:
Parameters:
Name Type Attributes Description
params params

params object
callback function

function to call only if validation passes
callbackParam any <optional>

parameter to pass to callback function (params is automatically passed to callback function, no need to include that)
Returns:

promise

Type
Promise

(static) validateCreate(params, feature, callback, callbackParamopt)

Description:

  • Validate user for create access by api_key for provided app_id (both required parameters for the request).

Source:
Parameters:
Name Type Attributes Description
params params

params object
feature string

feature that trying to access
callback function

function to call only if validation passes
callbackParam any <optional>

parameter to pass to callback function (params is automatically passed to callback function, no need to include that)

(static) validateDelete(params, feature, callback, callbackParamopt)

Description:

  • Validate user for delete access by api_key for provided app_id (both required parameters for the request).

Source:
Parameters:
Name Type Attributes Description
params params

params object
feature string

feature that trying to access
callback function

function to call only if validation passes
callbackParam any <optional>

parameter to pass to callback function (params is automatically passed to callback function, no need to include that)

(static) validateGlobalAdmin(params, callback, callbackParamopt) → {Promise}

Description:

  • Validate user for global admin access by api_key (required parameter for the request). User must exist, must not be locked, must pass plugin validation (if any) and have global admin access. If user does not pass validation, it outputs error to request. In case validation passes, provided callback is called. Additionally populates params with member information.

Source:
Parameters:
Name Type Attributes Description
params params

params object
callback function

function to call only if validation passes
callbackParam any <optional>

parameter to pass to callback function (params is automatically passed to callback function, no need to include that)
Returns:

promise

Type
Promise

(static) validateRead(params, feature, callback, callbackParamopt) → {Promise}

Description:

  • Validate user for read access by api_key for provided app_id (both required parameters for the request). User must exist, must not be locked, must pass plugin validation (if any) and have at least read access to the provided app (which also must exist). If user does not pass validation, it outputs error to request. In case validation passes, provided callback is called. Additionally populates params with member information and app information.

Source:
Parameters:
Name Type Attributes Description
params params

params object
feature string

feature that trying to access
callback function

function to call only if validation passes
callbackParam any <optional>

parameter to pass to callback function (params is automatically passed to callback function, no need to include that)
Returns:

promise

Type
Promise

(static) validateUpdate(params, feature, callback, callbackParamopt)

Description:

  • Validate user for update access by api_key for provided app_id (both required parameters for the request).

Source:
Parameters:
Name Type Attributes Description
params params

params object
feature string

feature that trying to access
callback function

function to call only if validation passes
callbackParam any <optional>

parameter to pass to callback function (params is automatically passed to callback function, no need to include that)

(static) validateUser(params, callback, callbackParamopt) → {Promise}

Description:

  • Basic user validation by api_key (required parameter for the request), mostly used for custom validation afterwards (like multi app access). User must exist, must not be locked and must pass plugin validation (if any). If user does not pass validation, it outputs error to request. In case validation passes, provided callback is called. Additionally populates params with member information.

Source:
Parameters:
Name Type Attributes Description
params params

params object
callback function

function to call only if validation passes
callbackParam any <optional>

parameter to pass to callback function (params is automatically passed to callback function, no need to include that)
Returns:

promise

Type
Promise

(static) validateUserForRead(params, callback, callbackParamopt) → {Promise}

Description:

  • Validate user for read access by api_key for provided app_id (both required parameters for the request). User must exist, must not be locked, must pass plugin validation (if any) and have at least user access to the provided app (which also must exist). If user does not pass validation, it outputs error to request. In case validation passes, provided callback is called. Additionally populates params with member information and app information.

Source:
Parameters:
Name Type Attributes Description
params params

params object
callback function

function to call only if validation passes
callbackParam any <optional>

parameter to pass to callback function (params is automatically passed to callback function, no need to include that)
Returns:

promise

Type
Promise

(static) validateUserForWrite(params, callback, callbackParamopt) → {Promise}

Description:

  • Validate user for write access by api_key for provided app_id (both required parameters for the request). User must exist, must not be locked, must pass plugin validation (if any) and have at least admin access to the provided app (which also must exist). If user does not pass validation, it outputs error to request. In case validation passes, provided callback is called. Additionally populates params with member information and app information.

Source:
Parameters:
Name Type Attributes Description
params params

params object
callback function

function to call only if validation passes
callbackParam any <optional>

parameter to pass to callback function (params is automatically passed to callback function, no need to include that)
Returns:

promise

Type
Promise

(inner) appOnlyPermission(apps) → {object}

Description:

  • A permission granting everything on the given apps, to intersect an owner with: the result is exactly the owner's own authority on those apps.

Source:
Parameters:
Name Type Description
apps Array.<string>

app ids
Returns:

permission object

Type
object

(inner) applyTokenScope(params, member) → {object}

Description:

  • Bound a member by the permissions of the token used to authenticate as them.

    Authenticating with a token resolves to the token's owner, and every validator then decides what to allow from that member. Without this step the member is loaded at full strength, so a token deliberately scoped to one app authorizes everything its owner can do - the escalation this model exists to prevent. Applied as soon as the member is loaded, so that the validators' own permission checks already see the bounded member.

    A token created before this model with an app restriction is bounded to its owner's authority on those apps. A token with no restriction at all (an api_key request, a dashboard session token) is returned unchanged, so existing integrations are unaffected.

Source:
Parameters:
Name Type Description
params params

params object, carrying token_data when a token was used
member object

member document loaded for the token owner
Returns:

the member, bounded by the token's permissions when the token is scoped

Type
object

(inner) dashboardGrant(tokenPermission) → {Object}

Description:

  • The dashboard operations a token_permission grants under its dashboards key.

    Only an explicit true counts: per-app grants, all:true included, never imply it.

Source:
Parameters:
Name Type Description
tokenPermission object

token_permission of a token, or undefined for a legacy token
Returns:

granted operations

Type
Object

(inner) dbLoadEventsData(params, apps, callback)

Description:

  • Get events data A helper function for db access check

Source:
Parameters:
Name Type Description
params object

params object
apps array

array with each element being app document
callback function

callback method

(inner) grantingApps(permission) → {Array.<string>}

Description:

  • App ids a permission object actually grants something on.

    Distinct from principalApps: the permission editor emits an entry for every app the editing user can see, most of them granting nothing, and an empty entry is not a grant. Apps listed under _.u do count, because some validators authorize on app membership alone.

Source:
Parameters:
Name Type Description
permission object

permission object
Returns:

list of app ids the permission grants something on

Type
Array.<string>

(inner) isScopeRestricted(scope) → {boolean}

Description:

  • Whether a legacy token scope field asks for a restriction, including a malformed non-empty list whose entries normalize to no valid apps.

Source:
Parameters:
Name Type Description
scope string | Array

token app or endpoint field
Returns:

true if the field represents a restriction

Type
boolean

(inner) legacyTokenApps(token) → {Array.<string>}

Description:

  • Apps a legacy (pre-permission-model) token is restricted to.

Source:
Parameters:
Name Type Description
token object

auth_tokens document
Returns:

app ids, empty when the token has no app restriction

Type
Array.<string>

(inner) loadAndCacheEventsData(apps, callback)

Description:

  • Function to load and cache data

Source:
Parameters:
Name Type Description
apps object

apps
callback function

callback function

(inner) principalAllows(principal, type, appId, feature) → {boolean}

Description:

  • Whether a principal grants a single feature on an app for one access type.

    A principal is anything holding authority: a member (with global_admin / permission, or the legacy admin_of / user_of arrays), or a bare token permission set wrapped as {permission: obj}. This is the same rule the hasCreateRight / hasReadRight / hasUpdateRight / hasDeleteRight helpers apply to a member, expressed once so it can also be applied to a token.

Source:
Parameters:
Name Type Description
principal object

object with permission (and optionally global_admin)
type string

access type (c, r, u, d)
appId string

id of the app
feature string

feature name
Returns:

true if the principal allows that feature

Type
boolean

(inner) principalAllowsAll(principal, type, appId) → {boolean}

Description:

  • Whether a principal grants every feature on an app for one access type.

    Distinct from principalAllows because "all" also covers features that do not exist yet, so it may only be granted by a principal that itself holds "all".

Source:
Parameters:
Name Type Description
principal object

object with permission (and optionally global_admin)
type string

access type (c, r, u, d)
appId string

id of the app
Returns:

true if the principal allows everything for that app and type

Type
boolean

(inner) principalApps(principal) → {Array.<string>}

Description:

  • Every app id a principal actually reaches: the ones it is a member of, plus the ones it holds a c/r/u/d grant on.

    An entry under c/r/u/d that grants nothing does not count. The permission editor writes an entry for every app the editing user could see, so a member routinely carries empty entries for apps it has no access to at all; treating those as apps the member reaches would let a token be scoped to one of them and come out wider than its own owner.

Source:
Parameters:
Name Type Description
principal object

object with permission (and optionally the legacy arrays)
Returns:

list of app ids

Type
Array.<string>

(inner) principalFeatures(principal, type, appId) → {Array.<string>}

Description:

  • Feature names a principal explicitly allows for an app and access type.

Source:
Parameters:
Name Type Description
principal object

object with permission
type string

access type (c, r, u, d)
appId string

id of the app
Returns:

list of feature names

Type
Array.<string>

(inner) principalMemberApps(principal) → {Array.<string>}

Description:

  • Apps a principal is a member of - the ones it administers, and the ones it is a user of.

    Distinct from the apps it can reach a feature on: some validators (validateUserForRead and validateUserForWrite) authorize on membership alone, so membership is authority in its own right and has to be bounded separately from the c/r/u/d grants.

Source:
Parameters:
Name Type Description
principal object

object with permission (and optionally the legacy arrays)
Returns:

list of app ids the principal is a member of

Type
Array.<string>

(inner) validateWrite(params, feature, accessType, callback, callbackParamopt) → {Promise}

Description:

  • Validate user for write access by api_key for provided app_id (both required parameters for the request). User must exist, must not be locked, must pass plugin validation (if any) and have accessType that passed as accessType parameter to the provided app (which also must exist). If user does not pass validation, it outputs error to request. In case validation passes, provided callback is called. Additionally populates params with member information and app information.

Source:
Parameters:
Name Type Attributes Description
params params

params object
feature string

feature that trying to access
accessType string

required access type for related request (c: create, u: update and d: delete)
callback function

function to call only if validation passes
callbackParam any <optional>

parameter to pass to callback function (params is automatically passed to callback function, no need to include that)
Returns:

promise

Type
Promise

(inner) validate_token_if_exists(params) → {Promise}

Description:

  • Validate if token exists and is not expired(uzing authorize.js)

Source:
Parameters:
Name Type Description
params object

params

Properties
Name Type Description
qstring.auth_token string

authentication token
req.headers.countly-token string

{string} authentication token
fullPath string

current full path
Returns:

promise

Type
Promise

(inner) wrapCallback(params, callback, callbackParamopt, func) → {Promise}

Description:

  • Wrap callback using promise

Source:
Parameters:
Name Type Attributes Description
params params

params object
callback function

function to call only if validation passes
callbackParam any <optional>

parameter to pass to callback function
func function

promise function
Returns:

promise

Type
Promise