GizStackGizStack
View .mdOpen in ChatGPTOpen in Claude

gizlang/webpush

Web Push: a message to a browser that subscribed, which it shows even with no tab of the site open. The message is encrypted for the browser (RFC 8291, aes128gcm, one record) and the request is signed by the sender's VAPID key (RFC 8292, an ES256 JWT). push sends one and answers the push service's status: 404 and 410 say the subscription is gone.

gizlang
import * as Webpush from "gizlang/webpush";

Types

Vapid

gizlang
type Vapid = { key: bytes; public: bytes; subject: string; }

A sender's VAPID key: the P-256 private scalar, its public point (65 octets, uncompressed) and the contact address the push service may write to (mailto: or https:).

  • key: bytes
  • public: bytes
  • subject: string

Functions

vapid

gizlang
function vapid(key: string, subject: string): Option<Vapid>

The VAPID key of KEY, a base64url P-256 private scalar (32 octets), with SUBJECT; undefined when KEY is none.

Effects: fail, alloc.

sealed

gizlang
function sealed(payload: bytes, ua: bytes, auth: bytes, asKey: bytes, salt: bytes): Option<bytes>

PAYLOAD encrypted for the browser key UA (65 octets) and secret AUTH (16), by the ephemeral key AS_KEY with SALT (16): the whole aes128gcm body. Undefined for a key of another size or a point off the curve.

Effects: fail, alloc.

authorization

gizlang
function authorization(v: Vapid, endpoint: string, now: i64): Option<string>

The VAPID Authorization header value for ENDPOINT at NOW (seconds), valid 12 hours.

Effects: fail, alloc.

push

gizlang
function push(v: Vapid, endpoint: string, p256dh: string, auth: string, payload: bytes): i64 throws string

Sends PAYLOAD from V to the browser at ENDPOINT with its keys P256DH and AUTH (base64url, as the browser's subscription has them), kept by the push service a day: the service's status. Throws when the keys are invalid or the service cannot be reached.

Effects: fail, read, write, console, io, alloc.