idp-admin 0.1.1 → 0.2.0

package/README.md

@@ -6,13 +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.
-
-```sh
-npm install idp-admin
-```
-
-The reference for every entry point is in [docs](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
 
@@ -41,6 +35,81 @@ This package came out of exactly that situation: two production apps, each with
 - **Not a lowest common denominator.** Providers differ, and some features don't exist everywhere. Adapters declare what they support, and you can always reach the provider's own SDK for anything the shared interface doesn't cover.
 - **Not a UI.** It's the server-side layer an admin screen, a background job or a seed script would call.
 
+## Quick start
+
+```sh
+npm install idp-admin
+npm install @aws-sdk/client-cognito-identity-provider   # only for Cognito
+```
+
+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 { 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 adapter = process.env.COGNITO_USER_POOL_ID
+    ? new CognitoAdapter({
+        userPoolId: process.env.COGNITO_USER_POOL_ID,
+        region: "us-east-1",
+        attributes: { company: "custom:companyName" },
+    })
+    : new KeycloakAdapter({
+        issuer: "http://localhost:8080/realms/acme",
+        clientId: "acme-admin",
+        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.
+
+```ts
+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 admin.createUser({
+        email: "Dana@Example.com",   // stored and matched as dana@example.com
+        name: "Dana Lee",
+        attributes: { company: "Acme" },
+        temporaryPassword: "Temp-pass-1!",
+    })
+    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: disabled at the provider, signed out there, then onAccessReduced
+const dana = await admin.findUserByEmail("dana@example.com")
+if(dana) await admin.disableUser(dana.id)
+
+// 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, 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:
+
+```ts
+import { FakeAdapter } from "idp-admin/fake"
+
+const fake = new FakeAdapter({ attributes: ["company"] })
+const admin = new IdpAdmin(fake, { onAccessReduced })
+// ...run the code under test with `admin`, then:
+expect(fake.signOuts).toContain(userId)
+```
+
 ## Providers
 
 Cognito, Keycloak and the fake provider are included today: the ones we run in production and can test properly.

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/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,7 +22,7 @@ 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`

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
 
@@ -87,7 +155,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/package.json

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