edgepush

web push notifications on webcrypto. zero deps. runs on workers, deno, bun, node and anywhere else crypto.subtle exists.

npm i edgepush

why

the package everyone uses does 6.2M downloads a week, was last published in january 2024, carries five dependencies, and is wired directly to node's crypto and https modules. that means it does not run on cloudflare workers, deno deploy, bun's edge target, or any other runtime without node builtins — which is where a lot of push senders now live.

the whole of web push is four crypto.subtle calls: ecdh on p-256, hkdf, aes-128-gcm, and an es256 jwt. none of it needs node.

use

import { sendNotification, generateVapidKeys } from 'edgepush'

// once, and keep these. the public key goes to the browser
const keys = await generateVapidKeys()

const result = await sendNotification(
  subscription,                       // straight from pushManager.subscribe()
  JSON.stringify({ title: 'hello' }),
  { vapid: { ...keys, subject: 'mailto:[email protected]' } }
)

if (result.expired) await db.deleteSubscription(subscription.endpoint)

expired is the one response you have to act on. a 404 or 410 means the browser has thrown the subscription away and it will never work again, so it is returned rather than thrown — pruning dead subscriptions is normal business, not an error. everything else non-2xx throws a PushError.

bring your own transport

import { buildRequest } from 'edgepush'

const { endpoint, headers, body } = await buildRequest(sub, payload, { vapid })
await myQueue.push({ endpoint, headers, body })

useful when you batch pushes, retry through a queue, or are somewhere global fetch is not what you want to use.

testing your own pipeline

servers do not hold subscription private keys, so this is not part of sending — but it makes an end to end test possible:

import { encryptPayload, decryptPayload } from 'edgepush'

const body = await encryptPayload(sub, 'hello')
const back = await decryptPayload(body, { privateKey, publicKey, auth })
// -> Uint8Array of 'hello'

conformance

the encryption is checked byte for byte against the test vector in rfc 8291 appendix a. that is the whole reason to trust it: given the same salt and the same ephemeral key, this library produces exactly the bytes the specification says it should.

the round trip is then tested the other way, with a fresh random salt and sender key each time, to prove a real browser can read what we send.

35 tests covering:

• the rfc vector, and the rfc vector decrypting back to its plaintext
• fresh salt and ephemeral key per message, asserted by comparing two sends
• a payload ceiling of 3993 bytes, enforced before any crypto runs
• subscription keys rejected when they are the wrong length, the wrong prefix, not base64url, or not actually a point on p-256
• vapid tokens bound to a single push service, capped at 24 hours per rfc 8292, refused when the private key does not match the public key, and refused when the claims have been swapped
• 404/410 handled as expiry, other statuses as failures, with the service response truncated rather than echoed whole
• base64url round tripping at every length, with padding and non-alphabet input handled explicitly

api

• sendNotification(sub, payload, opts) → { status, expired, body }
• buildRequest(sub, payload, opts) → { endpoint, headers, body }
• generateVapidKeys() → { publicKey, privateKey }
• vapidHeader(endpoint, vapid) → the Authorization value
• verifyVapid(header) → the claims, or throws
• encryptPayload(sub, payload) / decryptPayload(body, keys)
• isExpired(status) → boolean
• toB64 / fromB64 — base64url

opts takes ttl, urgency (very-low … high), topic, and fetch.

errors are all PushError with a code: BAD_SUBSCRIPTION, PAYLOAD_TOO_LARGE, BAD_VAPID_KEY, BAD_ENDPOINT, REJECTED.

notes

payloads are capped at 3993 bytes after encryption overhead, for the 4096 byte record size every push service accepts. send an id and let the service worker fetch the rest.

a fresh ephemeral key pair and salt are generated for every message. the salt and senderKey options exist only so the rfc vector can be reproduced in a test — reusing either in production would undo the encryption.

runtime

needs global crypto.subtle, so node 20 or newer (node 18 went end of life in april 2025 and never exposed webcrypto as a global). workers, deno and bun all have it.

license

MIT