@adatechnology/keycloak-admin 0.1.16 → 1.0.0-rc.1

package/README.md

@@ -0,0 +1,63 @@
+# @adatechnology/keycloak-admin
+
+Cliente do Keycloak Admin API autenticado como **service account** (`client_credentials`).
+Agnóstico de framework e de runtime: só depende de `fetch` e de `zod`.
+
+Diferença deliberada para o `@adatechnology/nestjs-keycloak-admin`: aquele obtém token com
+`grant_type=password` usando o usuário administrador do realm `master`. Este **nunca** envia senha
+nem usuário — a identidade é do client confidencial, com `manage-users` do `realm-management`.
+
+## Uso
+
+```ts
+import { createKeycloakAdminClient } from '@adatechnology/keycloak-admin'
+
+const keycloak = createKeycloakAdminClient({
+  config: {
+    baseUrl: process.env.KEYCLOAK_URL,
+    clientId: process.env.KEYCLOAK_ADMIN_CLIENT_ID,
+    clientSecret: process.env.KEYCLOAK_ADMIN_CLIENT_SECRET,
+    realm: process.env.KEYCLOAK_REALM,
+  },
+})
+
+const { id } = await keycloak.createUser({
+  attributes: { company_id: companyId },
+  email: 'admin@transportadora.example',
+  enabled: true,
+  firstName: 'Ada',
+  lastName: 'Lovelace',
+  password: { temporary: false, value: chosenPassword },
+  username: 'admin@transportadora.example',
+})
+```
+
+Operações: `createUser`, `findUserByEmail`, `listUsers`, `updateUser`, `setEnabled`,
+`updateAttributes`, `deleteUser`, `setPassword`, `setTemporaryPassword`.
+
+`listUsers({ first, limit, search })` devolve `{ users, hasMore }`. O realm não informa total, então
+a página pede um registro a mais que o limite e descarta-o: é assim que `hasMore` sai sem uma
+segunda chamada.
+
+## Token
+
+Obtido sob demanda, guardado em memória e renovado 30s antes de expirar
+(`KEYCLOAK_ADMIN_TOKEN_RENEWAL_SKEW_MS`). Chamadas concorrentes compartilham a mesma requisição em
+voo — o Keycloak recebe uma, não N.
+
+## Injeção
+
+`fetch` e `now` são injetáveis, o que torna rede e relógio observáveis em teste:
+
+```ts
+createKeycloakAdminClient({ config, fetch: stubFetch, now: clock.now })
+```
+
+## Erros
+
+Toda falha vira `KeycloakAdminError` com `code` estável (`KEYCLOAK_ADMIN_ERROR_CODE`), `status` e
+`context`. O contexto é montado por allowlist e passa por um redator que substitui `clientSecret`,
+access token e senha por `[REDACTED]` — nem a mensagem nem o erro serializado carregam segredo.
+
+Configuração inválida falha na construção do cliente, com o **caminho** do campo no contexto e nunca
+o valor.

package/dist/index.d.ts

@@ -1,91 +1,158 @@
-import { DynamicModule } from "@nestjs/common";
+import { z } from 'zod';
 
-export interface KeycloakAdminConfig {
-  baseUrl: string;
-  realm: string;
-  adminUser: string;
-  adminPassword: string;
-}
-
-export interface GetAdminTokenResult {
-  accessToken: string;
-  expiresIn: number;
-  tokenType: string;
-}
-
-export interface UpdateUserParams {
-  userId: string;
-  userData: Record<string, unknown>;
-  adminToken: string;
-}
+declare const KEYCLOAK_ADMIN_TOKEN_RENEWAL_SKEW_MS = 30000;
+declare const KEYCLOAK_ADMIN_ERROR_CODE: {
+    readonly CONFIGURATION_INVALID: "KEYCLOAK_ADMIN_CONFIGURATION_INVALID";
+    readonly REQUEST_FAILED: "KEYCLOAK_ADMIN_REQUEST_FAILED";
+    readonly TOKEN_REQUEST_FAILED: "KEYCLOAK_ADMIN_TOKEN_REQUEST_FAILED";
+    readonly TOKEN_RESPONSE_INVALID: "KEYCLOAK_ADMIN_TOKEN_RESPONSE_INVALID";
+    readonly USER_ALREADY_EXISTS: "KEYCLOAK_ADMIN_USER_ALREADY_EXISTS";
+    readonly USER_ID_MISSING: "KEYCLOAK_ADMIN_USER_ID_MISSING";
+    readonly USER_NOT_FOUND: "KEYCLOAK_ADMIN_USER_NOT_FOUND";
+};
+type KeycloakAdminErrorCode = (typeof KEYCLOAK_ADMIN_ERROR_CODE)[keyof typeof KEYCLOAK_ADMIN_ERROR_CODE];
+type BuildKeycloakAdminEndpointsParams = {
+    readonly baseUrl: string;
+    readonly realm: string;
+};
+declare function buildKeycloakAdminEndpoints({ baseUrl, realm }: BuildKeycloakAdminEndpointsParams): {
+    readonly token: `${string}/realms/${string}/protocol/openid-connect/token`;
+    readonly user: (userId: string) => string;
+    readonly userPassword: (userId: string) => string;
+    readonly users: string;
+};
+type KeycloakAdminEndpoints = ReturnType<typeof buildKeycloakAdminEndpoints>;
 
-export interface ResetPasswordParams {
-  userId: string;
-  password: string;
-  temporary: boolean;
-  adminToken: string;
+type KeycloakAdminErrorContext = Readonly<Record<string, unknown>>;
+type KeycloakAdminErrorParams = {
+    readonly code: KeycloakAdminErrorCode;
+    readonly context?: KeycloakAdminErrorContext;
+    readonly message: string;
+    readonly status?: number;
+};
+type SerializedKeycloakAdminError = {
+    readonly code: KeycloakAdminErrorCode;
+    readonly context: KeycloakAdminErrorContext;
+    readonly message: string;
+    readonly name: string;
+    readonly status: number | undefined;
+};
+/**
+ * Falha de qualquer operação do Admin API, com código estável para o consumidor decidir.
+ * O contexto é montado por allowlist e passa pelo redator — segredo, token e senha nunca entram.
+ */
+declare class KeycloakAdminError extends Error {
+    readonly code: KeycloakAdminErrorCode;
+    readonly context: KeycloakAdminErrorContext;
+    readonly status: number | undefined;
+    constructor({ code, context, message, status }: KeycloakAdminErrorParams);
+    toJSON(): SerializedKeycloakAdminError;
 }
+declare function isKeycloakAdminError(value: unknown): value is KeycloakAdminError;
 
-export interface ToggleUserEnabledParams {
-  userId: string;
-  enabled: boolean;
-  adminToken: string;
-}
-
-export interface DeleteUserParams {
-  userId: string;
-  adminToken: string;
-}
-
-export interface UpdateUserAttributesParams {
-  userId: string;
-  attributes: Record<string, string | string[]>;
-  adminToken: string;
-}
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+type KeycloakAdminConfig = {
+    readonly baseUrl: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly realm: string;
+};
+type KeycloakUserAttributes = Readonly<Record<string, string | readonly string[]>>;
+type KeycloakUser = {
+    readonly attributes?: KeycloakUserAttributes;
+    readonly email?: string;
+    readonly emailVerified?: boolean;
+    readonly enabled?: boolean;
+    readonly firstName?: string;
+    readonly id: string;
+    readonly lastName?: string;
+    readonly username?: string;
+};
+type KeycloakPassword = {
+    readonly temporary: boolean;
+    readonly value: string;
+};
+type CreateUserParams = {
+    readonly attributes?: KeycloakUserAttributes;
+    readonly email: string;
+    readonly emailVerified?: boolean;
+    readonly enabled?: boolean;
+    readonly firstName?: string;
+    readonly lastName?: string;
+    readonly password?: KeycloakPassword;
+    readonly username: string;
+};
+type CreateUserResult = {
+    readonly id: string;
+};
+type FindUserByEmailParams = {
+    readonly email: string;
+};
+/**
+ * O realm não devolve página infinita: `first`/`max` são o recorte que o Keycloak entende, e quem
+ * chama precisa saber se ainda há mais — daí `hasMore`, derivado de pedir um a mais que o limite.
+ */
+type ListUsersParams = {
+    readonly first?: number;
+    readonly limit?: number;
+    readonly search?: string;
+};
+type ListUsersResult = {
+    readonly hasMore: boolean;
+    readonly users: readonly KeycloakUser[];
+};
+type UpdateUserParams = {
+    readonly user: Readonly<Partial<Pick<KeycloakUser, 'email' | 'emailVerified' | 'firstName' | 'lastName' | 'username'>>>;
+    readonly userId: string;
+};
+type SetEnabledParams = {
+    readonly enabled: boolean;
+    readonly userId: string;
+};
+type UpdateAttributesParams = {
+    readonly attributes: KeycloakUserAttributes;
+    readonly userId: string;
+};
+type DeleteUserParams = {
+    readonly userId: string;
+};
+type SetPasswordParams = {
+    readonly password: string;
+    readonly temporary: boolean;
+    readonly userId: string;
+};
+type SetTemporaryPasswordParams = {
+    readonly password: string;
+    readonly userId: string;
+};
+type KeycloakAdminClient = {
+    createUser(params: CreateUserParams): Promise<CreateUserResult>;
+    deleteUser(params: DeleteUserParams): Promise<void>;
+    findUserByEmail(params: FindUserByEmailParams): Promise<KeycloakUser | undefined>;
+    listUsers(params?: ListUsersParams): Promise<ListUsersResult>;
+    setEnabled(params: SetEnabledParams): Promise<void>;
+    setPassword(params: SetPasswordParams): Promise<void>;
+    setTemporaryPassword(params: SetTemporaryPasswordParams): Promise<void>;
+    updateAttributes(params: UpdateAttributesParams): Promise<void>;
+    updateUser(params: UpdateUserParams): Promise<void>;
+};
+type CreateKeycloakAdminClientParams = {
+    readonly config: KeycloakAdminConfig;
+    readonly fetch?: FetchLike;
+    readonly now?: () => number;
+};
 
-export interface SendVerifyEmailParams {
-  userId: string;
-  adminToken: string;
-}
-
-export interface KeycloakAdminClientInterface {
-  getAdminToken(): Promise<GetAdminTokenResult>;
-  updateUser(params: UpdateUserParams): Promise<void>;
-  resetPassword(params: ResetPasswordParams): Promise<void>;
-  toggleUserEnabled(params: ToggleUserEnabledParams): Promise<void>;
-  deleteUser(params: DeleteUserParams): Promise<void>;
-  updateUserAttributes(params: UpdateUserAttributesParams): Promise<void>;
-  sendVerifyEmail(params: SendVerifyEmailParams): Promise<void>;
-}
-
-export class KeycloakAdminError extends Error {
-  readonly statusCode?: number;
-  readonly code?: string;
-  readonly context?: Record<string, unknown>;
-  constructor(params: {
-    message: string;
-    statusCode?: number;
-    code?: string;
-    context?: Record<string, unknown>;
-  });
-}
-
-export class KeycloakAdminClient implements KeycloakAdminClientInterface {
-  getAdminToken(): Promise<GetAdminTokenResult>;
-  updateUser(params: UpdateUserParams): Promise<void>;
-  resetPassword(params: ResetPasswordParams): Promise<void>;
-  toggleUserEnabled(params: ToggleUserEnabledParams): Promise<void>;
-  deleteUser(params: DeleteUserParams): Promise<void>;
-  updateUserAttributes(params: UpdateUserAttributesParams): Promise<void>;
-  sendVerifyEmail(params: SendVerifyEmailParams): Promise<void>;
-}
-
-export class KeycloakAdminModule {
-  static forRoot(config: KeycloakAdminConfig): DynamicModule;
-}
+declare const keycloakAdminConfigSchema: z.ZodObject<{
+    baseUrl: z.ZodString;
+    clientId: z.ZodString;
+    clientSecret: z.ZodString;
+    realm: z.ZodString;
+}, z.core.$strip>;
+/**
+ * A falha carrega só o caminho do campo inválido. O valor nunca entra — seria o `clientSecret`.
+ */
+declare function parseKeycloakAdminConfig(value: unknown): KeycloakAdminConfig;
 
-export function validateKeycloakAdminConfig(config: KeycloakAdminConfig): void;
+declare function createKeycloakAdminClient({ config: rawConfig, fetch: injectedFetch, now, }: CreateKeycloakAdminClientParams): KeycloakAdminClient;
 
-export const KEYCLOAK_ADMIN_CLIENT = "KEYCLOAK_ADMIN_CLIENT";
-export const KEYCLOAK_ADMIN_CONFIG = "KEYCLOAK_ADMIN_CONFIG";
-export const KEYCLOAK_ADMIN_PROVIDER = "KEYCLOAK_ADMIN_PROVIDER";
+export { type CreateKeycloakAdminClientParams, type CreateUserParams, type CreateUserResult, type DeleteUserParams, type FetchLike, type FindUserByEmailParams, KEYCLOAK_ADMIN_ERROR_CODE, KEYCLOAK_ADMIN_TOKEN_RENEWAL_SKEW_MS, type KeycloakAdminClient, type KeycloakAdminConfig, type KeycloakAdminEndpoints, KeycloakAdminError, type KeycloakAdminErrorCode, type KeycloakAdminErrorContext, type KeycloakAdminErrorParams, type KeycloakPassword, type KeycloakUser, type KeycloakUserAttributes, type ListUsersParams, type ListUsersResult, type SerializedKeycloakAdminError, type SetEnabledParams, type SetPasswordParams, type SetTemporaryPasswordParams, type UpdateAttributesParams, type UpdateUserParams, buildKeycloakAdminEndpoints, createKeycloakAdminClient, isKeycloakAdminError, keycloakAdminConfigSchema, parseKeycloakAdminConfig };