Seguridad y gobernanza

Referencia para las revisiones de seguridad y las conversaciones con el equipo de Seguridad. Como siempre: el IdP autentica, no autoriza aplicaciones.

1. Modelo de tokens

Token	Formato	TTL típico	Emitido por	Validado por
Código de autorización	Opaco	5–10 min	Motor OAuth	Motor (endpoint de token)
Token de acceso OAuth	JWT ES256	30 min	Motor + hook	App cliente vía JWKS
Refresh token	Opaco, rotativo	30 días	Motor OAuth	Motor OAuth
ID token (OIDC)	JWT ES256	30 min	Motor + hook	App cliente
JWT interno de B Brands	JWT HS256	Corto (900s exchange)	Endpoint de exchange	Autorizador interno de B Brands

Distinción clave: los tokens ES256 demuestran identidad y son consumidos por la app cliente — nunca llegan a las APIs de B Brands. El token HS256 es consumido por las APIs de B Brands vía el autorizador interno existente.

Claims canónicos del token de acceso OAuth (identidad + dimensión de cuenta)

{
  "iss": "https://auth.bbrands.io",
  "sub": "<user_id uuid>",
  "aud": "bbrands-idp",
  "exp": 1734268800,
  "iat": 1734267000,
  "jti": "<uuid>",
  "email": "user@example.com",
  "client_id": "<client uuid>",
  "https://bbrands.io/client_handle": "<client_handle>",
  "https://bbrands.io/platform_type": "<platform_type>",
  "https://bbrands.io/profile": {
    "account": "<account.document_id | null>",
    "odoo": "<account.external_id | null>",
    "user": "<user_id uuid>"
  }
}

Reglas inviolables: iss es siempre la URL auth.* por entorno; aud es siempre la audiencia fija del IdP bbrands-idp; el cliente solicitante se transporta en https://bbrands.io/client_handle; jti está siempre presente e impulsa la blacklist; no hay claim de permisos ni de rol. El claim https://bbrands.io/profile lleva solo contexto de tenancy: account es la cuenta vinculada al usuario estrictamente mediante el rol primary_user (un usuario primario por cuenta), odoo es el id del sistema externo de esa cuenta (null hasta que la API de migración la mapee) y user es igual a sub. El endpoint UserInfo devuelve el mismo objeto.

Validación del lado del cliente

import { jwtVerify, createRemoteJWKSet } from "jose";

const JWKS = createRemoteJWKSet(
  new URL("https://auth.bbrands.io/.well-known/jwks.json"),
  { cooldownDuration: 30_000, cacheMaxAge: 3_600_000 },
);

export async function validateAccessToken(token: string, myHandle: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: "https://auth.bbrands.io",
    audience: "bbrands-idp",
    algorithms: ["ES256"],
  });
  if (payload["https://bbrands.io/client_handle"] !== myHandle) {
    throw new Error("Token was issued for another client");
  }
  return payload; // identity + account profile, never permissions
}

2. Dónde vive la autorización

Escenario	Quién autoriza	Mecanismo
El usuario actúa dentro de una app cliente	La app cliente	Su propio modelo de permisos/grupos
La app cliente consume las APIs de B Brands	B Brands	RBAC interno existente
Proceso M2M (sin usuario) consume las APIs	B Brands	API key + permisos por clave

El JWT de exchange otorga al cliente los permisos completos del usuario en B Brands (sin least-privilege por cliente). Aceptable para clientes first-party confiables; introduce la acotación en el exchange si necesitas reducirlos.

3. Gestión de secretos

Secreto	Generado	Almacenado en B Brands	Almacenado en el cliente	Rotación
`client_secret` OAuth	B Brands en el onboarding	hasheado en el motor	secret manager del cliente	90 días
Secreto del webhook de provisioning	B Brands en el onboarding	para firmar	para verificar	180 días
Secreto de firma interno (HS256)	B Brands	env del servidor	n/a	Ante sospecha de compromiso
Clave de servicio del motor	Motor	env del servidor	n/a	365 días
Clave de firma ES256	Motor	KMS administrado	n/a	Anual, con solapamiento
API key (M2M)	B Brands	hasheada en reposo	secret manager del cliente	Política existente

Reglas de almacenamiento: nunca en el repositorio, nunca en los logs (enmascara los headers Authorization), nunca en los payloads de webhook, cifrado en reposo, acceso restringido a los administradores del IdP.

Rotación de `client_secret`

El administrador hace clic en Rotar

B Brands genera un nuevo secreto.

Período de gracia

El antiguo y el nuevo se aceptan simultáneamente durante una ventana de gracia configurable (por defecto 24h).

El cliente actualiza su config

En cualquier momento durante la ventana de gracia.

Termina la gracia

El secreto antiguo deja de aceptarse; la auditoría registra la rotación.

Rotación de la clave de firma ES256

El motor soporta rotación basada en kid. Genera la nueva clave, mantén ambas activas, espera el TTL máximo del token de acceso (30 min) + buffer (1h), retira la clave antigua, luego elimínala tras la retención. El endpoint JWKS debe exponer ambas durante la ventana.

4. Modelo de amenazas (mini-STRIDE)

#	Amenaza	Mitigación
T1	Robo de `client_secret`	Rotación, alertas de uso anómalo, allowlist de IP opcional
T2	Intercepción del código de autorización	TLS + PKCE + `state`
T3	Replay de token	`jti` + blacklist + TTL corto
T4	Phishing de la pantalla de consentimiento	UI clara, sin autoaprobación sin el `trust_level` adecuado
T5	JWT de exchange con TTL largo	TTL corto obligatorio + blacklist
T6	Compromiso del usuario	MFA en B Brands, alertas de login anómalo, kill switch
T7	Robo de API key (M2M)	Least privilege, rotación, auditoría
T8	Replay de webhook	`event_id` idempotente
T9	Webhook falsificado	Firma HMAC + allowlist de IP
T10	Compromiso del hook	Revisión de código, deploy desde main, auditoría de cambios
T11	Token del cliente A presentado al cliente B	Cada cliente valida `https://bbrands.io/client_handle`
T12	Ataque de timing en la verificación del secreto	Comparación de tiempo constante
T13	Race de revocación	Blacklist verificada en cada validación

5. Niveles de revocación

Nivel	Alcance	Efecto inmediato	Cómo
L1: Un solo token	Un token de acceso / exchange	Sí (blacklist)	`POST /oauth/revoke`
L2: Sesión de usuario	Todos los refresh tokens del usuario	El próximo refresh falla	Engine admin API
L3: Usuario × plataforma	Tokens de ese cliente/usuario	El próximo refresh/exchange falla (≤ TTL)	`DELETE /idp/access/:user/:client`
L4: Cliente completo	Todos los tokens de ese cliente	El próximo refresh falla; los tokens vivos duran ≤ TTL	`POST /idp/clients/:handle/suspend`
L5: Usuario completo (kill switch)	Todas las habilitaciones, todas las plataformas	Inmediato si se combina con la blacklist	Rutina de kill switch

6. Requisitos de auditoría

Inmutable: append-only, sin UPDATE/DELETE.
Trazable: actor, ip, user_agent, correlation_id.
Retención: 12 meses en línea, más tiempo en almacenamiento en frío.
Exportable: /idp/audit/users/:id/export para GDPR/compliance.
Nunca registrado: tokens completos (solo el prefijo del jti), secretos en texto plano, contraseñas.

7. Defensa en profundidad

Capa	Control
Red	TLS, HSTS, CORS estricto, WAF
Cliente OAuth	PKCE, `state`, redirect URI exacta, validar `iss` + `client_handle`
Endpoint OAuth	Rate limit, validación estricta, auditoría
Hook	Verificación de habilitación, denegación por defecto seguro ante error
Exchange	Verificar subject token + habilitación + TTL corto + blacklist
Token interno	HS256, RBAC interno, blacklist
Operacional	MFA de administradores, registro de auditoría, alertas, runbooks

Primeros pasos

Documentación de la API

OAuth e Identidad (IdP)

Monitoreo e Infraestructura

Realtime (Pusher)

Notificaciones (OneSignal)

1. Modelo de tokens

Claims canónicos del token de acceso OAuth (identidad + dimensión de cuenta)

Validación del lado del cliente

2. Dónde vive la autorización

3. Gestión de secretos

Rotación de `client_secret`

Rotación de la clave de firma ES256

4. Modelo de amenazas (mini-STRIDE)

5. Niveles de revocación

6. Requisitos de auditoría

7. Defensa en profundidad

​1. Modelo de tokens

​Claims canónicos del token de acceso OAuth (identidad + dimensión de cuenta)

​Validación del lado del cliente

​2. Dónde vive la autorización

​3. Gestión de secretos

​Rotación de client_secret

​Rotación de la clave de firma ES256

​4. Modelo de amenazas (mini-STRIDE)

​5. Niveles de revocación

​6. Requisitos de auditoría

​7. Defensa en profundidad

1. Modelo de tokens

Claims canónicos del token de acceso OAuth (identidad + dimensión de cuenta)

Validación del lado del cliente

2. Dónde vive la autorización

3. Gestión de secretos

Rotación de `client_secret`

Rotación de la clave de firma ES256

4. Modelo de amenazas (mini-STRIDE)

5. Niveles de revocación

6. Requisitos de auditoría

7. Defensa en profundidad