@eva_solutions/auth-sdk 0.0.0-stage → 3.0.0-dev-20261107051125

package/dist/index-DBZoLU4E.d.ts

@@ -0,0 +1,240 @@
+import { d as Result } from "./types-CLOIHzRu.js";
+import { Bn as UpdateServiceClientResponse, Ct as UpdateProductoRequest, D as SetProductoPermisosAutorizablesRequest, E as ProductoPermisosAutorizablesResponse, Fn as ServiceClientGrant$1, Ht as ReassignTitularRequest, In as ServiceClientPublic$1, Ln as SetServiceClientGrantRequest, On as CreateServiceClientRequest, Pn as RotateServiceClientSecretResponse, Pt as EmpresaEstadoResponse, St as ProductoResponse, Ut as ReassignTitularResponse, bt as ListProductosResponse, ct as SetContratacionRequest, f as ListServiceClientDelegationsResponse, gi as ACCOUNT_STATES, jn as ListServiceClientGrantsResponse, kn as CreateServiceClientResponse, m as SetServiceClientDelegationRequest, nr as MaintenanceCleanupResponse, ot as ContratacionResponse, p as ServiceClientDelegation$1, ur as RepublishPendingResponse, yt as CreateProductoRequest, zn as UpdateServiceClientRequest } from "./index-Dold-Ycb.js";
+/** Unión de literales de todos los estados de cuenta posibles. */
+type AccountState = (typeof ACCOUNT_STATES)[keyof typeof ACCOUNT_STATES];
+/**
+ * Configuración del cliente Admin: las credenciales de un service client con la marca `esAdmin`.
+ * Cada request se firma con HMAC S2S; el secret nunca viaja.
+ */
+type AdminClientConfig = {
+  /** Slug del service client con la marca `esAdmin` (clientId). */
+  clientId: string;
+  /** Secret del service client admin en hex (64 chars), el que devuelve su creación o rotación. */
+  secretHex: string;
+  /**
+   * URL base del Auth Service API (sin trailing slash).
+   * Validada en `createAdminClient`: se requiere https (o http con host loopback para tests).
+   */
+  baseUrl: string;
+};
+/**
+ * Service client público (sin el plaintext del secret).
+ * Shape del wire en GET /admin/service-clients/*.
+ * Las fechas vienen serializadas como ISO strings en el wire.
+ */
+type ServiceClientPublic = ServiceClientPublic$1;
+/**
+ * Input para crear un nuevo service client (alias del request del contrato). Nace sin
+ * concesiones: se asignan con `setServiceClientGrant`. `auth-service` es un slug reservado.
+ */
+type CreateServiceClientInput = CreateServiceClientRequest;
+/** Input para crear un producto (alias del request del contrato). `enabled` por defecto es `true`. */
+type CreateProductoInput = CreateProductoRequest;
+/** Input para actualizar un producto (patch parcial; alias del request del contrato). */
+type UpdateProductoInput = UpdateProductoRequest;
+/** Resultado de `listProductos`: `{ productos }`. */
+type ListProductosResult = ListProductosResponse['data'];
+/** Resultado de crear o actualizar un producto: `{ producto }`. */
+type ProductoResult = ProductoResponse['data'];
+/** Concesión de un service client sobre una audiencia: los permisos que puede pedir en su token. */
+type ServiceClientGrant = ServiceClientGrant$1;
+/**
+ * Input de `setServiceClientGrant`: audiencia y permisos del catálogo de `auth-contracts`.
+ * Un permiso que no es de esa audiencia (p. ej. `admin` en `auth-api`) no compila y el API lo rechaza.
+ */
+type SetServiceClientGrantInput = SetServiceClientGrantRequest;
+/** Resultado de `listServiceClientGrants`. */
+type ListServiceClientGrantsResult = ListServiceClientGrantsResponse['data'];
+/**
+ * Resultado de crear un service client.
+ * El `secret` solo se devuelve UNA VEZ — guardarlo de inmediato.
+ */
+type CreateServiceClientResult = CreateServiceClientResponse['data'];
+/**
+ * Input para actualizar un service client (patch parcial; alias del request del contrato).
+ * Al menos un campo debe estar presente.
+ */
+type UpdateServiceClientInput = UpdateServiceClientRequest;
+/**
+ * Resultado de actualizar un service client.
+ */
+type UpdateServiceClientResult = UpdateServiceClientResponse['data'];
+/**
+ * Resultado de rotar el secret de un service client.
+ * El `secret` nuevo solo se devuelve UNA VEZ.
+ */
+type RotateSecretResult = RotateServiceClientSecretResponse['data'];
+/**
+ * Resultado de restaurar una cuenta de usuario eliminada.
+ * REQ-RESTORE-01 LOCKED.
+ *
+ * Tipo propio del SDK: `stateAccount` es la unión completa `AccountState`, y en el wire es el único
+ * literal `no_verificado`.
+ */
+type RestoreUserResult = {
+  userId: string;
+  /** Estado de la cuenta tras la restauración. */
+  stateAccount: AccountState;
+  previouslyDeletedAt: string | null;
+  restoredAt: string;
+};
+/**
+ * Query de `republishPendingWebhooks`. Tipo propio del SDK (como `ListWebhookDeliveriesQuery`):
+ * el query del contrato coacciona strings y su tipo de entrada es `unknown`. Los rangos los valida
+ * el API (400).
+ */
+type RepublishPendingWebhooksQuery = {
+  /** Antigüedad mínima en minutos de las entregas `pending` a republicar. Default del API: 10. */
+  older_than_minutes?: number;
+  /** Máximo de entregas por llamada. Default y tope del API: 100. */
+  limit?: number;
+};
+/**
+ * Resultado de `republishPendingWebhooks`: cuántas entregas se republicaron y si quedan más
+ * (`hasMore`: vuelve a llamar). Un 503 `service_unavailable` indica que QStash no aceptó el lote.
+ */
+type RepublishPendingWebhooksResult = RepublishPendingResponse['data'];
+/**
+ * Query de `maintenanceCleanup`. Tipo propio del SDK (como {@link RepublishPendingWebhooksQuery}):
+ * el rango lo valida el API (400).
+ */
+type MaintenanceCleanupQuery = {
+  /** Máximo por lote en cada una de las dos limpiezas. Default y tope del API: 100. */
+  limit?: number;
+};
+/**
+ * Resultado de `maintenanceCleanup`: cuentas `eliminado` purgadas (ventana de restauración vencida),
+ * `webhook_events` sin entregas vivas borrados (fuera de la retención) y si queda más (`hasMore`:
+ * vuelve a llamar).
+ */
+type MaintenanceCleanupResult = MaintenanceCleanupResponse['data'];
+/**
+ * Arista de delegación de un service client: puede intercambiar tokens hacia `audience` con, como
+ * máximo, `scopes`; `requiere_scope_origen` vacío = no admite re-exchange.
+ */
+type ServiceClientDelegation = ServiceClientDelegation$1;
+/**
+ * Input de `setServiceClientDelegation`: audiencia delegable y permisos delegables del catálogo
+ * (`auth-api` y `admin` no compilan y el API los rechaza). `requiere_scope_origen` es opcional.
+ */
+type SetServiceClientDelegationInput = SetServiceClientDelegationRequest;
+/** Resultado de `listServiceClientDelegations`. */
+type ListServiceClientDelegationsResult = ListServiceClientDelegationsResponse['data'];
+/** Input de `setProductoPermisosAutorizables`: la lista COMPLETA de permisos entre empresas (vacía = ninguno). */
+type SetProductoPermisosAutorizablesInput = SetProductoPermisosAutorizablesRequest;
+/** Permisos entre empresas que un producto puede conceder: `{ producto, permisos }`. */
+type ProductoPermisosAutorizablesResult = ProductoPermisosAutorizablesResponse['data'];
+/**
+ * Input de `reassignEmpresaTitular`: la persona que pasa a titular y qué pasa con el titular
+ * anterior (`'miembro'` por defecto, o `'fuera'`).
+ */
+type ReassignEmpresaTitularInput = ReassignTitularRequest;
+/** Resultado de la reasignación de titular. */
+type ReassignEmpresaTitularResult = ReassignTitularResponse['data'];
+/** Estado de la empresa tras `bajaEmpresa` / `reactivarEmpresa`. */
+type AdminEmpresaEstadoResult = EmpresaEstadoResponse['data'];
+/** Input de `setContratacion`: estado (`prueba`, `activo`, `suspendido`, `cancelado`) y vencimiento. */
+type AdminSetContratacionInput = SetContratacionRequest;
+/** Contratación de un producto tras escribirla. */
+type AdminContratacionResult = ContratacionResponse['data'];
+/**
+ * Tipo del cliente Admin retornado por `createAdminClient`.
+ */
+type AdminClient = {
+  createServiceClient(input: CreateServiceClientInput): Promise<Result<CreateServiceClientResult>>;
+  listServiceClients(): Promise<Result<{
+    clientes: ServiceClientPublic[];
+  }>>;
+  getServiceClient(slug: string): Promise<Result<{
+    cliente: ServiceClientPublic;
+  }>>;
+  updateServiceClient(slug: string, input: UpdateServiceClientInput): Promise<Result<UpdateServiceClientResult>>;
+  deleteServiceClient(slug: string): Promise<Result<void>>;
+  rotateServiceClientSecret(slug: string): Promise<Result<RotateSecretResult>>;
+  listServiceClientGrants(slug: string): Promise<Result<ListServiceClientGrantsResult>>;
+  /** Crea o reemplaza la concesión del client sobre una audiencia. */
+  setServiceClientGrant(slug: string, input: SetServiceClientGrantInput): Promise<Result<{
+    grant: ServiceClientGrant;
+  }>>;
+  deleteServiceClientGrant(slug: string, audience: string): Promise<Result<void>>;
+  /** Lista las aristas de delegación del client (token exchange). */
+  listServiceClientDelegations(slug: string): Promise<Result<ListServiceClientDelegationsResult>>;
+  /** Crea o reemplaza la arista del client hacia una audiencia delegable (`scopes`, `requiere_scope_origen`). */
+  setServiceClientDelegation(slug: string, input: SetServiceClientDelegationInput): Promise<Result<{
+    delegation: ServiceClientDelegation;
+  }>>;
+  deleteServiceClientDelegation(slug: string, audience: string): Promise<Result<void>>;
+  /** Permisos entre empresas que el producto puede conceder en nombre de sus empresas. */
+  getProductoPermisosAutorizables(slug: string): Promise<Result<ProductoPermisosAutorizablesResult>>;
+  /** Reemplaza la lista de permisos autorizables del producto (vacía = ninguno). */
+  setProductoPermisosAutorizables(slug: string, input: SetProductoPermisosAutorizablesInput): Promise<Result<ProductoPermisosAutorizablesResult>>;
+  /** Reasigna el titular de una empresa (disputa de RUC o empresa sin titular). */
+  reassignEmpresaTitular(empresaId: string, input: ReassignEmpresaTitularInput): Promise<Result<ReassignEmpresaTitularResult>>;
+  /** Da de baja una empresa (limpia sus sesiones activas; las autorizaciones y contrataciones dejan de valer). */
+  bajaEmpresa(empresaId: string): Promise<Result<AdminEmpresaEstadoResult>>;
+  /** Reactiva una empresa de baja. */
+  reactivarEmpresa(empresaId: string): Promise<Result<AdminEmpresaEstadoResult>>;
+  /** Escribe el estado y el vencimiento de la contratación de un producto por una empresa (hasta que exista facturación, así se activa a mano). */
+  setContratacion(empresaId: string, producto: string, input: AdminSetContratacionInput): Promise<Result<AdminContratacionResult>>;
+  /** Lista los productos (la audiencia del access token de usuario). */
+  listProductos(): Promise<Result<ListProductosResult>>;
+  /** Crea un producto (201). 409 si el slug existe; 400 si es una audiencia de servicio. */
+  createProducto(input: CreateProductoInput): Promise<Result<ProductoResult>>;
+  /** Actualiza `nombre` o `enabled`. 404 si no existe; 400 con body vacío. No hay delete: se deshabilita. */
+  updateProducto(slug: string, input: UpdateProductoInput): Promise<Result<ProductoResult>>;
+  restoreUser(userId: string): Promise<Result<RestoreUserResult>>;
+  republishPendingWebhooks(query?: RepublishPendingWebhooksQuery): Promise<Result<RepublishPendingWebhooksResult>>;
+  maintenanceCleanup(query?: MaintenanceCleanupQuery): Promise<Result<MaintenanceCleanupResult>>;
+};
+/**
+ * Crea un cliente Admin para provisioning del Auth Service.
+ *
+ * ADVERTENCIA: solo usar desde backends o herramientas de operador seguras — el secret del
+ * service client admin nunca debe exponerse en el cliente/browser.
+ *
+ * @example
+ * ```ts
+ * const admin = createAdminClient({
+ *   clientId: process.env.AUTH_ADMIN_SLUG,
+ *   secretHex: process.env.AUTH_ADMIN_SECRET,
+ *   baseUrl: 'https://auth.miapp.com',
+ * })
+ * const result = await admin.createServiceClient({ slug: 'mi-servicio' })
+ * if (!result.ok) return handleError(result.error)
+ * console.log('Secret (guardar ahora):', result.data.secret)
+ * ```
+ */
+declare function createAdminClient(config: AdminClientConfig): AdminClient;
+/**
+ * Códigos de error específicos del módulo Admin.
+ *
+ * Complementan a `ERROR_CODES` (core) para errores que solo ocurren
+ * en operaciones de provisioning de service clients.
+ *
+ * @example
+ * ```ts
+ * import { ADMIN_ERROR_CODES } from '@eva_solutions/auth-sdk/admin'
+ *
+ * if (!result.ok && result.error.code === ADMIN_ERROR_CODES.service_client_already_exists) {
+ *   return res.status(409).json({ error: 'El service client ya existe' })
+ * }
+ * ```
+ */
+declare const ADMIN_ERROR_CODES: {
+  readonly service_client_already_exists: "service_client_already_exists";
+  readonly service_client_not_found: "service_client_not_found";
+  /**
+   * `rotate-secret` perdió contra otra rotación concurrente del mismo service client (409).
+   * El perdedor no recibe secret; es reintentable.
+   */
+  readonly service_client_secret_rotation_conflict: "service_client_secret_rotation_conflict";
+  /**
+   * La operación dejaría al sistema sin ningún service client admin habilitado (409): borrar,
+   * deshabilitar o quitarle `esAdmin` al último. No se aplica; habilita o crea otro admin.
+   */
+  readonly last_admin_client: "last_admin_client";
+};
+/** Unión de literales de los error codes específicos del módulo Admin. */
+type AdminErrorCode = (typeof ADMIN_ERROR_CODES)[keyof typeof ADMIN_ERROR_CODES];
+export { SetServiceClientGrantInput as A, RestoreUserResult as C, ServiceClientPublic as D, ServiceClientGrant as E, UpdateServiceClientInput as M, UpdateServiceClientResult as N, SetProductoPermisosAutorizablesInput as O, AccountState as P, RepublishPendingWebhooksResult as S, ServiceClientDelegation as T, ProductoPermisosAutorizablesResult as _, AdminClientConfig as a, ReassignEmpresaTitularResult as b, AdminSetContratacionInput as c, CreateServiceClientResult as d, ListProductosResult as f, MaintenanceCleanupResult as g, MaintenanceCleanupQuery as h, createAdminClient as i, UpdateProductoInput as j, SetServiceClientDelegationInput as k, CreateProductoInput as l, ListServiceClientGrantsResult as m, AdminErrorCode as n, AdminContratacionResult as o, ListServiceClientDelegationsResult as p, AdminClient as r, AdminEmpresaEstadoResult as s, ADMIN_ERROR_CODES as t, CreateServiceClientInput as u, ProductoResult as v, RotateSecretResult as w, RepublishPendingWebhooksQuery as x, ReassignEmpresaTitularInput as y };
+//# sourceMappingURL=index-DBZoLU4E.d.ts.map

package/dist/index-DBZoLU4E.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-DBZoLU4E.d.ts","names":["ContractServiceClientPublic","ContractServiceClientGrant","ContractServiceClientDelegation"],"sources":["../src/account-states.ts","../src/admin/types.ts","../src/admin/client.ts","../src/admin/error-codes.ts"],"mappings":";;;KAuBY,uBAAuB,6BAA6B;;;;;KCgBpD;;EAEV;;EAEA;;;;;EAKA;;;;;;;KAQU,sBAAsBA;;;;;KAMtB,2BAA2B;;KAG3B,sBAAsB;;KAGtB,sBAAsB;;KAGtB,sBAAsB;;KAGtB,iBAAiB;;KAGjB,qBAAqBC;;;;;KAMrB,6BAA6B;;KAG7B,gCACV;;;;;KAMU,4BAA4B;;;;;KAM5B,2BAA2B;;;;KAK3B,4BAA4B;;;;;KAM5B,qBAAqB;;;;;;;;KASrB;EACV;;EAEA,cAAc;EACd;EACA;;;;;;;KAQU;;EAEV;;EAEA;;;;;;KAOU,iCAAiC;;;;;KAMjC;;EAEV;;;;;;;KAQU,2BAA2B;;;;;KAM3B,0BAA0BC;;;;;KAM1B,kCAAkC;;KAGlC,qCACV;;KAGU,uCACV;;KAGU,qCACV;;;;;KAMU,8BAA8B;;KAG9B,+BAA+B;;KAG/B,2BAA2B;;KAG3B,4BAA4B;;KAG5B,0BAA0B;;;;KClH1B;EACV,oBACE,OAAO,2BACN,QAAQ,OAAO;EAClB,sBAAsB,QAAQ;IAAS,UAAU;;EACjD,iBACE,eACC,QAAQ;IAAS,SAAS;;EAC7B,oBACE,cACA,OAAO,2BACN,QAAQ,OAAO;EAClB,oBAAoB,eAAe,QAAQ;EAC3C,0BAA0B,eAAe,QAAQ,OAAO;EACxD,wBACE,eACC,QAAQ,OAAO;;EAElB,sBACE,cACA,OAAO,6BACN,QAAQ;IAAS,OAAO;;EAC3B,yBACE,cACA,mBACC,QAAQ;;EAEX,6BACE,eACC,QAAQ,OAAO;;EAElB,2BACE,cACA,OAAO,kCACN,QAAQ;IAAS,YAAY;;EAChC,8BACE,cACA,mBACC,QAAQ;;EAEX,gCACE,eACC,QAAQ,OAAO;;EAElB,gCACE,cACA,OAAO,uCACN,QAAQ,OAAO;;EAElB,uBACE,mBACA,OAAO,8BACN,QAAQ,OAAO;;EAElB,YAAY,oBAAoB,QAAQ,OAAO;;EAE/C,iBAAiB,oBAAoB,QAAQ,OAAO;;EAEpD,gBACE,mBACA,kBACA,OAAO,4BACN,QAAQ,OAAO;;EAElB,iBAAiB,QAAQ,OAAO;;EAEhC,eAAe,OAAO,sBAAsB,QAAQ,OAAO;;EAE3D,eACE,cACA,OAAO,sBACN,QAAQ,OAAO;EAClB,YAAY,iBAAiB,QAAQ,OAAO;EAC5C,yBACE,QAAQ,gCACP,QAAQ,OAAO;EAClB,mBACE,QAAQ,0BACP,QAAQ,OAAO;;;;;;;;;;;;;;;;;;;;iBA0HJ,kBAAkB,QAAQ,oBAAoB;;;;;;;;;;;;;;;;cChRjD;;;;;;;;;;;;;;;KAiBD,yBACF,gCAAgC"}

package/dist/index-DcvQWByo.d.cts

@@ -0,0 +1,66 @@
+import "./index-Dold-Ycb.cjs";
+import "./types-B5sf7kKE.cjs";
+/**
+ * Verificación de firma HMAC-SHA-256 de webhooks entrantes del Auth Service.
+ *
+ * REQ-WH-03, REQ-WH-04, REQ-WH-05, REQ-WH-06 LOCKED.
+ *
+ * Algoritmo (espejo del API `firmarWebhook` en webhook-dispatcher.ts):
+ *   canonical = `${timestamp}\n${eventId}\n${sha256Hex(rawBody)}`
+ *   expected  = HMAC-SHA-256(signingKey, canonical)
+ *
+ * Usa Web Crypto API (`crypto.subtle`) — isomorfo (browser + worker + Node 20+).
+ *
+ * D-12 LOCKED: hexToBytes y sha256Hex se duplican aquí (NO se extraen a shared)
+ * para que el entry point ./webhooks sea completamente tree-shakeable.
+ */
+type VerifyWebhookSignatureParams = {
+  /** Body raw del request (string, antes de parsear JSON). */
+  rawBody: string;
+  /**
+   * Signing key del webhook — hex 64 chars (32 bytes).
+   * Es el `signingKey` que devolvió el API al crear/rotar la subscription.
+   * NOTA H3 LOCKED: NO re-hashear — usarlo tal como viene.
+   */
+  signingKey: string;
+  /**
+   * Valor completo del header `X-Eva-Webhook-Signature`.
+   * Debe comenzar con `"sha256="`.
+   */
+  signature: string;
+  /** Valor del header `X-Eva-Webhook-Id` (UUID del evento). */
+  eventId: string;
+  /**
+   * Valor del header `X-Eva-Webhook-Timestamp` parseado a number
+   * (unix seconds).
+   */
+  timestamp: number;
+  /**
+   * Override del tiempo actual (unix seconds) para tests.
+   * Por defecto: `Math.floor(Date.now() / 1000)`.
+   */
+  now?: number;
+};
+/**
+ * Verifica la firma HMAC-SHA-256 de un webhook entrante del Auth Service.
+ *
+ * @returns `true` si la firma es válida y está dentro de la ventana de tiempo;
+ *          `false` en cualquier otro caso (firma inválida, expirada, formato incorrecto).
+ *
+ * La comparación es constant-time via `crypto.subtle.verify` (por spec).
+ *
+ * @example
+ * ```ts
+ * const valid = await verifyWebhookSignature({
+ *   rawBody: await req.text(),
+ *   signingKey: process.env.WEBHOOK_SIGNING_KEY,
+ *   signature: req.headers.get('x-eva-webhook-signature') ?? '',
+ *   eventId: req.headers.get('x-eva-webhook-id') ?? '',
+ *   timestamp: Number(req.headers.get('x-eva-webhook-timestamp')),
+ * })
+ * if (!valid) return new Response('Unauthorized', { status: 401 })
+ * ```
+ */
+declare function verifyWebhookSignature({ rawBody, signingKey, signature, eventId, timestamp, now }: VerifyWebhookSignatureParams): Promise<boolean>;
+export { verifyWebhookSignature as n, VerifyWebhookSignatureParams as t };
+//# sourceMappingURL=index-DcvQWByo.d.cts.map

package/dist/index-DcvQWByo.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-DcvQWByo.d.cts","names":[],"sources":["../src/webhooks/verify-signature.ts"],"mappings":";;;;;;;;;;;;;;;;KAqDY;;EAEV;;;;;;EAMA;;;;;EAKA;;EAEA;;;;;EAKA;;;;;EAKA;;;;;;;;;;;;;;;;;;;;;;iBAuBoB,yBACpB,SACA,YACA,WACA,SACA,WACA,OACC,+BAA+B"}