Web Push VAPID from scratch: the complete Web Crypto implementation

You do not need the library. You need Web Crypto.#

Search for how to send a Web Push VAPID message and you land in one of two places. Conceptual explainers name the specs, draw a box labelled "encrypt", and hand the actual bytes to a library. Library READMEs, meanwhile, show you sendNotification and hide the protocol entirely. Both are written for Node, and many still reference the legacy aesgcm content coding that browsers deprecated years ago. As a result, the middle is empty: nobody shows the modern path built by hand.

That empty middle is exactly where you end up the day you move the send path to the edge. The Node web-push library depends on Node's crypto module, so it will not run on Cloudflare Workers, Deno, or Bun's edge surface. When that happens, you need to know what the library was doing for you. After all, you are about to do it yourself with the one crypto API those runtimes all share: Web Crypto. This page is that implementation. Five primitives, no dependencies, runnable in your browser, and portable to any language with an HKDF and an AES-GCM.

The whole Web Push VAPID send path, from scratch#

Before the zoom-ins, hold the shape of the whole thing. Two independent branches feed one request. First, the identity branch signs a VAPID JWT that proves who is sending. Second, the encryption branch turns your plaintext into an aes128gcm body that only the subscriber can read. They then meet at one HTTPS POST, which the push service relays to a service worker on the device.

Every section below is a zoom into one node of this map: the JWT you sign, the three encryption steps, the body you assemble, the POST you send, and the statuses you route. None of them needs a dependency.

VAPID identity: sign the JWT with Web Crypto (no jsonwebtoken)#

VAPID (Voluntary Application Server Identification, RFC 8292) is how a push service knows a message came from you without any account or shared secret. It is a plain ECDSA key pair on the P-256 curve. The public key is your applicationServerKey; the private key signs a short JWT you attach to every send. Getting the JWT right is two parts: the claims you put in, and the signature you produce.

The three claims: aud, exp, sub#

The payload is three claims, and each one maps to a specific failure when it is wrong. Sign this exact JSON, base64url-encoded, as the token payload.

{
  "aud": "https://fcm.googleapis.com",
  "exp": 1720483200,
  "sub": "mailto:push@atyantik.com"
}

aud is the push service origin, scheme and host with no path; a token minted for one push service is rejected by another. exp is Unix seconds, at most 24 hours out, and a stale one is the classic 401. sub is a mailto: or https: contact so the push service can reach you about abuse. None of these is secret; the signature is what makes the token trustworthy.

Signing with ES256, and the raw-vs-DER trap#

ES256 is ECDSA on P-256 with SHA-256. The trap that silently breaks ports is the signature encoding. JWS wants the raw r||s value, 64 bytes. OpenSSL and Node's jsonwebtoken hand back a DER-wrapped ECDSA signature that is around 70 to 72 bytes, and if you drop that into the token unconverted the push service returns 401. crypto.subtle.sign returns the raw form directly, which is one reason the Web Crypto path is less error-prone than the one you are porting from. Sign a token below and toggle the encoding to see the two shapes.

The encryption: aes128gcm from ECDH to AES-GCM (RFC 8291)#

This is the internal the libraries hide most completely, and the strongest reason to read past a quick-start. Web Push payloads are encrypted to the subscriber's keys, so the push service relays bytes it cannot read. The scheme is Message Encryption for Web Push (RFC 8291) using the aes128gcm content coding (RFC 8188). It is three real steps, each runnable on Web Crypto.

ECDH on P-256: the shared secret#

Every message starts with a fresh ephemeral server key pair and an elliptic-curve Diffie-Hellman against the client's p256dh. Both sides can compute the same 32-byte secret without it ever crossing the wire. The ephemeral key per message is what makes the same plaintext encrypt differently every time.

// Import the client public key (p256dh) and generate an ephemeral server pair.
const clientPub = await crypto.subtle.importKey(
  'raw', p256dh,                          // the 65-byte uncompressed point
  { name: 'ECDH', namedCurve: 'P-256' }, false, [],
)
const server = await crypto.subtle.generateKey(
  { name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits'],
)

// The 32-byte ECDH shared secret. The push service holds neither private key,
// so it relays the bytes without ever computing this.
const ecdhSecret = new Uint8Array(
  await crypto.subtle.deriveBits(
    { name: 'ECDH', public: clientPub }, server.privateKey, 256,
  ),
)

HKDF with the exact info strings#

The shared secret is not the key you encrypt with. RFC 8291 runs it through HKDF twice, and the byte-exact info arguments to those HKDF calls are the single detail no competitor prints. Get one byte of an info string wrong and every message fails the recipient's GCM tag check silently, with no error you can see server-side. Step through the derivation and watch the literal strings that produce the content key and the nonce.

AES-128-GCM: encrypt the padded plaintext#

With the content-encryption key and nonce in hand, the encryption itself is one call. RFC 8188 appends a single 0x02 padding delimiter to the plaintext first, then AES-128-GCM produces the ciphertext and a 16-byte authentication tag. GCM is authenticated, so any tampering in transit fails the tag and the browser drops the message before your service worker ever runs.

// cek and nonce come from the HKDF step. RFC 8188 appends a single 0x02
// padding delimiter to the plaintext before encryption.
const key = await crypto.subtle.importKey('raw', cek, 'AES-GCM', false, ['encrypt'])
const record = new Uint8Array([...plaintext, 0x02])

const sealed = new Uint8Array(
  await crypto.subtle.encrypt(
    { name: 'AES-GCM', iv: nonce, tagLength: 128 }, key, record,
  ),
)
// `sealed` is the ciphertext followed by the 16-byte GCM tag, exactly the
// layout the aes128gcm record expects next.

Assemble the body byte by byte (RFC 8188 framing)#

The ciphertext and tag are not the request body on their own. RFC 8188 frames them with a fixed header so the recipient can re-derive the same key and nonce: the salt, a record size, the length and value of the server public key, then the ciphertext and tag. This is the "read it byte for byte" promise made literal. Click any field to inspect its offset, length, and meaning.

The picture also settles the payload budget without a separate meter. Because that framing is fixed overhead on every single message, the practical rule is to send an id, not the object. So push a short notice with an identifier and a URL, then let the opened page or the service worker fetch the full record over a normal request. A push is a doorbell, not a delivery truck.

The POST: RFC 8030 headers and the request on the wire#

Delivery is one HTTPS POST to the subscription endpoint (RFC 8030). The body is the record you just assembled; what carries the real delivery decisions is a handful of headers.

TTL, Urgency, Topic#

Three headers change how and whether a message is delivered. The defaults are rarely what you want, so set them deliberately.

Topic is the one teams discover late. Without it, a user who was offline for an hour comes back to ten stale copies of the same alert. With a shared topic, the push service keeps only the newest undelivered one. Use it for anything that supersedes itself, like a live score or an order status.

The full request, in fetch and raw#

Here is the assembled send with everything above in place, and the raw request it produces on the wire. The fetch version is the whole point of the from-scratch path: it is standard fetch plus Web Crypto, so it runs on every edge runtime without change.

// `body` is the assembled aes128gcm record:
//   salt | rs | idlen | keyid | ciphertext | tag
// `jwt` is the ES256 token you signed; `serverPubB64` is its public key.
const res = await fetch(subscription.endpoint, {
  method: 'POST',
  headers: {
    Authorization: `vapid t=${jwt}, k=${serverPubB64}`,
    'Content-Encoding': 'aes128gcm',
    'Content-Type': 'application/octet-stream',
    TTL: '86400',
    Urgency: 'normal',
    Topic: 'order-4210',
  },
  body,
})

// Everything above is standard fetch plus Web Crypto, so it runs unchanged on
// Cloudflare Workers, Deno, Bun, and the browser. No Node crypto, no library.
route(res.status, subscription)   // the status router from the next section

POST /wp/abcd1234 HTTP/1.1
Host: fcm.googleapis.com
Authorization: vapid t=eyJ0eXAiOiJKV1Qi..., k=BFx...
Content-Encoding: aes128gcm
Content-Type: application/octet-stream
TTL: 86400
Urgency: normal
Topic: order-4210
Content-Length: 189

<binary aes128gcm record: salt | rs | idlen | keyid | ciphertext | tag>

Route every status code, and keep the store healthy#

The send returns a status, and that status is an instruction. Mishandling one is how a working push system slowly rots. The two branches that matter most are opposite reflexes: delete on 410, but never delete on 401. Pick a status the push service returned and see the correct branch and what it does to your subscription store.

The single highest-value line in a push system is the one that deletes on 410. It is also the one most demos never write, because on localhost a subscription never dies. Real subscriptions die constantly and silently: a user clears site data, uninstalls, or the browser expires the endpoint, and it returns 404 or 410 forever after. Delete those and your store stays honest for years. Confuse a 401 for a dead subscription and you delete live subscribers over a token bug you could have fixed.

Receiving: the service worker#

The last two hops run on the device, in the service worker, which can wake with no tab open. That is the whole point of push. It has two events to handle, and both are short.

The push event fires with the decrypted payload; call showNotification inside event.waitUntil, so the browser keeps the worker alive until the notification is shown. Meanwhile the notificationclick handler focuses an already-open tab for the target URL when there is one, and otherwise opens a new window. That small branch is the difference between a notification that feels native and one that reloads a fresh tab every time.

// sw.js runs in the service worker, even with no tab open.
self.addEventListener('push', (event) => {
  const data = event.data?.json() ?? {}
  event.waitUntil(
    self.registration.showNotification(data.title ?? 'New update', {
      body: data.body,
      icon: '/icons/pwa-192.png',
      data: { url: data.url ?? '/' },
    }),
  )
})

self.addEventListener('notificationclick', (event) => {
  event.notification.close()
  const target = event.notification.data?.url ?? '/'
  event.waitUntil(
    clients.matchAll({ type: 'window', includeUncontrolled: true }).then((wins) => {
      const open = wins.find((w) => new URL(w.url).pathname === target)
      return open ? open.focus() : clients.openWindow(target)
    }),
  )
})

Port the five primitives to any language#

The reason to learn the path this way is that it is not tied to JavaScript. Five primitives carry the entire send, and every mainstream language has all five in its standard library or a small, well-known crate. Move the same shape to your backend of choice and the protocol does not change.

The two places a port goes wrong are both in this table. First, the ES256 signature needs converting from DER to raw in every ecosystem except Web Crypto. Second, the HKDF info strings must be byte-identical to the ones the derivation step showed. Get those two right, however, and the rest is plumbing.

When not to build this from scratch#

Understanding the internals is the point of this guide. Shipping the hand-rolled version is a narrower call. If you are already on Node and staying there, the web-push library is well-tested and there is no prize for replacing it. Build it yourself when you have a reason the library cannot serve.

Where to go next#

Web Push sits on top of a service worker, so if you have not shipped one yet, the mechanics of registration, caching, and updates are the companion read: building a real Progressive Web App with React. If the send path runs on the edge, how you render and run a React app on Cloudflare covers the same Workers runtime this backend lives in, and it is how we build on Cloudflare in practice. The key handling and encryption here are one slice of broader application security work, and keeping delivery fast is part of Core Web Vitals and performance.

If you want a second set of hands on a push system that has to survive its ninetieth day, you can hire Node.js developers or React developers from our team, or talk to us about the fit. No pressure and no lock-in: everything above is standard, documented web platform work you own outright, and it is the same approach we use to build and launch a production MVP.