@nymphjs/tilmeld 1.0.0-beta.14 → 1.0.0-beta.140

package/README.md

@@ -1,8 +1,10 @@
 # Tilmeld - User/Group System for Nymph
 
-Powerful object data storage and querying.
+Application Data and Access Framework for Node.js and the browser.
 
-Tilmeld (the d is silent) is a user and group management system for Nymph. It provides strict access controls to protect entities from unauthorized access/modification. It allows for granting and revoking ad hoc abilities to users and groups, then checking for those abilities. It provides authentication services and features protection against XSRF attacks.
+https://nymph.io/
+
+Tilmeld (the d is silent) is a user and group management, access control, and authentication system for Nymph. It allows creation and management of users and groups, including the ability to manage multiple domains. It provides strict access controls to protect entities from unauthorized access/modification. It allows for granting and revoking ad hoc abilities to users and groups, then checking for those abilities. It provides authentication services and features protection against XSRF attacks.
 
 ## Installation
 
@@ -38,7 +40,7 @@ const nymph = new Nymph(
   new SQLite3Driver({
     filename: ':memory:',
   }),
-  tilmeld
+  tilmeld,
 );
 
 // These are the classes specific to this instance of Tilmeld.
@@ -47,11 +49,25 @@ const { User, Group } = tilmeld;
 
 ## Options
 
-See the [config declaration file](src/conf/d.ts).
+See the [config declaration file](src/conf/index.ts).
+
+## Abilities
+
+There are a few abilities that Tilmeld uses internally:
+
+- `system/admin` - A user with this ability has **all** abilities.
+- `tilmeld/admin` - Allow the user to manage and edit other user's account and group information and grant/revoke abilities.
+- `tilmeld/switch` - Allow the user to switch to other users (log in as them without their password).
+- `tilmeld/domain/[domain]/admin` - Allow a user to create and edit users in a domain.
+- `uid/get/[name]` - Allow the user to read the named UID.
+- `uid/new/[name]` - Allow the user to read, create, and increment the named UID.
+- `uid/set/[name]` - Allow the user to read, create, increment, set, and delete the named UID.
+
+The admin and switch abilities cannot be inherited from groups.
 
 # License
 
-Copyright 2021 SciActive Inc
+Copyright 2021-2026 SciActive Inc
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

package/dist/AbleObject.d.ts

@@ -1,7 +1,25 @@
 import { Entity } from '@nymphjs/nymph';
-export default abstract class AbleObject<T extends {
+export interface AbleObjectData {
     abilities?: string[];
-}> extends Entity<T> {
+}
+export interface AbleObject<T extends {}> extends AbleObjectData {
+}
+/**
+ * AbleObject abstract class.
+ *
+ * Used in entities which support abilities, such as users and groups.
+ */
+export declare abstract class AbleObject<T extends {}> extends Entity<T & AbleObjectData> {
+    /**
+     * Grant an ability.
+     *
+     * @param ability The ability.
+     */
     $grant(ability: string): void;
+    /**
+     * Revoke an ability.
+     *
+     * @param ability The ability.
+     */
     $revoke(ability: string): void;
 }

package/dist/AbleObject.js

@@ -1,27 +1,39 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const nymph_1 = require("@nymphjs/nymph");
-class AbleObject extends nymph_1.Entity {
+import { Entity } from '@nymphjs/nymph';
+/**
+ * AbleObject abstract class.
+ *
+ * Used in entities which support abilities, such as users and groups.
+ */
+export class AbleObject extends Entity {
+    /**
+     * Grant an ability.
+     *
+     * @param ability The ability.
+     */
     $grant(ability) {
-        if (!Array.isArray(this.$data.abilities)) {
-            this.$data.abilities = [];
+        if (!Array.isArray(this.abilities)) {
+            this.abilities = [];
         }
-        if (this.$data.abilities.indexOf(ability) === -1) {
-            this.$data.abilities.push(ability);
+        if (!this.abilities.includes(ability)) {
+            this.abilities.push(ability);
         }
     }
+    /**
+     * Revoke an ability.
+     *
+     * @param ability The ability.
+     */
     $revoke(ability) {
-        if (!Array.isArray(this.$data.abilities)) {
-            this.$data.abilities = [];
+        if (!Array.isArray(this.abilities)) {
+            this.abilities = [];
         }
         let idx;
         do {
-            idx = this.$data.abilities.indexOf(ability);
+            idx = this.abilities.indexOf(ability);
             if (idx !== -1) {
-                this.$data.abilities.splice(idx, 1);
+                this.abilities.splice(idx, 1);
             }
         } while (idx !== -1);
     }
 }
-exports.default = AbleObject;
 //# sourceMappingURL=AbleObject.js.map

package/dist/AbleObject.js.map

@@ -1 +1 @@
-{"version":3,"file":"AbleObject.js","sourceRoot":"","sources":["../src/AbleObject.ts"],"names":[],"mappings":";;AAAA,0CAAwC;AAOxC,MAA8B,UAE5B,SAAQ,cAAS;IAMV,MAAM,CAAC,OAAe;QAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE;YACxC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC;SAC3B;QACD,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE;YAChD,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;SACpC;IACH,CAAC;IAOM,OAAO,CAAC,OAAe;QAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE;YACxC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC;SAC3B;QACD,IAAI,GAAW,CAAC;QAChB,GAAG;YACD,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAC5C,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE;gBACd,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;aACrC;SACF,QAAQ,GAAG,KAAK,CAAC,CAAC,EAAE;IACvB,CAAC;CACF;AAlCD,6BAkCC"}
+{"version":3,"file":"AbleObject.js","sourceRoot":"","sources":["../src/AbleObject.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAQxC;;;;GAIG;AACH,MAAM,OAAgB,UAAyB,SAAQ,MAEtD;IACC;;;;OAIG;IACI,MAAM,CAAC,OAAe;QAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;QACtB,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,OAAO,CAAC,OAAe;QAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;QACtB,CAAC;QACD,IAAI,GAAW,CAAC;QAChB,GAAG,CAAC;YACF,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACtC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;gBACf,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAChC,CAAC;QACH,CAAC,QAAQ,GAAG,KAAK,CAAC,CAAC,EAAE;IACvB,CAAC;CACF"}

package/dist/Group.d.ts

@@ -1,25 +1,109 @@
-import { EntityData, EntityJson, EntityPatch, Options, Selector, SerializedEntityData } from '@nymphjs/nymph';
-import type Tilmeld from './Tilmeld';
-import AbleObject from './AbleObject';
-import User, { UserData } from './User';
-export type GroupData = {
+import { type EntityJson, type EntityPatch, type Options, type Selector, type SerializedEntityData } from '@nymphjs/nymph';
+import { AbleObject } from './AbleObject.js';
+import { User as UserClass } from './User.js';
+export type GroupEventType = 'checkGroupname' | 'beforeSave' | 'afterSave' | 'beforeDelete' | 'afterDelete';
+/**
+ * This is run when the user has entered an otherwise valid groupname into the
+ * signup form. It should return a result, which when false will stop the
+ * process and return the included message, disallowing the groupname.
+ */
+export type TilmeldCheckGroupnameCallback = (group: Group, data: {
+    groupname: string;
+}) => Promise<{
+    result: boolean;
+    message?: string;
+}>;
+/**
+ * This is run just before the group is saved, so all checks have passed.
+ *
+ * The transaction is available in `group.$nymph`.
+ */
+export type TilmeldBeforeGroupSaveCallback = (group: Group) => Promise<void>;
+/**
+ * This is run before the transaction is committed, and you can perform
+ * additional functions on the transaction, which is available in
+ * `group.$nymph`.
+ */
+export type TilmeldAfterGroupSaveCallback = (group: Group) => Promise<void>;
+/**
+ * The transaction is available in `group.$nymph`.
+ */
+export type TilmeldBeforeGroupDeleteCallback = (group: Group) => Promise<void>;
+/**
+ * This is run before the transaction is committed, and you can perform
+ * additional functions on the transaction, which is available in
+ * `group.$nymph`.
+ */
+export type TilmeldAfterGroupDeleteCallback = (group: Group) => Promise<void>;
+export interface GroupData {
+    /**
+     * The abilities granted to the group.
+     */
     abilities?: string[];
+    /**
+     * The group's groupname.
+     */
     groupname?: string;
+    /**
+     * The group's name.
+     */
     name?: string;
+    /**
+     * The group's email address.
+     */
     email?: string;
+    /**
+     * The group's avatar URL. (Use getAvatar() to support Gravatar.)
+     */
     avatar?: string;
+    /**
+     * The group's telephone number.
+     */
     phone?: string;
-    parent?: Group & GroupData;
-    user?: (User & UserData) | null;
+    /**
+     * The group's parent.
+     */
+    parent?: Group;
+    /**
+     * If generatePrimary is on, this will be the user who generated this group.
+     */
+    user?: UserClass | null;
+    /**
+     * Whether the group can be used.
+     */
     enabled?: boolean;
+    /**
+     * Whether this group is the default primary group for new users.
+     */
     defaultPrimary?: boolean;
+    /**
+     * Whether this group is a default secondary group for new users.
+     */
     defaultSecondary?: boolean;
+    /**
+     * Whether this group is a default secondary group for unverified users.
+     */
     unverifiedSecondary?: boolean;
-};
-export default class Group extends AbleObject<GroupData> {
-    static tilmeld: Tilmeld;
+}
+export interface Group extends GroupData {
+}
+/**
+ * A user group data model.
+ *
+ * Written by Hunter Perrin for SciActive.
+ *
+ * @author Hunter Perrin <hperrin@port87.com>
+ * @copyright SciActive Inc
+ * @see http://nymph.io/
+ */
+export declare class Group extends AbleObject<GroupData> {
     static ETYPE: string;
     static class: string;
+    private static checkGroupnameCallbacks;
+    private static beforeSaveCallbacks;
+    private static afterSaveCallbacks;
+    private static beforeDeleteCallbacks;
+    private static afterDeleteCallbacks;
     private static DEFAULT_PRIVATE_DATA;
     private static DEFAULT_ALLOWLIST_DATA;
     protected $tags: never[];
@@ -29,35 +113,114 @@ export default class Group extends AbleObject<GroupData> {
     static searchRestrictedData: string[];
     protected $allowlistData?: string[] | undefined;
     protected $allowlistTags?: string[];
+    /**
+     * This should only be used by the backend.
+     */
     private $skipAcWhenSaving;
-    static factory(guid?: string): Promise<Group & GroupData>;
-    static factoryGroupname(groupname?: string): Promise<Group & GroupData>;
-    static factorySync(guid?: string): Group & GroupData;
-    constructor(guid?: string);
-    static getPrimaryGroups(options?: Options, selectors?: Selector[]): Promise<(Group & GroupData)[]>;
-    static getSecondaryGroups(options?: Options, selectors?: Selector[]): Promise<(Group & GroupData)[]>;
+    /**
+     * This should only be used by the backend.
+     */
+    private $skipAcWhenDeleting;
+    /**
+     * Used to save the current groupname for domain admin permissions.
+     */
+    $originalGroupname?: string;
+    static getFTSText(name: string, value: any): string | null;
+    static factoryGroupname(groupname?: string): Promise<Group>;
+    /**
+     * Get all the groups that can be assigned as primary groups.
+     *
+     * @param options The options for an optional search query.
+     * @param selectors The selectors for an optional search query.
+     * @returns An array of the assignable primary groups.
+     */
+    static getPrimaryGroups(options?: Options, selectors?: Selector[]): Promise<Group[]>;
+    /**
+     * Get all the groups that can be assigned as secondary groups.
+     *
+     * @param options The options for an optional search query.
+     * @param selectors The selectors for an optional search query.
+     * @returns An array of the assignable secondary groups.
+     */
+    static getSecondaryGroups(options?: Options, selectors?: Selector[]): Promise<Group[]>;
     private static getAssignableGroups;
+    constructor();
+    $getUniques(): Promise<string[]>;
     $getAvatar(): string;
     $jsonAcceptData(input: EntityJson, allowConflict?: boolean): void;
     $jsonAcceptPatch(patch: EntityPatch, allowConflict?: boolean): void;
-    $putData(data: EntityData, sdata?: SerializedEntityData): void;
-    $updateDataProtection(givenUser?: User & UserData): void;
-    $isDescendant(givenGroup: (Group & GroupData) | string): boolean;
-    $getChildren(): Promise<(Group & GroupData)[]>;
-    $getDescendants(andSelf?: boolean): Promise<(Group & GroupData)[]>;
-    $getDescendantsSync(andSelf?: boolean): (Group & GroupData)[];
-    $getLevel(): number;
-    $getUsers(descendants?: boolean, limit?: number, offset?: number): Promise<(User & UserData)[]>;
+    private $checkIncomingAbilities;
+    $putData(data: GroupData, sdata?: SerializedEntityData, source?: 'server'): void;
+    /**
+     * Update the data protection arrays for the current user.
+     */
+    $updateDataProtection(): void;
+    /**
+     * Check whether the group is a descendant of the given group.
+     *
+     * @param group The group, or the group's GUID.
+     * @returns True or false.
+     */
+    $isDescendant(givenGroup: Group | string): Promise<boolean>;
+    /**
+     * Gets an array of the group's child groups.
+     *
+     * @returns An array of groups.
+     */
+    $getChildren(): Promise<Group[]>;
+    /**
+     * Gets an array of the group's descendant groups.
+     *
+     * @param andSelf Include this group in the returned array.
+     * @param andDisabled Include disabled groups.
+     * @returns An array of groups.
+     */
+    $getDescendants(andSelf?: boolean, andDisabled?: boolean): Promise<Group[]>;
+    /**
+     * 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.
+     *
+     * Levels will max out at 1024 to avoid recursive loops.
+     *
+     * @returns The level of the group.
+     */
+    $getLevel(): Promise<number>;
+    /**
+     * Gets an array of enabled users in the group.
+     *
+     * @param descendants Include users in all descendant groups too.
+     * @param limit The limit for the query.
+     * @param offset The offset for the query.
+     * @returns An array of users.
+     */
+    $getUsers(descendants?: boolean, limit?: number, offset?: number): Promise<UserClass[]>;
+    /**
+     * Check that a groupname is valid.
+     *
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     $checkGroupname(): Promise<{
         result: boolean;
         message: string;
     }>;
+    /**
+     * Check that an email is unique.
+     *
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     $checkEmail(): Promise<{
         result: boolean;
         message: string;
     }>;
-    $save(): Promise<boolean>;
-    $saveSkipAC(): Promise<boolean>;
+    $save(): Promise<void>;
+    $saveSkipAC(): Promise<void>;
     $tilmeldSaveSkipAC(): boolean;
-    $delete(): Promise<boolean>;
+    $delete(): Promise<void>;
+    $deleteSkipAC(): Promise<void>;
+    $tilmeldDeleteSkipAC(): boolean;
+    static on<T extends GroupEventType>(event: T, callback: T extends 'checkGroupname' ? TilmeldCheckGroupnameCallback : T extends 'beforeSave' ? TilmeldBeforeGroupSaveCallback : T extends 'afterSave' ? TilmeldAfterGroupSaveCallback : T extends 'beforeDelete' ? TilmeldBeforeGroupDeleteCallback : T extends 'afterDelete' ? TilmeldAfterGroupDeleteCallback : never): () => boolean;
+    static off<T extends GroupEventType>(event: T, callback: T extends 'checkGroupname' ? TilmeldCheckGroupnameCallback : T extends 'beforeSave' ? TilmeldBeforeGroupSaveCallback : T extends 'afterSave' ? TilmeldAfterGroupSaveCallback : T extends 'beforeDelete' ? TilmeldBeforeGroupDeleteCallback : T extends 'afterDelete' ? TilmeldAfterGroupDeleteCallback : never): boolean;
 }