Standard library · Web and services

webpush

Sending notifications to browsers from a server, with VAPID keys and the standard encryption.

import webpush

A web push notification is a message a server sends to a user's browser even when the site is not open: a new chat message, a shipped order, a breaking news alert. This package is the server side. It makes the VAPID keys that identify your server, encrypts each message for one browser under RFC 8291 (aes128gcm) so the push service in between never sees its contents, signs the request, and posts it with net.http. The page side is plain JavaScript: a service worker and pushManager.subscribe.

The flow:

  1. Make a key pair once with GenerateKeys and keep it; load it later with KeysFrom.
  2. The page subscribes with the public key and sends you the subscription JSON; store it with the user as a Subscription.
  3. Send messages with Send, and delete a subscription when the result says gone.

Things that catch people out:

  • New keys break every subscription. Each subscription is tied to the public key it was made with.
  • A ttl of 0 is replaced by the 28 day default, so "deliver now or drop it" cannot be expressed; use a short value such as 60 instead.
  • The payload size is not checked. More than 3993 bytes of text is still encrypted and sent, and the push service rejects it, usually with 413.
  • Send waits as long as the push service takes; it has no time limit, so sending to thousands of users one after another can be slow. KeysFrom only checks that both keys are non-empty.

Make the VAPID keys once

The VAPID key pair identifies your server to the push services, and every browser subscription is tied to its public key. If you make new keys at every start, all existing subscriptions stop working. So make them once, keep them somewhere safe, and load them with KeysFrom afterwards. The program keeps them in a file; a real server would more likely read them from its configuration or environment.

webpush-keys-file.salam
import webpush
import os
import str

func load_or_create(path: str): webpush.Keys:
    if os.Exists(path):
        lines := str.Split(os.ReadFile(path), "\n")
        if lines.Len() >= 2:
            ret webpush.KeysFrom(lines.Get(0), lines.Get(1))
        end
    end
    fresh := webpush.GenerateKeys()
    os.WriteFile(path, fresh.public_key + "\n" + fresh.private_key + "\n")
    ret fresh
end

func main:
    path := "vapid-keys.txt"
    first := load_or_create(path)
    second := load_or_create(path)
    println "keys valid:", first.ok, second.ok
    println "same keys on the second start:", first.public_key == second.public_key
    println "public key length:", first.public_key.Len()
    println "uncompressed point (starts with B):", str.StartsWith(first.public_key, "B")
    os.Remove(path)
end
Outputkeys valid: true true same keys on the second start: true public key length: 87 uncompressed point (starts with B): true

The public key is the 87 character text that the page passes as applicationServerKey to pushManager.subscribe. The private key never leaves the server.

Read the subscription the browser sends

After the user allows notifications, pushManager.subscribe() in the page returns a subscription. Its toJSON() form has an endpoint and two keys, p256dh and auth. Send that JSON to your server, read it into a Subscription with encoding.json and store it with the user. Encrypt reports through its ok argument whether the keys are usable, which is a cheap way to reject a broken subscription before you store it.

webpush-subscription.salam
import webpush
import encoding.json
import str

func from_browser(text: str): webpush.Subscription:
    ret webpush.Subscription {
        endpoint = json.Get(text, "endpoint"),
        p256dh = json.GetPath(text, "keys.p256dh"),
        auth = json.GetPath(text, "keys.auth")
    }
end

func main:
    posted := `{"endpoint":"https://fcm.googleapis.com/fcm/send/dQw4w9WgXcQ:APA91b","expirationTime":null,"keys":{"p256dh":"BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4","auth":"BTBZMqHH6r4Tts7J_aSIgg"}}`
    sub := from_browser(posted)
    println "endpoint:", sub.endpoint
    println "push service:", str.StartsWith(sub.endpoint, "https://fcm.googleapis.com/")
    println "p256dh length:", sub.p256dh.Len(), "auth length:", sub.auth.Len()

    mut ok := false
    body := webpush.Encrypt(sub, "{\"title\":\"Welcome\"}", ok)
    println "keys usable:", ok, "encrypted body ready:", body.Len() > 0

    broken := from_browser(`{"endpoint":"https://push.example.net/1","keys":{"p256dh":"abc","auth":"xyz"}}`)
    _ := webpush.Encrypt(broken, "hi", ok)
    println "broken keys usable:", ok
end
Outputendpoint: https://fcm.googleapis.com/fcm/send/dQw4w9WgXcQ:APA91b push service: true p256dh length: 87 auth length: 22 keys usable: true encrypted body ready: true broken keys usable: false

Keep the payload small

A push message carries at most 4096 bytes after encryption, which leaves 3993 bytes for your text. Most services also deliver small messages faster. Send a title, a short body and a link, and let the page fetch anything bigger when the user opens the notification. The program shows how the size grows: the encrypted body adds a fixed header and the padding, and base64url makes it a third longer again.

webpush-payload-size.salam
import webpush
import encoding.json

func payload(title: str, text: str, url: str): str:
    mut members := Vector {} as Vector<str>
    members.Push(json.Member("title", title))
    members.Push(json.Member("body", text))
    members.Push(json.Member("url", url))
    ret json.Object(members)
end

func main:
    sub := webpush.Subscription {
        endpoint = "https://push.example.net/x",
        p256dh = "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4",
        auth = "BTBZMqHH6r4Tts7J_aSIgg"
    }
    small := payload("New reply", "Sara answered your question", "/q/1042")
    println small

    mut ok := false
    each n in [small.Len(), 1000, 3000, 3993]:
        mut text := ""
        until text.Len() < n:
            text += "x"
        end
        sealed := webpush.Encrypt(sub, text, ok)
        println "plain", n, "bytes, sealed and base64url encoded", sealed.Len()
    end
end
Output{"title": "New reply", "body": "Sara answered your question", "url": "/q/1042"} plain 79 bytes, sealed and base64url encoded 243 plain 1000 bytes, sealed and base64url encoded 1471 plain 3000 bytes, sealed and base64url encoded 4138 plain 3993 bytes, sealed and base64url encoded 5462

Send to many users and clean up

To notify everyone, loop over the stored subscriptions and call Send for each one. Look at the Result: ok means the push service accepted the message, gone (HTTP 404 or 410) means the user unsubscribed or the browser dropped the subscription, so delete it; anything else is worth trying again later. ttl says how long the service may hold the message for an offline device, urgency lets a phone save battery on low priority messages, and a message with the same topic replaces an older one that is still waiting.

webpush-broadcast.salam
import webpush

func main:
    keys := webpush.KeysFrom("BLmOwafYGSjiuCX_1RSCO_n0YmacxYMDqitMydKE4A1Wp2qmUuMXg2IM_hzcrmZLun4jEu_lKfVdtnAp0LMK4NE", "Nhh4m4Va4yhL-53i302044iqeAeMtnOEYlIT2KWRJmg")
    if not keys.ok:
        println "the VAPID keys are broken"
        ret 1
    end
    mut subs := Vector {} as Vector<webpush.Subscription>
    subs.Push(webpush.Subscription { endpoint = "https://fcm.googleapis.com/fcm/send/abc", p256dh = "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4", auth = "BTBZMqHH6r4Tts7J_aSIgg" })
    subs.Push(webpush.Subscription { endpoint = "https://updates.push.services.mozilla.com/wpush/v2/def", p256dh = "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4", auth = "BTBZMqHH6r4Tts7J_aSIgg" })

    mut o := webpush.NewOptions("mailto:ops@example.com")
    o.ttl = 3600
    o.urgency = "high"
    o.topic = "deploy"

    mut keep := Vector {} as Vector<webpush.Subscription>
    mut sent := 0
    each s in subs:
        r := webpush.Send(keys, s, `{"title":"Deploy finished","body":"Version 2.4 is live"}`, o)
        if r.ok:
            sent++
            keep.Push(s)
        else r.gone:
            println "dropping", s.endpoint
        else:
            println "will retry", s.endpoint, r.status, r.error
            keep.Push(s)
        end
    end
    println "sent", sent, "of", subs.Len(), "and keeping", keep.Len()
    ret 0
end

This program needs real subscriptions from a browser and network access, so it is only checked here. To try it, replace the sample endpoints with subscriptions taken from your own page.

Types

Keys

struct Keys
The VAPID keys of the server.
NameTypeDescription
public_keystr = ""The public key as url safe base64; this is what you give to applicationServerKey in the page JavaScript.
private_keystr = ""The private key; keep it secret.
okbool = falseThe keys are valid.
webpush-Keys.salam
import webpush
import str

func main:
    fresh := webpush.GenerateKeys()
    println fresh.ok, fresh.public_key.Len(), fresh.private_key.Len()

    k := webpush.KeysFrom("BLmOwafYGSjiuCX_1RSCO_n0YmacxYMDqitMydKE4A1Wp2qmUuMXg2IM_hzcrmZLun4jEu_lKfVdtnAp0LMK4NE", "Nhh4m4Va4yhL-53i302044iqeAeMtnOEYlIT2KWRJmg")
    println k.ok, webpush.KeysFrom("", "").ok
    at := webpush.VapidHeaderAt(k, "https://fcm.googleapis.com", "mailto:ali@example.com", 1700000000)
    println at
    now := webpush.VapidHeader(k, "https://fcm.googleapis.com", "mailto:ali@example.com")
    println str.StartsWith(now, "vapid t="), str.Contains(now, ", k=" + k.public_key)

    mut o := webpush.NewOptions("mailto:ali@example.com")
    println o.subject, o.ttl == webpush.DEFAULT_TTL, o.ttl / 86400
    o.urgency = "high"
    o.topic = "news"
    o.ttl = 3600
    println o.urgency, o.topic, o.ttl
end
Outputtrue 87 43 true false vapid t=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJhdWQiOiJodHRwczovL2ZjbS5nb29nbGVhcGlzLmNvbSIsImV4cCI6MTcwMDA0MzIwMCwic3ViIjoibWFpbHRvOmFsaUBleGFtcGxlLmNvbSJ9.8Sx-V8MK5NDw923EAMtv8NSCJzQMdhQx8E_ItZUuaMU_VVCv0NzyPG0vZ6JfRsu-S6h99PJJFB6_vgd3NGT_Lw, k=BLmOwafYGSjiuCX_1RSCO_n0YmacxYMDqitMydKE4A1Wp2qmUuMXg2IM_hzcrmZLun4jEu_lKfVdtnAp0LMK4NE true true mailto:ali@example.com true 28 high news 3600

Subscription

struct Subscription
The subscription the browser makes with pushManager.subscribe and sends to your server.
NameTypeDescription
endpointstr = ""The address of the browser push service.
p256dhstr = ""The public key of the browser, from the keys part of the subscription.
authstr = ""The authentication secret, from the same part.
webpush-Encrypt.salam
import webpush

func main:
    sub := webpush.Subscription {
        endpoint = "https://push.example.net/x",
        p256dh = "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4",
        auth = "BTBZMqHH6r4Tts7J_aSIgg"
    }
    mut good := false
    body := webpush.EncryptWith(sub, "When I grow up, I want to be a watermelon", "yfWPiYE-n46HLnH0KqZOF1fJJU3MYrct3AELtAQ-oRw", "DGv6ra1nlYgDCS1FRnbzlw", good)
    println good
    println body

    one := webpush.Encrypt(sub, "hello", good)
    two := webpush.Encrypt(sub, "hello", good)
    println good, one != two, one.Len() == two.Len()
end
Outputtrue DGv6ra1nlYgDCS1FRnbzlwAAEABBBP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIgDll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A_yl95bQpu6cVPTpK4Mqgkf1CXztLVBSt2Ks3oZwbuwXPXLWyouBWLVWGNWQexSgSxsj_Qulcy4a-fN true true true

Options

struct Options
The send options.
NameTypeDescription
subjectstr = ""Your contact address, as a mailto: or a web address; the services require it.
ttlint = 2419200How many seconds the service should hold the message for a browser that is off. 0 or less sends the 28 day default.
urgencystr = ""The urgency: very-low, low, normal or high; empty sends no header, which services treat as normal. The value is not checked.
topicstr = ""The topic; a new message with the same topic replaces an earlier undelivered one.

The example for this item is shown with the ones above: webpush-Keys.salam

Result

struct Result
The result of the send.
NameTypeDescription
okbool = falseThe service accepted the message.
statusint = 0The HTTP status code of the service.
gonebool = falseThe subscription is no longer valid (404 or 410); delete it from your database.
errorstr = ""Why the send failed: a network error, or the body of the service's answer when it is short.
webpush-Send.salam
import webpush

func main:
    k := webpush.KeysFrom("BLmOwafYGSjiuCX_1RSCO_n0YmacxYMDqitMydKE4A1Wp2qmUuMXg2IM_hzcrmZLun4jEu_lKfVdtnAp0LMK4NE", "Nhh4m4Va4yhL-53i302044iqeAeMtnOEYlIT2KWRJmg")
    sub := webpush.Subscription {
        endpoint = "https://fcm.googleapis.com/fcm/send/abc",
        p256dh = "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4",
        auth = "BTBZMqHH6r4Tts7J_aSIgg"
    }
    o := webpush.NewOptions("mailto:ali@example.com")
    r := webpush.Send(k, sub, `{"title":"hello","body":"you have a new message"}`, o)
    if r.ok:
        println "sent", r.status
    else r.gone:
        println "the subscription has expired; delete it"
    else:
        println "error:", r.status, r.error
    end
end

Constants and variables

DEFAULT_TTL

const DEFAULT_TTL: i32 = 2419200
How long the push service keeps a message by default: 28 days, in seconds.

The example for this item is shown with the ones above: webpush-Keys.salam

Functions

GenerateKeys

func GenerateKeys(): Keys
Makes a fresh VAPID key pair; make it once and keep it, because the subscriptions are tied to the public key.

The example for this item is shown with the ones above: webpush-Keys.salam

VapidHeaderAt

func VapidHeaderAt(keys: Keys, audience: str, subject: str, epoch_seconds: i64): str
The Authorization header for the service at the given address, at the given time in Unix seconds. The signature is deterministic, so the same input gives the same output.

The example for this item is shown with the ones above: webpush-Keys.salam

VapidHeader

func VapidHeader(keys: Keys, audience: str, subject: str): str
The same, at the current time.

The example for this item is shown with the ones above: webpush-Keys.salam

EncryptWith

func EncryptWith(sub: Subscription, payload: str, as_private: str, salt: str, ok &: bool): str
Encrypts the message with the given key and salt under RFC 8291; for testing against the standard vectors. In real work use Encrypt.

The example for this item is shown with the ones above: webpush-Encrypt.salam

Encrypt

func Encrypt(sub: Subscription, payload: str, ok &: bool): str
Encrypts the message for this subscription; with a fresh key and salt every time, so two outputs are never the same.

The example for this item is shown with the ones above: webpush-Encrypt.salam

Send

func Send(keys: Keys, sub: Subscription, payload: str, opts: Options): Result
Encrypts the message and sends it to the browser push service with the VAPID header, which is valid for 12 hours. An empty message is a push with no body. There is no time limit and no check of the payload size.

The example for this item is shown with the ones above: webpush-Send.salam

NewOptions

func NewOptions(subject: str): Options
The default options with a contact address.

The example for this item is shown with the ones above: webpush-Keys.salam

KeysFrom

func KeysFrom(public_key: str, private_key: str): Keys
Returns stored keys; ok is false when either one is empty. The keys themselves are not checked until the first Send.

The example for this item is shown with the ones above: webpush-Keys.salam