idp-admin 0.0.0-stage → 0.1.1

package/docs/fake.md

@@ -0,0 +1,59 @@
+# fake
+
+`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.
+
+Not for production: nothing is shared between instances or kept after the process exits.
+
+## `new FakeAdapter(options?)`
+
+```ts
+import { FakeAdapter } from "idp-admin/fake"
+
+const fake = new FakeAdapter({ attributes: ["company"] })
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `attributes` | none | Custom attribute names users may have. They become the adapter's attribute type, so only these compile, and anything else is also rejected at runtime with a `TypeError`, as a real provider would. |
+| `pageSize` | `60` | Most items per page from the list methods. `60` is Cognito's largest page; set it low to test paging. |
+
+## 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.
+- **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
+- **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.
+- **Deleting** a user also frees their email and removes them from every group. Deleting a group removes it from its members.
+
+## Fake-only helpers
+
+### `addFederatedUser(input)`
+
+```ts
+const admin = fake.addFederatedUser({ email: "admin@mc3.co", name: "An Admin", attributes: { company: "MC3" } })
+```
+
+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.
+
+### `invitations`
+
+```ts
+fake.invitations   // readonly { userId: string; email: string }[]
+```
+
+Every provider invitation the fake would have sent, oldest first: one per `createUserWithInvite` and one per `resendInvite`. `createUser` sends none, because the app sends its own email.
+
+### `signOuts`
+
+```ts
+fake.signOuts   // readonly string[]
+```
+
+The id of every user signed out at the provider, oldest first, once per `signOutEverywhere` call.

package/docs/index.md

@@ -0,0 +1,115 @@
+# 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.
+
+| Entry point | Doc |
+|---|---|
+| `idp-admin` | This file |
+| `idp-admin/fake` | [fake.md](fake.md) |
+| `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.
+
+## Types
+
+### `IdpUser<TAttr>`
+
+```ts
+type IdpUser<TAttr extends string = never> = {
+    id: string
+    email: string
+    name: string | null
+    status: UserStatus
+    enabled: boolean
+    attributes: UserAttributes<TAttr>
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `id` | The provider's permanent id for the user: the one their sign-in tokens carry as `sub`. Cognito: the user's `sub`. Keycloak: the user id. Fake: a UUID v4. |
+| `email` | Always lowercase. |
+| `name` | `null` when the provider has none. |
+| `status` | Where they are in their account lifecycle. See `UserStatus`. |
+| `enabled` | `false` once disabled. A disabled user can't sign in, whatever their `status`. |
+| `attributes` | Custom attributes, keyed by the names declared in the adapter's config. |
+
+### `UserStatus`
+
+```ts
+type UserStatus = "active" | "password_change_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. |
+| `federated` | Signs in through another identity provider (SSO), so has no password here. |
+| `unconfirmed` | Signed themselves up and hasn't confirmed their account yet. |
+
+Whether a user is disabled is `enabled`, not a status: a user disabled before setting a password is still `password_change_required`.
+
+### `UserAttributes<TAttr>`
+
+```ts
+type UserAttributes<TAttr extends string> = [TAttr] extends [never] ? Record<string, never> : Partial<Record<TAttr, string>>
+```
+
+`TAttr` is the attribute names declared in the adapter's config, inferred from it; no type parameter is written by hand. Only declared names compile, and with none declared no attribute compiles. Values are strings, because that is what providers store.
+
+### `Page<T>`
+
+```ts
+type Page<T> = { items: T[]; nextCursor: string | null }
+```
+
+One page of a list. Pass `nextCursor` back to get the next page; it is `null` on the last page. Cursors are opaque: don't build or change them.
+
+## Errors
+
+Every error idp-admin throws on purpose extends `IdpAdminError`, so `instanceof IdpAdminError` separates them from provider and network failures. Each has a fixed `code`, typed as a literal, and `name` set to its class name. `AnyIdpAdminError` is the union of all of them, so `switch(error.code)` narrows to the matching class.
+
+| Class | `code` | Extra fields | Thrown when |
+|---|---|---|---|
+| `UserNotFoundError` | `USER_NOT_FOUND` | `userId` | The user doesn't exist, or no longer does. |
+| `UserExistsError` | `USER_EXISTS` | `email` | Creating a user whose email is taken. |
+| `GroupNotFoundError` | `GROUP_NOT_FOUND` | `group` | The group doesn't exist. |
+| `GroupExistsError` | `GROUP_EXISTS` | `group` | Creating a group that exists. |
+| `NotSupportedError` | `NOT_SUPPORTED` | `feature` | The adapter can't do what was asked; `feature` names the method or option. |
+| `AccessReductionIncompleteError` | `ACCESS_REDUCTION_INCOMPLETE` | `userId`, `action`, `failedStep`, `cause` | A user was deleted, disabled or removed from a group at the provider, but a later step failed. |
+
+`AccessReductionIncompleteError`:
+- `action` is `"deleted"`, `"disabled"` or `"removed-from-group"`: what already happened at the provider. It is not undone.
+- `failedStep` is `"provider-sign-out"` or `"hook"`: the step after it that failed.
+- `cause` is the original error.
+- Calling the same method again is safe and repeats every step.
+
+## `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.
+
+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.
+
+| Method | Returns | Behaviour |
+|---|---|---|
+| `createUser(input)` | `IdpUser` | Creates a user with `input.temporaryPassword`, who must replace it at first sign-in. The provider sends no message. Throws `UserExistsError`. |
+| `createUserWithInvite?(input)` | `IdpUser` | Optional. The provider generates a password and sends its own invitation. Throws `UserExistsError`. |
+| `getUser(userId)` | `IdpUser` | |
+| `findUserByEmail(email)` | `IdpUser \| null` | `null` when nobody has that email. |
+| `listUsersPage(cursor)` | `Page<IdpUser>` | One page of every user. Pass `null` for the first page. |
+| `setPassword(userId, password, { temporary })` | `void` | A temporary password must be replaced at next sign-in. |
+| `setEnabled(userId, enabled)` | `void` | Succeeds if the user is already in that state. |
+| `deleteUser(userId)` | `void` | Also removes them from every group. |
+| `updateAttributes(userId, attributes)` | `void` | Sets the given attributes and leaves the rest unchanged. |
+| `resendInvite?(userId)` | `void` | Optional. Sends the provider's invitation again. |
+| `signOutEverywhere(userId)` | `void` | Revokes the user's tokens at the provider. |
+| `addToGroup(userId, group)` | `void` | Succeeds if they're already a member. |
+| `removeFromGroup(userId, group)` | `void` | Succeeds if they aren't a member. |
+| `listUserGroupsPage(userId, cursor)` | `Page<string>` | One page of the names of the groups a user is in. |
+| `groupExists(group)` | `boolean` | |
+| `createGroup(group)` | `void` | Throws `GroupExistsError`. |
+| `deleteGroup(group)` | `void` | Removes every member from it first. |
+| `listGroupMembersPage(group, cursor)` | `Page<IdpUser>` | One page of a group's members. |
+
+`AdapterCreateUserInput<TAttr>` is `{ email, name?, attributes?, temporaryPassword }`. `AdapterInviteUserInput<TAttr>` is the same without `temporaryPassword`.

package/docs/keycloak.md

@@ -0,0 +1,71 @@
+# keycloak
+
+`idp-admin/keycloak`: Keycloak, through its admin REST API. [Index](index.md)
+
+Tested against Keycloak 26. It uses the global `fetch` and has no dependencies.
+
+## `new KeycloakAdapter(options)`
+
+```ts
+import { KeycloakAdapter } from "idp-admin/keycloak"
+
+const adapter = new KeycloakAdapter({
+    issuer: "https://auth.example.com/realms/frcs",
+    clientId: "frcs-admin",
+    clientSecret: process.env.KEYCLOAK_ADMIN_SECRET!,
+    attributes: { company: "companyName" },
+})
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `issuer` | required | The realm's URL, `<host>/realms/<realm>`: the same value the app uses as its OIDC issuer. A trailing slash is fine. Anything else throws a `TypeError`. |
+| `clientId`, `clientSecret` | required | A confidential client whose service account the adapter acts as. See [Realm setup](#realm-setup). |
+| `attributes` | none | App attribute name → Keycloak attribute name. The app names become the adapter's attribute type, so only they compile, and any other name is rejected at runtime with a `TypeError`. |
+| `pageSize` | `50` | Most items per page from the list methods, a whole number from 1 to 99. Anything else throws a `RangeError`. |
+
+## Realm setup
+
+The adapter needs three things from the realm:
+
+1. **A confidential client with a service account.** Client authentication on, Service account roles on. Nothing else about the client matters to the adapter.
+2. **These realm-management roles on the service account,** exported as `KEYCLOAK_ADMIN_ROLES`: `manage-users`, `view-users`, `query-users`, `query-groups`, and `manage-realm` (for creating and deleting groups). The tests run with exactly these. If a call is refused, the error names them.
+3. **Somewhere for custom attributes to go,** if `attributes` is set. Keycloak's user profile **silently drops** an attribute it doesn't declare unless unmanaged attributes are enabled. Either declare each Keycloak attribute name in Realm settings → User profile, or set Unmanaged attributes to Enabled. Before writing attributes, the adapter reads the realm's user profile and throws, without creating or changing anyone, if Keycloak would drop one.
+
+Also worth knowing: by default Keycloak requires a first and last name before anyone can sign in ("Account is not fully set up"). A user created without a name, or with a one-word name, can't sign in until the realm's user profile makes those fields optional or the user fills them in.
+
+## Behaviour
+
+- **Ids** are Keycloak user ids, which Keycloak puts in the `sub` of the user's tokens.
+- **Emails** are the username too. Keycloak stores them lowercase and rejects emails it considers invalid, including ones containing `"`. `findUserByEmail` matches exactly.
+- **Names:** Keycloak keeps a first and a last name. The first word of `name` becomes the first name and the rest the last name. Reading joins them back with a space.
+- **Status:**
+  - `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.
+  - `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.
+- **Sign-out:** `signOutEverywhere` ends every session the user has, so their refresh tokens stop working. Access tokens already issued stay valid until they expire.
+- **Not supported:** `createUserWithInvite` and `resendInvite`. Keycloak can only send invitations through required-action emails, which need SMTP on the realm. Send your own email with a temporary password instead.
+- **Lists** ask Keycloak for one item more than a page, so the last page is known without an extra request. Detecting federated users takes one extra request per user listed.
+- **Tokens:** the adapter gets a client-credentials token and reuses it until 30 seconds before it expires. Concurrent calls share one token request.
+
+## Errors
+
+Besides the idp-admin errors in the [index](index.md#errors):
+
+| Error | When |
+|---|---|
+| `KeycloakRequestError` | Keycloak answered with a status the adapter doesn't turn into an idp-admin error. It has `method`, `path` and `status`. A rejected client secret and a refused call (403) both explain what to fix. |
+| `TypeError` | An unknown attribute name, or an issuer that isn't `<host>/realms/<realm>`. |
+| `Error` | The realm would silently drop an attribute. See [Realm setup](#realm-setup). |
+
+## `native`
+
+```ts
+const response = await adapter.native.request("GET", "/users/count")
+adapter.native.adminUrl   // https://auth.example.com/admin/realms/frcs
+```
+
+The admin API, authenticated as the service account, for anything the shared interface doesn't cover. Paths are relative to `/admin/realms/<realm>`. `request` returns the raw `Response` and doesn't throw on error statuses.

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "idp-admin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "One user-management API for any identity provider.",
+  "keywords": [
+    "identity-provider",
+    "idp",
+    "user-management",
+    "users",
+    "groups",
+    "admin",
+    "iam",
+    "oidc",
+    "cognito",
+    "keycloak"
+  ],
+  "license": "MIT",
+  "author": "Leighton Miguel",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shortxmas/idp-admin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shortxmas/idp-admin/issues"
+  },
+  "homepage": "https://github.com/shortxmas/idp-admin#readme",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cognito": {
+      "types": "./dist/cognito/index.d.ts",
+      "default": "./dist/cognito/index.js"
+    },
+    "./keycloak": {
+      "types": "./dist/keycloak/index.d.ts",
+      "default": "./dist/keycloak/index.js"
+    },
+    "./fake": {
+      "types": "./dist/fake/index.d.ts",
+      "default": "./dist/fake/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "jest",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-cognito-identity-provider": "^3"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-cognito-identity-provider": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-cognito-identity-provider": "^3.1151.0",
+    "@swc/core": "^1.16.13",
+    "@swc/jest": "^0.2.39",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.6.4",
+    "jest": "^30.5.2",
+    "tsx": "^4.23.15",
+    "typescript": "5.9.3"
+  }
+}