Proveedores de sincronización (apiVersion 12, Kino 0.9.74)¶
Un proveedor de sincronización es un plugin que lleva la sincronización propia de Kino entre los aparatos de una persona por un servicio que tú eliges, en lugar de la red local. Kino hace todo el trabajo de sincronizar y le entrega a tu plugin un archivo cifrado para guardarlo y devolverlo: tu plugin solo mueve bytes.
Para qué sirve¶
Desde "apiVersion": 12 (Kino 0.9.74), cualquier cosa que pueda guardar un archivo de hasta 4 MiB detrás
de una API https pública puede llevar la biblioteca, el historial, el progreso y los ajustes de una
persona:
- Tu propio servidor o NAS, por una dirección
httpspública (un túnel):kino.fetchnunca llega directo a la red local. - Un disco en la nube o un servicio de almacenamiento con una API
httpsy un token largo y aleatorio por persona. - Un bot de chat de la propia persona, como Sync-Gram: la copia es un archivo fijado en su chat privado con el bot.
- La propia cuenta de chat de la persona, como Sync-Gram Cuenta: la copia es un archivo
fijado en sus Mensajes guardados de Telegram, por un WebSocket (
socket, apiVersion 13). - Un repositorio privado de Git, con la copia como un solo archivo escrito por la API del servicio.
- Una Raspberry Pi en casa con un servidor pequeño como Sync Servidor, detrás de un túnel
https. - El servidor de una empresa o un colegio con una dirección
httpspública que le da un token a cada persona. - Sincronizar sin compartir el Wi-Fi: aparatos en lugares distintos siguen al día, tan seguido como la persona elija (cada 1 a 60 minutos).
Cómo habla con Kino¶
celular / TV (Kino) tu plugin tu servicio
─────────────────── ───────── ───────────
arma la copia y la cifra ──▶ syncPush({ blob, expectedVersion }) ──▶ guarda los bytes
combina lo que lee de vuelta ◀── syncPull() → { blob, version } ◀── devuelve los bytes
- Kino arma una copia de todo lo que ya sincroniza (cada perfil que sincroniza el aparato), la comprime y la cifra entera (AES-256-GCM).
- Llama a tu
syncPull(): devuelves la copia guardada en base64 con unaversiontuya, onullsi todavía no hay nada. Kino la abre, la combina con los datos del aparato y arma la copia nueva. - Llama a tu
syncPush({ blob, expectedVersion }): guardas los bytes tal cual y devuelves laversionnueva. Si tu servicio sabe que otro aparato guardó una copia después deexpectedVersion, lanzaskino.error("conflict", …)y Kino trae, combina y vuelve a enviar. - Eso es todo lo que hace tu código. Kino nunca le pasa una fila ni la llave; pero la llave se deriva de
uno de los ajustes
passwordde tu propio plugin (elsync.keySecretobligatorio), que tu código puede leer, así que el plugin y su servicio pueden leer los datos, y la hoja de consentimiento lo dice en rojo (quién ve qué).
Lo que Kino hace por ti, sin código tuyo:
- El horario: cuándo traer y enviar, una espera después de los cambios, como mucho 60 rondas por hora, esperas más largas después de fallas y el "Sincronizar cada" de la persona (1 a 60 minutos) en la tarjeta de tu proveedor.
- Combinar y resolver conflictos: se combinan las filas de los dos lados (gana la más nueva, los
borrados se conservan); un
conflictque avisas se reintenta hasta 3 veces. - Perfiles: cada perfil que sincroniza el aparato viaja en la misma copia.
- Otro aparato: "Enviar configuración" le pasa tus ajustes a un segundo aparato, que muestra "Recibir configuración", con un QR o un código escrito, por la red local o por un túnel temporal de Cloudflare (pasar los ajustes).
- Ajustes y pantallas: tu formulario de ajustes, la lista de proveedores con tu tarjeta, su línea de
estado (de tu
syncStatusopcional) y un botón "Sincronización ▸ Proveedor" en la página de tu plugin.
Haz el tuyo en 4 pasos¶
El ejemplo habla con un servidor tuyo en https://sync.example.com con dos llamadas: GET /blob responde
200 { "blob", "version" } (o 404 si está vacío) y PUT /blob con If-Match: <versión> responde
200 { "version" } (o 409 si la versión guardada es otra).
1. El manifiesto (kino-plugin.json):
{
"id": "my-sync",
"name": "My Sync",
"version": "1.0.0",
"apiVersion": 12,
"entry": "plugin.js",
"description": "Syncs your Kino devices through my server.",
"author": "me",
"hosts": ["sync.example.com"],
"capabilities": ["syncProvider"],
"settings": [
{ "key": "token", "label": "Token", "type": "password", "required": true,
"hint": "The long random token your account page shows", "devices": ["phone"] }
],
"sync": { "mode": "poll", "keySecret": "token", "provision": ["token"] }
}
keySecret nombra el ajuste del que sale la llave de sincronización; provision lista lo que "Enviar
configuración" le pasa a un segundo aparato (tiene que incluir keySecret); "devices": ["phone"] dibuja
el campo del token solo en el celular, porque un TV lo recibe.
2. El código (plugin.js):
const API = "https://sync.example.com";
const auth = () => ({ Authorization: "Bearer " + kino.config.get("token") });
// The stored copy and its version, or null when nothing is stored yet.
export async function syncPull() {
const r = await kino.fetch(API + "/blob", { headers: auth() });
if (r.status === 404) return null;
if (r.status === 401) throw kino.error("auth_required", "token refused");
if (!r.ok) throw kino.error("unavailable", "pull " + r.status);
const { blob, version } = r.json();
return { blob, version };
}
// Stores the copy only if the server still holds expectedVersion; a 409 means another device was faster.
export async function syncPush({ blob, expectedVersion }) {
const r = await kino.fetch(API + "/blob", {
method: "PUT",
headers: { ...auth(), "If-Match": expectedVersion ?? "" },
body: { json: { blob } },
});
if (r.status === 409) throw kino.error("conflict", "the stored copy changed");
if (r.status === 401) throw kino.error("auth_required", "token refused");
if (!r.ok) throw kino.error("unavailable", "push " + r.status);
return { version: r.json().version };
}
3. Pruébalo con el kit: node sdk/validate.mjs . revisa el manifiesto y el bloque sync como lo hace
Kino (estos dos archivos lo pasan) y muestra la línea roja de consentimiento; luego prueba las dos
funciones contra una imitación local de tu servicio con node --test (probar en local).
4. Publícalo: un repositorio público de GitHub con los archivos en la raíz y el topic kino-plugin
(publicar); la gente lo instala escribiendo usuario/repositorio. Fírmalo si quieres que
se sepa que cada actualización es tuya, y pide aparecer en la lista si lo quieres entre los
plugins recomendados de Kino.
El resto de esta página es la referencia. Tres proveedores completos, con guías que cualquiera puede seguir, son repositorios públicos: kinotvapp/kino-plugin-sync-gram, kinotvapp/kino-plugin-sync-server y kinotvapp/kino-plugin-sync-gram-account (los tres ejemplos); el kit es kinotvapp/kino-plugin-sdk.
¿Es la herramienta correcta?¶
- Sí, si tu plugin puede guardar un archivo de hasta 4 MiB en un lugar que controla la persona y
leerlo después, con una API
httpsen un host público. - No, para cualquier otra cosa: un proveedor no puede ver ni cambiar lo que sincroniza Kino, no puede sincronizar solo algunas tablas y no reemplaza el emparejamiento (el control remoto y el envío a la TV siguen por la red local).
- La persona escoge un proveedor, o ninguno: en Ajustes de todos los perfiles ▸ Sincronización ▸
Proveedor la lista tiene Red local y cada proveedor instalado, cada uno con un interruptor.
Encender uno apaga el anterior (Kino pregunta antes: "¿Sincronizar con <nombre>?", con
"Combinar con este aparato"); apagar el activo deja la sincronización apagada. La elección es por
aparato y nunca se sincroniza: cada aparato enciende su proveedor él mismo, con los ajustes que
escribió o que recibió. Ahí cada proveedor se dibuja como su propia tarjeta, con su
estado, sus botones y su "Sincronizar cada" (la línea roja de consentimiento está en la hoja de
instalación y en la confirmación al encenderlo, no en la tarjeta). Los botones siguen el estado del
proveedor: "Configurar" abre tu formulario de ajustes, y en un aparato que todavía no tiene los valores
de tu
provisionla tarjeta empieza por "Recibir configuración" (detalles). - La página propia de tu plugin en Ajustes (celular y TV) empieza con el botón "Sincronización ▸
Proveedor" de Kino, que abre esa lista (en el TV con la tarjeta de tu proveedor enfocada); no declaras
nada para eso. Marca con
devicesla preparación que el TV no puede hacer, para que el TV muestre solo lo que necesita.
Quién ve qué¶
Kino comprime la copia y la cifra entera (AES-256-GCM) antes de llamar a tu plugin. El blob que recibe tu código es texto cifrado, y Kino nunca le entrega la llave a tu código. Pero la llave siempre sale de los propios ajustes de tu plugin:
- Todo proveedor declara
sync.keySecret, lakeyde uno de sus ajustespassword. Un manifiesto consyncProvidery sinkeySecretse rechaza (The "syncProvider" capability needs a "sync" field whose "keySecret" is the key of one of the plugin's own "password" settings), en la app y en el kit. Aunque Kino cree él mismo ese valor (generateKey), la llave sale de ese ajuste. - Kino deriva la llave de sincronización en cada aparato del valor de ese ajuste (HKDF-SHA256, del lado de Kino). Un segundo aparato con el mismo valor deriva la misma llave, así que abre la misma copia y ninguna llave viaja entre aparatos.
- Por eso el plugin y su servicio SÍ pueden leer los datos sincronizados: la derivación es pública y tu código lee ese ajuste; un servicio que emitió el token (Telegram, para el token de un bot) también. La hoja de consentimiento lo dice en una línea en rojo, la misma para todo proveedor: "Sincronizará tus datos a través de su servicio: el plugin y su servicio podrán leerlos". Una actualización que agrega la capacidad siempre espera la aprobación de la persona.
- Dilo claro también en la descripción y en la guía de tu plugin: quien tenga el token puede leer los datos.
Lo que va en la copia: todo lo que Kino ya sincroniza entre aparatos emparejados por la red local, las mismas filas (biblioteca, historial, progreso, ajustes, los plugins instalados y sus ajustes), de cada perfil que sincroniza este aparato. Las contraseñas de los plugins y los demás secretos que sincroniza Kino también van, cada uno sellado fila por fila con la llave de sincronización. Los secretos sellados en el manifiesto de un plugin nunca viajan, como siempre.
El contrato¶
Declara la capacidad (puede ser la única) y "apiVersion": 12, y exporta dos funciones, más una
tercera opcional. Desde apiVersion 13 un proveedor también puede declarar socket, storageLarge,
catalog y qrScan junto a syncProvider y seguir sin necesitar resolve, search ni home
(["syncProvider", "socket"] para un proveedor que habla por kino.ws); cualquier otra
capacidad junto a ellas los vuelve a exigir.
"apiVersion": 12,
"capabilities": ["syncProvider"],
"hosts": ["api.example.com"],
"sync": { "mode": "poll", "maxBlobBytes": 4194304, "keySecret": "token", "provision": ["token"] }
export async function syncPull({ maxBlobBytes }) {
const r = await kino.fetch(API + "/blob", { headers: auth() });
if (r.status === 404) return null; // todavía no hay nada guardado
if (r.status === 401) throw kino.error("auth_required", "token refused");
if (!r.ok) throw kino.error("unavailable", "pull " + r.status);
return { blob: r.json().blob, version: r.json().version };
}
export async function syncPush({ maxBlobBytes, blob, expectedVersion }) {
const r = await kino.fetch(API + "/blob", { method: "PUT", headers: { ...auth(), "If-Match": expectedVersion ?? "" },
body: { json: { blob } } });
if (r.status === 409) throw kino.error("conflict", "the stored copy changed");
if (!r.ok) throw kino.error("unavailable", "push " + r.status);
return { version: r.json().version };
}
export async function syncStatus(_null) { // opcional
if (!kino.config.get("token")) return { ready: false, message: "Falta el token: escríbelo en Configurar" };
return { ready: true };
}
- Un argumento, un objeto (
nullensyncStatus).maxBlobByteses el valor del manifiesto (como mucho 4194304). blobes base64 estándar (RFC 4648,+y/, con relleno) sin saltos de línea, en las dos direcciones. Guárdalo y devuélvelo byte por byte; nunca lo decodifiques a texto. Una lectura responde{ blob, version }, onullcuando todavía no hay nada guardado.versiones un texto no vacío tuyo (un ETag, el id de un mensaje, un contador). Kino le pasa la última que trajo asyncPushcomoexpectedVersion(nullsi no trajo nada).- Conflictos. Si tu servicio puede saber que la copia remota cambió desde
expectedVersion, lanzakino.error("conflict", "…"): Kino trae, combina y vuelve a enviar, como mucho 3 veces más por ronda. Si no puede saberlo (no tiene comparar y escribir), ignoraexpectedVersion: la combinación de la ronda siguiente arregla la carrera. - Falta configuración. Lanza
auth_requireddesdesyncPull/syncPushcuando al plugin le faltan sus ajustes o el servicio rechaza las credenciales: la persona lee "al proveedor le falta configuración, revísala en Configurar" en vez de una falla genérica. syncStatusresponde{ ready, message? }para la fila del proveedor. Antes de cada ronda Kino se lo pregunta:ready: falsese salta la ronda (sin falla, sin espera creciente, los cambios pendientes se conservan) y Kino vuelve a preguntar un periodo de lectura después, cuando la persona abre la pantalla o justo después de que guarda tus ajustes. Sin el export, está listo. UnsyncStatusque lanzaauth_requiredtambién quiere decir que no está listo; cualquier otra falla suya muestra el proveedor como no listo pero deja correr la ronda, que falla por su cuenta. Nunca descargues el blob ahí: una petición liviana como mucho.- Tiempo:
syncPullysyncPush60 s cada una,syncStatus15 s. Corren en segundo plano: nadie espera en pantalla, y sus tiempos agotados nunca marcan tu plugin como "No responde". Todas las reglas dekino.fetch, de los hosts y del motor valen como en cualquier otra llamada, salvo los topes de tamaño de abajo. - Errores: usa los códigos de
kino.errorde siempre;conflictes el propio. UnuserMessagesigue las reglas de siempre, así que una frase que nombra un token o una marca de la lista bloqueada (Telegram, por ejemplo) se muestra como la línea de Kino. - Las formas en TypeScript son
KinoSyncPullFn,KinoSyncPushFn,KinoSyncStatusFn,KinoSyncContextyKinoManifestSync, enkino.d.ts.
El bloque sync del manifiesto¶
Desde apiVersion 12, obligatorio con la capacidad syncProvider y solo con ella (si no, se rechaza
el manifiesto: The "sync" field needs the "syncProvider" capability; un proveedor sin él o sin
keySecret: The "syncProvider" capability needs a "sync" field whose "keySecret" is the key of one of the
plugin's own "password" settings). keySecret y provision son obligatorios; lo demás es opcional:
| Clave | Por defecto | Regla |
|---|---|---|
mode |
"poll" |
"poll" o "realtime" (cada cuánto) |
pullEveryMs |
600000 (10 min) | un número entero positivo; Kino lo sube a 30 s como mínimo |
pushDebounceMs |
300000 (5 min) | un número entero positivo; Kino lo sube a 5 s como mínimo |
maxBlobBytes |
4194304 | el blob más grande que acepta tu servicio, como mucho 4194304 (4 MiB) |
keySecret |
obligatorio | la key de uno de tus ajustes password, que no puede tener default |
provision |
obligatorio | hasta 8 claves distintas de tus ajustes que guardan valor (secretos o no); tiene que incluir keySecret; desde apiVersion 13 puede nombrar una contraseña con "sync": false (de un solo uso), nunca un texto con "sync": false |
generateKey |
false |
apiVersion 13: con true Kino crea él mismo el valor de keySecret (abajo) |
Los mensajes que da Kino con un bloque mal formado (todos en inglés, al instalar):
The "sync" field must be an object with an optional "mode" of "poll" or "realtime" and optional positive whole numbers "pullEveryMs", "pushDebounceMs" and "maxBlobBytes" (at most 4194304)The "keySecret" of the "sync" field must be the key of one of the plugin's own "password" settingsThe setting the "keySecret" of the "sync" field names must not have a "default"The "provision" of the "sync" field must be a list of at most 8 different keys of the plugin's own settings that hold a valueThe "provision" of the "sync" field must include its "keySecret"The "keySecret" of the "sync" field can't name a setting with "sync": false(apiVersion 13)The "provision" of the "sync" field can't name a text setting with "sync": false(apiVersion 13)The "generateKey" of the "sync" field must be true or false(apiVersion 13)
keySecret tiene que ser un token largo y aleatorio (el token de un bot, una API key, un token
que imprime tu servidor), nunca una contraseña que escoge una persona: quien consiga un blob guardado
puede probar adivinanzas sin conexión. Mientras la persona no lo escriba, Kino no corre ninguna ronda
(la tarjeta nombra el ajuste por su etiqueta, "Falta «Clave de sincronización»: ve a Configurar"; una
etiqueta con "token" dice "Falta el token"). Cambiar su valor cambia la llave: la copia
remota ya no abre ("El token no coincide o los datos guardados no son de Kino", con "Corregir el token" y
"Restablecer sincronización") hasta que la persona corrige el token o restablece la sincronización en un
aparato. Todos los demás aparatos también necesitan el valor nuevo ("Enviar configuración", o escrito).
provision nombra lo que "Enviar configuración" le pasa a un segundo aparato (abajo).
Nombra todo lo que el segundo aparato necesita para correr el mismo proveedor (en Telegram, el token del
bot y el id del chat), y nada que no necesite.
Una llave que crea Kino (generateKey, apiVersion 13)¶
Un proveedor cuyo servicio no da un secreto compartido propio (la propia cuenta de la persona, no el token
de un bot) declara "generateKey": true. Kino crea entonces él mismo el valor de keySecret: 32 bytes
aleatorios de un SecureRandom, como 64 caracteres hexadecimales en minúscula, solo mientras ese ajuste
está vacío y en dos momentos: cuando la persona enciende el proveedor y cuando toca "Enviar configuración"
(la llave se crea antes de leer los valores, así que una llave vacía nunca esconde ese botón: aparece en
cuanto tus otros ajustes de provision tienen valor). Se guarda igual que una contraseña escrita (sellada,
sincronizada de punta a punta, por perfil), nunca se registra y nunca se dibuja en tu formulario en ningún
aparato. Un valor que ya existe, escrito o recibido, nunca se reemplaza; un valor recibido de otro aparato
siempre reemplaza a uno creado. Tu plugin no necesita una acción "Crear clave". Por debajo de apiVersion 13
la clave se ignora.
"sync": { "keySecret": "syncKey", "generateKey": true, "provision": ["syncKey", "api_id", "api_hash"] }
Las versiones anteriores de Kino rechazan apiVersion 12 ("Este plugin necesita una versión más nueva
de Kino").
Cuándo corren las rondas¶
Una ronda es traer, combinar y enviar. Con mode: "poll" Kino corre una:
- cuando la app pasa al frente, y después cada
pullEveryMsmientras siga ahí; pushDebounceMsdespués del último cambio local (una ráfaga de cambios es un solo envío), y nunca antes de ese tiempo desde la ronda anterior; al pasar a segundo plano, un envío pendiente sale de una vez;- para la posición de reproducción, cuando la reproducción se detiene o la app pasa a segundo plano, nunca mientras avanza;
- cuando la persona toca "Sincronizar ahora".
pullEveryMs es solo el valor de partida: la tarjeta de cada proveedor en Sincronización ▸ Proveedor tiene
"Sincronizar cada" (1, 5, 10, 30 o 60 minutos, empezando por tu valor redondeado al más cercano), elegido
en cada aparato y nunca sincronizado. A tu plugin no se le avisa y no necesita nada para eso; la espera
antes de enviar sigue siendo la tuya.
Hay como mucho 60 rondas en cualquier hora, pida quien pida. Una ronda que falla espera el intervalo de lectura multiplicado por dos por cada falla seguida (hasta 30 minutos); los cambios que llevaba siguen pendientes.
mode: "realtime" conserva todo eso y agrega un aviso: cuando tu código se entera de que otro
aparato guardó una copia nueva, llama a kino.sync.remoteChanged() y Kino la trae
de una vez. Kino acepta como mucho un aviso cada 30 segundos y descarta uno que llega durante una
lectura. Tu código solo corre mientras Kino lo llama (no hay conexión abierta entre llamadas), así que el
lugar para notar un cambio es syncStatus, no syncPull.
Límites de tamaño¶
- El blob mide como mucho
sync.maxBlobBytes(4 MiB como máximo) decodificado. Kino rechaza uno más grande en las dos direcciones: una copia más grande que tu límite se rechaza antes de llegarte ("tus datos superan el tamaño que admite el proveedor"), y un blob traído que lo supera no se aplica. - Solo dentro de
syncPullysyncPush, una petición dekino.fetch(su JSON, con el cuerpo en base64) y el cuerpo de una respuesta pueden llegar a ceil(maxBlobBytes× 4/3) + 64 KB en vez de 1 MB y 5 MB, y lo mismo el resultado de la llamada, para que el blob en base64 quepa en una sola petición. Todas las demás llamadas del plugin siguen con los topes de siempre; los hosts, los cupos, las redirecciones y los tiempos no cambian. - Por qué 4 MiB: el blob cruza el motor como texto en base64 varias veces. Con 4 MiB un proveedor necesita de 25 a 30 MB de los 64 MB de memoria del motor del plugin, así que mantén pequeños tus propios datos mientras corren esas llamadas y nunca hagas copias extra del blob (mira cómo Sync-Gram arma un cuerpo multipart sin decodificarlo).
- Declara lo que tu servicio de verdad acepta: un
maxBlobBytesmás pequeño también mantiene pequeños los topes ampliados.
Pasar los ajustes a otro aparato¶
La persona configura el proveedor en un aparato (el primero nunca necesita un QR). Para el segundo, Kino
lleva los ajustes que tu manifiesto nombra en sync.provision, cifrados de punta a punta de un Kino al
otro (con una llave que el aparato que recibe hace solo para esa sesión):
- En el segundo aparato (por ejemplo, la TV): la tarjeta del proveedor ▸ "Recibir configuración". Durante 3 minutos muestra un QR, una dirección en la red local y un código de 6 dígitos. Al mismo tiempo intenta abrir una segunda ruta por internet ("Desde otra red (por internet)", un túnel rápido de Cloudflare); cuando abre, la pantalla también muestra unas palabras unidas por guiones (el nombre del túnel). El QR espera al túnel como mucho unos segundos y, si no, muestra solo la red local.
- En el primer aparato: la misma tarjeta ▸ "Enviar configuración". Lee el QR, que lista primero las
direcciones de la red local y después
https://<palabras>.trycloudflare.com/t/<token>; el celular prueba primero las direcciones locales y después el túnel. Sin cámara, o con la cámara rechazada, pasa a "Escribir dirección": "Misma red" (la persona escribe solo el último número de la dirección) u "Otra red" (solo las palabras; Kino ponehttps://y.trycloudflare.com), más el código de 6 dígitos. El celular acepta solo esas dos formas, así que un error al escribir no puede mandar los ajustes a otro lado. - El segundo aparato pregunta "Recibido para <plugin>: ¿aplicar?" y lista los ajustes por sus
etiquetas, nunca valores secretos (un ajuste
urlmuestra su dirección, con un aviso cuando está en la red local). Solo Aplicar los guarda.
Qué protege la ruta por internet, sin rodeos. Las palabras del túnel son públicas: las ven la
pantalla de la TV, la consulta DNS y el nombre TLS del aparato que envía, y Cloudflare. La ruta
/t/<token> del QR es solo una defensa extra (la ruta escrita llega a la misma sesión sin ella). La
verdadera puerta, en todas las rutas, es el código de 6 dígitos (más, en una ruta escrita, la llave del
receptor enmascarada con ese código), con 5 intentos en total, de los cuales como mucho 3 pueden llegar
por el túnel (después del tercero se cierra solo el túnel y la red local conserva sus intentos), un solo
mensaje válido, 3 minutos de vida, un tope de 40 peticiones en el túnel y el "¿aplicar?" de la
persona. El transporte nunca es de confianza. El riesgo que queda es una denegación de servicio: quien
tenga las palabras puede gastar los intentos del túnel y cerrar esa ruta.
Sobre el túnel. Es la biblioteca
cloudflare-quick-tunnel-kotlin del dueño,
incluida en la app y cargada solo cuando se abre una pantalla para recibir. Usa TCP 7844 (TLS 1.3 + HTTP/2)
hacia el borde de Cloudflare, sin QUIC; le pide un túnel a api.trycloudflare.com y encuentra el borde con
DNS públicos (1.1.1.1, 1.0.0.1, 8.8.8.8). Los túneles rápidos de Cloudflare son anónimos y están pensados
para pruebas y desarrollo: no tienen garantía de disponibilidad, pueden estar limitados ("Cloudflare está
limitando las rutas por internet…"), y una red que los bloquea deja solo la ruta local. Tu plugin no tiene
nada que ver con eso.
Lo que eso significa para tu plugin:
- Solo viajan los ajustes de
sync.provision, sellados como los escritos a mano; cualquier otro se rechaza. La llave de sincronización nunca viaja: cada aparato la deriva del mismo token. Los valores recibidos se guardan como los escritos, pero, como con elsetSettingsde una acción, Kino no corre tuvalidateSettingscon ellos. - "Enviar configuración" solo se ofrece cuando este aparato tiene un valor para cada ajuste de
provision, salvo una llave que crea Kino (generateKey: se crea en ese momento) y una contraseña de un solo uso que se queda en el aparato (se deja afuera mientras está vacía). Llena tú mismo los que encuentras (el id de un chat) consetSettings, para que la persona nunca los escriba; desde apiVersion 13setSettingstambién puede llenar una contraseña. - La tarjeta sigue el estado del proveedor. En un aparato que todavía no tiene los valores de
provisionque necesita, tu tarjeta empieza por "Recibir configuración" (con una línea que dice cómo) y "Configurar" queda discreto. En el TV: sin nada recibido, solo "Recibir configuración"; recibido pero sin terminar de configurar (falta la llave, tusyncStatusdice que no está listo o la última ronda pidió configuración), "Configurar" y un "Recibir" discreto; listo, "Sincronizar cada" y un "Recibir" discreto. El TV nunca nombra un ajuste cuando falta la llave: dice que se reciba la configuración desde otro aparato, así que escribe tus propias líneas del TV de la misma forma. - El plugin tiene que estar instalado en el aparato que recibe ("Instala primero <plugin>").
- Sin ninguna ruta, la persona escribe los mismos ajustes en el formulario del segundo aparato, salvo que
tu plugin los dibuje solo en el celular (
devices): entonces el TV los recibe.
Un secreto de un solo uso para el aparato nuevo (apiVersion 13)¶
provision también puede nombrar una contraseña con "sync": false, para un
secreto que el aparato nuevo necesita una vez (una contraseña de verificación en dos pasos, para que el
TV nunca la escriba). Solo va mientras tiene valor en el aparato que envía: vacía (ya usada y borrada), se
deja afuera y nunca frena el resto. La pantalla que envía agrega una línea sencilla que la nombra por su
etiqueta ("También se envía: Contraseña 2FA. En el otro aparato queda solo ahí: no se sincroniza ni entra
en las copias de seguridad."); el aparato que recibe lista solo su etiqueta, nunca el valor, y la guarda
sellada y solo en ese aparato, igual que si se hubiera escrito ahí: nunca se sincroniza, nunca va en una
copia de seguridad. Tu plugin la borra él mismo una vez usada (el clearSettings de una acción). Nunca la
uses para un secreto duradero, ni como keySecret (se rechaza). Un texto con "sync": false (un número
de teléfono que se queda en el aparato) nunca puede ir en provision.
Ajustes, perfiles y lo que lee la persona¶
- Configurar, en la tarjeta del proveedor, abre el formulario de ajustes de tu plugin. Usa las
ayudas para configurar: un
helpcorto (qué necesita la persona y dónde lo consigue) y unlinkal lugar donde lo consigue (https://t.me/BotFather, tu guía). Usaaction.linkcuando una acción encuentra a quién vincular ("¿Eres tú, @ana?") ysetSettingspara guardar lo que encontró. Un inicio de sesión por pasos puede esconder lo que el paso actual no necesita con elhidedesettingsStatus(apiVersion 13). - El proveedor es por aparato, pero sus llamadas corren con los ajustes del perfil en uso, los mismos de los que sale la llave derivada. Un perfil sin el token muestra "Este perfil no tiene el token"; dos perfiles con tokens distintos leen la copia del otro como llave equivocada. Dile a la persona que configure el proveedor en el perfil que usa.
- La fila muestra las líneas de Kino ("Sincronizado hace 3 min", "Esperando la primera sincronización",
"Falló la última sincronización: …") y, debajo, el
messagede tusyncStatus, sin tus secretos. Cuando una ronda falla, la persona lee una de las razones de Kino, no el texto de tu error: pon lo que la persona tiene que hacer en elmessagedesyncStatus. - Nunca pongas un token en un error, una línea de estado o un registro. Kino les quita tus secretos guardados a lo que muestra y registra solo el host de cada petición del plugin, pero un valor que armas tú (un texto con forma de token en el error del propio servicio) te toca quitarlo a ti.
Notas de seguridad¶
- El compromiso de
keySecret. Las llaves derivadas hacen fácil un segundo aparato (el mismo token y nada más) a cambio de la confidencialidad frente al plugin y al servicio. Dilo claro en tu descripción y en tu guía; la línea de consentimiento ya lo dice en rojo. - Revocar el token. Si un token se filtra o se pierde un aparato, la persona lo revoca en el
servicio (en Telegram,
/revokeen @BotFather), escribe el nuevo en un aparato y toca "Restablecer sincronización": después de una confirmación, la copia de ese aparato reemplaza a la que ya no se puede leer, cifrada con la llave nueva. Después les pasa el token nuevo a los otros aparatos ("Enviar configuración", o escrito en cada uno). Documenta esos pasos en tu guía. - Restablecer la sincronización reemplaza la copia remota por la de este aparato, con el token que tiene ahora; nunca borra datos del aparato. La confirmación de Kino lo dice: "Se reemplaza la copia guardada en <nombre> por la de este aparato, con el token que tienes ahora. Tus otros aparatos siguen sincronizando si usan el mismo token; si lo cambiaste, pásales el nuevo con «Enviar configuración» o escríbelo en cada uno."
- El servicio puede retener o borrar la copia, y quien tenga el token puede leerla o escribir una nueva. Un blob que no se descifra con la llave del aparato se rechaza, nunca se aplica.
- Hosts.
"hosts"lista lo que alcanza tu código. Un proveedor para un servidor de la persona, en una dirección que no puedes conocer, necesita un ajusteurlo"fetchHosts": "any"(consentimiento en rojo, solohttpspúblico, nunca la red de la casa): Sync Servidor usafetchHostscon un ajustetextque revisa él mismo. - Túneles. Un plugin nunca llega a la red de la casa. Un servidor en el computador de la persona
necesita una dirección
httpspública delante (un túnel de Cloudflare, por ejemplo), y la persona debe saber quién maneja esa dirección.
Probar en local¶
node sdk/validate.mjs .revisa el bloquesyncigual que Kino y muestra la línea de consentimiento (siempre en rojo).sdk/run.mjsno tiene un comando para los exports de sincronización. Pruébalos connode --test, como los ejemplos: carga el plugin conloadPlugin(sdk/sandbox.mjs) ycreateKino(sdk/kino-shim.mjs), córrelo contra una imitación local de tu servicio y revisa cada respuesta concheckSyncAnswer(sdk/contract.mjs). Incluye un blob de 4 MiB en las dos direcciones y un conflicto.- En un aparato: enciende el proveedor, Configurar, una primera ronda, un cambio en cada aparato, un token equivocado, "Restablecer sincronización" y "Enviar configuración" a un segundo aparato.
Los tres proveedores de ejemplo¶
Los tres son repositorios públicos que puedes leer, copiar o usar como plantilla, cada uno con una guía en español y en inglés que una persona puede seguir de principio a fin, y pruebas que no necesitan red.
- Sync-Gram, kinotvapp/kino-plugin-sync-gram
(id
sync-gram; no oficial, sin relación con Telegram): un bot de Telegram que la persona crea con @BotFather. Solo"hosts": ["api.telegram.org"]; la copia es un documento fijado en el chat privado de la persona con el bot (sendDocument,pinChatMessage,getChatpara la versión y para revisar una carrera,getFilepara leerla de vuelta). Muestra un envío multipart porkino.fetchsin decodificar el blob, cómo vincular el chat congetUpdatesyaction.link, el chat confirmado guardado consetSettings, unhelpcorto y unlinka @BotFather, y cada error limpio del token.keySecretes el token del bot yprovisiones["botToken", "chatId"]. Su preparación es"devices": ["phone"]con títulos de sección numerados, y su acción de confirmar eslinkOnly. Es la referencia para un proveedor sobre un servicio de terceros. Está firmado y aparece en los plugins recomendados de Kino desde Kino 0.9.74 (requires: ["syncProvider"], así que un Kino anterior nunca lo muestra). - Sync Servidor, kinotvapp/kino-plugin-sync-server
(id
sync-server): un servidor de Node de un solo archivo y sin dependencias (GET /blob,PUT /blobconIf-Match, un 409 cuando la versión no coincide, un token de portador) y el plugin que habla con él ("fetchHosts": "any",keySecretyprovision, un 409 lanzado comoconflict), al que se llega por un túnel de Cloudflare. Es la referencia para un proveedor sobre el servidor propio de la persona. Kino no lo lista: se instala pegando la dirección de su repositorio,kinotvapp/kino-plugin-sync-server/plugin(firmado), o la de su propio servidor,https://<dirección>/plugin/kino-plugin.json. - Sync-Gram Cuenta, kinotvapp/kino-plugin-sync-gram-account
(id
sync-gram-account, apiVersion 13, Kino 0.9.74 o más nuevo; no oficial, sin relación con Telegram): la propia cuenta de Telegram de la persona, sin bot. La copia es un archivo,kino-sync.bin, fijado y enviado en silencio en sus Mensajes guardados, por la API MTProto de Telegram sobrekino.ws("capabilities": ["syncProvider", "socket", "storageLarge"], solo los cinco hosts*.web.telegram.org). La persona pone su propioapi_idyapi_hashde my.telegram.org. Es la referencia de lo que agrega apiVersion 13:generateKey(sin paso "Crear clave"), una contraseña de dos pasos de un solo uso que va una vez al TV, el número de teléfono como texto con"sync": false, elhidedesettingsStatussegún la etapa del inicio de sesión y un inicio de sesión conqrdibujado solo en el TV. El celular inicia sesión con su número y un código; el TV recibe los ajustes con "Recibir configuración" y después muestra un QR para escanear con Telegram en el celular. Está firmado y Kino no lo lista: se instala pegando la dirección de su repositorio,kinotvapp/kino-plugin-sync-gram-account.