idp-admin 0.3.0 → 0.4.0

package/README.md

@@ -72,7 +72,7 @@ const admin = new IdpAdmin(adapter, {
 `attributes` maps the names your app uses to the provider's own, and only those names compile.
 
 ```ts
-import { UserExistsError } from "idp-admin"
+import { UserExistsError, generateTemporaryPassword } from "idp-admin"
 
 // create a user who must set their own password at first sign-in; send them the temporary one yourself
 try{
@@ -80,7 +80,7 @@ try{
         email: "Dana@Example.com",   // stored and matched as dana@example.com
         name: "Dana Lee",
         attributes: { company: "Acme" },
-        temporaryPassword: "Temp-pass-1!",
+        temporaryPassword: generateTemporaryPassword(),
     })
     await admin.ensureGroup("admins")
     await admin.addToGroup(user.id, "admins")

package/dist/errors.d.ts

@@ -40,18 +40,22 @@ export type AccessReductionStep = "provider-sign-out" | "hook";
 /**
  * The provider change happened, but a step after it didn't, so the user may still have live sessions
  * or provider tokens. The provider change is not undone. Calling the same method again is safe: it
- * repeats every step.
+ * repeats every step. The exception is `deleteGroup`, which stops at the member whose step failed and
+ * leaves the group in place: call `removeFromGroup` for that member and group, then `deleteGroup` again.
  */
 export declare class AccessReductionIncompleteError extends IdpAdminError {
     readonly code = "ACCESS_REDUCTION_INCOMPLETE";
     readonly userId: string;
     readonly action: AccessReductionAction;
+    readonly group: string | undefined;
     readonly failedStep: AccessReductionStep;
     constructor(details: {
         userId: string;
         action: AccessReductionAction;
+        group?: string;
         failedStep: AccessReductionStep;
         cause: unknown;
+        deletingGroup?: boolean;
     });
 }
 /** Every idp-admin error, as a union, so `switch(error.code)` narrows to the matching class. */

package/dist/errors.js

@@ -71,19 +71,28 @@ const STEP_TEXT = {
 /**
  * The provider change happened, but a step after it didn't, so the user may still have live sessions
  * or provider tokens. The provider change is not undone. Calling the same method again is safe: it
- * repeats every step.
+ * repeats every step. The exception is `deleteGroup`, which stops at the member whose step failed and
+ * leaves the group in place: call `removeFromGroup` for that member and group, then `deleteGroup` again.
  */
 class AccessReductionIncompleteError extends IdpAdminError {
     code = "ACCESS_REDUCTION_INCOMPLETE";
     userId;
     action;
+    // the group the user was removed from, for `removed-from-group`
+    group;
     failedStep;
     constructor(details) {
         const reason = details.cause instanceof Error ? details.cause.message : String(details.cause);
-        super(`User ${details.userId} was ${ACTION_TEXT[details.action]} at the provider, but ${STEP_TEXT[details.failedStep]}: ${reason}. ` +
-            "Calling the same method again is safe and retries it.", { cause: details.cause });
+        const action = details.action === "removed-from-group" && details.group !== undefined
+            ? `removed from group ${details.group}`
+            : ACTION_TEXT[details.action];
+        const recovery = details.deletingGroup
+            ? "The group wasn't deleted. Call removeFromGroup for this user and group, then deleteGroup again."
+            : "Calling the same method again is safe and retries it.";
+        super(`User ${details.userId} was ${action} at the provider, but ${STEP_TEXT[details.failedStep]}: ${reason}. ${recovery}`, { cause: details.cause });
         this.userId = details.userId;
         this.action = details.action;
+        this.group = details.group;
         this.failedStep = details.failedStep;
     }
 }

package/dist/idp-admin.d.ts

@@ -78,6 +78,11 @@ export declare class IdpAdmin<TAttr extends string = never> {
     listGroupMembers(group: string): AsyncGenerator<IdpUser<TAttr>>;
     /** Creates the group, or does nothing if it exists. */
     ensureGroup(group: string): Promise<void>;
-    /** Deletes the group, removing every member from it first. @throws {GroupNotFoundError} */
+    /**
+     * Removes every member from the group the way `removeFromGroup` does (signed out at the provider, then
+     * `onAccessReduced`), then deletes the group. If a member's step fails it stops there and leaves the
+     * group in place: call `removeFromGroup` for that member, then `deleteGroup` again.
+     * @throws {GroupNotFoundError} @throws {AccessReductionIncompleteError} a member is removed, but a later step failed
+     */
     deleteGroup(group: string): Promise<void>;
 }

package/dist/idp-admin.js

@@ -73,8 +73,7 @@ class IdpAdmin {
      */
     async disableUser(userId) {
         await this.adapter.setEnabled(userId, false);
-        await this.#signOut(userId, "disabled");
-        await this.#accessReduced({ userId, action: "disabled" });
+        await this.#reduced({ userId, action: "disabled" }, { signOut: true });
     }
     /**
      * Deletes the user, then calls `onAccessReduced`, also when the user was already gone. Deleting ends
@@ -92,7 +91,7 @@ class IdpAdmin {
                 throw error;
             deleted = false;
         }
-        await this.#accessReduced({ userId, action: "deleted" });
+        await this.#reduced({ userId, action: "deleted" }, { signOut: false });
         return deleted;
     }
     // ---- groups
@@ -115,8 +114,7 @@ class IdpAdmin {
             // nobody is in a group that doesn't exist, but the user must still exist
             await this.adapter.getUser(userId);
         }
-        await this.#signOut(userId, "removed-from-group");
-        await this.#accessReduced({ userId, action: "removed-from-group", group });
+        await this.#reduced({ userId, action: "removed-from-group", group }, { signOut: true });
     }
     /** The names of every group the user is in. @throws {UserNotFoundError} */
     listUserGroups(userId) {
@@ -139,25 +137,47 @@ class IdpAdmin {
                 throw error;
         }
     }
-    /** Deletes the group, removing every member from it first. @throws {GroupNotFoundError} */
-    deleteGroup(group) {
-        return this.adapter.deleteGroup(group);
+    /**
+     * Removes every member from the group the way `removeFromGroup` does (signed out at the provider, then
+     * `onAccessReduced`), then deletes the group. If a member's step fails it stops there and leaves the
+     * group in place: call `removeFromGroup` for that member, then `deleteGroup` again.
+     * @throws {GroupNotFoundError} @throws {AccessReductionIncompleteError} a member is removed, but a later step failed
+     */
+    async deleteGroup(group) {
+        // collected first, because removing members while paging through them would skip some
+        const members = [];
+        for await (const member of this.listGroupMembers(group))
+            members.push(member.id);
+        for (const userId of members) {
+            await this.adapter.removeFromGroup(userId, group);
+            await this.#reduced({ userId, action: "removed-from-group", group }, { signOut: true, deletingGroup: true });
+        }
+        await this.adapter.deleteGroup(group);
     }
     // ---- access reduction
-    async #signOut(userId, action) {
-        try {
-            await this.adapter.signOutEverywhere(userId);
-        }
-        catch (cause) {
-            throw new errors_1.AccessReductionIncompleteError({ userId, action, failedStep: "provider-sign-out", cause });
+    // the steps after a provider change that reduced someone's access: provider sign-out, then the hook
+    async #reduced(event, options) {
+        const incomplete = (failedStep, cause) => new errors_1.AccessReductionIncompleteError({
+            userId: event.userId,
+            action: event.action,
+            group: event.action === "removed-from-group" ? event.group : undefined,
+            failedStep,
+            cause,
+            deletingGroup: options.deletingGroup,
+        });
+        if (options.signOut) {
+            try {
+                await this.adapter.signOutEverywhere(event.userId);
+            }
+            catch (cause) {
+                throw incomplete("provider-sign-out", cause);
+            }
         }
-    }
-    async #accessReduced(event) {
         try {
             await this.#onAccessReduced?.(event);
         }
         catch (cause) {
-            throw new errors_1.AccessReductionIncompleteError({ userId: event.userId, action: event.action, failedStep: "hook", cause });
+            throw incomplete("hook", cause);
         }
     }
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export type { AdapterCreateUserInput, AdapterInviteUserInput, IdpAdapter } from "./adapter";
 export { AccessReductionIncompleteError, GroupExistsError, GroupNotFoundError, IdpAdminError, NotSupportedError, UserExistsError, UserNotFoundError, type AccessReductionAction, type AccessReductionStep, type AnyIdpAdminError, } from "./errors";
 export { IdpAdmin, type AccessReducedEvent, type IdpAdminOptions, type IdpAdminSupports } from "./idp-admin";
+export { generateTemporaryPassword, type TemporaryPasswordOptions } from "./passwords";
 export type { IdpUser, Page, UserAttributes, UserStatus } from "./types";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IdpAdmin = exports.UserNotFoundError = exports.UserExistsError = exports.NotSupportedError = exports.IdpAdminError = exports.GroupNotFoundError = exports.GroupExistsError = exports.AccessReductionIncompleteError = void 0;
+exports.generateTemporaryPassword = exports.IdpAdmin = exports.UserNotFoundError = exports.UserExistsError = exports.NotSupportedError = exports.IdpAdminError = exports.GroupNotFoundError = exports.GroupExistsError = exports.AccessReductionIncompleteError = void 0;
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "AccessReductionIncompleteError", { enumerable: true, get: function () { return errors_1.AccessReductionIncompleteError; } });
 Object.defineProperty(exports, "GroupExistsError", { enumerable: true, get: function () { return errors_1.GroupExistsError; } });
@@ -11,3 +11,5 @@ Object.defineProperty(exports, "UserExistsError", { enumerable: true, get: funct
 Object.defineProperty(exports, "UserNotFoundError", { enumerable: true, get: function () { return errors_1.UserNotFoundError; } });
 var idp_admin_1 = require("./idp-admin");
 Object.defineProperty(exports, "IdpAdmin", { enumerable: true, get: function () { return idp_admin_1.IdpAdmin; } });
+var passwords_1 = require("./passwords");
+Object.defineProperty(exports, "generateTemporaryPassword", { enumerable: true, get: function () { return passwords_1.generateTemporaryPassword; } });

package/dist/passwords.d.ts

@@ -0,0 +1,10 @@
+export type TemporaryPasswordOptions = {
+    length?: number;
+};
+/**
+ * A random temporary password for `createUser` or `setPassword`, from Node's cryptographic random
+ * source. It always has at least one uppercase letter, lowercase letter, digit and symbol, so default
+ * password policies accept it, and is 16 characters unless `length` says otherwise. A provider policy
+ * stricter than that (a longer minimum, say) needs a matching `length`.
+ */
+export declare function generateTemporaryPassword(options?: TemporaryPasswordOptions): string;

package/dist/passwords.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateTemporaryPassword = generateTemporaryPassword;
+const node_crypto_1 = require("node:crypto");
+const UPPER = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const LOWER = "abcdefghijklmnopqrstuvwxyz";
+const DIGITS = "0123456789";
+// a subset every provider accepts, and that needs no escaping in an email or a URL
+const SYMBOLS = "!@#$%^&*";
+const ALL = UPPER + LOWER + DIGITS + SYMBOLS;
+/**
+ * A random temporary password for `createUser` or `setPassword`, from Node's cryptographic random
+ * source. It always has at least one uppercase letter, lowercase letter, digit and symbol, so default
+ * password policies accept it, and is 16 characters unless `length` says otherwise. A provider policy
+ * stricter than that (a longer minimum, say) needs a matching `length`.
+ */
+function generateTemporaryPassword(options = {}) {
+    const length = options.length ?? 16;
+    if (!Number.isInteger(length) || length < 8 || length > 256) {
+        throw new RangeError(`A temporary password's length must be a whole number from 8 to 256, not ${length}`);
+    }
+    const characters = [UPPER, LOWER, DIGITS, SYMBOLS].map(pick);
+    while (characters.length < length)
+        characters.push(pick(ALL));
+    // shuffle, so the guaranteed characters aren't always first
+    for (let i = characters.length - 1; i > 0; i--) {
+        const j = (0, node_crypto_1.randomInt)(i + 1);
+        const swapped = characters[i];
+        characters[i] = characters[j];
+        characters[j] = swapped;
+    }
+    return characters.join("");
+}
+function pick(from) {
+    return from[(0, node_crypto_1.randomInt)(from.length)];
+}

package/docs/index.md

@@ -39,12 +39,12 @@ type AccessReducedEvent =
 ### Shared rules
 
 - **Emails** are trimmed and lowercased before they reach the adapter, in `createUser`, `createUserWithInvite` and `findUserByEmail`. `Dana@Example.com` and `dana@example.com` are the same user.
-- **Taking access away** (`deleteUser`, `disableUser`, `removeFromGroup`) runs these steps in order:
+- **Taking access away** (`deleteUser`, `disableUser`, `removeFromGroup`, and `deleteGroup` for each member) runs these steps in order:
   1. the change at the provider
-  2. provider sign-out (`signOutEverywhere`), for `disableUser` and `removeFromGroup`. Deleting already ends the user's tokens at the provider, so `deleteUser` skips it
+  2. provider sign-out (`signOutEverywhere`), for everything but `deleteUser`. Deleting already ends the user's tokens at the provider, so `deleteUser` skips it
   3. `onAccessReduced`
 
-  If step 2 or 3 fails, the method throws `AccessReductionIncompleteError` and the provider change stands. All three methods are safe to repeat and run every step each time, so calling the same method again is the recovery.
+  If step 2 or 3 fails, the method throws `AccessReductionIncompleteError` and the provider change stands. `deleteUser`, `disableUser` and `removeFromGroup` are safe to repeat and run every step each time, so calling the same method again is the recovery. `deleteGroup` stops at the member whose step failed and leaves the group in place; the member is already out of it, so calling `deleteGroup` again wouldn't reach them. Call `removeFromGroup(error.userId, group)`, then `deleteGroup` again. The error's message says so.
 - **Provider sign-out revokes refresh tokens.** Access and ID tokens already issued stay valid until they expire (about an hour by default on Cognito). Ending the app's sessions in `onAccessReduced` is what takes effect immediately.
 - **Lists** are async iterators over the adapter's pages. The next page is fetched only when the loop reaches it, and `break` stops fetching.
 - **Optional features:** a method the adapter lacks throws `NotSupportedError`. `supports` tells you beforehand.
@@ -70,7 +70,7 @@ type AccessReducedEvent =
 | `listUserGroups(userId)` | `AsyncGenerator<string>` | The names of the groups a user is in. |
 | `listGroupMembers(group)` | `AsyncGenerator<IdpUser>` | Throws `GroupNotFoundError`. |
 | `ensureGroup(group)` | `void` | Creates the group, or does nothing if it exists, including when another caller creates it at the same moment. |
-| `deleteGroup(group)` | `void` | Removes every member first. Doesn't call `onAccessReduced`; to end members' sessions, call `removeFromGroup` for each before deleting it. |
+| `deleteGroup(group)` | `void` | Removes every member as `removeFromGroup` does (provider sign-out, then `onAccessReduced` for each), then deletes the group. Throws `GroupNotFoundError`. See **Taking access away** for recovering from a failure part way. |
 
 Unless a row says otherwise, a method addressing a missing user throws `UserNotFoundError`.
 
@@ -79,6 +79,22 @@ Unless a row says otherwise, a method addressing a missing user throws `UserNotF
 | `adapter` | The adapter passed in, for its `native` client and anything the shared methods don't cover. Calls made on it directly skip the shared rules. |
 | `supports` | `{ createUserWithInvite: boolean; resendInvite: boolean }`: which optional features the adapter has. |
 
+## `generateTemporaryPassword(options?)`
+
+```ts
+import { generateTemporaryPassword } from "idp-admin"
+
+await admin.createUser({ email, temporaryPassword: generateTemporaryPassword() })
+```
+
+A random password for `createUser` or a temporary `setPassword`, from Node's cryptographic random source (`crypto.randomInt`).
+
+| Option | Default | Meaning |
+|---|---|---|
+| `length` | `16` | A whole number from 8 to 256. Anything else throws a `RangeError`. |
+
+It always contains at least one uppercase letter, lowercase letter, digit and symbol, in random positions, so the default password policies of Cognito and Keycloak accept it. Symbols are from `!@#$%^&*`, which every provider accepts and which need no escaping in an email or a URL. If your pool or realm requires more than 16 characters, pass a matching `length`.
+
 ## Types
 
 ### `IdpUser<TAttr>`
@@ -146,13 +162,14 @@ Every error idp-admin throws on purpose extends `IdpAdminError`, so `instanceof
 | `GroupNotFoundError` | `GROUP_NOT_FOUND` | `group` | The group doesn't exist. |
 | `GroupExistsError` | `GROUP_EXISTS` | `group` | Creating a group that exists. |
 | `NotSupportedError` | `NOT_SUPPORTED` | `feature` | The adapter can't do what was asked; `feature` names the method or option. |
-| `AccessReductionIncompleteError` | `ACCESS_REDUCTION_INCOMPLETE` | `userId`, `action`, `failedStep`, `cause` | A user was deleted, disabled or removed from a group at the provider, but a later step failed. |
+| `AccessReductionIncompleteError` | `ACCESS_REDUCTION_INCOMPLETE` | `userId`, `action`, `group`, `failedStep`, `cause` | A user was deleted, disabled or removed from a group at the provider, but a later step failed. |
 
 `AccessReductionIncompleteError`:
 - `action` is `"deleted"`, `"disabled"` or `"removed-from-group"`: what already happened at the provider. It is not undone.
+- `group` is the group they were removed from, for `"removed-from-group"`; otherwise `undefined`.
 - `failedStep` is `"provider-sign-out"` or `"hook"`: the step after it that failed.
 - `cause` is the original error.
-- Calling the same method again is safe and repeats every step.
+- Calling the same method again is safe and repeats every step, except after `deleteGroup`: call `removeFromGroup(userId, group)`, then `deleteGroup` again.
 
 ## `IdpAdapter<TAttr>`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idp-admin",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "One user-management API for any identity provider.",
   "keywords": [
     "identity-provider",
@@ -76,5 +76,10 @@
     "jest": "^30.5.2",
     "tsx": "^4.23.15",
     "typescript": "5.9.3"
+  },
+  "overrides": {
+    "@istanbuljs/load-nyc-config": {
+      "js-yaml": "^4.1.0"
+    }
   }
 }