idp-admin 0.0.0-stage → 0.1.0

package/dist/fake/index.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeAdapter = void 0;
+const node_crypto_1 = require("node:crypto");
+const errors_1 = require("../errors");
+/**
+ * An identity provider that keeps users and groups in memory: the reference implementation every
+ * other adapter is tested against, and a provider for tests that need no container or cloud account.
+ * Ids are UUID v4s. Nothing is shared between instances or kept after the process exits.
+ */
+class FakeAdapter {
+    #attributeNames;
+    #pageSize;
+    // insertion order is creation order, which is the order the list methods return
+    #users = new Map();
+    #idsByEmail = new Map();
+    #groups = new Map();
+    #invitations = [];
+    #signOuts = [];
+    constructor(options = {}) {
+        this.#attributeNames = new Set(options.attributes ?? []);
+        this.#pageSize = options.pageSize ?? 60;
+    }
+    /** Every provider invitation sent so far, oldest first: from `createUserWithInvite` and `resendInvite`. */
+    get invitations() {
+        return this.#invitations.map((invitation) => ({ ...invitation }));
+    }
+    /** The id of every user signed out at the provider so far, oldest first, once per call. */
+    get signOuts() {
+        return [...this.#signOuts];
+    }
+    /** Adds a user who signs in through another identity provider (SSO). Only the fake can do this directly. */
+    addFederatedUser(input) {
+        return copy(this.#add(input, "federated"));
+    }
+    async createUser(input) {
+        return copy(this.#add(input, "password_change_required"));
+    }
+    async createUserWithInvite(input) {
+        const user = this.#add(input, "password_change_required");
+        this.#invitations.push({ userId: user.id, email: user.email });
+        return copy(user);
+    }
+    async getUser(userId) {
+        return copy(this.#user(userId));
+    }
+    async findUserByEmail(email) {
+        const id = this.#idsByEmail.get(email);
+        return id === undefined ? null : copy(this.#user(id));
+    }
+    async listUsersPage(cursor) {
+        return this.#page([...this.#users.values()].map(copy), cursor);
+    }
+    async setPassword(userId, _password, options) {
+        const user = this.#user(userId);
+        // an SSO user signs in elsewhere, so a password here doesn't change how they sign in
+        if (user.status !== "federated")
+            user.status = options.temporary ? "password_change_required" : "active";
+    }
+    async setEnabled(userId, enabled) {
+        this.#user(userId).enabled = enabled;
+    }
+    async deleteUser(userId) {
+        const user = this.#user(userId);
+        for (const members of this.#groups.values())
+            members.delete(userId);
+        this.#idsByEmail.delete(user.email);
+        this.#users.delete(userId);
+    }
+    async updateAttributes(userId, attributes) {
+        const user = this.#user(userId);
+        this.#checkAttributes(attributes);
+        Object.assign(user.attributes, attributes);
+    }
+    async resendInvite(userId) {
+        const user = this.#user(userId);
+        this.#invitations.push({ userId, email: user.email });
+    }
+    async signOutEverywhere(userId) {
+        this.#user(userId);
+        this.#signOuts.push(userId);
+    }
+    async addToGroup(userId, group) {
+        this.#user(userId);
+        this.#group(group).add(userId);
+    }
+    async removeFromGroup(userId, group) {
+        this.#user(userId);
+        this.#group(group).delete(userId);
+    }
+    async listUserGroupsPage(userId, cursor) {
+        this.#user(userId);
+        const names = [...this.#groups].filter(([, members]) => members.has(userId)).map(([name]) => name);
+        return this.#page(names, cursor);
+    }
+    async groupExists(group) {
+        return this.#groups.has(group);
+    }
+    async createGroup(group) {
+        if (this.#groups.has(group))
+            throw new errors_1.GroupExistsError(group);
+        this.#groups.set(group, new Set());
+    }
+    async deleteGroup(group) {
+        this.#group(group);
+        this.#groups.delete(group);
+    }
+    async listGroupMembersPage(group, cursor) {
+        const members = [...this.#group(group)].map((id) => copy(this.#user(id)));
+        return this.#page(members, cursor);
+    }
+    #add(input, status) {
+        if (this.#idsByEmail.has(input.email))
+            throw new errors_1.UserExistsError(input.email);
+        this.#checkAttributes(input.attributes ?? {});
+        const user = {
+            id: (0, node_crypto_1.randomUUID)(),
+            email: input.email,
+            name: input.name ?? null,
+            status,
+            enabled: true,
+            attributes: { ...input.attributes },
+        };
+        this.#users.set(user.id, user);
+        this.#idsByEmail.set(user.email, user.id);
+        return user;
+    }
+    // The stored user, for reading or changing in place; callers get copies.
+    #user(userId) {
+        const user = this.#users.get(userId);
+        if (!user)
+            throw new errors_1.UserNotFoundError(userId);
+        return user;
+    }
+    #group(group) {
+        const members = this.#groups.get(group);
+        if (!members)
+            throw new errors_1.GroupNotFoundError(group);
+        return members;
+    }
+    // The type system already rejects undeclared names; this catches callers without it, as a provider would.
+    #checkAttributes(attributes) {
+        for (const name of Object.keys(attributes)) {
+            if (!this.#attributeNames.has(name)) {
+                const declared = [...this.#attributeNames].join(", ") || "none";
+                throw new TypeError(`Unknown attribute ${name}. Declared attributes: ${declared}`);
+            }
+        }
+    }
+    // The cursor is the offset of the page's first item.
+    #page(items, cursor) {
+        const start = cursor === null ? 0 : Number(cursor);
+        const end = start + this.#pageSize;
+        return { items: items.slice(start, end), nextCursor: end < items.length ? String(end) : null };
+    }
+}
+exports.FakeAdapter = FakeAdapter;
+function copy(user) {
+    return { ...user, attributes: { ...user.attributes } };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { AdapterCreateUserInput, AdapterInviteUserInput, IdpAdapter } from "./adapter";
+export { AccessReductionIncompleteError, GroupExistsError, GroupNotFoundError, IdpAdminError, NotSupportedError, UserExistsError, UserNotFoundError, type AccessReductionAction, type AccessReductionStep, type AnyIdpAdminError, } from "./errors";
+export type { IdpUser, Page, UserAttributes, UserStatus } from "./types";

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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; } });
+Object.defineProperty(exports, "GroupNotFoundError", { enumerable: true, get: function () { return errors_1.GroupNotFoundError; } });
+Object.defineProperty(exports, "IdpAdminError", { enumerable: true, get: function () { return errors_1.IdpAdminError; } });
+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; } });

package/dist/keycloak/index.d.ts

@@ -0,0 +1,53 @@
+import type { AdapterCreateUserInput, IdpAdapter } from "../adapter";
+import type { IdpUser, Page, UserAttributes } from "../types";
+export type KeycloakAdapterOptions<TMap extends Record<string, string>> = {
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    attributes?: TMap;
+    pageSize?: number;
+};
+/** The realm-management roles the client's service account needs. `manage-realm` is for creating and deleting groups. */
+export declare const KEYCLOAK_ADMIN_ROLES: readonly ["manage-users", "view-users", "query-users", "query-groups", "manage-realm"];
+/** Keycloak answered with a status the adapter doesn't turn into an idp-admin error. */
+export declare class KeycloakRequestError extends Error {
+    readonly method: string;
+    readonly path: string;
+    readonly status: number;
+    constructor(method: string, path: string, status: number, message: string);
+}
+type Attr<TMap> = Extract<keyof TMap, string>;
+/**
+ * Keycloak, through its admin REST API, authenticated as a client's service account. A user's id is
+ * their Keycloak user id, which Keycloak puts in the `sub` of their tokens. Groups are top-level realm
+ * groups, addressed by name. Keycloak has no provider invitation without SMTP and required-action
+ * emails, so `createUserWithInvite` and `resendInvite` aren't implemented.
+ */
+export declare class KeycloakAdapter<const TMap extends Record<string, string> = {}> implements IdpAdapter<Attr<TMap>> {
+    #private;
+    /** The admin API, authenticated, for anything the shared interface doesn't cover. Paths are relative to /admin/realms/<realm>. */
+    readonly native: {
+        adminUrl: string;
+        request(method: string, path: string, body?: unknown): Promise<Response>;
+    };
+    constructor(options: KeycloakAdapterOptions<TMap>);
+    createUser(input: AdapterCreateUserInput<Attr<TMap>>): Promise<IdpUser<Attr<TMap>>>;
+    getUser(userId: string): Promise<IdpUser<Attr<TMap>>>;
+    findUserByEmail(email: string): Promise<IdpUser<Attr<TMap>> | null>;
+    listUsersPage(cursor: string | null): Promise<Page<IdpUser<Attr<TMap>>>>;
+    setPassword(userId: string, password: string, options: {
+        temporary: boolean;
+    }): Promise<void>;
+    setEnabled(userId: string, enabled: boolean): Promise<void>;
+    deleteUser(userId: string): Promise<void>;
+    updateAttributes(userId: string, attributes: UserAttributes<Attr<TMap>>): Promise<void>;
+    signOutEverywhere(userId: string): Promise<void>;
+    addToGroup(userId: string, group: string): Promise<void>;
+    removeFromGroup(userId: string, group: string): Promise<void>;
+    listUserGroupsPage(userId: string, cursor: string | null): Promise<Page<string>>;
+    groupExists(group: string): Promise<boolean>;
+    createGroup(group: string): Promise<void>;
+    deleteGroup(group: string): Promise<void>;
+    listGroupMembersPage(group: string, cursor: string | null): Promise<Page<IdpUser<Attr<TMap>>>>;
+}
+export {};

package/dist/keycloak/index.js

@@ -0,0 +1,288 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeycloakAdapter = exports.KeycloakRequestError = exports.KEYCLOAK_ADMIN_ROLES = void 0;
+const errors_1 = require("../errors");
+/** The realm-management roles the client's service account needs. `manage-realm` is for creating and deleting groups. */
+exports.KEYCLOAK_ADMIN_ROLES = ["manage-users", "view-users", "query-users", "query-groups", "manage-realm"];
+/** Keycloak answered with a status the adapter doesn't turn into an idp-admin error. */
+class KeycloakRequestError extends Error {
+    method;
+    path;
+    status;
+    constructor(method, path, status, message) {
+        super(message);
+        this.method = method;
+        this.path = path;
+        this.status = status;
+        this.name = "KeycloakRequestError";
+    }
+}
+exports.KeycloakRequestError = KeycloakRequestError;
+// Renewed this long before it expires, so a token never lapses mid-request.
+const TOKEN_EXPIRY_SKEW_MS = 30_000;
+/**
+ * Keycloak, through its admin REST API, authenticated as a client's service account. A user's id is
+ * their Keycloak user id, which Keycloak puts in the `sub` of their tokens. Groups are top-level realm
+ * groups, addressed by name. Keycloak has no provider invitation without SMTP and required-action
+ * emails, so `createUserWithInvite` and `resendInvite` aren't implemented.
+ */
+class KeycloakAdapter {
+    #realmUrl;
+    #adminUrl;
+    #clientId;
+    #clientSecret;
+    #attributes;
+    #pageSize;
+    #token;
+    #profile;
+    /** The admin API, authenticated, for anything the shared interface doesn't cover. Paths are relative to /admin/realms/<realm>. */
+    native;
+    constructor(options) {
+        const match = options.issuer.replace(/\/+$/, "").match(/^(.*)\/realms\/([^/]+)$/);
+        if (!match)
+            throw new TypeError(`issuer must look like <host>/realms/<realm>, got ${options.issuer}`);
+        const [, host, realm] = match;
+        const pageSize = options.pageSize ?? 50;
+        if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 99)
+            throw new RangeError(`pageSize must be a whole number from 1 to 99, got ${pageSize}`);
+        this.#realmUrl = `${host}/realms/${realm}`;
+        this.#adminUrl = `${host}/admin/realms/${realm}`;
+        this.#clientId = options.clientId;
+        this.#clientSecret = options.clientSecret;
+        this.#attributes = new Map(Object.entries(options.attributes ?? {}));
+        this.#pageSize = pageSize;
+        this.native = {
+            adminUrl: this.#adminUrl,
+            request: async (method, path, body) => this.#fetch(method, path, body),
+        };
+    }
+    async createUser(input) {
+        const attributes = await this.#toKeycloakAttributes(input.attributes);
+        const response = await this.#request("POST", "/users", {
+            body: {
+                username: input.email,
+                email: input.email,
+                emailVerified: true,
+                enabled: true,
+                ...splitName(input.name),
+                attributes,
+                credentials: [{ type: "password", value: input.temporaryPassword, temporary: true }],
+            },
+            conflict: () => new errors_1.UserExistsError(input.email),
+        });
+        // Keycloak returns the new user's id only in the Location header
+        const id = response.headers.get("location").split("/").pop();
+        return this.getUser(id);
+    }
+    async getUser(userId) {
+        const response = await this.#request("GET", `/users/${encodeURIComponent(userId)}`, { notFound: () => new errors_1.UserNotFoundError(userId) });
+        return this.#toUser(await response.json());
+    }
+    async findUserByEmail(email) {
+        const response = await this.#request("GET", `/users?email=${encodeURIComponent(email)}&exact=true&briefRepresentation=false`);
+        const match = (await response.json()).find((user) => user.email === email);
+        return match ? this.#toUser(match) : null;
+    }
+    async listUsersPage(cursor) {
+        return this.#page(cursor, "/users?briefRepresentation=false", async (users) => Promise.all(users.map((user) => this.#toUser(user))));
+    }
+    async setPassword(userId, password, options) {
+        await this.#request("PUT", `/users/${encodeURIComponent(userId)}/reset-password`, {
+            body: { type: "password", value: password, temporary: options.temporary },
+            notFound: () => new errors_1.UserNotFoundError(userId),
+        });
+    }
+    async setEnabled(userId, enabled) {
+        // a partial representation: Keycloak leaves every field it doesn't contain unchanged
+        await this.#request("PUT", `/users/${encodeURIComponent(userId)}`, { body: { enabled }, notFound: () => new errors_1.UserNotFoundError(userId) });
+    }
+    async deleteUser(userId) {
+        await this.#request("DELETE", `/users/${encodeURIComponent(userId)}`, { notFound: () => new errors_1.UserNotFoundError(userId) });
+    }
+    async updateAttributes(userId, attributes) {
+        const changes = await this.#toKeycloakAttributes(attributes);
+        const path = `/users/${encodeURIComponent(userId)}`;
+        const current = (await (await this.#request("GET", path, { notFound: () => new errors_1.UserNotFoundError(userId) })).json());
+        // Keycloak replaces the whole attribute map, and with its user profile that map includes email and
+        // names: send the whole user back, with the attributes this app didn't declare unchanged
+        await this.#request("PUT", path, {
+            body: { ...current, attributes: { ...current.attributes, ...changes } },
+            notFound: () => new errors_1.UserNotFoundError(userId),
+        });
+    }
+    async signOutEverywhere(userId) {
+        await this.#request("POST", `/users/${encodeURIComponent(userId)}/logout`, { notFound: () => new errors_1.UserNotFoundError(userId) });
+    }
+    async addToGroup(userId, group) {
+        const groupId = await this.#requireGroupId(group);
+        await this.#request("PUT", `/users/${encodeURIComponent(userId)}/groups/${groupId}`, { notFound: () => new errors_1.UserNotFoundError(userId) });
+    }
+    async removeFromGroup(userId, group) {
+        const groupId = await this.#requireGroupId(group);
+        await this.#request("DELETE", `/users/${encodeURIComponent(userId)}/groups/${groupId}`, { notFound: () => new errors_1.UserNotFoundError(userId) });
+    }
+    async listUserGroupsPage(userId, cursor) {
+        const path = `/users/${encodeURIComponent(userId)}/groups?briefRepresentation=true`;
+        return this.#page(cursor, path, async (groups) => groups.map((group) => group.name), () => new errors_1.UserNotFoundError(userId));
+    }
+    async groupExists(group) {
+        return (await this.#groupId(group)) !== null;
+    }
+    async createGroup(group) {
+        await this.#request("POST", "/groups", { body: { name: group }, conflict: () => new errors_1.GroupExistsError(group) });
+    }
+    async deleteGroup(group) {
+        const groupId = await this.#requireGroupId(group);
+        await this.#request("DELETE", `/groups/${groupId}`, { notFound: () => new errors_1.GroupNotFoundError(group) });
+    }
+    async listGroupMembersPage(group, cursor) {
+        const groupId = await this.#requireGroupId(group);
+        const path = `/groups/${groupId}/members?briefRepresentation=false`;
+        return this.#page(cursor, path, async (users) => Promise.all(users.map((user) => this.#toUser(user))), () => new errors_1.GroupNotFoundError(group));
+    }
+    // One page from a Keycloak list endpoint that takes first/max. Asks for one item more than a page,
+    // so the last page is known to be the last without an extra request.
+    async #page(cursor, path, map, notFound) {
+        const first = cursor === null ? 0 : Number(cursor);
+        const response = await this.#request("GET", `${path}&first=${first}&max=${this.#pageSize + 1}`, { notFound });
+        const raw = (await response.json());
+        const more = raw.length > this.#pageSize;
+        return { items: await map(raw.slice(0, this.#pageSize)), nextCursor: more ? String(first + this.#pageSize) : null };
+    }
+    async #toUser(user) {
+        // a link to an identity provider is the only sign of an SSO user, and Keycloak keeps it off the user
+        const links = await this.#request("GET", `/users/${encodeURIComponent(user.id)}/federated-identity`, { notFound: () => new errors_1.UserNotFoundError(user.id) });
+        const federated = (await links.json()).length > 0;
+        const attributes = {};
+        for (const [appName, keycloakName] of this.#attributes) {
+            const value = user.attributes?.[keycloakName]?.[0];
+            if (value !== undefined)
+                attributes[appName] = value;
+        }
+        return {
+            id: user.id,
+            email: user.email ?? "",
+            name: [user.firstName, user.lastName].filter(Boolean).join(" ") || null,
+            status: statusOf(user, federated),
+            enabled: user.enabled ?? false,
+            attributes: attributes,
+        };
+    }
+    // Checks every name is declared, then that the realm will keep them: with Keycloak's user profile,
+    // an attribute it doesn't declare is dropped without an error unless unmanaged attributes are enabled.
+    async #toKeycloakAttributes(attributes) {
+        const entries = Object.entries(attributes ?? {});
+        const result = {};
+        for (const [name, value] of entries) {
+            const keycloakName = this.#attributes.get(name);
+            if (keycloakName === undefined) {
+                const declared = [...this.#attributes.keys()].join(", ") || "none";
+                throw new TypeError(`Unknown attribute ${name}. Declared attributes: ${declared}`);
+            }
+            result[keycloakName] = [value];
+        }
+        if (entries.length)
+            await this.#assertRealmKeeps(Object.keys(result));
+        return result;
+    }
+    async #assertRealmKeeps(keycloakNames) {
+        this.#profile ??= this.#request("GET", "/users/profile").then((response) => response.json());
+        let profile;
+        try {
+            profile = await this.#profile;
+        }
+        catch (error) {
+            this.#profile = undefined;
+            throw error;
+        }
+        if (profile.unmanagedAttributePolicy === "ENABLED" || profile.unmanagedAttributePolicy === "ADMIN_EDIT")
+            return;
+        const declared = new Set((profile.attributes ?? []).map((attribute) => attribute.name));
+        const dropped = keycloakNames.find((name) => !declared.has(name));
+        if (dropped === undefined)
+            return;
+        // read the profile again next time, so fixing the realm doesn't need a restart
+        this.#profile = undefined;
+        throw new Error(`Keycloak would silently drop the attribute ${dropped}: the realm's user profile doesn't declare it and ` +
+            "unmanaged attributes are disabled. Declare it in Realm settings → User profile, or set Unmanaged attributes to Enabled.");
+    }
+    // The id of the top-level group with exactly this name, or null.
+    async #groupId(group) {
+        const response = await this.#request("GET", `/groups?search=${encodeURIComponent(group)}&exact=true&briefRepresentation=true`);
+        const match = (await response.json()).find((candidate) => candidate.name === group);
+        return match?.id ?? null;
+    }
+    async #requireGroupId(group) {
+        const id = await this.#groupId(group);
+        if (id === null)
+            throw new errors_1.GroupNotFoundError(group);
+        return id;
+    }
+    async #request(method, path, options = {}) {
+        const response = await this.#fetch(method, path, options.body);
+        if (response.ok)
+            return response;
+        const where = `${method} ${path.split("?")[0]}`;
+        if (response.status === 404 && options.notFound)
+            throw options.notFound();
+        if (response.status === 409 && options.conflict)
+            throw options.conflict();
+        if (response.status === 403) {
+            throw new KeycloakRequestError(method, path, 403, `Keycloak refused ${where} (403). The client's service account needs these realm-management roles: ${exports.KEYCLOAK_ADMIN_ROLES.join(", ")}.`);
+        }
+        const detail = await response.text().catch(() => "");
+        throw new KeycloakRequestError(method, path, response.status, `Keycloak ${where} failed (${response.status}): ${detail}`);
+    }
+    async #fetch(method, path, body) {
+        return fetch(`${this.#adminUrl}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${await this.#accessToken()}`,
+                ...(body === undefined ? {} : { "content-type": "application/json" }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+    }
+    // A client-credentials token, shared by concurrent calls and reused until shortly before it expires.
+    async #accessToken() {
+        const cached = this.#token && (await this.#token.catch(() => undefined));
+        if (cached && cached.expiresAt > Date.now())
+            return cached.value;
+        this.#token = this.#requestToken();
+        try {
+            return (await this.#token).value;
+        }
+        catch (error) {
+            this.#token = undefined;
+            throw error;
+        }
+    }
+    async #requestToken() {
+        const response = await fetch(`${this.#realmUrl}/protocol/openid-connect/token`, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({ grant_type: "client_credentials", client_id: this.#clientId, client_secret: this.#clientSecret }),
+        });
+        if (!response.ok) {
+            throw new KeycloakRequestError("POST", "/protocol/openid-connect/token", response.status, `Keycloak rejected the client credentials for ${this.#clientId} (${response.status}). The client needs Client authentication ` +
+                "and Service account roles enabled, and the right secret.");
+        }
+        const body = (await response.json());
+        return { value: body.access_token, expiresAt: Date.now() + (body.expires_in ?? 60) * 1000 - TOKEN_EXPIRY_SKEW_MS };
+    }
+}
+exports.KeycloakAdapter = KeycloakAdapter;
+// Keycloak keeps a first and a last name; the first word is the first name, the rest the last.
+function splitName(name) {
+    const [firstName, ...rest] = (name ?? "").trim().split(/\s+/).filter(Boolean);
+    return { ...(firstName ? { firstName } : {}), ...(rest.length ? { lastName: rest.join(" ") } : {}) };
+}
+function statusOf(user, federated) {
+    if (federated)
+        return "federated";
+    if (user.requiredActions?.includes("UPDATE_PASSWORD"))
+        return "password_change_required";
+    if (user.requiredActions?.includes("VERIFY_EMAIL"))
+        return "unconfirmed";
+    return "active";
+}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where a user is in their account lifecycle. Whether they can sign in is separate: see `IdpUser.enabled`.
+ *
+ * - `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
+ * - `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";
+/**
+ * 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
+ * allowed (an empty `{}` type would accept any key).
+ */
+export type UserAttributes<TAttr extends string> = [TAttr] extends [never] ? Record<string, never> : Partial<Record<TAttr, string>>;
+/** A user as every adapter reports them. */
+export type IdpUser<TAttr extends string = never> = {
+    id: string;
+    email: string;
+    name: string | null;
+    status: UserStatus;
+    enabled: boolean;
+    attributes: UserAttributes<TAttr>;
+};
+/** One page of a list, and where the next one starts. */
+export type Page<T> = {
+    items: T[];
+    nextCursor: string | null;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/docs/cognito.md

@@ -0,0 +1,72 @@
+# cognito
+
+`idp-admin/cognito`: Amazon Cognito user pools, through the admin API of the AWS SDK. [Index](index.md)
+
+`@aws-sdk/client-cognito-identity-provider` (v3) is an optional peer dependency: install it alongside idp-admin to use this adapter.
+
+```sh
+npm install idp-admin @aws-sdk/client-cognito-identity-provider
+```
+
+## `new CognitoAdapter(options)`
+
+```ts
+import { CognitoAdapter } from "idp-admin/cognito"
+
+const adapter = new CognitoAdapter({
+    userPoolId: process.env.COGNITO_USER_POOL_ID!,
+    region: "us-east-1",
+    attributes: { company: "custom:companyName" },
+})
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `userPoolId` | required | The user pool to manage. |
+| `client` | none | A `CognitoIdentityProviderClient` you configured. When given, `region` and `credentials` are ignored. |
+| `region` | none | The pool's region, to build a client with. Either `client` or `region` is required; with neither, the constructor throws a `TypeError`. |
+| `credentials` | the AWS SDK's credential chain | Credentials for the built client. |
+| `attributes` | none | App attribute name → Cognito attribute name, e.g. `{ company: "custom:companyName" }`. The app names become the adapter's attribute type, so only they compile, and any other name is rejected at runtime with a `TypeError`. Custom attributes must exist in the pool's schema. |
+| `pageSize` | `60` | Most items per page from the list methods, a whole number from 1 to 60 (Cognito's largest page). Anything else throws a `RangeError`. |
+
+## IAM permissions
+
+The adapter calls these `cognito-idp` actions on the pool:
+
+`AdminCreateUser`, `AdminGetUser`, `ListUsers`, `AdminSetUserPassword`, `AdminEnableUser`, `AdminDisableUser`, `AdminDeleteUser`, `AdminUpdateUserAttributes`, `AdminUserGlobalSignOut`, `AdminAddUserToGroup`, `AdminRemoveUserFromGroup`, `AdminListGroupsForUser`, `ListUsersInGroup`, `GetGroup`, `CreateGroup`, `DeleteGroup`
+
+Every one of them can be limited to the pool's ARN, `arn:aws:cognito-idp:<region>:<account>:userpool/<pool id>`.
+
+## Behaviour
+
+- **Ids** are the user's `sub`, which their tokens carry. A local user's `sub` is also their Cognito username, so admin calls use it directly. An SSO user's username is provider-qualified (`MicrosoftEntraIDSAML_…`), and Cognito won't take their `sub`: the first call for one looks their username up by `sub` and the adapter remembers it. Lists remember the usernames they see, too.
+- **Emails** are the username, and are stored as verified, because an admin typed them in. Cognito matches them case-insensitively and rejects emails it considers invalid, including ones containing `"`. `findUserByEmail` returns `null` for an email containing `"` without asking Cognito, because Cognito's filter syntax has no way to escape one.
+- **Names** are stored in Cognito's standard `name` attribute.
+- **Status:**
+
+  | Cognito `UserStatus` | `status` |
+  |---|---|
+  | `CONFIRMED` | `active` |
+  | `FORCE_CHANGE_PASSWORD`, `RESET_REQUIRED`, `COMPROMISED` | `password_change_required` |
+  | `UNCONFIRMED` | `unconfirmed` |
+  | `EXTERNAL_PROVIDER` | `federated` |
+  | anything else | `active` |
+
+- **Attributes** are single Cognito attributes under their Cognito names. `updateAttributes` changes only the ones given.
+- **Invitations:** `createUser` sends nothing, because the app sends its own email with the temporary password. `createUserWithInvite` has Cognito generate a password and email its invitation, and `resendInvite` sends it again. Both use the pool's email settings; Cognito's default sender has a low daily limit.
+- **Groups** are addressed by name. Cognito removes a user from a group that doesn't exist without complaint, so `removeFromGroup` checks the group first and throws `GroupNotFoundError`.
+- **Sign-out:** `signOutEverywhere` revokes the user's refresh tokens. Access and ID tokens already issued stay valid until they expire, about an hour by default.
+- **Lists** use Cognito's own page tokens as cursors. Cognito doesn't return users in creation order.
+
+## Errors
+
+Cognito's `UsernameExistsException` and `AliasExistsException` become `UserExistsError`, `UserNotFoundException` becomes `UserNotFoundError`, `ResourceNotFoundException` on a group becomes `GroupNotFoundError`, and `GroupExistsException` becomes `GroupExistsError`. Every other Cognito error, such as `TooManyRequestsException`, is thrown unchanged. An unknown attribute name throws a `TypeError` before anything is sent.
+
+## `native`
+
+```ts
+adapter.native.client       // the CognitoIdentityProviderClient
+adapter.native.userPoolId
+```
+
+The client and pool, for anything the shared interface doesn't cover.