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

package/dist/types-DGeQ8j4k.d.cts

@@ -0,0 +1,538 @@
+import { Ar as UsersBatchResponse, At as CreateEmpresaRequest, Bt as ListEmpresasQuery, C as DeleteAutorizacionRequest, Ft as EmpresaMemberResponse, H as DirectorioQuery, J as CreateGrupoRequest, Jt as UpdateEmpresaMemberRequest, Lt as EmpresaRecortadaResponse, Mt as DeactivateSucursalRequest, Nt as EmpresaDetailResponse, O as VerificarAutorizacionQuery, Pt as EmpresaEstadoResponse, Q as RenameGrupoRequest, Rt as EmpresaResponse, S as CreateAutorizacionRequest, T as ListAutorizacionesResponse, U as DirectorioResponse, Vt as ListEmpresasResponse, Wt as RemoveEmpresaMemberRequest, X as GrupoResponse, Xt as UpdateSucursalRequest, Yt as UpdateEmpresaRequest, Z as RemoveGrupoEmpresaRequest, ar as CreateSubscriptionRequest, ct as SetContratacionRequest, gr as UpdateSubscriptionRequest, jt as CreateSucursalRequest, k as VerificarAutorizacionResponse, kr as UsersBatchRequest, kt as AddEmpresaMemberRequest, ot as ContratacionResponse, q as AddGrupoEmpresaRequest, qt as SucursalResponse, st as ContratadoResponse, w as ListAutorizacionesQuery, x as AutorizacionResponse, zr as ProfileResponse, zt as GetEmpresaResponse } from "./index-Dold-Ycb.cjs";
+import { f as ServiceAudience, i as DelegableAudience } from "./catalog-CIqpzgsM.cjs";
+import { d as Result } from "./types-qh6ANBCV.cjs";
+import "./types-B5sf7kKE.cjs";
+import { JWTVerifyGetKey } from "jose";
+/** Tolerancia por defecto al desfase de relojes, en segundos. */
+declare const SERVICE_TOKEN_CLOCK_TOLERANCE_SECONDS = 5;
+/**
+ * Motivos de rechazo de `verifyServiceToken`.
+ *
+ * - `token_missing` — no hay `Authorization: Bearer <jwt>` (solo lo produce el middleware).
+ * - `token_malformed` — no es un JWT bien formado.
+ * - `token_expired` — `exp` ya pasó (más la tolerancia).
+ * - `signature_invalid` — firma inválida, `kid` ausente, de otro tipo o desconocido, o algoritmo distinto de ES256.
+ * - `claims_invalid` — `typ`, `iss`, `aud`, `sub`, `client_id`, `iat`/`exp` ausentes o fuera de rango, o vida mayor al máximo.
+ * - `scope_insufficient` — el claim `scope` no cubre el permiso requerido.
+ */
+type ServiceTokenVerifyReason = 'token_missing' | 'token_malformed' | 'token_expired' | 'signature_invalid' | 'claims_invalid' | 'scope_insufficient';
+type ServiceTokenVerifyError = {
+  reason: ServiceTokenVerifyReason;
+  message: string;
+};
+/** Datos verificados del token de servicio. */
+type ServiceTokenClaims = {
+  /** `sub`: id interno estable del service client. Es la identidad; no cambia ni se reutiliza. */
+  serviceClientId: string;
+  /** `client_id`: slug del service client. Dato visible (logs, UI); no usarlo como identidad. */
+  serviceClientSlug: string;
+  /** Permisos del claim `scope` (separado por espacios). */
+  scopes: readonly string[];
+  /** `jti` del token, si lo trae. */
+  jti: string | undefined;
+};
+type ServiceTokenVerifyResult = {
+  ok: true;
+  data: ServiceTokenClaims;
+} | {
+  ok: false;
+  error: ServiceTokenVerifyError;
+};
+/**
+ * Permiso exigido: uno concreto (`requiredScope`), al menos uno de varios (`anyScope`) o
+ * `scopeCheck: 'deferred'`, que no exige ninguno aquí y deja el permiso por ruta a `requireScope`
+ * (cadena Bearer + permiso por ruta). Es explícito para que olvidar el permiso no abra la ruta.
+ */
+type ServiceTokenScopeRequirement = {
+  requiredScope: string;
+  anyScope?: never;
+  scopeCheck?: never;
+} | {
+  anyScope: readonly string[];
+  requiredScope?: never;
+  scopeCheck?: never;
+} | {
+  scopeCheck: 'deferred';
+  requiredScope?: never;
+  anyScope?: never;
+};
+type ServiceTokenVerifyOptions = ServiceTokenScopeRequirement & {
+  /**
+   * Audiencia propia del servicio receptor (`'whatsapp-api'`), del catálogo de `auth-contracts`.
+   * Un slug de producto o cualquier otro valor lanza `TypeError`.
+   */
+  audience: ServiceAudience;
+  /**
+   * Resolutor de claves. Por defecto el JWKS remoto del Auth Service (`getJwksKeyFn()`, requiere
+   * `configureEvaAuth({ authUrl })`). Inyectable para tests. Siempre se filtra por el prefijo
+   * `svc-`, también el inyectado.
+   */
+  jwks?: JWTVerifyGetKey;
+  /** Vida máxima aceptada (`exp - iat`). Default: `SERVICE_TOKEN_LIFETIME_SECONDS` (300). */
+  maxLifetimeSeconds?: number;
+  /** Tolerancia de reloj. Default: `SERVICE_TOKEN_CLOCK_TOLERANCE_SECONDS` (5). */
+  clockToleranceSeconds?: number;
+  /** Overrides de mensajes (i18n). Las keys no provistas usan el default en inglés. */
+  messages?: Partial<Record<ServiceTokenVerifyReason, string>>;
+};
+/**
+ * Verifica un token de servicio.
+ *
+ * Contrato del token (lo emite el Auth Service):
+ * - Header: `alg: 'ES256'`, `typ: 'svc-at+jwt'`, `kid` con prefijo `svc-`.
+ * - Claims: `iss: 'auth-service'`, `aud` (una sola, la del receptor), `sub` (id del service
+ *   client), `client_id` (su slug), `scope` (separado por espacios), `iat`, `exp` (con
+ *   `exp - iat` <= `maxLifetimeSeconds`) y `jti`.
+ *
+ * Un token de servicio es reutilizable dentro de su vida: no hay replay cache.
+ *
+ * @throws `TypeError` si `audience` no es del catálogo, si no se indica exactamente uno de
+ *   `requiredScope` / `anyScope`, o si un permiso no pertenece a la audiencia.
+ * @throws Error de configuración (`EvaAuthConfigError`) si falta `authUrl` y no se inyecta `jwks`, y
+ *   los fallos de red del JWKS: son errores de infraestructura, no un token inválido, así que no
+ *   se degradan a un rechazo.
+ */
+declare function verifyServiceToken(token: string, opts: ServiceTokenVerifyOptions): Promise<ServiceTokenVerifyResult>;
+/** Motivos de rechazo: los mismos que los del token de servicio. */
+type DelegatedTokenVerifyReason = ServiceTokenVerifyReason;
+type DelegatedTokenVerifyError = {
+  reason: DelegatedTokenVerifyReason;
+  message: string;
+};
+/** Un actor de la cadena: el servicio que intercambió el token. */
+type DelegatedActor = {
+  /** `act.sub`: id interno estable del service client. */
+  serviceClientId: string;
+  /** `act.client_id`: slug del service client. Dato visible, no identidad. */
+  serviceClientSlug: string;
+};
+/** Datos verificados del token delegado. */
+type DelegatedTokenClaims = {
+  /** `sub`: el usuario en cuyo nombre se actúa. */
+  userId: string;
+  /** `empresa`: obligatoria e inmutable en toda la cadena. */
+  empresaId: string;
+  /** `producto`: producto de origen de la cadena. */
+  producto: string;
+  /** `sid`: sesión de origen. */
+  sessionId: string;
+  /**
+   * Cadena de actores, del último (quien llama a este servicio) al primero (quien partió del
+   * access token del usuario). Siempre tiene al menos uno y como máximo `DELEGATED_TOKEN_MAX_DEPTH`.
+   */
+  actorChain: readonly DelegatedActor[];
+  /** `client_id` del token: slug del actor, para logs y rate limit. */
+  clientId: string;
+  /** Permisos del claim `scope` (separado por espacios). */
+  scopes: readonly string[];
+  /** `jti` del token (obligatorio). */
+  jti: string;
+};
+type DelegatedTokenVerifyResult = {
+  ok: true;
+  data: DelegatedTokenClaims;
+} | {
+  ok: false;
+  error: DelegatedTokenVerifyError;
+};
+type DelegatedTokenVerifyOptions = ServiceTokenScopeRequirement & {
+  /**
+   * Audiencia propia del servicio receptor, del catálogo delegable de `auth-contracts`. `auth-api`
+   * (o cualquier otro valor) lanza `TypeError`: Auth nunca es destino de un token delegado.
+   */
+  audience: DelegableAudience;
+  /** Resolutor de claves; por defecto el JWKS remoto. Siempre se filtra por el prefijo `svc-`. */
+  jwks?: JWTVerifyGetKey;
+  /** Vida máxima aceptada (`exp - iat`). Default: `DELEGATED_TOKEN_LIFETIME_SECONDS` (120). */
+  maxLifetimeSeconds?: number;
+  /** Tolerancia de reloj. Default: 5 s. */
+  clockToleranceSeconds?: number;
+  /** Overrides de mensajes (i18n). */
+  messages?: Partial<Record<DelegatedTokenVerifyReason, string>>;
+};
+/**
+ * Verifica un token delegado.
+ *
+ * Contrato del token (lo emite el Auth Service en `POST /internal/token-exchange`):
+ * - Header: `alg: 'ES256'`, `typ: 'dlg-at+jwt'`, `kid` con prefijo `svc-`.
+ * - Claims: `iss: 'auth-service'`, `aud` (una sola, la del receptor), `sub` (el usuario),
+ *   `client_id`, `act` (cadena de actores), `empresa`, `producto` y `sid` (obligatorios: la
+ *   empresa es inmutable en la cadena), `scope`, `iat`, `exp` (con `exp - iat` <=
+ *   `maxLifetimeSeconds`) y `jti`.
+ *
+ * Un token delegado sin empresa se rechaza (`claims_invalid`): la delegación sin empresa no existe.
+ * Es reutilizable dentro de su vida (120 s): no hay replay cache.
+ *
+ * @throws `TypeError` si `audience` no es delegable o los permisos exigidos no lo son.
+ * @throws Error de configuración si falta `authUrl` y no se inyecta `jwks`, y los fallos de red del
+ *   JWKS (son de infraestructura, no un token inválido).
+ */
+declare function verifyDelegatedToken(token: string, opts: DelegatedTokenVerifyOptions): Promise<DelegatedTokenVerifyResult>;
+/** Cuánto antes del vencimiento se renueva el token, en milisegundos. */
+declare const SERVICE_TOKEN_RENEW_MARGIN_MS = 30000;
+type ServiceTokenProviderConfig = {
+  /**
+   * URL base del Auth Service (sin `/api/v1`). Se requiere https (o http con host loopback para
+   * tests); admite path (`https://host/auth`).
+   */
+  authUrl: string;
+  /** Slug del service client (`clientId`) que firma el pedido. */
+  clientId: string;
+  /** Clave del service client en hex (64 chars). Nunca viaja: solo firma el pedido. */
+  secretHex: string;
+  /** Servicio destino del token (`'auth-api'`, `'whatsapp-api'`). */
+  audience: string;
+  /** Permisos pedidos separados por espacio. Si falta, se piden todos los concedidos. */
+  scope?: string;
+};
+/**
+ * What the clients that call a service need from a provider: a token and a way to drop a rejected
+ * one. `createServiceTokenProvider` returns more ({@link ServiceTokenProvider}); a hand-made source
+ * (tests, another credential flow) only needs these two.
+ */
+type ServiceTokenSource = {
+  /**
+   * Devuelve un token vigente: el guardado mientras falten más de 30 s para su vencimiento, o uno
+   * nuevo. Los pedidos simultáneos comparten una sola llamada al Auth Service.
+   * @throws {ServiceTokenRequestError} si el Auth Service rechaza el pedido; `Error` de red si no responde.
+   */
+  getToken(): Promise<string>;
+  /**
+   * Descarta el token guardado para que la próxima `getToken()` pida uno nuevo. Úsalo cuando el
+   * servicio destino responde 401 con un token que creías vigente, pasando ESE token:
+   * solo se descarta si sigue siendo el guardado. Así, N respuestas 401 simultáneas del mismo
+   * token provocan UN pedido nuevo (la primera descarta; las demás ven que ya no es el guardado
+   * y comparten el pedido en curso o el token renovado). Nunca descarta un pedido en curso.
+   * Sin argumento descarta el token guardado, sea cual sea.
+   */
+  invalidate(rejectedToken?: string): void;
+};
+/** Input of {@link ServiceTokenProvider.exchangeToken}. */
+type ExchangeTokenInput = {
+  /**
+   * Token to exchange: the access token of the user (`aud` = product of this actor) or a delegated
+   * token (`aud` = audience of this actor, for a re-exchange). Pass one your service has ALREADY
+   * verified (`verifyAccessToken`, `verifyDelegatedToken` or the middleware): the SDK does not.
+   */
+  subjectToken: string;
+  /** Destination service of the delegated token: one audience with a delegation edge from this client. Never `auth-api`. */
+  audience: string;
+  /** Permissions asked for, separated by space. If absent, everything delegable on that edge. */
+  scope?: string;
+};
+/** A delegated token (`typ: dlg-at+jwt`) and the permissions it carries. */
+type DelegatedTokenGrant = {
+  accessToken: string;
+  /** Permissions issued, separated by space (they can be fewer than asked for). */
+  scope: string;
+};
+/**
+ * Provider of service tokens for ONE (audience, scope), plus the token exchange of the same client.
+ */
+type ServiceTokenProvider = ServiceTokenSource & {
+  /**
+   * Exchanges a subject token for a delegated one (RFC 8693) so this service can call another one
+   * on behalf of the user. Authenticates with its own service token (`aud: auth-api`, permission
+   * `tokens:exchange`), which it obtains and renews by itself whatever the audience of this
+   * provider is.
+   *
+   * Caches the delegated token in this isolate until 30 s before its `exp` (it lives 120 s). The
+   * key is the audience, the scope and a fingerprint of the WHOLE subject token: a token with other
+   * claims (another session, user or company), or the same re-exchanged from another token of the
+   * chain (other `jti`), never reuses an entry. Errors are not cached.
+   *
+   * Returns a Result: `invalid_grant` (session closed, user or company out, product not contracted,
+   * depth or cycle) is a normal answer, not an exception. The failures of Auth keep their RFC code
+   * in `error.code` (`invalid_grant`, `invalid_target`, `invalid_scope`, `invalid_client`, ...).
+   */
+  exchangeToken(input: ExchangeTokenInput): Promise<Result<DelegatedTokenGrant>>;
+};
+/** El Auth Service rechazó el pedido de token. `code` es el `error` de RFC 6749 (`invalid_client`, …). */
+declare class ServiceTokenRequestError extends Error {
+  readonly code: string;
+  readonly status: number;
+  /** Segundos de espera que pidió Auth con `Retry-After` (429 / 503), si los mandó. */
+  readonly retryAfterSeconds?: number;
+  constructor(code: string, status: number, description?: string, retryAfterSeconds?: number);
+}
+/**
+ * Crea un proveedor de tokens de servicio.
+ *
+ * Deduplica los pedidos simultáneos dentro del mismo proceso (isolate): N llamadas concurrentes a
+ * `getToken()` con el caché vacío o vencido hacen UN pedido al Auth Service. Un pedido fallido no
+ * se guarda: la siguiente llamada reintenta.
+ *
+ * Valida su configuración al crearse (audiencia del catálogo, permisos de esa audiencia, clave hex).
+ *
+ * @example
+ * ```ts
+ * const provider = createServiceTokenProvider({
+ *   authUrl: env.AUTH_URL,
+ *   clientId: env.AUTH_CLIENT_ID,
+ *   secretHex: env.AUTH_CLIENT_SECRET_HEX,
+ *   audience: 'auth-api',
+ * })
+ * const s2s = createS2SClient({ baseUrl: env.AUTH_URL, tokenProvider: provider })
+ * ```
+ */
+declare function createServiceTokenProvider(config: ServiceTokenProviderConfig): ServiceTokenProvider;
+/**
+ * Configuración del cliente S2S.
+ */
+type S2SClientConfig = {
+  /**
+   * URL base del Auth Service API (sin trailing slash).
+   * Validada en `createS2SClient`: se requiere https (o http con host loopback para tests).
+   */
+  baseUrl: string;
+  /**
+   * Proveedor del token de servicio con audiencia `auth-api` (`createServiceTokenProvider`). El
+   * cliente lo usa en cada llamada y, ante un 401, lo invalida y reintenta una vez.
+   */
+  tokenProvider: ServiceTokenSource;
+};
+/**
+ * Partes del request necesarias para construir el canonical string SigV4-style
+ * (7 líneas: método, path, query, timestamp, nonce, clientId, hash del body).
+ */
+type S2SCanonicalParts = {
+  /** HTTP method en uppercase (GET, POST, PATCH, DELETE). */
+  method: string;
+  /** Pathname del request sin query string ni fragment. */
+  path: string;
+  /** Query string crudo (sin el `?`). String vacío si no hay query. */
+  rawQuery: string;
+  /** Unix timestamp en segundos como string decimal. */
+  timestamp: string;
+  /** Nonce del request: 32 hex en minúsculas (ver `generateS2SNonce`). */
+  nonce: string;
+  /** Slug del service client (clientId). */
+  clientId: string;
+  /** Bytes raw del body. GET/sin body → `new Uint8Array(0)`. */
+  bodyBytes: Uint8Array;
+};
+/**
+ * Resultado de `getUser` — perfil público del usuario (alias del `data` de la respuesta del
+ * contrato). El wire es `{ data: perfil }` y `result.data` es el perfil directamente, sin
+ * envoltorio. Un usuario inexistente o soft-deleted llega como error `user_not_found` (404).
+ */
+type S2SGetUserResult = ProfileResponse['data'];
+/**
+ * Input para `batchUsers` — lista de IDs a consultar (alias del request del contrato).
+ * El tope de `USERS_BATCH_MAX_IDS` lo aplica el cliente, no el tipo.
+ */
+type S2SBatchUsersInput = UsersBatchRequest;
+/**
+ * Resultado de `batchUsers` — usuarios activos encontrados (alias del `data` de la respuesta del
+ * contrato). IDs inválidos, inexistentes o soft-deleted se omiten.
+ */
+type S2SBatchUsersResult = UsersBatchResponse['data'];
+/**
+ * Input para crear una subscription de webhook (alias del request del contrato): `url` donde el
+ * Auth Service enviará los eventos, `eventCodes` a suscribir (al menos uno) y `enabled` (por
+ * defecto `true` en el API).
+ */
+type CreateWebhookSubscriptionInput = CreateSubscriptionRequest;
+/**
+ * Input para actualizar una subscription de webhook (patch parcial; alias del request del
+ * contrato).
+ */
+type UpdateWebhookSubscriptionInput = UpdateSubscriptionRequest;
+/**
+ * Query params para listar deliveries.
+ *
+ * Tipo propio del SDK, no alias del contrato: el query del contrato coacciona strings a números y
+ * por eso su tipo de entrada es `unknown`; aquí `limit` y `offset` son `number`.
+ */
+type ListWebhookDeliveriesQuery = {
+  event_id?: string;
+  subscription_id?: string;
+  status?: 'pending' | 'delivering' | 'success' | 'expired';
+  limit?: number;
+  offset?: number;
+};
+/**
+ * Toda acción de una persona sobre una empresa lleva su access token como `subjectToken`: el
+ * backend del producto manda su token de servicio y, en el body, el token de la persona.
+ */
+type SubjectTokenInput = RemoveEmpresaMemberRequest;
+/**
+ * Input para crear una empresa (alias del request del contrato). La persona del `subjectToken`
+ * queda como titular y el producto del actor queda en `prueba`.
+ */
+type CreateEmpresaInput = CreateEmpresaRequest;
+/** Input para editar datos maestros, perfil y visibilidad (RUC y slug son inmutables). */
+type UpdateEmpresaInput = UpdateEmpresaRequest;
+/** Query de `listEmpresas`: `q` y `cursor` (la siguiente página sale de `nextCursor`). */
+type ListEmpresasInput = ListEmpresasQuery;
+/** Página de empresas contratadas por el producto del actor. */
+type ListEmpresasResult = ListEmpresasResponse['data'];
+/** Input para agregar un miembro (entra como `miembro`). */
+type AddEmpresaMemberInput = AddEmpresaMemberRequest;
+/** Input para cambiar el rol de un miembro (solo el titular). */
+type UpdateEmpresaMemberInput = UpdateEmpresaMemberRequest;
+/** Input para quitar un miembro; `userId` = la persona del token es salir por cuenta propia. */
+type RemoveEmpresaMemberInput = RemoveEmpresaMemberRequest;
+/** Input para crear una sucursal (alias del request del contrato). */
+type CreateSucursalInput = CreateSucursalRequest;
+/** Input para editar una sucursal. */
+type UpdateSucursalInput = UpdateSucursalRequest;
+/** Input para dar de baja lógica una sucursal (`activa = false`). */
+type DeactivateSucursalInput = DeactivateSucursalRequest;
+/** Empresa creada o editada (`data` de la respuesta). */
+type EmpresaResult = EmpresaResponse['data'];
+/** Vista completa de una empresa: el actor tiene su producto contratado (`vista: 'completa'`). */
+type EmpresaDetailResult = EmpresaDetailResponse['data'];
+/** Vista recortada para un actor sin producto: sin contacto ni miembros (`vista: 'recortada'`). */
+type EmpresaRecortadaResult = EmpresaRecortadaResponse['data'];
+/** Resultado de `getEmpresa`: una de las dos vistas, distinguidas por `vista`. */
+type GetEmpresaResult = GetEmpresaResponse['data'];
+/** Miembro agregado o con rol cambiado (`data` de la respuesta). */
+type EmpresaMemberResult = EmpresaMemberResponse['data'];
+/** Sucursal creada o editada (`data` de la respuesta). */
+type SucursalResult = SucursalResponse['data'];
+/** Estado de la empresa tras `bajaEmpresa` / `reactivarEmpresa`. */
+type EmpresaEstadoResult = EmpresaEstadoResponse['data'];
+/** Contratación de un producto por una empresa. */
+type ContratacionResult = ContratacionResponse['data'];
+/** Input de `setContratacion` (facturación y admin): estado y vencimiento. */
+type SetContratacionInput = SetContratacionRequest;
+/** `{ contratado }`: ¿la empresa tiene el producto en `prueba` o `activo` y sin vencer? */
+type ContratadoResult = ContratadoResponse['data'];
+/** Input para crear un grupo con una empresa de la persona. */
+type CreateGrupoInput = CreateGrupoRequest;
+/** Input para renombrar un grupo. */
+type RenameGrupoInput = RenameGrupoRequest;
+/** Input para agregar una empresa a un grupo. */
+type AddGrupoEmpresaInput = AddGrupoEmpresaRequest;
+/** Input para quitar una empresa de un grupo. */
+type RemoveGrupoEmpresaInput = RemoveGrupoEmpresaRequest;
+/** Grupo con los ids de sus empresas. */
+type GrupoResult = GrupoResponse['data'];
+/** Query del directorio: `q`, `rubro`, `ciudad` y `cursor`. */
+type SearchDirectorioInput = DirectorioQuery;
+/** Página del directorio: solo campos de perfil público. */
+type DirectorioResult = DirectorioResponse['data'];
+/** Input para conceder una autorización a otra empresa (solo permisos del catálogo entre empresas). */
+type CreateAutorizacionInput = CreateAutorizacionRequest;
+/** Input para revocar (otorgante) o renunciar (beneficiaria) a una autorización. */
+type DeleteAutorizacionInput = DeleteAutorizacionRequest;
+/** Input de `listAutorizaciones`: dirección y persona (viaja en el header `x-eva-subject-token`). */
+type ListAutorizacionesInput = ListAutorizacionesQuery & {
+  subjectToken: string;
+};
+/** Autorización vigente. */
+type AutorizacionResult = AutorizacionResponse['data'];
+/** Autorizaciones vigentes de una empresa. */
+type ListAutorizacionesResult = ListAutorizacionesResponse['data'];
+/** Input de `checkAutorizacion`: otorgante, beneficiaria y permiso. */
+type CheckAutorizacionInput = VerificarAutorizacionQuery;
+/** `{ autorizado }`. */
+type CheckAutorizacionResult = VerificarAutorizacionResponse['data'];
+/**
+ * All possible reasons why an S2S request verification can fail.
+ *
+ * - `header_missing` — one or more required headers are absent (client id, timestamp, nonce, signature).
+ * - `timestamp_invalid` — the `x-eva-timestamp` header is not a valid integer string.
+ * - `timestamp_expired` — the timestamp is outside the allowed window (default ±120 s).
+ * - `nonce_malformed` — the `x-eva-nonce` header is not 32 lowercase hex chars.
+ * - `signature_malformed` — the `x-eva-signature` header is not in `sha256=<hex64>` format.
+ * - `client_unknown` — `secretStore` returned null for the given clientId.
+ * - `signature_invalid` — the HMAC signature does not match the expected value.
+ * - `replay_detected` — the `(clientId, nonce)` pair has already been seen (only when `replayCache` is configured).
+ *
+ * `client_unknown` and `signature_invalid` share the same human-readable message
+ * ("Authentication failed") to avoid revealing whether the clientId exists.
+ */
+type S2SVerifyReason = 'header_missing' | 'timestamp_invalid' | 'timestamp_expired' | 'nonce_malformed' | 'signature_malformed' | 'client_unknown' | 'signature_invalid' | 'replay_detected';
+/**
+ * Discriminated union of all S2S verification failure modes.
+ * Q-E01 LOCKED — this is a module-specific type, NOT the global Result<T, E>.
+ */
+type S2SVerifyError = {
+  reason: S2SVerifyReason;
+  message: string;
+};
+/**
+ * Result of S2S verification.
+ *
+ * Use the `ok` discriminant to narrow:
+ * ```ts
+ * const result = await verifyS2SRequest(req, opts)
+ * if (!result.ok) return new Response(result.error.message, { status: 401 })
+ * const { clientId } = result.data
+ * ```
+ */
+type S2SVerifyResult<T> = {
+  ok: true;
+  data: T;
+} | {
+  ok: false;
+  error: S2SVerifyError;
+};
+/**
+ * Input options for `verifyS2SRequest`.
+ */
+type S2SVerifyOptions = {
+  /**
+   * Callback that must return the plaintext secret (64 hex chars = 32 bytes) for the given
+   * clientId, or null if the client is unknown. The SDK applies a timing-safe dummy HMAC
+   * when null — callers MUST NOT throw; return null for unknown clients instead.
+   */
+  secretStore: (clientId: string) => Promise<string | null>;
+  /**
+   * Override timestamp validation window in seconds.
+   * Default: `S2S_TIMESTAMP_WINDOW_SECONDS` (120).
+   */
+  timestampWindowSeconds?: number;
+  /**
+   * Optional nonce store for replay protection. When provided, `verifyS2SRequest`
+   * calls `setIfAbsent` after a successful HMAC verify to detect replayed requests.
+   *
+   * The SDK builds the key internally as `${clientId}:${nonce}` (`nonce` is the validated
+   * `x-eva-nonce` header, 32 lowercase hex). The TTL passed to `setIfAbsent` is
+   * `2 * timestampWindowSeconds + 1` (default 241 s): the current time is floored to seconds
+   * and the window is inclusive on both sides (±W), so a request stays acceptable for 2W + 1
+   * seconds and the key must outlive that.
+   *
+   * @remarks
+   * The implementation MUST be atomic (e.g. Redis `SET key value NX EX ttl`).
+   * Non-atomic implementations are vulnerable to TOCTOU race conditions.
+   *
+   * The store SHOULD be shared across all instances of the same service that share
+   * the clientId/secret pair. Independent per-instance stores allow cross-instance
+   * replay attacks.
+   *
+   * @security Critical for replay protection — must be atomic.
+   * @security Check occurs AFTER HMAC verify (D16) to preserve timing-safe invariant.
+   */
+  replayCache?: {
+    /**
+     * Atomically insert `key` (`${clientId}:${nonce}`) if not present, expiring after `ttlSeconds`
+     * (`2 * timestampWindowSeconds + 1`).
+     * @returns `true` if inserted (request is fresh); `false` if the key already existed (replay detected).
+     *
+     * Implementation MUST be atomic (e.g. Redis `SET ... NX EX ttl`).
+     * Non-atomic implementations are vulnerable to TOCTOU race conditions.
+     *
+     * @security Critical for replay protection — must be atomic.
+     */
+    setIfAbsent(key: string, ttlSeconds: number): Promise<boolean>;
+  };
+  /**
+   * Optional message overrides for i18n. Keys not provided fall back to the
+   * default English messages. An empty string `''` is respected as an explicit
+   * override (D12 LOCKED).
+   *
+   * @example
+   * ```ts
+   * messages: {
+   *   timestamp_expired: 'El timestamp está fuera del rango permitido',
+   *   replay_detected: 'Firma ya utilizada',
+   * }
+   * ```
+   */
+  messages?: Partial<Record<S2SVerifyReason, string>>;
+};
+export { ServiceTokenRequestError as $, RenameGrupoInput as A, SearchDirectorioInput as B, ListAutorizacionesInput as C, ListWebhookDeliveriesQuery as D, ListEmpresasResult as E, S2SGetUserResult as F, UpdateEmpresaMemberInput as G, SubjectTokenInput as H, S2SVerifyError as I, DelegatedTokenGrant as J, UpdateSucursalInput as K, S2SVerifyOptions as L, S2SBatchUsersResult as M, S2SCanonicalParts as N, RemoveEmpresaMemberInput as O, S2SClientConfig as P, ServiceTokenProviderConfig as Q, S2SVerifyReason as R, GrupoResult as S, ListEmpresasInput as T, SucursalResult as U, SetContratacionInput as V, UpdateEmpresaInput as W, SERVICE_TOKEN_RENEW_MARGIN_MS as X, ExchangeTokenInput as Y, ServiceTokenProvider as Z, EmpresaEstadoResult as _, CheckAutorizacionResult as a, DelegatedTokenVerifyOptions as at, EmpresaResult as b, CreateAutorizacionInput as c, verifyDelegatedToken as ct, CreateSucursalInput as d, ServiceTokenScopeRequirement as dt, ServiceTokenSource as et, CreateWebhookSubscriptionInput as f, ServiceTokenVerifyError as ft, EmpresaDetailResult as g, verifyServiceToken as gt, DirectorioResult as h, ServiceTokenVerifyResult as ht, CheckAutorizacionInput as i, DelegatedTokenVerifyError as it, S2SBatchUsersInput as j, RemoveGrupoEmpresaInput as k, CreateEmpresaInput as l, SERVICE_TOKEN_CLOCK_TOLERANCE_SECONDS as lt, DeleteAutorizacionInput as m, ServiceTokenVerifyReason as mt, AddGrupoEmpresaInput as n, DelegatedActor as nt, ContratacionResult as o, DelegatedTokenVerifyReason as ot, DeactivateSucursalInput as p, ServiceTokenVerifyOptions as pt, UpdateWebhookSubscriptionInput as q, AutorizacionResult as r, DelegatedTokenClaims as rt, ContratadoResult as s, DelegatedTokenVerifyResult as st, AddEmpresaMemberInput as t, createServiceTokenProvider as tt, CreateGrupoInput as u, ServiceTokenClaims as ut, EmpresaMemberResult as v, ListAutorizacionesResult as w, GetEmpresaResult as x, EmpresaRecortadaResult as y, S2SVerifyResult as z };
+//# sourceMappingURL=types-DGeQ8j4k.d.cts.map

package/dist/types-DGeQ8j4k.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-DGeQ8j4k.d.cts","names":[],"sources":["../src/s2s/service-token.ts","../src/s2s/delegated-token.ts","../src/s2s/token-provider.ts","../src/s2s/types.ts"],"mappings":";;;;;;cA4Ba;;;;;;;;;;;KAYD;KAQA;EACV,QAAQ;EACR;;;KAIU;;EAEV;;EAEA;;EAEA;;EAEA;;KAGU;EACN;EAAU,MAAM;;EAChB;EAAW,OAAO;;;;;;;KAOZ;EACN;EAAuB;EAAkB;;EACzC;EAA6B;EAAuB;;EACpD;EAAwB;EAAuB;;KAEzC,4BAA4B;;;;;EAKtC,UAAU;;;;;;EAMV,OAAO;;EAEP;;EAEA;;EAEA,WAAW,QAAQ,OAAO;;;;;;;;;;;;;;;;;;;iBAuGN,mBACpB,eACA,MAAM,4BACL,QAAQ;;KClKC,6BAA6B;KAE7B;EACV,QAAQ;EACR;;;KAIU;;EAEV;;EAEA;;;KAIU;;EAEV;;EAEA;;EAEA;;EAEA;;;;;EAKA,qBAAqB;;EAErB;;EAEA;;EAEA;;KAGU;EACN;EAAU,MAAM;;EAChB;EAAW,OAAO;;KAEZ,8BAA8B;;;;;EAKxC,UAAU;;EAEV,OAAO;;EAEP;;EAEA;;EAEA,WAAW,QAAQ,OAAO;;;;;;;;;;;;;;;;;;;iBAiGN,qBACpB,eACA,MAAM,8BACL,QAAQ;;cC1KE;KASD;;;;;EAKV;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;KAQU;;;;;;EAMV,YAAY;;;;;;;;;EASZ,WAAW;;;KAID;;;;;;EAMV;;EAEA;;EAEA;;;KAIU;EACV;;EAEA;;;;;KAMU,uBAAuB;;;;;;;;;;;;;;;;EAgBjC,cAAc,OAAO,qBAAqB,QAAQ,OAAO;;;cAI9C,iCAAiC;WACnC;WACA;;WAEA;EAGP,YAAA,cACA,gBACA,sBACA;;;;;;;;;;;;;;;;;;;;;;iBAyKY,2BACd,QAAQ,6BACP;;;;KCxOS;;;;;EAKV;;;;;EAKA,eAAe;;;;;;KAOL;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,WAAW;;;;;;;KAQD,mBAAmB;;;;;KAMnB,qBAAqB;;;;;KAMrB,sBAAsB;;;;;;KAOtB,iCAAiC;;;;;KAMjC,iCAAiC;;;;;;;KAQjC;EACV;EACA;EACA;EACA;EACA;;;;;;KAOU,oBAAoB;;;;;KAMpB,qBAAqB;;KAGrB,qBAAqB;;KAGrB,oBAAoB;;KAGpB,qBAAqB;;KAGrB,wBAAwB;;KAGxB,2BAA2B;;KAG3B,2BAA2B;;KAG3B,sBAAsB;;KAGtB,sBAAsB;;KAGtB,0BAA0B;;KAG1B,gBAAgB;;KAGhB,sBAAsB;;KAGtB,yBAAyB;;KAGzB,mBAAmB;;KAGnB,sBAAsB;;KAGtB,iBAAiB;;KAGjB,sBAAsB;;KAGtB,qBAAqB;;KAGrB,uBAAuB;;KAGvB,mBAAmB;;KAGnB,mBAAmB;;KAGnB,mBAAmB;;KAGnB,uBAAuB;;KAGvB,0BAA0B;;KAG1B,cAAc;;KAGd,wBAAwB;;KAGxB,mBAAmB;;KAGnB,0BAA0B;;KAG1B,0BAA0B;;KAG1B,0BAA0B;EACpC;;;KAIU,qBAAqB;;KAGrB,2BAA2B;;KAG3B,yBAAyB;;KAGzB,0BAA0B;;;;;;;;;;;;;;;;KAmB1B;;;;;KAcA;EACV,QAAQ;EACR;;;;;;;;;;;;KAaU,gBAAgB;EACtB;EAAU,MAAM;;EAChB;EAAW,OAAO;;;;;KAKZ;;;;;;EAMV,cAAc,qBAAqB;;;;;EAKnC;;;;;;;;;;;;;;;;;;;;;;EAsBA;;;;;;;;;;;IAWE,YAAY,aAAa,qBAAqB;;;;;;;;;;;;;;;EAehD,WAAW,QAAQ,OAAO"}