@enonic-types/lib-auth 8.0.0-B4 → 8.0.0-B5

package/auth.d.ts

@@ -136,6 +136,7 @@ export interface CreateUserParams {
  * @param {string} params.name User login name to set.
  * @param {string} [params.displayName] User display name.
  * @param {string} [params.email] User email.
+ * @returns {User} The created user.
  */
 export declare function createUser(params: CreateUserParams): User;
 export interface ModifyUserParams {
@@ -150,7 +151,7 @@ export interface ModifyUserParams {
  * @param {object} params JSON parameters.
  * @param {string} params.key Principal key of the user to modify.
  * @param {function} params.editor User editor function to apply to user.
- * @returns {User} the updated user or null if a  user not found.
+ * @returns {User | null} The updated user, or null if user not found.
  */
 export declare function modifyUser(params: ModifyUserParams): User | null;
 export interface CreateGroupParams {
@@ -168,7 +169,8 @@ export interface CreateGroupParams {
  * @param {string} params.idProvider Key for id provider where group has to be created.
  * @param {string} params.name Group name.
  * @param {string} [params.displayName] Group display name.
- * @param {string} [params.description] as principal description .
+ * @param {string} [params.description] Group description.
+ * @returns {Group} The created group.
  */
 export declare function createGroup(params: CreateGroupParams): Group;
 export interface ModifyGroupParams {
@@ -183,25 +185,25 @@ export interface ModifyGroupParams {
  * @param {object} params JSON parameters.
  * @param {string} params.key Principal key of the group to modify.
  * @param {function} params.editor Group editor function to apply to group.
- * @returns {Group} the updated group or null if a group not found.
+ * @returns {Group | null} The updated group, or null if group not found.
  */
 export declare function modifyGroup(params: ModifyGroupParams): Group | null;
 /**
- * Adds members to a principal (user or role).
+ * Adds members to a principal (group or role).
  *
  * @example-ref examples/auth/addMembers.js
  *
  * @param {string} principalKey Key of the principal to add members to.
- * @param {Array<string>} members Keys of users and groups to add.
+ * @param {string[]} members Keys of users and groups to add.
  */
 export declare function addMembers(principalKey: GroupKey | RoleKey, members: (UserKey | GroupKey)[]): void;
 /**
- * Removes members from a principal (user or role).
+ * Removes members from a principal (group or role).
  *
  * @example-ref examples/auth/removeMembers.js
  *
  * @param {string} principalKey Key of the principal to remove members from.
- * @param {string} members Keys of the principals to remove.
+ * @param {string[]} members Keys of the principals to remove.
  */
 export declare function removeMembers(principalKey: GroupKey | RoleKey, members: (UserKey | GroupKey)[]): void;
 export interface FindPrincipalsParams {
@@ -249,7 +251,7 @@ export declare function deletePrincipal(principalKey: PrincipalKey): boolean;
  *
  * @returns {object} The ID provider configuration as JSON.
  */
-export declare function getIdProviderConfig<IdProviderConfig extends Record<string, unknown>>(): IdProviderConfig | null;
+export declare function getIdProviderConfig<Config extends Record<string, unknown>>(): Config | null;
 export interface GetProfileParams {
     key: UserKey;
     scope?: string;
@@ -306,9 +308,11 @@ export interface CreateRoleParams {
  *
  * @example-ref examples/auth/createRole.js
  *
+ * @param {object} params JSON parameters.
  * @param {string} params.name Role name.
  * @param {string} [params.displayName] Role display name.
- * @param {string} [params.description] as principal description .
+ * @param {string} [params.description] Role description.
+ * @returns {Role} The created role.
  */
 export declare function createRole(params: CreateRoleParams): Role;
 export interface ModifyRoleParams {
@@ -323,6 +327,94 @@ export interface ModifyRoleParams {
  * @param {object} params JSON parameters.
  * @param {string} params.key Principal key of the role to modify.
  * @param {function} params.editor Role editor function to apply to role.
- * @returns {Role} the updated role or null if a role not found.
+ * @returns {Role | null} The updated role, or null if role not found.
  */
 export declare function modifyRole(params: ModifyRoleParams): Role | null;
+export type IdProviderAccess = 'READ' | 'CREATE_USERS' | 'WRITE_USERS' | 'ID_PROVIDER_MANAGER' | 'ADMINISTRATOR';
+export interface IdProviderAccessControlEntry {
+    principal: PrincipalKey;
+    access: IdProviderAccess;
+}
+/**
+ * Configuration that binds an id provider to the application implementing
+ * its authentication flow.
+ *
+ * An id provider can be bound to at most **one** application via
+ * `applicationKey`. The same application may, in turn, back several id
+ * providers — each with its own `config` tree (e.g. a `staff` and a
+ * `customers` provider both implemented by the same id-provider app).
+ *
+ * An id provider without `idProviderConfig` is incomplete and most
+ * flows that rely on it won't work until a binding is added.
+ */
+export interface IdProviderConfig {
+    /**
+     * Key of the application whose handlers serve requests for this
+     * provider.
+     */
+    applicationKey: string;
+    /**
+     * Per-instance configuration tree, exposed to the bound application.
+     */
+    config?: Record<string, unknown>;
+}
+/**
+ * An id provider. Has 0 or 1 bound application via `idProviderConfig`;
+ * the binding determines which app handles login, logout, registration,
+ * and similar flows for this provider.
+ */
+export interface IdProvider {
+    /** Unique key identifying this provider (e.g. `system`, `simpleid`). */
+    key: string;
+    /** Human-readable label shown in admin UIs. */
+    displayName: string;
+    /** Optional free-text description. */
+    description?: string;
+    /**
+     * Application binding. Absent ⇒ the provider is incomplete and
+     * dependent flows generally won't work.
+     */
+    idProviderConfig?: IdProviderConfig;
+}
+/**
+ * Parameters for {@link createIdProvider}. See {@link IdProvider} for the
+ * meaning of each field; without `idProviderConfig` the provider is
+ * incomplete.
+ */
+export interface CreateIdProviderParams {
+    key: string;
+    displayName: string;
+    description?: string;
+    idProviderConfig?: IdProviderConfig;
+    permissions?: IdProviderAccessControlEntry[];
+}
+/**
+ * Creates an id provider.
+ *
+ * An id provider can be bound to at most one application via
+ * `params.idProviderConfig`. Without it the provider is incomplete and
+ * most flows that rely on it won't work until a binding is added.
+ *
+ * @example-ref examples/auth/createIdProvider.js
+ *
+ * @param {object} params JSON parameters.
+ * @param {string} params.key Id provider key.
+ * @param {string} params.displayName Id provider display name.
+ * @param {string} [params.description] Id provider description.
+ * @param {object} [params.idProviderConfig] Binds this provider to one application. Without it the provider is incomplete.
+ * @param {string} params.idProviderConfig.applicationKey Application that handles requests for this provider. Required when `idProviderConfig` is set.
+ * @param {object} [params.idProviderConfig.config] Per-instance configuration tree passed to the bound application.
+ * @param {Array<object>} [params.permissions] Id provider permissions.
+ * @returns {IdProvider} The created id provider.
+ */
+export declare function createIdProvider(params: CreateIdProviderParams): IdProvider;
+/**
+ * Returns all id providers. Each entry's `idProviderConfig` is present
+ * only when the provider is bound to an application; incomplete
+ * providers come back without it.
+ *
+ * @example-ref examples/auth/getIdProviders.js
+ *
+ * @returns {Array<IdProvider>} List of id providers.
+ */
+export declare function getIdProviders(): IdProvider[];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@enonic-types/lib-auth",
-    "version": "8.0.0-B4",
+    "version": "8.0.0-B5",
     "description": "Type definitions for lib-auth.",
     "types": "auth.d.ts",
     "files": [
@@ -27,7 +27,7 @@
     },
     "homepage": "https://github.com/enonic/xp/tree/master#readme",
     "dependencies": {
-        "@enonic-types/core": "8.0.0-B4"
+        "@enonic-types/core": "8.0.0-B5"
     },
     "publishConfig": {
         "access": "public"