Inicio/Documentación/Arquitectura y nodos

Documentación del sistema · piloto de uso interno

Cómo funciona CivicOS.

Una guía para entender la publicación de documentos, sus firmas, el papel de OrbitDB y Supabase, y cómo poner en marcha una réplica del nodo. Las propuestas publicadas se diseñan como documentos Markdown verificables; la base de datos facilita su consulta.

01 · MODELO

El documento publicado es la referencia

Una propuesta se redacta como Markdown con metadatos estructurados (frontmatter). Al publicarla, el contenido y sus metadatos se serializan, se calcula un hash y se añade la firma del autor. El registro incluye identificadores y relaciones necesarias para reconstruir la vista —por ejemplo, tipo, tema, autor cívico y referencias—, sin convertir la base de datos en la autoridad sobre el texto.

01

Markdown firmado

Contenido, metadatos, hash y firma de autor.

02

OrbitDB

Log replicable elegido como fuente canónica de documentos publicados.

03

Índice de consulta

Supabase facilita búsquedas y relaciones; puede reconstruirse desde los registros.

Si el índice y el registro canónico discrepan, debe prevalecer el documento validado en OrbitDB. Los lectores pueden verificar la firma y el hash con los registros disponibles; la firma prueba control de una clave e integridad del contenido, no que sus afirmaciones sean verdaderas.

02 · PUBLICACIÓN

Del borrador al registro consultable

  1. Redactar. La persona elige el tipo y prepara un documento en el editor y la aplicación genera Markdown con metadatos.
  2. Firmar. El navegador firma el documento con una clave Ed25519 de su navegador; el flujo común no exige cuenta.
  3. Validar y registrar. El servicio de escritura comprueba formato, hash y firma, y envía el evento al nodo OrbitDB.
  4. Actualizar el índice. Supabase guarda campos de consulta para listar y relacionar el documento. La página vuelve a obtener el registro canónico y comprueba la firma.
  5. Consultar y exportar. La vista permite leer el texto y acceder a su representación Markdown para conservarlo o verificarlo.

Una nueva versión debe publicarse como un registro nuevo que enlace con la anterior y explique el cambio; no se debe presentar una edición como si el texto original nunca hubiera existido.

03 · DEBATE DISTRIBUIDO

Comentarios en OrbitDB, firmas opcionales y réplica Nostr

Puedes comentar sin cuenta y sin firma de autor. El editor conserva el formato como Markdown. Cada comentario y apoyo se registra primero en el log OrbitDB y recibe un enlace permanente. Supabase facilita encontrar el documento principal; los comentarios nuevos se leen desde el nodo.

  1. Escribe un nombre o alias si quieres: será un nombre declarado. Puedes publicar sin firma o añadir una firma de dispositivo.
  2. La lista muestra primero las identidades con acreditación vigente, después las firmas de dispositivo y al final los comentarios sin firma. Más apoyados, Relevancia y Más recientes ordenan dentro de esos grupos. Sólo firmados oculta los comentarios sin firma.
  3. Los comentarios firmados usan eventos Nostr NIP-22 con texto plano y una extensión propia que incluye Markdown firmado. Las respuestas o apoyos a un comentario sin firma usan una referencia CivicOS propia; no se presentan como un estándar Nostr universal.
  4. Los apoyos tienen firma y cuentan una vez por clave y comentario. Cada apoyo es público; varias claves pueden pertenecer a una misma persona. No tienen valor electoral.
  5. Tras el registro canónico se intenta enviar el evento firmado a los relays. Un rechazo del relay no borra el comentario recibido en OrbitDB. Un comentario sin firma no se disfraza como una firma de su autor.
Una firma de dispositivo no acredita una identidad real.

La acreditación se consulta en el servidor, con caducidad y revocación. El verificador FNMT/DNIe todavía no está integrado; el piloto permite participar sin esa acreditación. No publiques información privada ni documentos de identidad.

Compartir abre un enlace independiente con acceso al documento principal y a todos sus comentarios. Fuente del comentario exporta el registro sin firma; Evento firmado exporta el evento verificable. Consulta la guía de participación.

03 · IDENTIDAD Y FIRMAS

Tres pruebas distintas

Firma del documento

Vincula el contenido a una clave de autor y permite detectar cambios posteriores.

Identidad del nodo

Identifica al peer que escribe en OrbitDB y permite comprobar operaciones del log.

Identidad civil

Requeriría una credencial verificada por un emisor y pruebas de unicidad adecuadas. DNIe, FNMT y Cl@ve aún no están integrados como login o acreditación verificable en esta aplicación.

La clave de firma de autor vive en el navegador y no equivale a un certificado digital. El estado de verificación que consulta la web pertenece al servicio actual; por sí solo no demuestra a terceros la identidad civil de una persona. No publiques documentos de identidad, secretos ni datos personales en OrbitDB.

04 · ESTADO Y LÍMITES

Qué ofrece hoy el piloto

  • Crear documentos: se puede empezar sin cuenta. El borrador se conserva en el navegador; una cuenta solo es opcional y no sincroniza todavía ese borrador.
  • Publicar: la persona firma una sola vez al final con una clave Ed25519 creada en el navegador. Puede declarar un nombre público o publicar con seudónimo. El nombre no se verifica como identidad civil.
  • Propuestas: publicación firmada y lectura desde OrbitDB, con Supabase como índice auxiliar.
  • Versiones: el autor puede añadir ediciones con su misma clave. Cada una enlaza el hash anterior, muestra un resumen y permite comparar el texto. Marcar definitiva impide más ediciones en esa cadena.
  • Asambleas y actas: las nuevas convocatorias y actas del editor se registran en OrbitDB y admiten enlaces firmados. Se exige lugar, fecha, facilitación y participantes. Cada persona puede firmar una declaración propia sobre esa versión; no demuestra por sí sola identidad civil ni presencia física. Las actas editoriales anteriores conservan su ruta R2 y firma del servicio.
  • Comentarios nuevos: se conservan en OrbitDB con o sin firma; los eventos firmados pueden replicarse además en Nostr. Supabase conserva el vínculo privado de las claves que se acreditan. Los comentarios históricos siguen en Supabase.
  • Votación: no hay una urna electrónica habilitada. No usar este prototipo para decisiones vinculantes.
  • Publicación sin cuenta: hay cuotas persistentes y atómicas de admisión en Supabase, por origen de red y globales. La publicación permanece cerrada por defecto. Antes de abrirla hace falta configurar el nodo privado online, mitigación de bots, moderación y política de privacidad.
  • Red: existe un primer nodo de ensayo. La replicación entre operadores independientes, la recuperación completa del índice y la operación pública sostenida necesitan pruebas.
OrbitDB no significa invulnerable ni incensurable.

La replicación puede mejorar la disponibilidad, pero requiere peers independientes, copias y procedimientos operativos. El prototipo no tiene auditoría de seguridad, consenso electoral, protección contra ataques coordinados ni garantía de permanencia.

05 · OPERAR UN NODO

Ejecuta una copia del nodo Orbit

El código inicial está dentro del repositorio de CivicOS, en nodes/orbitdb-node-01. Necesitas Node.js 22 o posterior, npm 10 o posterior y acceso al repositorio privado.

  1. Clona el repositorio y entra en la carpeta del nodo.
  2. Instala las dependencias fijadas con npm ci.
  3. Arranca el proceso con npm start; para comprobar el inicio y cierre, usa npm run check.
  4. El primer arranque crea los datos locales en nodes/orbitdb-node-01/data/node-01/. Conserva esa carpeta para mantener la identidad del peer.
git clone --branch codex/orbitdb-signed-publication https://github.com/gordo-labs/bases-futuro-compartido.git
cd bases-futuro-compartido/nodes/orbitdb-node-01
npm ci
npm start

Código del nodo · repositorio privado

OrbitDB Node 01

Guía de requisitos, arranque, persistencia de datos y configuración de una segunda réplica.

Abrir código del nodo ↗

Claves y seguridad del operador

  • No compartas data/node-01/node-key.pb, la carpeta de datos ni secretos de entorno. Esa clave representa la identidad técnica del peer.
  • Para una segunda réplica, crea una identidad y carpeta de datos propias. Configura la dirección del log y un peer alcanzable; nunca copies la clave del primer nodo.
  • La API del nodo escucha en loopback y exige un secreto de servicio. El primer nodo usa un túnel HTTPS autenticado por la aplicación; no publiques la API directamente ni compartas ese secreto. Las cuotas se aplican en la web.
  • El servicio web desplegado no puede acceder a 127.0.0.1 del ordenador del usuario. El piloto usa un túnel HTTPS hacia el primer nodo. Su disponibilidad depende de que el equipo esté encendido; todavía hacen falta réplicas de operadores independientes.

ALOJAMIENTO SENCILLO · SERVIDOR LINUX CON DOCKER

Deja una réplica encendida

Esta receta ejecuta un nodo P2P en un servidor y conserva sus datos en un volumen. Para replicar el registro canónico necesitas la dirección OrbitDB y una dirección de red alcanzable de un peer que ya participe.

  1. Prepara un servidor Linux con Docker Engine y Docker Compose. Sigue la instalación oficial de Docker ↗.
  2. Clona la rama privada y entra en la carpeta del nodo:
git clone --branch codex/orbitdb-signed-publication https://github.com/gordo-labs/bases-futuro-compartido.git
cd bases-futuro-compartido/nodes/orbitdb-node-01
  1. Crea un archivo .env en esa carpeta y configura este peer con la dirección del nodo existente:
CIVIC_ORBIT_NODE_ID=02
CIVIC_ORBIT_PORT=4102
CIVIC_ORBIT_DB_ADDRESS=/orbitdb/DIRECCION_DEL_REGISTRO
CIVIC_ORBIT_BOOTSTRAP_PEERS=/ip4/IP_PUBLICA_DEL_PEER/tcp/4101/p2p/PEER_ID
  1. Abre 4102/TCP en el firewall. Sustituye los valores de ejemplo por los reales. Si dejas vacía la dirección OrbitDB, el nodo creará un registro independiente.
  2. Construye y arranca el contenedor:
docker compose up -d --build
docker compose logs -f orbit-node
  1. Comprueba en los registros el Peer ID y la dirección de la base. Para parar el nodo sin borrar sus datos usa docker compose down. El volumen orbit_data conserva claves y bloques; no uses down -v.
La receta no expone la API de publicación.

Solo publica el puerto P2P. La web alojada necesita conectarse al nodo por un canal privado autenticado; la API de desarrollo no debe abrirse directamente a Internet.

EVOLUCIÓN FUTURA · AÚN NO IMPLEMENTADA

Una aplicación para operar el nodo

Sí, se puede diseñar una app de escritorio basada en Electron para que instalarla, elegir una carpeta y pulsar Iniciar nodo sea el recorrido normal. La app empaquetaría el runtime y el nodo, crearía una identidad técnica propia, conectaría con peers configurados y mostraría el estado sin exigir terminal ni editar archivos de entorno.

  • La carpeta elegida guardaría identidad y bloques; la app avisaría que no conviene sincronizarla con iCloud, Dropbox u otros servicios de nube.
  • La interfaz distinguiría un proceso simplemente activo de un nodo conectado y sincronizado, y explicaría si se creó una base independiente.
  • La clave del nodo permanecería local. La app no firmaría documentos en nombre de usuarios, no validaría ciudadanía y no expondría el control del nodo a Internet.
  • Incluiría parada segura, copia de seguridad cifrada y recuperación, actualización firmada y comprobaciones de red. NAT, firewall, suspensión del equipo y disponibilidad del operador seguirían afectando la réplica.

Es una propuesta, no una función disponible hoy. Requiere antes estabilizar el protocolo, probar la replicación entre operadores y crear una interfaz local segura. Los requisitos, etapas y criterios de aceptación están en la propuesta de arquitectura para la app de escritorio ↗.

El repositorio principal es privado, así que este enlace sólo funciona para personas con acceso concedido. Para que cualquier ciudadano u organización pueda ejecutar un nodo, habría que publicar un repositorio de operador separado o hacer público este código; esta página no cambia la visibilidad del repositorio.

Volver a la guía de uso →