Manifiesto y firma

El manifiesto orkan-module.toml declara qué es el módulo y qué necesita. La firma demuestra quién lo ha publicado. Orkan comprueba las dos cosas al instalarlo.

El manifiesto

id = "acme.echo"
version = "0.1.0"
name = "Acme echo"
description = "Devuelve la entrada tal cual."
publisher = "acme"
world = "orkan:module/node-module@1.0.0"
min_host_version = "1.0.0"
credential_types = []

[[capabilities]]
kind = "network.http"
allowed_hosts = ["api.example.com"]

[files]

Campo	Notas
`id`	DNS inverso en minúsculas, con al menos dos segmentos (`acme.echo`). El espacio `orkan.` está reservado* a la clave oficial de Gnevoo.
`version`	Versión semver del paquete.
`name`, `publisher`	Obligatorios. `description` es opcional, pero conviene rellenarla.
`world`	`orkan:module/node-module@1.0.0` o `orkan:module/trigger-module@1.0.0`.
`min_host_version`	La versión mínima de Orkan que necesita el módulo.
`capabilities`	Lista de capacidades, sin repetir.
`credential_types`	Tipos de cuenta propios del módulo.
`files`	Hash SHA-256 de cada archivo. Lo rellena `pack`: no lo escribas a mano. Debe existir la tabla `[files]`, aunque esté vacía.

Cualquier clave que no sea de esta lista es un error. Los archivos del paquete solo pueden ser module.wasm (obligatorio), README.md, LICENSE, icon.svg y lo que cuelgue de assets/.

Capacidades

Una capacidad es un permiso concreto. Lo que no declares queda denegado, y si el componente importa algo sin declarar su capacidad, Orkan rechaza el módulo.

`kind`	Qué desbloquea
`network.http`	Peticiones HTTP a `allowed_hosts` (nombres exactos, IP o `*.dominio`).
`network.socket`	Conexiones TCP/UDP a `allowed_endpoints` (`host:puerto`).
`credentials.inject`	Que Orkan ponga la autenticación de la cuenta en la petición, sin que el módulo vea la clave.
`credentials.read-secret`	Leer en claro un campo secreto. Es la de más riesgo: úsala solo si la inyección no sirve.
`state`	Guardar estado entre ejecuciones.
`binary`	Leer y crear archivos.
`ai`	Llamar a modelos de IA de Orkan.
`sql`	Consultas SQL con una cuenta.
`flow`	Solo `orkan.core`.

Consejos: declara solo lo que el componente importa (orkan-module build te lo dice); usa dominios exactos; prefiere credentials.inject a credentials.read-secret; pide network.socket solo para protocolos que no sean HTTP.

Hosts que aprueba cada instalación. Un módulo genérico que no conoce sus servidores de antemano puede declarar hosts = "installation" en lugar de una lista fija: entonces la lista la aprueba quien administra cada Orkan. Solo vale para módulos oficiales o verificados.

Quién aprueba qué. Al instalar, quien administra el Orkan ve las capacidades que pide el módulo. Si una actualización pide más, queda pendiente hasta que se aprueben.

La firma

El paquete lleva module.sig: una firma Ed25519 sobre el hash del manifiesto en su forma canónica. Por eso cualquier cambio en el manifiesto obliga a volver a empaquetar.

orkan-module keygen --out ./claves
orkan-module pack --key ./claves/<key_id>.pk8
orkan-module verify <id>-<version>.orkmod --trust ./claves/trust.toml

keygen crea <key_id>.pk8 (clave privada, no la compartas ni la subas), <key_id>.pub (pública) y trust.toml, un almacén de confianza local para verify.
pack calcula los hashes, escribe module.sig y genera <id>-<version>.orkmod.
verify comprueba firma, hashes, manifiesto y que las capacidades declaradas cubren los imports.

Niveles de confianza según la clave que firma:

Nivel	Qué es
Oficial	Firmado con la clave oficial de Gnevoo. Es el único que puede usar `orkan.*`.
Verificado	Paquete de un desarrollador que ha pasado las comprobaciones y la revisión de Gnevoo.
Privado	Firmado con la clave de una organización, para su propio Orkan.
Sin firma	Solo para desarrollo local (`--allow-unsigned`). Nunca en el registro.

Publicar

Publicar en el catálogo exige una invitación de Gnevoo: escríbenos. El recorrido es:

Canjear la invitación (orkan-module redeem): da un token de publicación que se muestra una sola vez. Guárdalo en un archivo con permisos restringidos.
Registrar tu clave pública (orkan-module register-key <clave>.pub).
Empaquetar y verificar (pack, verify).
Publicar (orkan-module publish <paquete>.orkmod).
Revisión: el staff de Gnevoo revisa el paquete; cuando lo aprueba, entra en el catálogo firmado. Una versión publicada es inmutable: para cambiar el código, sube la versión.

orkan-module list muestra el estado de tus paquetes. orkan-module yank (retirar una versión propia) todavía no está disponible en el registro.