idp-admin 0.1.2 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ Apps that sign people in through an identity provider (Cognito, Keycloak, Entra
 
 idp-admin is that layer, written once.
 
-> **Status:** 0.x, so the API may still change between minor versions. The adapters are published and usable directly; `IdpAdmin`, the class that adds the shared rules on top of them (including the access-reduced hook below), isn't built yet. See the [quick start](#quick-start) and the [reference](docs/index.md).
+> **Status:** 0.x, so the API may still change between minor versions. See the [quick start](#quick-start) and the [reference](docs/index.md).
 
 ## Why it exists
 
@@ -42,15 +42,15 @@ npm install idp-admin
 npm install @aws-sdk/client-cognito-identity-provider   # only for Cognito
 ```
 
-Pick an adapter for your provider. Each one's setup (credentials, permissions, realm or pool settings) is in its doc: [Cognito](docs/cognito.md), [Keycloak](docs/keycloak.md), [fake](docs/fake.md).
+Wrap the adapter for your provider in `IdpAdmin`. Each adapter's setup (credentials, permissions, realm or pool settings) is in its doc: [Cognito](docs/cognito.md), [Keycloak](docs/keycloak.md), [fake](docs/fake.md).
 
 ```ts
-import type { IdpAdapter } from "idp-admin"
+import { IdpAdmin } from "idp-admin"
 import { CognitoAdapter } from "idp-admin/cognito"
 import { KeycloakAdapter } from "idp-admin/keycloak"
 
 // Cognito in production, Keycloak in a container locally: the rest of the app doesn't know which
-const idp: IdpAdapter<"company"> = process.env.COGNITO_USER_POOL_ID
+const adapter = process.env.COGNITO_USER_POOL_ID
     ? new CognitoAdapter({
         userPoolId: process.env.COGNITO_USER_POOL_ID,
         region: "us-east-1",
@@ -62,6 +62,11 @@ const idp: IdpAdapter<"company"> = process.env.COGNITO_USER_POOL_ID
         clientSecret: process.env.KEYCLOAK_ADMIN_SECRET!,
         attributes: { company: "companyName" },
     })
+
+const admin = new IdpAdmin(adapter, {
+    // runs whenever someone loses access, so their sessions in your app end too
+    onAccessReduced: ({ userId }) => revokeAllSessionsFor(userId),
+})
 ```
 
 `attributes` maps the names your app uses to the provider's own, and only those names compile.
@@ -71,36 +76,28 @@ import { UserExistsError } from "idp-admin"
 
 // create a user who must set their own password at first sign-in; send them the temporary one yourself
 try{
-    const user = await idp.createUser({
-        email: "dana@example.com",
+    const user = await admin.createUser({
+        email: "Dana@Example.com",   // stored and matched as dana@example.com
         name: "Dana Lee",
         attributes: { company: "Acme" },
         temporaryPassword: "Temp-pass-1!",
     })
-    if(!(await idp.groupExists("admins"))) await idp.createGroup("admins")
-    await idp.addToGroup(user.id, "admins")
+    await admin.ensureGroup("admins")
+    await admin.addToGroup(user.id, "admins")
 }catch(error){
     if(error instanceof UserExistsError) console.log("already invited")
     else throw error
 }
 
-// take access away, and end the sessions the provider already issued
-const dana = await idp.findUserByEmail("dana@example.com")
-if(dana){
-    await idp.setEnabled(dana.id, false)
-    await idp.signOutEverywhere(dana.id)
-}
+// take access away: disabled at the provider, signed out there, then onAccessReduced
+const dana = await admin.findUserByEmail("dana@example.com")
+if(dana) await admin.disableUser(dana.id)
 
-// list everyone, a page at a time
-let cursor: string | null = null
-do{
-    const page = await idp.listUsersPage(cursor)
-    for(const user of page.items) console.log(user.email, user.status, user.enabled)
-    cursor = page.nextCursor
-}while(cursor)
+// everyone, fetched a page at a time behind the scenes
+for await (const user of admin.listUsers()) console.log(user.email, user.status, user.enabled)
 ```
 
-A user's `id` is the `sub` in their sign-in tokens, so it matches what your auth library gives you. Pass emails lowercased and trimmed, and `findUserByEmail` returns `null` while `getUser` throws `UserNotFoundError`. The full list of methods, types and errors is in [docs/index.md](docs/index.md).
+A user's `id` is the `sub` in their sign-in tokens, so it matches what your auth library gives you, and it's what `onAccessReduced` receives. `findUserByEmail` returns `null` while `getUser` throws `UserNotFoundError`. If ending sessions fails after the provider change, the method throws `AccessReductionIncompleteError`, and calling it again is safe. The full list of methods, types and errors is in [docs/index.md](docs/index.md).
 
 In tests, use the fake instead. It keeps everything in memory and records what a real provider would have done:
 
@@ -108,7 +105,8 @@ In tests, use the fake instead. It keeps everything in memory and records what a
 import { FakeAdapter } from "idp-admin/fake"
 
 const fake = new FakeAdapter({ attributes: ["company"] })
-// ...run the code under test with `fake` as its IdpAdapter, then:
+const admin = new IdpAdmin(fake, { onAccessReduced })
+// ...run the code under test with `admin`, then:
 expect(fake.signOuts).toContain(userId)
 ```
 

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/idp-admin.d.ts

@@ -0,0 +1,83 @@
+import type { AdapterCreateUserInput, AdapterInviteUserInput, IdpAdapter } from "./adapter";
+import { type AccessReductionAction } from "./errors";
+import type { IdpUser, UserAttributes } from "./types";
+/** What the access-reduced hook is told: whose access was reduced, and how. */
+export type AccessReducedEvent = {
+    userId: string;
+    action: Exclude<AccessReductionAction, "removed-from-group">;
+} | {
+    userId: string;
+    action: "removed-from-group";
+    group: string;
+};
+export type IdpAdminOptions = {
+    onAccessReduced?: (event: AccessReducedEvent) => void | Promise<void>;
+};
+/** The optional adapter methods, and whether the adapter in use has each. */
+export type IdpAdminSupports = {
+    createUserWithInvite: boolean;
+    resendInvite: boolean;
+};
+/**
+ * What apps call to manage users in their identity provider, through one adapter. Holds the rules every
+ * provider shares: emails are lowercased and trimmed, and taking access away (deleting, disabling,
+ * removing from a group) always ends the user's sessions, by signing them out at the provider and
+ * calling `onAccessReduced`.
+ */
+export declare class IdpAdmin<TAttr extends string = never> {
+    #private;
+    /** The adapter, for its `native` client and anything the shared methods don't cover. */
+    readonly adapter: IdpAdapter<TAttr>;
+    constructor(adapter: IdpAdapter<TAttr>, options?: IdpAdminOptions);
+    get supports(): IdpAdminSupports;
+    /** Creates a user who must replace `temporaryPassword` at first sign-in. The provider sends no message. @throws {UserExistsError} */
+    createUser(input: AdapterCreateUserInput<TAttr>): Promise<IdpUser<TAttr>>;
+    /** Creates a user the provider generates a password for and sends its own invitation. @throws {UserExistsError} @throws {NotSupportedError} */
+    createUserWithInvite(input: AdapterInviteUserInput<TAttr>): Promise<IdpUser<TAttr>>;
+    /** @throws {UserNotFoundError} */
+    getUser(userId: string): Promise<IdpUser<TAttr>>;
+    /** The user with this email, whatever its case, or null. */
+    findUserByEmail(email: string): Promise<IdpUser<TAttr> | null>;
+    /** Every user, fetched a page at a time as the loop needs them. */
+    listUsers(): AsyncGenerator<IdpUser<TAttr>>;
+    /** A temporary password must be replaced at next sign-in. @throws {UserNotFoundError} */
+    setPassword(userId: string, password: string, options: {
+        temporary: boolean;
+    }): Promise<void>;
+    /** Sets the given attributes and leaves the rest unchanged. @throws {UserNotFoundError} */
+    updateAttributes(userId: string, attributes: UserAttributes<TAttr>): Promise<void>;
+    /** Sends the provider's invitation again. @throws {UserNotFoundError} @throws {NotSupportedError} */
+    resendInvite(userId: string): Promise<void>;
+    /** Revokes the user's tokens at the provider. Doesn't call `onAccessReduced`. @throws {UserNotFoundError} */
+    signOutEverywhere(userId: string): Promise<void>;
+    enableUser(userId: string): Promise<void>;
+    /**
+     * Disables the user, signs them out at the provider, then calls `onAccessReduced`. Succeeds for a user
+     * who is already disabled, and repeats every step.
+     * @throws {UserNotFoundError} @throws {AccessReductionIncompleteError} the user is disabled, but a later step failed
+     */
+    disableUser(userId: string): Promise<void>;
+    /**
+     * Deletes the user, then calls `onAccessReduced`, also when the user was already gone. Deleting ends
+     * their tokens at the provider, so there is no separate sign-out. True if a user was deleted, false
+     * if there was none.
+     * @throws {AccessReductionIncompleteError} the user is deleted, but the hook failed
+     */
+    deleteUser(userId: string): Promise<boolean>;
+    /** Succeeds if they're already a member. @throws {UserNotFoundError} @throws {GroupNotFoundError} */
+    addToGroup(userId: string, group: string): Promise<void>;
+    /**
+     * Removes the user from the group, signs them out at the provider, then calls `onAccessReduced`.
+     * Succeeds if they aren't a member, or the group doesn't exist, and repeats every step.
+     * @throws {UserNotFoundError} @throws {AccessReductionIncompleteError} the user is removed, but a later step failed
+     */
+    removeFromGroup(userId: string, group: string): Promise<void>;
+    /** The names of every group the user is in. @throws {UserNotFoundError} */
+    listUserGroups(userId: string): AsyncGenerator<string>;
+    /** Every member of the group. @throws {GroupNotFoundError} */
+    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} */
+    deleteGroup(group: string): Promise<void>;
+}

package/dist/idp-admin.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdpAdmin = void 0;
+const errors_1 = require("./errors");
+/**
+ * What apps call to manage users in their identity provider, through one adapter. Holds the rules every
+ * provider shares: emails are lowercased and trimmed, and taking access away (deleting, disabling,
+ * removing from a group) always ends the user's sessions, by signing them out at the provider and
+ * calling `onAccessReduced`.
+ */
+class IdpAdmin {
+    #onAccessReduced;
+    /** The adapter, for its `native` client and anything the shared methods don't cover. */
+    adapter;
+    constructor(adapter, options = {}) {
+        this.adapter = adapter;
+        this.#onAccessReduced = options.onAccessReduced;
+    }
+    get supports() {
+        return {
+            createUserWithInvite: typeof this.adapter.createUserWithInvite === "function",
+            resendInvite: typeof this.adapter.resendInvite === "function",
+        };
+    }
+    // ---- users
+    /** Creates a user who must replace `temporaryPassword` at first sign-in. The provider sends no message. @throws {UserExistsError} */
+    createUser(input) {
+        return this.adapter.createUser({ ...input, email: normalizeEmail(input.email) });
+    }
+    /** Creates a user the provider generates a password for and sends its own invitation. @throws {UserExistsError} @throws {NotSupportedError} */
+    async createUserWithInvite(input) {
+        if (!this.adapter.createUserWithInvite)
+            throw new errors_1.NotSupportedError("createUserWithInvite");
+        return this.adapter.createUserWithInvite({ ...input, email: normalizeEmail(input.email) });
+    }
+    /** @throws {UserNotFoundError} */
+    getUser(userId) {
+        return this.adapter.getUser(userId);
+    }
+    /** The user with this email, whatever its case, or null. */
+    findUserByEmail(email) {
+        return this.adapter.findUserByEmail(normalizeEmail(email));
+    }
+    /** Every user, fetched a page at a time as the loop needs them. */
+    listUsers() {
+        return all((cursor) => this.adapter.listUsersPage(cursor));
+    }
+    /** A temporary password must be replaced at next sign-in. @throws {UserNotFoundError} */
+    setPassword(userId, password, options) {
+        return this.adapter.setPassword(userId, password, options);
+    }
+    /** Sets the given attributes and leaves the rest unchanged. @throws {UserNotFoundError} */
+    updateAttributes(userId, attributes) {
+        return this.adapter.updateAttributes(userId, attributes);
+    }
+    /** Sends the provider's invitation again. @throws {UserNotFoundError} @throws {NotSupportedError} */
+    async resendInvite(userId) {
+        if (!this.adapter.resendInvite)
+            throw new errors_1.NotSupportedError("resendInvite");
+        await this.adapter.resendInvite(userId);
+    }
+    /** Revokes the user's tokens at the provider. Doesn't call `onAccessReduced`. @throws {UserNotFoundError} */
+    signOutEverywhere(userId) {
+        return this.adapter.signOutEverywhere(userId);
+    }
+    async enableUser(userId) {
+        await this.adapter.setEnabled(userId, true);
+    }
+    /**
+     * Disables the user, signs them out at the provider, then calls `onAccessReduced`. Succeeds for a user
+     * who is already disabled, and repeats every step.
+     * @throws {UserNotFoundError} @throws {AccessReductionIncompleteError} the user is disabled, but a later step failed
+     */
+    async disableUser(userId) {
+        await this.adapter.setEnabled(userId, false);
+        await this.#signOut(userId, "disabled");
+        await this.#accessReduced({ userId, action: "disabled" });
+    }
+    /**
+     * Deletes the user, then calls `onAccessReduced`, also when the user was already gone. Deleting ends
+     * their tokens at the provider, so there is no separate sign-out. True if a user was deleted, false
+     * if there was none.
+     * @throws {AccessReductionIncompleteError} the user is deleted, but the hook failed
+     */
+    async deleteUser(userId) {
+        let deleted = true;
+        try {
+            await this.adapter.deleteUser(userId);
+        }
+        catch (error) {
+            if (!(error instanceof errors_1.UserNotFoundError))
+                throw error;
+            deleted = false;
+        }
+        await this.#accessReduced({ userId, action: "deleted" });
+        return deleted;
+    }
+    // ---- groups
+    /** Succeeds if they're already a member. @throws {UserNotFoundError} @throws {GroupNotFoundError} */
+    addToGroup(userId, group) {
+        return this.adapter.addToGroup(userId, group);
+    }
+    /**
+     * Removes the user from the group, signs them out at the provider, then calls `onAccessReduced`.
+     * Succeeds if they aren't a member, or the group doesn't exist, and repeats every step.
+     * @throws {UserNotFoundError} @throws {AccessReductionIncompleteError} the user is removed, but a later step failed
+     */
+    async removeFromGroup(userId, group) {
+        try {
+            await this.adapter.removeFromGroup(userId, group);
+        }
+        catch (error) {
+            if (!(error instanceof errors_1.GroupNotFoundError))
+                throw error;
+            // 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 });
+    }
+    /** The names of every group the user is in. @throws {UserNotFoundError} */
+    listUserGroups(userId) {
+        return all((cursor) => this.adapter.listUserGroupsPage(userId, cursor));
+    }
+    /** Every member of the group. @throws {GroupNotFoundError} */
+    listGroupMembers(group) {
+        return all((cursor) => this.adapter.listGroupMembersPage(group, cursor));
+    }
+    /** Creates the group, or does nothing if it exists. */
+    async ensureGroup(group) {
+        if (await this.adapter.groupExists(group))
+            return;
+        try {
+            await this.adapter.createGroup(group);
+        }
+        catch (error) {
+            // created by someone else since the check
+            if (!(error instanceof errors_1.GroupExistsError))
+                throw error;
+        }
+    }
+    /** Deletes the group, removing every member from it first. @throws {GroupNotFoundError} */
+    deleteGroup(group) {
+        return 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 });
+        }
+    }
+    async #accessReduced(event) {
+        try {
+            await this.#onAccessReduced?.(event);
+        }
+        catch (cause) {
+            throw new errors_1.AccessReductionIncompleteError({ userId: event.userId, action: event.action, failedStep: "hook", cause });
+        }
+    }
+}
+exports.IdpAdmin = IdpAdmin;
+function normalizeEmail(email) {
+    return email.trim().toLowerCase();
+}
+async function* all(page) {
+    let cursor = null;
+    do {
+        const result = await page(cursor);
+        yield* result.items;
+        cursor = result.nextCursor;
+    } while (cursor !== null);
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 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 type { IdpUser, Page, UserAttributes, UserStatus } from "./types";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UserNotFoundError = exports.UserExistsError = exports.NotSupportedError = exports.IdpAdminError = exports.GroupNotFoundError = exports.GroupExistsError = exports.AccessReductionIncompleteError = void 0;
+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; } });
@@ -9,3 +9,5 @@ Object.defineProperty(exports, "IdpAdminError", { enumerable: true, get: functio
 Object.defineProperty(exports, "NotSupportedError", { enumerable: true, get: function () { return errors_1.NotSupportedError; } });
 Object.defineProperty(exports, "UserExistsError", { enumerable: true, get: function () { return errors_1.UserExistsError; } });
 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; } });

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

@@ -2,7 +2,7 @@
 
 `idp-admin/fake`: an identity provider that keeps users and groups in memory. [Index](index.md)
 
-It's the reference implementation every other adapter is tested against, and a provider for tests that need no container or cloud account. It implements every method of [`IdpAdapter`](index.md#idpadaptertattr), including the optional ones, and adds a few helpers only a fake can offer.
+It's the reference implementation every other adapter is tested against, and a provider for tests that need no container or cloud account: wrap it in `IdpAdmin` like any other adapter, and use the helpers below to check what happened. It implements every method of [`IdpAdapter`](index.md#idpadaptertattr), including the optional ones, and adds a few helpers only a fake can offer.
 
 Not for production: nothing is shared between instances or kept after the process exits.
 
@@ -22,11 +22,12 @@ const fake = new FakeAdapter({ attributes: ["company"] })
 ## Behaviour
 
 - **Ids** are UUID v4s from `crypto.randomUUID()`.
-- **Emails** are matched exactly. The adapter contract expects them already lowercased and trimmed, so the fake doesn't lowercase again; pass them that way when calling it directly.
+- **Emails** are matched exactly. They arrive already lowercased and trimmed (`IdpAdmin` normalises them), so the fake doesn't do it again.
 - **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

@@ -1,6 +1,6 @@
 # idp-admin reference
 
-One file per published entry point. This file covers the core, `idp-admin`: the types every adapter shares, the errors, and the adapter contract.
+One file per published entry point. This file covers the core, `idp-admin`: `IdpAdmin`, the types every adapter shares, the errors, and the adapter contract.
 
 | Entry point | Doc |
 |---|---|
@@ -9,7 +9,75 @@ One file per published entry point. This file covers the core, `idp-admin`: the
 | `idp-admin/cognito` | [cognito.md](cognito.md) |
 | `idp-admin/keycloak` | [keycloak.md](keycloak.md) |
 
-`IdpAdmin`, the class apps call, is not built yet. Until it is, the adapters are usable directly, but without the shared rules (email normalisation, the access-reduced hook, provider sign-out, paging, idempotent removal) that `IdpAdmin` adds.
+## `IdpAdmin`
+
+What apps call. It wraps one adapter and adds the rules every provider shares.
+
+```ts
+import { IdpAdmin } from "idp-admin"
+import { CognitoAdapter } from "idp-admin/cognito"
+
+const admin = new IdpAdmin(new CognitoAdapter({ userPoolId, region: "us-east-1" }), {
+    onAccessReduced: ({ userId }) => revokeAllSessionsFor(userId),
+})
+```
+
+`TAttr`, the attribute names, comes from the adapter, so `admin.createUser` accepts exactly the attributes that adapter declares.
+
+### Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `onAccessReduced` | none | Called after a user is deleted, disabled or removed from a group, with an `AccessReducedEvent`. Use it to end the app's own sessions for that user. It may be sync or async. It can run more than once for the same change, so it must be safe to repeat. |
+
+```ts
+type AccessReducedEvent =
+    | { userId: string; action: "deleted" | "disabled" }
+    | { userId: string; action: "removed-from-group"; group: string }
+```
+
+### 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:
+  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
+  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.
+- **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.
+
+### Methods
+
+| Method | Returns | Behaviour |
+|---|---|---|
+| `createUser({ email, name?, attributes?, temporaryPassword })` | `IdpUser` | The user must replace `temporaryPassword` at first sign-in. The provider sends no message, so send your own. Throws `UserExistsError`. |
+| `createUserWithInvite({ email, name?, attributes? })` | `IdpUser` | The provider generates a password and emails its own invitation. Throws `UserExistsError`, or `NotSupportedError` if the adapter can't. |
+| `getUser(userId)` | `IdpUser` | Throws `UserNotFoundError`. |
+| `findUserByEmail(email)` | `IdpUser \| null` | `null` when nobody has that email. |
+| `listUsers()` | `AsyncGenerator<IdpUser>` | Every user. |
+| `setPassword(userId, password, { temporary })` | `void` | A temporary password must be replaced at next sign-in. |
+| `updateAttributes(userId, attributes)` | `void` | Sets the given attributes and leaves the rest unchanged. |
+| `resendInvite(userId)` | `void` | Sends the provider's invitation again. Throws `NotSupportedError` if the adapter can't. |
+| `enableUser(userId)` | `void` | |
+| `disableUser(userId)` | `void` | Then provider sign-out, then `onAccessReduced`. Succeeds if already disabled. |
+| `deleteUser(userId)` | `boolean` | Then `onAccessReduced`. `true` if a user was deleted, `false` if they were already gone; the hook runs either way. |
+| `signOutEverywhere(userId)` | `void` | Revokes the user's tokens at the provider. Doesn't call `onAccessReduced`. |
+| `addToGroup(userId, group)` | `void` | Succeeds if they're already a member. Throws `GroupNotFoundError`. |
+| `removeFromGroup(userId, group)` | `void` | Then provider sign-out, then `onAccessReduced`. Succeeds if they aren't a member or the group doesn't exist. |
+| `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. |
+
+Unless a row says otherwise, a method addressing a missing user throws `UserNotFoundError`.
+
+| Property | Meaning |
+|---|---|
+| `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. |
 
 ## Types
 
@@ -38,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. |
 
@@ -87,7 +156,7 @@ Every error idp-admin throws on purpose extends `IdpAdminError`, so `instanceof
 
 ## `IdpAdapter<TAttr>`
 
-The contract every adapter implements: plain translation to one provider's admin API. Shared rules live in `IdpAdmin`, so an adapter can't get them wrong. Apps don't normally call adapters directly.
+The contract every adapter implements: plain translation to one provider's admin API. Shared rules live in `IdpAdmin`, so an adapter can't get them wrong. Apps call `IdpAdmin`, not adapters; this section is for writing an adapter.
 
 Every user is addressed by `userId`, the provider's permanent id. A method that addresses a user who doesn't exist throws `UserNotFoundError`; one that addresses a group that doesn't exist throws `GroupNotFoundError`. Emails passed in are already lowercased and trimmed.
 

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.1.2",
+  "version": "0.3.0",
   "description": "One user-management API for any identity provider.",
   "keywords": [
     "identity-provider",