Tenants e identidad

Darwin es multi-tenant by design. Esta página describe el modelo de identidad — qué es un tenant, cómo se ubican las organizaciones debajo, cómo se autentican los usuarios, y cómo los DIDs anclan todo on-chain.

La jerarquía

Tenant
 ├─ Organizaciones (múltiples)
 │   ├─ Miembros (usuarios)
 │   └─ Roles (Operator / Admin / Auditor / Compliance)
 ├─ Process maps (config: qué eventos, qué transformaciones)
 ├─ API keys (server-to-server)
 └─ contrato on-chain Tenant.sol + DID

Tenant

Un tenant es el cliente comercial. Un tenant por relación de pago (cooperativa de alimentos, supplier automotriz, brand textil, etc.). Cada tenant tiene:

• Un DID (Decentralized Identifier, W3C). El anclaje on-chain de la identidad del tenant.
• Un smart contract Tenant.sol dedicado. Todos los eventos on-chain que pasan por este tenant están gateados por él.
• Un sub-árbol de config-registry por tenant — definiciones del process map, asset types, frameworks de compliance habilitados, branding (brand.json).

Los tenants están aislados: la data del Tenant A nunca es visible para el Tenant B, ni on-chain ni off-chain.

Organización

Dentro de un tenant, una organización es una entidad legal que participa en la cadena de valor: una cooperativa, un supplier tier-2, un assembler tier-1, un retailer, un auditor. Múltiples organizaciones bajo un mismo tenant colaboran en una cadena de custodia compartida.

Cada organización tiene su propio DID. Los eventos de transferencia de custodia entre organizaciones están firmados por ambos DIDs y registrados on-chain.

Miembro (usuario)

Un usuario es una persona con credenciales. Pertenece a una o más organizaciones dentro de un tenant. Los usuarios tienen roles que determinan qué API surface pueden usar:

• Operator — captura eventos vía Captia (write-only sobre su org)
• Admin — gestiona process maps, organizaciones, miembros
• Auditor — read-only en todo el tenant
• Compliance — read + sign-off en bundles regulatorios

Los roles mapean a scopes en el JWT. Ver Autenticación para el formato del wire.

Formatos de identidad

Tipo	Formato	Vida útil	Uso
JWT bearer	Bearer <jwt>	corta (1h típico, refresh disponible)	calls user-driven
API key	X-API-Key: <key>	larga, rotable	server-to-server
DID	did:web:<dominio> o did:ethr:<addr>	permanente (rotación = nuevo DID)	anclaje on-chain
SIWE	nonce de Sign-In with Ethereum	por sesión	login con wallet

Modelo de permisos

Los process-scope grants (shipped 2026-05) extienden el acceso por rol con least-privilege por proceso:

Ejemplo: un Operator en la cooperativa solo puede capturar eventos de wool_shearing; no puede capturar garment_assembly aunque el rol técnicamente lo permita en write. El grant está scopeado a los procesos que él opera.

Esto es la base para abrir una organización a múltiples colaboradores sin exponer el process map completo.

Ver los contratos on-chain para la semántica canónica de permisos: traceability-protocol.

Whitelabel branding

Cada tenant tiene un brand.json que driveea:

• Logo (light + dark)
• Paleta de colores (primary / secondary / acentos)
• Dominio custom (ej. passport.<tenant>.com)
• Idioma (es / en / fr / pt-BR / extensible)
• Overrides de copy

El branding Darwin Evolution (#F47A3E orange / #033144 navy) es el primer cliente whitelabel; nuevos tenants overridean al provisioning.

Qué expone el dev portal

Este wiki documenta el surface REST + GraphQL para integradores. Los flujos internos de provisioning de tenant (CLI tooling para ops) viven en traceability-docs que es privado.