Class Tilmeld

A user and group system for Nymph.js.

Written by Hunter Perrin for SciActive.

Author

Hunter Perrin [email protected]

Copyright

SciActive Inc

See

http://nymph.io/

Hierarchy

Tilmeld

Implements

TilmeldInterface

Constructors

constructor

new Tilmeld(config): Tilmeld
Create a new instance of Tilmeld.
Parameters
- config: Partial<Config> & {
  jwtSecret: string;
  }
  
  The Tilmeld configuration.
Returns Tilmeld
- Defined in packages/tilmeld/src/Tilmeld.ts:91

Properties

Group

Group: typeof Group = Group

The group class for this instance of Tilmeld.

User

User: typeof User = User

The user class for this instance of Tilmeld.

`Private` alreadyLoggedOutSwitch

alreadyLoggedOutSwitch: boolean = false

Used to avoid infinite loop.

config

config: Config

The Tilmeld config.

currentUser

currentUser: null | User & UserData = null

The currently logged in user.

`Private` gatekeeperCache

gatekeeperCache: null | {
[k: string]: true;
} = null

Gatekeeper ability cache.

Gatekeeper will cache the user's abilities that it calculates, so it can check faster if that user has been checked before.

Type declaration

[k: string]: true

nymph

nymph: default = ...

The Nymph instance.

request

request: null | Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>> = null

If you will be performing authentication functions (logging in/out), you should set these so Tilmeld can read and write cookies and headers.

If you want the user to be authenticated with the cookie and/or header they provide, you should set at least the request. It's better to set both, so the JWT can be updated if needed.

After you set these, call authenticate() to read user authentication data from them and fill the user's session.

If you want to support cookie based authentication (which still requires an XSRF token for security), you should enable the cookie parser middleware.

response

response: null | Response<any, Record<string, any>> = null

Methods

addAccessControlSelectors

addAccessControlSelectors(options, selectors): void
Add selectors to a list of options and selectors which will limit results to only entities the current user has access to.
Parameters
- options: Options
- selectors: FormattedSelector[]
Returns void
- Defined in packages/tilmeld/src/Tilmeld.ts:527

authenticate

authenticate(skipXsrfToken?): Promise<boolean>
Check for TILMELDAUTH and TILMELDSWITCH tokens, and, if set, authenticate from it/them.

You can also call this function after setting response.locals.user to the user you want to authenticate. You should check for user.enabled before setting this variable, unless you explicitly want to log in as a disabled user. (The user must be an instance of the User class for this Tilmeld instance.)

This function will set response.locals.user to the logged in user on successful authentication.
Parameters
- skipXsrfToken: boolean = false
  
  Skip the XSRF token check.
Returns Promise<boolean>
True if a user was authenticated, false on any failure.
Implementation of TilmeldInterface.authenticate
- Defined in packages/tilmeld/src/Tilmeld.ts:924

checkClientUIDPermissions

checkClientUIDPermissions(name, type?, user?): Promise<boolean>
Check a UID's permissions for a user.

THIS ONLY CHECKS AUTOMATICALLY FOR CLIENT REQUESTS.
UID functions on the Node.js side are not checked automatically. This function is only run automatically for UID functions run from the client. You should call this function manually if you're running a UID function on the Node.js side and you want it gated.

This will check the Tilmeld config and the user's abilities.
- READ_ACCESS, the UID is listed in clientReadableUIDs or the user has the "uid/get/nameofuid" ability.
- WRITE_ACCESS, the UID is listed in clientEnabledUIDs or the user has the "uid/new/nameofuid" ability.
- FULL_ACCESS, the UID is listed in clientSetabledUIDs or the user has the "uid/set/nameofuid" ability.
Parameters
- name: string
  
  The UID to check.
- type: TilmeldAccessLevels = TilmeldAccessLevels.READ_ACCESS
  
  The lowest level of permission to consider a pass.
- Optional user: false | User & UserData
  
  The user to check permissions for. If null, uses the current user. If false, checks for public access.
Returns Promise<boolean>
Whether the current user has at least type permission for the UID.
Implementation of TilmeldInterface.checkClientUIDPermissions
- Defined in packages/tilmeld/src/Tilmeld.ts:811

checkPermissions

checkPermissions(entity, type?, user?, acProperties?): boolean
Check an entity's permissions for a user.

This will check the AC (Access Control) properties of the entity. These include the following properties:
- acUser
- acGroup
- acOther
- acRead
- acWrite
- acFull
"acUser" refers to the entity's owner, "acGroup" refers to all users in the entity's group and all ancestor groups, and "acOther" refers to any user who doesn't fit these descriptions.

Each of these properties should be either NO_ACCESS, READ_ACCESS, WRITE_ACCESS, or FULL_ACCESS.
- NO_ACCESS - the user has no access to the entity.
- READ_ACCESS, the user has read access to the entity.
- WRITE_ACCESS, the user has read and write access to the entity, but can't delete it, change its access controls, or change its ownership.
- FULL_ACCESS, the user has read, write, and delete access to the entity, as well as being able to manage its access controls and ownership.
These properties default to:
- acUser = TilmeldAccessLevels.FULL_ACCESS
- acGroup = TilmeldAccessLevels.READ_ACCESS
- acOther = TilmeldAccessLevels.NO_ACCESS
"acRead", "acWrite", and "acFull" are arrays of users and/or groups that also have those permissions.

Only users with FULL_ACCESS have the ability to change any of the ac*, user, and group properties.

The following conditions will result in different checks, which determine whether the check passes:
- It is a user or group. (True for READ_ACCESS or Tilmeld admins.)
- No user is logged in. (Check other AC.)
- The entity is the user. (Always true.)
- It is the user's primary group. (True for READ_ACCESS.)
- The user or its groups are listed in "acRead". (True for READ_ACCESS.)
- The user or its groups are listed in "acWrite". (True for READ_ACCESS and WRITE_ACCESS.)
- The user or its groups are listed in "acFull". (Always true.)
- Its "user" is the user. (It is owned by the user.) (Check user AC.)
- Its "group" is the user's primary group. (Check group AC.)
- Its "group" is one of the user's secondary groups. (Check group AC.)
- Its "group" is a descendant of one of the user's groups. (Check group AC.)
- None of the above. (Check other AC.)
Parameters
- entity: EntityInterface
  
  The entity to check.
- type: TilmeldAccessLevels = TilmeldAccessLevels.READ_ACCESS
  
  The lowest level of permission to consider a pass.
- Optional user: false | User & UserData
  
  The user to check permissions for. If null, uses the current user. If false, checks for public access.
- Optional acProperties: ACProperties
  
  The acProperties to use instead of getting them from the entity.
Returns boolean
Whether the current user has at least type permission for the entity.
- Defined in packages/tilmeld/src/Tilmeld.ts:690

clearSession

clearSession(): void
Clear session user data.

Returns void
Implementation of TilmeldInterface.clearSession
- Defined in packages/tilmeld/src/Tilmeld.ts:871

clone

clone(): Tilmeld
This is used internally by Nymph. Don't call it yourself.

Returns Tilmeld
A clone of this instance.
Implementation of TilmeldInterface.clone
- Defined in packages/tilmeld/src/Tilmeld.ts:100

extractToken

extractToken(token): Promise<null | User & UserData>
Validate and extract the user from a token.
Parameters
- token: string
  
  The authentication token.
Returns Promise<null | User & UserData>
The user on success, null on failure.
Implementation of TilmeldInterface.extractToken
- Defined in packages/tilmeld/src/Tilmeld.ts:887

fillSession

fillSession(user): Promise<void>
Fill session user data.
Parameters
- user: User & UserData
  
  The user.
Returns Promise<void>
Implementation of TilmeldInterface.fillSession
- Defined in packages/tilmeld/src/Tilmeld.ts:859

gatekeeper

gatekeeper(ability?): boolean
Check to see if the current user has an ability.

If ability is undefined, it will check to see if a user is currently logged in.
Parameters
- Optional ability: string
  
  The ability.
Returns boolean
Whether the user has the given ability.
Implementation of TilmeldInterface.gatekeeper
- Defined in packages/tilmeld/src/Tilmeld.ts:168

init

init(nymph): void
Initialize Tilmeld.

This is meant to be called internally by Nymph. Don't call this directly.
Parameters
- nymph: default
  
  The Nymph instance.
Returns void
Implementation of TilmeldInterface.init
- Defined in packages/tilmeld/src/Tilmeld.ts:117

`Private` initAccessControl

initAccessControl(): void
Returns void
- Defined in packages/tilmeld/src/Tilmeld.ts:181

login

login(user, sendAuthHeader, sendCookie?): Promise<boolean>
Logs the given user into the system.
Parameters
- user: User & UserData
  
  The user.
- sendAuthHeader: boolean
  
  Send the auth token as a custom header.
- sendCookie: boolean = true
  
  Send the auth token as a cookie.
Returns Promise<boolean>
True on success, false on failure.
- Defined in packages/tilmeld/src/Tilmeld.ts:1050

loginSwitch

loginSwitch(user, sendAuthHeader, sendCookie?): Promise<boolean>
Adds a switch auth token for the given user.

This effectively logs the current user in to the system as the given user.
Parameters
- user: User & UserData
  
  The user.
- sendAuthHeader: boolean
  
  Send the auth token as a custom header.
- sendCookie: boolean = true
  
  Send the auth token as a cookie.
Returns Promise<boolean>
True on success, false on failure.
- Defined in packages/tilmeld/src/Tilmeld.ts:1096

logout

logout(clearCookie?): Promise<void>
Logs the current user out of the system.
Parameters
- clearCookie: boolean = true
  
  Clear the auth cookie. (Also send a header.)
Returns Promise<void>
- Defined in packages/tilmeld/src/Tilmeld.ts:1137

logoutSwitch

logoutSwitch(clearCookie?): Promise<void>
Clears the switch user out of the system.
Parameters
- clearCookie: boolean = true
  
  Clear the auth cookie. (Also send a header.)
Returns Promise<void>
- Defined in packages/tilmeld/src/Tilmeld.ts:1165

Class Tilmeld

Author

Copyright

See

Hierarchy

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

config: Partial<Config> & { jwtSecret: string; }

Returns Tilmeld

Properties

Group

User

Private alreadyLoggedOutSwitch

config

currentUser

Private gatekeeperCache

Type declaration

[k: string]: true

nymph

request

response

Methods

addAccessControlSelectors

Parameters

options: Options

selectors: FormattedSelector[]

Returns void

authenticate

Parameters

skipXsrfToken: boolean = false

Returns Promise<boolean>

checkClientUIDPermissions

THIS ONLY CHECKS AUTOMATICALLY FOR CLIENT REQUESTS.

Parameters

name: string

type: TilmeldAccessLevels = TilmeldAccessLevels.READ_ACCESS

Optional user: false | User & UserData

Returns Promise<boolean>

checkPermissions

Parameters

entity: EntityInterface

type: TilmeldAccessLevels = TilmeldAccessLevels.READ_ACCESS

Optional user: false | User & UserData

Optional acProperties: ACProperties

Returns boolean

clearSession

Returns void

clone

Returns Tilmeld

extractToken

Parameters

token: string

Returns Promise<null | User & UserData>

fillSession

Parameters

user: User & UserData

Returns Promise<void>

gatekeeper

Parameters

Optional ability: string

Returns boolean

init

Parameters

nymph: default

Returns void

Private initAccessControl

Returns void

login

Parameters

user: User & UserData

sendAuthHeader: boolean

sendCookie: boolean = true

Returns Promise<boolean>

loginSwitch

config: Partial<Config> & {
jwtSecret: string;
}

`Private` alreadyLoggedOutSwitch

`Private` gatekeeperCache

`Optional` user: false | User & UserData

`Optional` user: false | User & UserData

`Optional` acProperties: ACProperties

`Optional` ability: string

`Private` initAccessControl