¿Qué debe llevar una entrega del proveedor además de un estado?
Un proveedor de verificación le informa de que una sesión está Approved. Su servicio de alta tiene que decidir si esa palabra puede cambiar algo en su aplicación. Un estado aislado no responde a esa pregunta. No indica a qué tenant y a qué usuario pertenece la sesión, si la sesión sigue dentro de su plazo ni si su propia política permite actualmente la acción. Este artículo propone un contrato de entrega hipotético que transporta esos datos. Después contrasta cada campo con el fixture sintético de entrega, para que pueda decidir si una integración en sandbox encaja con su tarea de identidad. Todo se ejecuta localmente con identificadores sintéticos. No se describe ni se insinúa ningún adaptador en vivo.
curl https://gridzen.ai/console/api/quickstart/trial \
-H 'Content-Type: application/json' \
-d '{"task": "identity_onboarding", "scenario": "success"}'El problema: un estado sin contexto
Suponga que su handler recibe un callback con estado Approved y un ID de sesión. Si actúa solo con eso, aparecen tres fallos posibles. Un callback vinculado a otro tenant o a otro usuario podría desbloquear la cuenta equivocada. Un callback tardío podría revivir una sesión que su producto ya abandonó. Una aprobación podría conceder una acción que su política ha desactivado después. La decisión que tiene delante es qué debe contener su registro de entrega y quién es responsable de cada comprobación. El fixture responde a una parte de esta pregunta. Su aplicación responde al resto.
Contrato de entrega propuesto (diseño de aplicación, no implementado por GridZen)
Proponemos que cada registro de entrega incluya lo siguiente: 1. Vinculación: session, tenant y subject, fijados al crear la sesión. 2. Plazo: una caducidad absoluta, a partir de la cual ningún estado puede conceder nada. 3. Política del llamador: policy_version y el indicador allow_action, ambos bajo el control de su aplicación. 4. Estado de la evidencia: el estado normalizado, además de si se concedió un permiso y cuántas concesiones hubo. 5. Siguiente acción: una instrucción explícita, nunca un permiso implícito. Esto es una recomendación de diseño. La guía Bring Your Own Provider de GridZen indica que el alfa actual no acepta claves arbitrarias de proveedor en el navegador ni en el cuerpo de la petición. También indica que cada producto de proveedor necesita su propio adaptador aprobado y su propia revisión de alcance, y que la disponibilidad de rutas en vivo requiere una confirmación aparte.
Lo que el fixture implementa realmente
La clase Identity guarda cada sesión en SQLite con estas columnas: id, tenant, subject, status, deadline, granted, grants, policy_version y allow_action. El método create rechaza cualquier identificador que no empiece por fixture-. También rechaza un timeout fuera del intervalo de 1 a 3600 segundos. El método event se comporta así: - Solo acepta mode synthetic_fixture con source fixture_callback. Cualquier otra cosa lanza PRODUCTION_SIGNATURE_VERIFIER_NOT_IMPLEMENTED, porque no existe verificación real de firmas. - Lanza BINDING_MISMATCH cuando el tenant o el subject no coinciden con los valores guardados. - Ignora los IDs de evento duplicados. - Marca la sesión como expirada cuando now alcanza o supera el deadline. - Convierte en unknown cualquier estado no reconocido. - Solo concede permiso cuando el estado es Approved, policy es True y allow_action está activo. El método handoff devuelve el registro actual con verified en false y next_action con el valor read_current_evidence_and_policy_before_explicit_decision. El método decide exige un policy_version coincidente, una aprobación explícita, un estado approved dentro del plazo y allow_action. Si el policy_version no coincide, lanza STALE_POLICY_VERSION.
Escenario hipotético y salidas esperadas
Un marketplace hipotético da de alta a un vendedor. Los pasos siguientes usan los valores por defecto del fixture. 1. Crear una sesión. La salida esperada incluye session fixture-session, un hosted_link bajo example.invalid, link_executable false y next send_real_provider_link_only_after_authorization. 2. Enviar el evento fixture-approved con policy True. La salida esperada es status approved, deadline 60, permission_granted true, grant_count 1, live_permission_changed false, policy_version 1 y allow_action true. 3. Repetir el mismo evento. La salida es idéntica y grant_count se mantiene en 1. 4. Enviar un evento posterior con estado Declined. La salida muestra status declined y permission_granted false. grant_count sigue en 1, porque registra el historial. 5. En una sesión nueva en la que no llega ningún callback, llamar a recover con now 61. La salida muestra status expired, permission_granted false, grant_count 0, next review_or_authorized_provider_refresh y provider_polled false. 6. Los errores se comportan así. Un evento para una sesión desconocida devuelve BINDING_MISMATCH. Una lectura de una sesión desconocida devuelve SESSION_NOT_FOUND.
Manejo de fallos a cargo del llamador
El fixture nombra los fallos. Su aplicación debe decidir qué significa cada uno. - BINDING_MISMATCH: trátelo como un incidente de seguridad. No lo reintente. - STALE_POLICY_VERSION: vuelva a leer la política y reintente la decisión. - Expirado: envíe la sesión a revisión o cree una sesión nueva autorizada. - Estado unknown: retenga la sesión para revisión. El método recover expira las sesiones localmente y nunca consulta a un proveedor. Refrescar la evidencia desde un proveedor real es una integración aparte que requiere autorización. Una concesión del fixture es un registro local. No es un permiso de negocio real, y live_permission_changed siempre vale false. En la prueba real de identidad alojada, GridZen verifica las notificaciones firmadas y vuelve a consultar las decisiones autoritativas. Sin embargo, el recorrido completo de un usuario recién aprobado seguido de una acción de negocio del cliente sigue sin verificarse.
Lista de aceptación
Antes de pasar del fixture a una solicitud de sandbox, confirme cada punto: - Cada registro de entrega guarda session, tenant, subject y deadline al crearse. - Un tenant o subject que no coincide se rechaza y se registra, sin reintentos. - Un evento duplicado no incrementa grant_count. - Un callback que llega después del plazo no puede conceder nada. - Un evento Declined posterior a una aprobación revoca permission_granted. - Un cambio de política reinicia la concesión, y se rechaza un policy_version obsoleto. - Ninguna ruta de código trata verified false como permiso. - La retención, el borrado, el registro de accesos y la responsabilidad sobre la política están aprobados antes de cualquier uso en vivo. Si su tarea necesita un proveedor o un país fuera de las rutas confirmadas, no dé por hecho que existe soporte. Solicite primero una revisión de alcance.
Ejecutar el ejemplo sintético comprobado
Descargue y extraiga https://gridzen.ai/downloads/verification-delivery.zip, entre en verification_delivery y ejecute con Python 3.10+. El ejemplo local no hace llamadas de red. Use una base nueva para otra prueba de identidad.
python3 delivery.py identity --db /tmp/gridzen-article-fixture.sqliteFuentes y alcance
https://gridzen.ai/guides/bring-your-own-provider/ https://gridzen.ai/guides/current-capabilities/ Basado en las fuentes comprobadas y el ejemplo local; las reglas propuestas son recomendaciones de diseño, no comportamiento de producción demostrado. Redacción asistida por IA con revisión independiente.
Probar por separado tres resultados del sandbox Crear una cuenta para continuar la integración
Una descarga no demuestra una ejecución correcta. Los ejemplos locales y el sandbox en línea se prueban por separado.