Saltar al contenido principal

Marketplace de apps

El marketplace lista las apps de socios que el operador de su PBX revisó y aprobó. Un administrador instala una app para la empresa. La app instalada inicia sesión en su PBX a través de su propio servidor de autorización OAuth 2.1, con exactamente los permisos que declaró y nunca más. No hay pagos en el marketplace.

Instalar una app​

Abra Admin > Conexiones > Marketplace (/admin/marketplace). Necesita integrations:read para explorar e integrations:write para instalar y desinstalar.

  1. Busque la app en Apps disponibles. Cada entrada muestra el editor, la versión y los permisos que obtiene.
  2. Pulse Instalar. El diálogo repite los permisos: la app solo puede iniciar sesión con estos, y cada usuario todavía la aprueba en la página de consentimiento.
  3. La app aparece ahora en Apps instaladas con su ID de cliente OAuth. Entregue ese id a la app. La app ejecuta entonces su inicio de sesión en su PBX.

Para quitar una app, pulse Desinstalar en Apps instaladas. Todos los tokens de la app dejan de funcionar de inmediato. Instalar y desinstalar se escriben en la bitácora de auditoría y generan los eventos integration.installed e integration.removed con el conector marketplace:<app_id>.

Cómo funciona el límite: una instalación registra en su empresa un cliente OAuth cuyo tope de permisos es exactamente el manifiesto de la app. Al iniciar sesión, cada usuario solo puede otorgar a la app los permisos solicitados que estén en ese tope y que el propio usuario tenga.

Cola de revisión para el operador​

Los administradores del sistema abren Admin > Revisión de apps (/admin/marketplace/review). Necesita system.settings:read para verla y system.settings:write para actuar.

Un envío pasa por estos estados:

submitted -> in review -> approved -> withdrawn
|-----> rejected

Un envío también puede retirarse desde enviado o en revisión. Solo las versiones aprobadas se listan y se pueden instalar. Rechazada y retirada son finales: el editor envía una versión nueva. Una app retirada no puede instalarse de nuevo, pero las empresas que la tienen la conservan hasta que la desinstalen.

Cada envío muestra su manifiesto firmado y una lista de verificación de licencia y seguridad. Aprobar exige marcar todos los puntos, y Rechazar exige una nota para el editor:

  • Cada dependencia incluida tiene una licencia permisiva.
  • La licencia y los avisos de terceros están publicados.
  • Ningún código copyleft o de fuente disponible se ejecuta dentro de la PBX.
  • Cada permiso solicitado lo necesita una función documentada.
  • Cada dirección de redirección y servidor de webhook pertenece al editor.
  • Cada punto final usa HTTPS con un certificado válido.
  • La app verifica las firmas de webhook y la ventana de reenvío.
  • Los tokens se guardan cifrados, nunca se registran y se rotan.
  • Una política de privacidad indica qué datos de llamadas se guardan, dónde y por cuánto tiempo.
  • Hay un contacto de seguridad y un proceso de divulgación publicados.
  • Las extensiones de consola funcionan en un marco aislado.

Editores y claves de firma​

En la misma página, Editores y claves de firma registra a un socio y sus claves (system.settings:write).

  1. Registrar editor: un id de editor (de 2 a 40 minúsculas, dígitos o guiones, empezando por una letra), un nombre y un contacto de seguridad.
  2. Registrar clave de firma: un id de clave (de 3 a 64 minúsculas, dígitos, puntos, guiones bajos o guiones) y la clave pública Ed25519 como 44 caracteres base64 (32 bytes). La clave privada nunca sale del editor.
  3. Para rotar, registre una clave nueva y revoque la anterior con Revocar clave de firma. Una clave revocada no verifica ningún envío nuevo. Las versiones ya revisadas quedan como están.

Qué envía un socio​

Un socio firma los bytes exactos de un manifiesto (esquema 1, JSON de hasta 64 KiB) con su clave Ed25519 y envía el manifiesto, el id de la clave y la firma, a través del operador, a POST /api/v1/system/marketplace/submissions. Una firma de una clave desconocida, revocada o de otro editor, o que no coincide con los bytes, se rechaza con MPBX-MKT-SIGNATURE. Un manifiesto que no sigue el esquema se rechaza con MPBX-MKT-MANIFEST-INVALID.

El manifiesto indica el id y la versión de la app, el editor, de 1 a 32 permisos (nunca system.*), de 1 a 8 direcciones de redirección y, opcionalmente, webhooks, puntos de extensión de la consola y la descripción de un conector. Los campos desconocidos se rechazan y toda dirección debe ser https. Cada versión es un envío nuevo.

API​

LlamadaPermiso
GET /api/v1/marketplace/apps, GET /api/v1/marketplace/installsintegrations:read
POST /api/v1/marketplace/apps/{app_id}/install, DELETE /api/v1/marketplace/installs/{app_id}integrations:write
Editores, claves y la cola de revisión en /api/v1/system/marketplace/...system.settings:read y system.settings:write

Conviene saber​

  • Los socios envían sus apps a través del operador, con una credencial de sistema.
  • Instalar le da a la app su cliente OAuth. No crea webhooks, no agrega páginas de la consola ni ejecuta un conector en su PBX.
  • Una instalación se queda en su versión. No hay aviso de actualización ni nuevo consentimiento cuando una versión nueva pide otros permisos.