@bigso/authz

Cliente exclusivamente server-side para resolver hechos de asignación desde Identity. No contiene políticas de dominio y no debe importarse en Angular ni otro bundle browser.

const authz = new BigsoAuthzClient({
  identityUrl: process.env.IDENTITY_INTERNAL_URL,
  getServiceToken: () => process.env.IDENTITY_ASSIGNMENTS_SERVICE_TOKEN,
});

const context = assignmentContextFromHeaders(request.headers);
if (!context)
  return reply.code(401).send({ error: "trusted_identity_required" });
const assignments = await authz.resolve(context);
if (!assignments.active)
  return reply.code(403).send({ error: "inactive_assignment" });

El backend decide PBAC con assignments.permissions; APGW no consulta este paquete ni recibe responsabilidades de autorización de dominio.

Contrato operativo

• IDENTITY_INTERNAL_URL: URL privada de Identity, por ejemplo http://idp-core:3000. La resolución backend → Identity no pasa por APGW.
• IDENTITY_ASSIGNMENTS_SERVICE_TOKEN: secreto runtime con type=service, audience exacta urn:bigso:identity:assignments y al menos un scope. La audiencia es compartida por todas las rutas internas de asignaciones; cada ruta exige un scope dedicado (ver ASSIGNMENTS_RESOLVE_SCOPE y DISPLAY_NAME_SCOPE).
• Caché positiva: 30 segundos por defecto, configurable hasta un máximo de 60 y siempre acotada por sessionExpiresAt.
• Caché negativa: máximo 5 segundos.
• Timeout: 2 segundos por defecto. Sin Identity ni caché vigente, resolve lanza AssignmentResolutionError y el backend debe responder sin ejecutar la operación protegida.
• La respuesta activa puede incluir tenant con id, name y slug canónicos para bootstrap. El cliente valida que el id coincida con el binding solicitado.
• El paquete acepta exclusivamente X-Bigso-Subject, X-Bigso-Session, X-Bigso-Tenant y X-Bigso-App; ignora headers legacy y permisos aportados por el cliente.

resolveDisplayName (opt-in)

A partir de @bigso/[email protected] el cliente expone además BigsoAuthzClient.resolveDisplayName(context), una segunda ruta interna de Identity que devuelve un shape mínimo:

type DisplayNameResolution =
  | {
      active: true;
      subject;
      sid;
      tenantId;
      appId;
      user: { id; email; displayName };
    }
  | { active: false; subject; sid; tenantId; appId };

El método reusa cacheTtlMs, negativeCacheTtlMs, timeoutMs, inFlight, fetchImpl y metrics. La única diferencia operativa con resolve() es que apunta a POST /api/v2/internal/assignments/display-name y exige el scope identity.assignments.display-name en la service JWT. La respuesta nunca incluye atributos administrativos del usuario (sin birthDate, gender, addresses, etc.).

Uso típico:

const client = new BigsoAuthzClient({
  identityUrl: env.IDENTITY_INTERNAL_URL,
  getServiceToken: () => env.IDENTITY_ASSIGNMENTS_SERVICE_TOKEN,
});
const context = assignmentContextFromHeaders(request.headers);
if (!context)
  return reply.code(401).send({ error: "trusted_identity_required" });
const displayName = await client.resolveDisplayName(context);
if (displayName.active) {
  order.sellerName = displayName.user.displayName; // fallback: order.sellerId
}

Si idp-core está caído o devuelve active: false, el cliente lanza AssignmentResolutionError('identity_unavailable'). El backend consumidor debe degradar al sellerId sin propagar el fallo a la operación protegida.

Esta ruta existe sólo para datos de presentación administrativa (poblar sellerName, changedByName, etc.). NO se debe usar para decidir autorización; las decisiones PBAC siguen tomándose exclusivamente con resolve() y AssignmentResolution.

El token se genera desde un entorno operativo autorizado de idp-core, nunca dentro del frontend ni se versiona:

node scripts/generate-token.js \
  --subject ordamy-backend \
  --audience urn:bigso:identity:assignments \
  --scope identity.assignments.resolve,identity.assignments.display-name \
  --expires-in 90d \
  --private-key ./keys/private.pem