Frontend

Tu app en el teléfono (PWA)

Un sitio Synsema se instala en un teléfono o en un escritorio como una app: un ícono en la pantalla de inicio, pantalla completa sin el chrome del navegador, una shell que abre sin red, y notificaciones push — con nada más que la web que el servidor ya renderiza. Sin cliente nativo, sin tienda, sin framework. El cliente es el navegador que el usuario ya tiene; el backend, los agentes y los secretos se quedan en el servidor, que es donde van.

synsema init --pwa miapp && cd miapp
synsema serve app.syn            # http://localhost:8080 — Chrome y Edge la instalan desde localhost

Apretá Run para la parte doctesteada — el par VAPID nace sellado, la clave privada sólo se acepta como secret, y el envío se rechaza antes de abrir ningún socket si no declaraste el push service:

-- Doc example: Web Push (installable apps). The VAPID pair is born SEALED, the private
-- key is accepted only as a secret, and delivering is refused before any socket opens
-- unless the push service's host was declared (deny-by-default). Runs anywhere: no
-- network is touched.
intent: "doc example: web push — VAPID keys + the gates"
require random                     -- push_vapid_keys() creates new secret material
require net("127.0.0.1")           -- a loopback mock endpoint: the option checks below run before any send

let keys be push_vapid_keys()      -- {public: text, private: secret}
print("public key: " + text(length(keys["public"])) + " chars · private: " + text(keys["private"]))

task subscription()
    -- the shape the browser gives you: PushSubscription.toJSON() (keys from RFC 8291 here)
    give {"endpoint": "https://web.push.apple.com/QAbc123", "keys": {"p256dh": "BP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIgDll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A8", "auth": "BTBZMqHH6r4Tts7J_aSIgg"}}

task send_without_net()
    -- no `require net("web.push.apple.com")` → refused at the capability check
    give push_send(subscription(), {"title": "hi"}, {"vapid": {"public": keys["public"], "private": keys["private"], "subject": "mailto:ops@example.com"}})

task send_with_a_plain_text_key()
    -- a private key as plain text is never accepted (doctrine: private keys are secrets)
    give push_send(subscription(), "hi", {"vapid": {"public": keys["public"], "private": "not-a-secret", "subject": "mailto:ops@example.com"}})

test "the pair: a base64url public key and a SEALED private key"
    assert_eq(length(keys["public"]), 87)                        -- 65-byte uncompressed P-256 point
    assert_eq(text(keys["private"]), "secret(vapid_private)")    -- redacted wherever it goes

test "delivering needs net(<push service host>) — refused before any socket opens"
    assert_error(send_without_net)

test "the VAPID private key is only accepted as a secret"
    assert_error(send_with_a_plain_text_key)

-- Every option is checked BEFORE anything is encrypted or sent. The endpoint is a closed
-- loopback port, so an accepted call ends in "could not reach the push service".
let mock be {"endpoint": "http://127.0.0.1:9/push", "keys": subscription()["keys"]}
let vapid be {"public": keys["public"], "private": keys["private"], "subject": "mailto:ops@example.com"}

task send_error(payload, opts)
    try
        push_send(mock, payload, opts)
        give "sent"
    recover err
        give err

test "opts: vapid is required, and its subject is mailto: or https://"
    assert(contains(send_error("hi", {}), "opts.vapid is required"))
    assert(contains(send_error("hi", {"vapid": merge(vapid, {"subject": "ops@example.com"})}), "must be a mailto: address or an https:// URL"))
    let other be push_vapid_keys()
    assert(contains(send_error("hi", {"vapid": merge(vapid, {"public": other["public"]})}), "does not match opts.vapid.private"))

test "opts: ttl, urgency, topic, timeout — and nothing else"
    assert(contains(send_error("hi", {"vapid": vapid, "ttl": -1}), "opts.ttl must be an integer"))
    assert(contains(send_error("hi", {"vapid": vapid, "urgency": "urgent"}), "very-low, low, normal, high"))
    assert(contains(send_error("hi", {"vapid": vapid, "topic": "bad topic!"}), "1-32 URL-safe characters"))
    assert(contains(send_error("hi", {"vapid": vapid, "timeout": 0}), "opts.timeout must be an integer"))
    assert(contains(send_error("hi", {"vapid": vapid, "bogus": 1}), "valid options are: vapid, ttl, urgency, topic, timeout"))
    let ok be {"vapid": vapid, "ttl": 3600, "urgency": "high", "topic": "order-1042", "timeout": 2}
    assert(contains(send_error("hi", ok), "could not reach the push service"))       -- all accepted

test "payload: text, a map, bytes or nothing — at most 3993 bytes"
    assert(contains(send_error({"title": "t", "body": "b", "url": "/"}, {"vapid": vapid}), "could not reach"))
    assert(contains(send_error(bytes("raw", "utf8"), {"vapid": vapid}), "could not reach"))
    assert(contains(send_error(nothing, {"vapid": vapid}), "could not reach"))
    let big be join(apply((i) => "x", range(3994)), "")
    assert(contains(send_error(big, {"vapid": vapid}), "at most 3993"))
    assert(contains(send_error(as_secret("s"), {"vapid": vapid}), "the payload cannot be a secret"))

Qué escribe synsema init --pwa (engine v0.6.15+)§

Todo lo demás que escribe init (.env.example, .gitignore, .mcp.json) viene también; hello.syn no — el starter es app.syn. Volver a correrlo es seguro: un archivo que editaste se conserva y la versión de fábrica queda al lado como <archivo>.new. --pwa y --synfide son starters distintos — elegí uno (exit 2 con los dos).

Las piezas, para sumarlas a una app que ya existe§

1. Montá public/ en la raíz — el service worker tiene que servirse desde /sw.js para controlar todo el origen:

require serve(8080)
require file.read("index.html")            -- render() reads the page from disk (engine v0.6.14+)
require file.read("./public/**")           -- static serves that folder: reading it (engine v0.6.45+)

serve on 8080
    static "/" from "./public" cache "1h"
    route "GET /"
        give render("index.html", {"title": "My app"})

.webmanifest se sirve como application/manifest+json (pinneado — el navegador rechaza el manifest con cualquier otro tipo). Las rutas declaradas ganan sobre el estático, así que / sigue siendo tuya. Sin la línea de ./public/ el server no arranca (… add require file.read("public/")); en un binario de synsema build el public/ empaquetado no necesita nada y se sirve solo desde el bundle.

2. El <head> de tu layout necesita las líneas del scaffold: <link rel="manifest" href="/manifest.webmanifest">, <meta name="theme-color">, <link rel="apple-touch-icon" href="/apple-touch-icon.png">, <meta name="mobile-web-app-capable" content="yes"> y su gemelo apple- (sin ellos iOS no abre a pantalla completa ni usa tu ícono), viewport-fit=cover.

3. HTTPS en producción: synsema serve app.syn --domain app.example.com --tls-auto vos@example.com (Deploy). localhost y 127.0.0.1 cuentan como seguros, así que desarrollar no necesita nada. iOS exige un certificado confiable para el service worker y la instalación.

4. Push es opcional — la app funciona sin claves; la página sólo dice que push no está configurado.

Dónde se instala, con honestidad§

Firefox de escritorio no tiene instalación ni modo app: el sitio funciona como sitio.

Un offline que dice la verdad§

El sw.js del scaffold cachea la shell (/, /app.js, el manifest, el ícono) y deja el API en red: sin conectividad /api/ responde 503 {"error": "offline"} y la página lo dice. Nunca cachea una respuesta que no sea OK, así que una falla jamás se repite como dato. Si tu / muestra datos del usuario logueado, sacala de la lista de la shell y cacheá una página pública de "estás sin conexión"* — el caché es del navegador, no de un usuario.

Dos cosas que el scaffold decide por vos, y por qué: la shell es stale-while-revalidate (la copia cacheada responde al instante, la red la refresca para la próxima apertura — así un cambio en app.js o / aparece una apertura después; subí CACHE en sw.js cuando lo necesites ya, el activate borra el caché viejo). Y una notificación tocada enfoca la ventana que ya está abierta y le avisa (postMessage({type: "notificationclick", url})) en vez de abrir una segunda instancia sin estado; sólo si no hay ninguna abre una. Si el SO mató la app, esa ventana nueva arranca de cero — lo que tenga que sobrevivir (un borrador, un filtro, la vista actual) va a localStorage/IndexedDB, no a variables.

Push, de punta a punta§

1. Claves, una vez. synsema run push_keys.syn imprime las tres líneas para .env. El par sale de push_vapid_keys() (necesita require random: crea material secreto). La privada nace sellada — se imprime redactada, por eso el script declara require reveal("vapid_private") y la revela a propósito (auditado). Mismos formatos que web-push generate-vapid-keys.

2. Suscribirse. app.js lee la clave pública de GET /api/push/config, pide permiso, llama pushManager.subscribe({userVisibleOnly: true, applicationServerKey}) y manda PushSubscription.toJSON() — {"endpoint", "keys": {"p256dh", "auth"}} — con POST a /api/push/subscribe. Guardala en una tabla, atada al usuario logueado (requires auth); el scaffold guarda hasta 500 en state_* como demo.

3. Enviar. Una línea por push service que atiendas — deny-by-default, el push service es un host como cualquier otro:

require secret("VAPID_PRIVATE_KEY")
require env("VAPID_PUBLIC_KEY")
require net("fcm.googleapis.com")                  -- Chrome, Android, Brave, Opera …
require net("jmt17.google.com")                    -- … Chrome hands out either FCM domain
require net("*.notify.windows.com")                -- Edge on Windows
require net("updates.push.services.mozilla.com")   -- Firefox
require net("web.push.apple.com")                  -- Safari, iPhone, iPad, Mac
require db                                         -- the subscriptions table (sql_exec below)

let vapid be {"public": env("VAPID_PUBLIC_KEY"), "private": secret("VAPID_PRIVATE_KEY"), "subject": "mailto:ops@example.com"}
let r be push_send(sub, {"title": "Order shipped", "body": "#1042 is on its way", "url": "/orders/1042"},
    {"vapid": vapid, "ttl": 3600, "urgency": "high", "topic": "order-1042"})
when r["gone"]                                     -- 404 / 410: the browser unsubscribed
    sql_exec("DELETE FROM push_subs WHERE endpoint = ?", [sub["endpoint"]])

push_send(subscription, payload, opts) → {status, ok, gone, retry_after, body}:

• payload: texto tal cual · un map/lista → JSON (lo que sw.js lee como {title, body, url}) · bytes · nothing para un "algo cambió" sin cuerpo. Como máximo 3993 bytes — el cuerpo cifrado tiene que quedar bajo los 4096 de los servicios. Un payload secret es error; un secret dentro de un map viaja redactado.
• opts.vapid (obligatorio): public (texto base64url), private (sólo un secret — de secret("VAPID_PRIVATE_KEY"), as_secret(...) o push_vapid_keys(); un texto plano se rechaza, exactamente como la clave privada de sign: quien la tiene manda push a todos los usuarios), subject (mailto: o https://). Una pública que no corresponde a la privada falla acá, no como un 401 opaco del servicio.
• opts.ttl segundos que el servicio guarda un mensaje no entregado (default 86400) · opts.urgency very-low | low | normal | high · opts.topic 1–32 caracteres [A-Za-z0-9_-] (un mensaje más nuevo con el mismo topic reemplaza al pendiente) · opts.timeout segundos (default 30, un entero ≥ 1). Esas cinco son todas las opciones: cualquier otra clave es un error que las enumera. Las opciones, el tamaño del payload y el par de claves se validan antes de cifrar o enviar nada, así que un error nunca cuesta un request (el ejemplo verifica cada una contra un mock en loopback).
• status 201 = aceptado; gone con 404/410 → borrá esa suscripción; retry_after (texto o nothing) con 429/503. El endpoint tiene que ser https:// (http:// sólo en loopback, para mocks). Servicio inalcanzable → error.
• No confundas tus errores con suscripciones muertas. Un error de capability (Capability not granted: net("jmt17.google.com") — un navegador cuyo push service no declaraste) o un servicio inalcanzable es tu configuración o tu red: conservá la suscripción, agregá el host que nombra el error, mandá de nuevo. Descartá una suscripción sólo con gone, o cuando el error nombra subscription (claves o endpoint rotos). El POST /api/push/test del scaffold hace exactamente eso en su recover. Y mantené los hosts exactos: net("*.google.com") abriría egress mucho más allá del push.
• Lo de adentro: RFC 8291/8188 aes128gcm — ECDH P-256 con clave efímera + sal de 16 bytes del CSPRNG del sistema por mensaje, HKDF, AES-128-GCM, un registro de 4096 bytes — y un JWT VAPID ES256 (RFC 8292) con exp de 12 horas. La aleatoriedad interna del protocolo no necesita la capability random, como el handshake TLS. No disponible en el perfil wasm/puro (necesita sockets); push_vapid_keys sí.

¿Ya usás un proveedor? OneSignal, Firebase Cloud Messaging, Pusher Beams y similares siguen funcionando: http_post a su API REST bajo require net(...) con bearer(secret("PROVIDER_KEY")). El push nativo es una opción, no una obligación.

Lo que esto no es§

Las APIs nativas que la web no tiene — Bluetooth, NFC, widgets en la pantalla de inicio, sincronización en segundo plano en iOS — viven en un cliente nativo (Swift, Kotlin, Flutter) que habla con el mismo servidor por el OpenAPI que deriva (Construí un API). Synsema no compila UI nativa, y jamás manda tus secretos a un dispositivo.

Un binario, la app entera (engine v0.6.16+)§

synsema build app.syn -o app --serve --bind 0.0.0.0 --port 8080 --domain app.example.com --tls-auto ops@example.com
./app                                   # el runtime de serve con esos flags horneados; Ctrl-C = shutdown ordenado

--serve construye un binario server: los mounts estáticos del bloque serve (public/) y los templates se empaquetan solos y se sirven desde adentro del archivo, con ETag por contenido — nada que llevar al lado. El bind es obligatorio (un distribuible jamás adivina su interfaz): --bind, o la cláusula bind "…" del bloque (v0.6.18+); los otros flags son los que toma synsema serve, horneados. Mirá CLI § synsema build.

El mismo layout es una app de escritorio (engine v0.6.18+): bind "127.0.0.1", synsema build … --serve --no-console --icon public/icon.svg --bundle, el navegador como ventana de app, el service worker y el manifest haciéndola instalable desde Edge/Chrome en 127.0.0.1 — Tu app en el escritorio.

Probarla en un teléfono real§

El teléfono necesita un origen HTTPS (localhost sólo es seguro en la propia máquina). Tres caminos, del más barato al real:

• Un túnel a tu máquina: cloudflared tunnel --url http://localhost:8080 o ngrok http 8080 te dan una URL HTTPS pública para el synsema serve local — instalar y push funcionan en Android y iOS como en producción. La URL cambia por corrida; las suscripciones mueren con ella.
• Android por USB: adb reverse tcp:8080 tcp:8080 y abrí http://localhost:8080 en el Chrome del teléfono — ahí localhost también es contexto seguro, sin certificado.
• Un VPS con --domain … --tls-auto — lo real; iOS exige un certificado confiable, uno autofirmado no sirve.

Si lo automatizás (Playwright/Puppeteer contra el server local): cerrá el navegador en un finally y matá el synsema serve hijo al terminar — un test que explota deja un Chrome headless huérfano (en Windows buscá chrome.exe con ms-playwright en la línea de comando).

Tiendas, si las querés§

• Google Play: empaquetá la PWA como Trusted Web Activity (PWABuilder o Bubblewrap). Play verifica que sos dueño del origen por /.well-known/assetlinks.json — ponelo bajo public/.well-known/ y el mount estático lo sirve como JSON.
• Microsoft Store: acepta una PWA directa (PWABuilder genera el paquete).
• App Store: necesita un wrapper nativo (PWABuilder → Xcode); ojo que Web Push no funciona dentro de WKWebView — el push de iOS es para la instalación en pantalla de inicio, no para una app envuelta. Esa línea es de Apple, no de Synsema.

Siguiente§

• Frontend — templates, layouts, estáticos.
• Deploy — --domain + --tls-auto, el flag que hace que iOS la instale.
• Secretos — por qué la privada VAPID es un secret, y la auditoría de reveal().