Skip to content

Commit

Permalink
docs: adjust max line length in comments to 80
Browse files Browse the repository at this point in the history
  • Loading branch information
@hperrin
hperrin committed Sep 1, 2021
1 parent 28ad2ca commit 935be83
Show file tree
Hide file tree
Showing 7 changed files with 140 additions and 115 deletions.
6 changes: 4 additions & 2 deletions packages/driver-sqlite3/src/conf/d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,11 @@ export interface SQLite3DriverConfig {
*/
filename: string;
/**
* If the file does not exist, an Error will be thrown instead of creating a new file.
* If the file does not exist, an Error will be thrown instead of creating a
* new file.
*
* This option is ignored for in-memory, temporary, or readonly database connections.
* This option is ignored for in-memory, temporary, or readonly database
* connections.
*/
fileMustExist: boolean;
/**
Expand Down
8 changes: 4 additions & 4 deletions packages/nymph/src/Entity.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,10 +77,10 @@ import {
* - 1 => The referenced entity's GUID.
* - 2 => The referenced entity's class name.
*
* Since the referenced entity's class name (meaning the `class` static property,
* not the name of the class itself) is stored in the reference on the parent
* entity, if you change the class name in an update, you need to reassign all
* referenced entities of that class and resave.
* Since the referenced entity's class name (meaning the `class` static
* property, not the name of the class itself) is stored in the reference on the
* parent entity, if you change the class name in an update, you need to
* reassign all referenced entities of that class and resave.
*
* When an entity is loaded, it does not request its referenced entities from
* Nymph. Instead, it creates instances without data called sleeping references.
Expand Down
4 changes: 2 additions & 2 deletions packages/tilmeld-client/src/User.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,8 +122,8 @@ export default class User extends Entity<UserData> {
private static removeNymphResponseListener?: () => void;

/**
* No need to call this function yourself. It is called when the class is loaded. It adds
* listeners to Nymph to handle authentication changes.
* No need to call this function yourself. It is called when the class is
* loaded. It adds listeners to Nymph to handle authentication changes.
*/
public static init() {
if (this.removeNymphResponseListener) {
Expand Down
5 changes: 3 additions & 2 deletions packages/tilmeld/src/Group.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -407,8 +407,9 @@ export default class Group extends AbleObject<GroupData> {
/**
* Get the number of parents the group has.
*
* If the group is a top level group, this will return 0. If it is a child of a top level group,
* this will return 1. If it is a grandchild of a top level group, this will return 2, and so on.
* If the group is a top level group, this will return 0. If it is a child of
* a top level group, this will return 1. If it is a grandchild of a top level
* group, this will return 2, and so on.
*
* Levels will max out at 1024 to avoid recursive loops.
*
Expand Down
96 changes: 52 additions & 44 deletions packages/tilmeld/src/Tilmeld.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,25 +33,27 @@ export default class Tilmeld {
public static currentUser: (User & UserData) | null = 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 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.
* 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.
* 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.
* If you want to support cookie based authentication (which still requires an
* XSRF token for security), you should enable the cookie parser middleware.
*/
public static request: Request;
public static response: Response;

/**
* 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.
* If `ability` is undefined, it will check to see if a user is currently
* logged in.
*
* @param ability The ability.
* @returns Whether the user has the given ability.
Expand Down Expand Up @@ -106,8 +108,8 @@ export default class Tilmeld {
('equal' in selectors[0] &&
selectors[0]['equal']?.[0] !== 'username'))
) {
// If the user is not specifically searching for a GUID or username, and they're not
// allowed to search, it should fail.
// If the user is not specifically searching for a GUID or username,
// and they're not allowed to search, it should fail.
throw new AccessControlError('No permission to search.');
}
}
Expand Down Expand Up @@ -144,8 +146,8 @@ export default class Tilmeld {
}
};

// Filter entities being saved for user permissions, and filter any disallowed changes to AC
// properties.
// Filter entities being saved for user permissions, and filter any
// disallowed changes to AC properties.
const checkPermissionsSaveAndFilterAcChanges = function (
entity: EntityInterface & AccessControlData
) {
Expand All @@ -160,8 +162,8 @@ export default class Tilmeld {
}

if (entity.guid != null) {
// If the entity is not new, check that the user has full access before allowing a change to
// ac properties.
// If the entity is not new, check that the user has full access before
// allowing a change to ac properties.

const originalAc = entity.$getOriginalAcValues();
const newAc = {
Expand Down Expand Up @@ -190,7 +192,8 @@ export default class Tilmeld {
setAcProperties(originalAc);
if (Tilmeld.checkPermissions(entity, Tilmeld.FULL_ACCESS)) {
// Only allow changes to AC properties if the user has full access.
// TODO: only allow changes to `user` and `group` if tilmeld admin or group is user's group.
// TODO: only allow changes to `user` and `group` if tilmeld admin or
// group is user's group.
setAcProperties(newAc);
}
}
Expand All @@ -204,7 +207,8 @@ export default class Tilmeld {
/*
* Add the current user's "user", "group", and access control to new entity.
*
* This occurs right before an entity is saved. It only alters the entity if:
* This occurs right before an entity is saved. It only alters the entity
* if:
*
* - There is a user logged in.
* - The entity is new (doesn't have a GUID.)
Expand Down Expand Up @@ -323,8 +327,8 @@ export default class Tilmeld {
}

/**
* Add selectors to a list of options and selectors which will limit results to only entities the
* current user has access to.
* Add selectors to a list of options and selectors which will limit results
* to only entities the current user has access to.
*
* @param optionsAndSelectors The options and selectors of the query.
*/
Expand Down Expand Up @@ -441,8 +445,8 @@ export default class Tilmeld {
/**
* Check an entity's permissions for a user.
*
* This will check the AC (Access Control) properties of the entity. These include the following
* properties:
* This will check the AC (Access Control) properties of the entity. These
* include the following properties:
*
* - acUser
* - acGroup
Expand All @@ -451,32 +455,34 @@ export default class Tilmeld {
* - 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.
* "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.
* 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.
* - 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 defaults to:
*
* - acUser = Tilmeld.FULL_ACCESS
* - acGroup = Tilmeld.READ_ACCESS
* - acOther = Tilmeld.NO_ACCESS
*
* "acRead", "acWrite", and "acFull" are arrays of users and/or groups that also have those
* permissions.
* "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.
* 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:
* The following conditions will result in different checks, which determine
* whether the check passes:
*
* - The user has the "system/admin" ability. (Always true.)
* - It is a user or group. (True for READ_ACCESS or Tilmeld admins.)
Expand Down Expand Up @@ -613,8 +619,8 @@ export default class Tilmeld {
* @param user The user.
*/
public static fillSession(user: User & UserData) {
// Read groups right now, since gatekeeper needs them, so $udpateDataProtection will fail to
// read them (since it runs gatekeeper).
// Read groups right now, since gatekeeper needs them, so
// $udpateDataProtection will fail to read them (since it runs gatekeeper).
const _group = user.group;
const _groups = user.groups;
this.currentUser = user;
Expand Down Expand Up @@ -685,8 +691,8 @@ export default class Tilmeld {

const cookies = this.request.cookies ?? {};

// If a client does't support cookies, they can use the X-TILMELDAUTH header to provide the auth
// token.
// If a client does't support cookies, they can use the X-TILMELDAUTH header
// to provide the auth token.
let fromAuthHeader = false;
let authToken: string;
if (this.request.header('HTTP_X_TILMELDAUTH') != null) {
Expand All @@ -704,12 +710,12 @@ export default class Tilmeld {
skipXsrfToken ||
this.request.originalUrl.startsWith(this.config.setupPath)
) {
// The request is for the setup app, or we were told to skip the XSRF check, so don't check
// for the XSRF token.
// The request is for the setup app, or we were told to skip the XSRF
// check, so don't check for the XSRF token.
extract = this.config.jwtExtract(authToken);
} else {
// The request is for something else, so check for a valid XSRF token, unless the auth token
// is provided by a header (instead of a cookie).
// The request is for something else, so check for a valid XSRF token,
// unless the auth token is provided by a header (instead of a cookie).
const xsrfToken = this.request.header('HTTP_X_XSRF_TOKEN');
if (xsrfToken == null && !fromAuthHeader) {
return false;
Expand All @@ -731,7 +737,8 @@ export default class Tilmeld {
}

if (expire.valueOf() < Date.now() + this.config.jwtRenew * 1000) {
// If the user is less than renew time from needing a new token, give them a new one.
// If the user is less than renew time from needing a new token, give them
// a new one.
this.login(user, fromAuthHeader);
} else {
this.fillSession(user);
Expand Down Expand Up @@ -786,7 +793,8 @@ export default class Tilmeld {
// /**
// * Sort an array of groups hierarchically.
// *
// * An additional property of the groups can be used to sort them under their parents.
// * An additional property of the groups can be used to sort them under their
// * parents.
// *
// * @param array The array of groups.
// * @param property The name of the property to sort groups by. Undefined for no additional sorting.
Expand Down
29 changes: 17 additions & 12 deletions packages/tilmeld/src/User.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -161,8 +161,8 @@ export default class User extends AbleObject<UserData> {
/**
* 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.
* Gatekeeper will cache the user's abilities that it calculates, so it can
* check faster if that user has been checked before.
*/
private $gatekeeperCache?: { [k: string]: true };
/**
Expand All @@ -174,7 +174,8 @@ export default class User extends AbleObject<UserData> {
*/
private $descendantGroups?: (Group & GroupData)[];
/**
* Temporary storage for passwords. This will be hashed before going into the database.
* Temporary storage for passwords. This will be hashed before going into the
* database.
*/
private $passwordTemp?: string;

Expand Down Expand Up @@ -602,10 +603,11 @@ export default class User extends AbleObject<UserData> {
/**
* Check to see if a user has an ability.
*
* This function will check both user and group abilities, if the user is marked to inherit the
* abilities of its group.
* This function will check both user and group abilities, if the user is
* marked to inherit the abilities of its group.
*
* If `ability` is undefined, it will check to see if the user is currently logged in.
* If `ability` is undefined, it will check to see if the user is currently
* logged in.
*
* If the user has the "system/admin" ability, this function will return true.
*
Expand Down Expand Up @@ -808,7 +810,7 @@ export default class User extends AbleObject<UserData> {
/**
* Check whether the user is in a (primary or secondary) group.
*
* @param mixed $group The group, or the group's GUID.
* @param group The group, or the group's GUID.
* @returns True or false.
*/
public $inGroup(group: (Group & GroupData) | string) {
Expand Down Expand Up @@ -1328,7 +1330,8 @@ export default class User extends AbleObject<UserData> {

// Email changes.
if (!Tilmeld.gatekeeper('tilmeld/admin')) {
// The user isn't an admin, so email address changes should contain some security measures.
// The user isn't an admin, so email address changes should contain some
// security measures.
if (Tilmeld.config.verifyEmail) {
// The user needs to verify this new email address.
if (this.guid == null) {
Expand Down Expand Up @@ -1358,7 +1361,8 @@ export default class User extends AbleObject<UserData> {
} else {
if (
this.$data.secret == null &&
// Make sure the user has at least the rate limit time to cancel an email change.
// Make sure the user has at least the rate limit time to cancel
// an email change.
(this.$data.emailChangeDate == null ||
this.$data.emailChangeDate <
strtotime('-' + Tilmeld.config.emailRateLimit) * 1000)
Expand All @@ -1376,13 +1380,14 @@ export default class User extends AbleObject<UserData> {
this.guid != null &&
this.$data.originalEmail != null &&
this.$data.originalEmail !== this.$data.email &&
// Make sure the user has at least the rate limit time to cancel an email change.
// Make sure the user has at least the rate limit time to cancel an
// email change.
(this.$data.emailChangeDate == null ||
this.$data.emailChangeDate <
strtotime('-' + Tilmeld.config.emailRateLimit) * 1000)
) {
// The user doesn't need to verify their new email address, but should be able to cancel the
// email change from their old address.
// The user doesn't need to verify their new email address, but should
// be able to cancel the email change from their old address.
this.$data.cancelEmailAddress = this.$data.originalEmail;
this.$data.cancelEmailSecret = nanoid();
sendVerification = true;
Expand Down
Loading

0 comments on commit 935be83

Please sign in to comment.