idp-admin 0.2.0 → 0.3.0

package/dist/cognito/index.js

@@ -6,9 +6,10 @@ const errors_1 = require("../errors");
 const STATUSES = {
     CONFIRMED: "active",
     FORCE_CHANGE_PASSWORD: "password_change_required",
-    RESET_REQUIRED: "password_change_required",
-    // Cognito suspects the password leaked, so the user must set a new one
-    COMPROMISED: "password_change_required",
+    // an admin reset the password; the user must use the forgot-password code to set a new one
+    RESET_REQUIRED: "password_reset_required",
+    // Cognito suspects the password leaked, so the user must reset it the same way
+    COMPROMISED: "password_reset_required",
     UNCONFIRMED: "unconfirmed",
     EXTERNAL_PROVIDER: "federated",
 };

package/dist/fake/index.d.ts

@@ -27,6 +27,12 @@ export declare class FakeAdapter<const TAttr extends string = never> implements
         name?: string;
         attributes?: UserAttributes<TAttr>;
     }): IdpUser<TAttr>;
+    /**
+     * Requires the user to reset their password, as an admin reset at a real provider does, so their
+     * status becomes `password_reset_required` until a password is set. Only the fake can do this
+     * directly. A federated user is unaffected. Synchronous. @throws {UserNotFoundError}
+     */
+    requirePasswordReset(userId: string): void;
     createUser(input: AdapterCreateUserInput<TAttr>): Promise<IdpUser<TAttr>>;
     createUserWithInvite(input: AdapterInviteUserInput<TAttr>): Promise<IdpUser<TAttr>>;
     getUser(userId: string): Promise<IdpUser<TAttr>>;

package/dist/fake/index.js

@@ -33,6 +33,16 @@ class FakeAdapter {
     addFederatedUser(input) {
         return copy(this.#add(input, "federated"));
     }
+    /**
+     * Requires the user to reset their password, as an admin reset at a real provider does, so their
+     * status becomes `password_reset_required` until a password is set. Only the fake can do this
+     * directly. A federated user is unaffected. Synchronous. @throws {UserNotFoundError}
+     */
+    requirePasswordReset(userId) {
+        const user = this.#user(userId);
+        if (user.status !== "federated")
+            user.status = "password_reset_required";
+    }
     async createUser(input) {
         return copy(this.#add(input, "password_change_required"));
     }

package/dist/types.d.ts

@@ -3,10 +3,12 @@
  *
  * - `active`: has a permanent password, or otherwise needs nothing before signing in
  * - `password_change_required`: has a temporary password and must set their own at next sign-in
+ * - `password_reset_required`: must reset their password through the provider's forgot-password flow;
+ *   a temporary password won't sign them in
  * - `federated`: signs in through another identity provider (SSO), so has no password here
  * - `unconfirmed`: signed themselves up and hasn't confirmed their account yet
  */
-export type UserStatus = "active" | "password_change_required" | "federated" | "unconfirmed";
+export type UserStatus = "active" | "password_change_required" | "password_reset_required" | "federated" | "unconfirmed";
 /**
  * Custom attributes, keyed by the names the app declared in its adapter's config. Values are strings,
  * because that is what providers store; convert other types yourself. With none declared, no key is

package/docs/cognito.md

@@ -47,7 +47,8 @@ Every one of them can be limited to the pool's ARN, `arn:aws:cognito-idp:<region
   | Cognito `UserStatus` | `status` |
   |---|---|
   | `CONFIRMED` | `active` |
-  | `FORCE_CHANGE_PASSWORD`, `RESET_REQUIRED`, `COMPROMISED` | `password_change_required` |
+  | `FORCE_CHANGE_PASSWORD` | `password_change_required` |
+  | `RESET_REQUIRED`, `COMPROMISED` | `password_reset_required` |
   | `UNCONFIRMED` | `unconfirmed` |
   | `EXTERNAL_PROVIDER` | `federated` |
   | anything else | `active` |

package/docs/fake.md

@@ -26,7 +26,8 @@ const fake = new FakeAdapter({ attributes: ["company"] })
 - **Status:**
   - a user from `createUser` or `createUserWithInvite` starts as `password_change_required`
   - `setPassword` with `temporary: true` sets `password_change_required`, and with `temporary: false` sets `active`
-  - a federated user stays `federated` whatever `setPassword` does, because they sign in elsewhere
+  - `requirePasswordReset` sets `password_reset_required`, until a password is set
+  - a federated user stays `federated` whatever `setPassword` or `requirePasswordReset` does, because they sign in elsewhere
 - **Disabling** changes `enabled` only; the status is kept.
 - **Lists** return items in creation order. A cursor is the offset of the next page's first item.
 - **Copies:** every user returned is a copy, so changing it doesn't change the stored user.
@@ -42,6 +43,14 @@ const admin = fake.addFederatedUser({ email: "admin@mc3.co", name: "An Admin", a
 
 Adds a user who signs in through another identity provider (SSO), with status `federated`. A real provider creates these when someone first signs in through SSO, so only the fake can add one directly. Synchronous. Throws `UserExistsError` if the email is taken.
 
+### `requirePasswordReset(userId)`
+
+```ts
+fake.requirePasswordReset(user.id)
+```
+
+Puts the user into `password_reset_required`, as an admin reset at a real provider does, so tests can cover that state. It lasts until a password is set with `setPassword`. A federated user is unaffected. Synchronous. Throws `UserNotFoundError` for an unknown id.
+
 ### `invitations`
 
 ```ts

package/docs/index.md

@@ -106,13 +106,14 @@ type IdpUser<TAttr extends string = never> = {
 ### `UserStatus`
 
 ```ts
-type UserStatus = "active" | "password_change_required" | "federated" | "unconfirmed"
+type UserStatus = "active" | "password_change_required" | "password_reset_required" | "federated" | "unconfirmed"
 ```
 
 | Value | Meaning |
 |---|---|
 | `active` | Has a permanent password, or otherwise needs nothing before signing in. |
 | `password_change_required` | Has a temporary password and must set their own at next sign-in. |
+| `password_reset_required` | Must reset their password through the provider's forgot-password flow. A temporary password won't sign them in. Only some providers report it. |
 | `federated` | Signs in through another identity provider (SSO), so has no password here. |
 | `unconfirmed` | Signed themselves up and hasn't confirmed their account yet. |
 

package/docs/keycloak.md

@@ -43,6 +43,7 @@ Also worth knowing: by default Keycloak requires a first and last name before an
   - `federated`: the user is linked to an identity provider (they signed in through SSO). This takes precedence over everything else.
   - `password_change_required`: the user has Keycloak's `UPDATE_PASSWORD` required action, which a temporary password sets.
   - `unconfirmed`: the user has the `VERIFY_EMAIL` required action.
+  - never `password_reset_required`: an admin reset in Keycloak sets the same `UPDATE_PASSWORD` action as a temporary password, so it reports `password_change_required`.
   - `active`: anything else.
 - **Attributes** are stored as single-value Keycloak attributes under their Keycloak names. `updateAttributes` keeps every attribute the app didn't declare, including ones set by other apps.
 - **Groups** are top-level realm groups, addressed by exact name. Subgroups aren't supported.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idp-admin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "One user-management API for any identity provider.",
   "keywords": [
     "identity-provider",