Skip to content

About

Web Push for Convex: VAPID notifications with WebCrypto only, durable delivery and subscription pruning.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

19 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@operatornest/convex-web-push

Send VAPID-signed, RFC 8291-encrypted push messages from Convex’s Web API runtime through a durable workpool.

Install

Use Node 24+, convex ^1.46.0 and convex-helpers ^0.1.128.

pnpm add @operatornest/convex-web-push convex convex-helpers@^0.1.128

Configure

Generate a VAPID pair and set the application’s environment variables:

pnpm exec convex-web-push generate-keys --subject '<mailto-address-or-https-url>'
pnpm exec convex env set WEB_PUSH_VAPID_PUBLIC_KEY '<generated-public-key>'
pnpm exec convex env set WEB_PUSH_VAPID_PRIVATE_KEY '<generated-private-key>'
pnpm exec convex env set WEB_PUSH_VAPID_SUBJECT '<mailto-address-or-https-url>'

generate-keys requires --subject and rejects reserved hosts, including localhost, .test, .invalid, .local and the example.com, example.net and example.org documentation domains.

Bind component env by reference in convex/convex.config.ts:

import { defineApp } from "convex/server";
import { v } from "convex/values";
import webPush from "@operatornest/convex-web-push/convex.config";

const app = defineApp({
  env: {
    WEB_PUSH_VAPID_PUBLIC_KEY: v.optional(v.string()),
    WEB_PUSH_VAPID_PRIVATE_KEY: v.optional(v.string()),
    WEB_PUSH_VAPID_SUBJECT: v.optional(v.string()),
    WEB_PUSH_TEST_MODE: v.optional(v.string()),
    WEB_PUSH_MAX_PARALLELISM: v.optional(v.string()),
  },
});
app.use(webPush, {
  env: {
    WEB_PUSH_VAPID_PUBLIC_KEY: app.env.WEB_PUSH_VAPID_PUBLIC_KEY,
    WEB_PUSH_VAPID_PRIVATE_KEY: app.env.WEB_PUSH_VAPID_PRIVATE_KEY,
    WEB_PUSH_VAPID_SUBJECT: app.env.WEB_PUSH_VAPID_SUBJECT,
    WEB_PUSH_TEST_MODE: app.env.WEB_PUSH_TEST_MODE,
    WEB_PUSH_MAX_PARALLELISM: app.env.WEB_PUSH_MAX_PARALLELISM,
  },
});
export default app;
Variable Required Default Valid values
WEB_PUSH_VAPID_PUBLIC_KEY Live registration and sending Unset Base64url P-256 public point, 65 decoded bytes
WEB_PUSH_VAPID_PRIVATE_KEY Live registration and sending Unset Base64url private scalar, 32 decoded bytes, matching the public key
WEB_PUSH_VAPID_SUBJECT Live registration and sending Unset Control-free mailto address or HTTPS contact URI, at most 2048 UTF-16 code units, non-reserved host
WEB_PUSH_TEST_MODE No Unset Exactly true or false; unset means live
WEB_PUSH_MAX_PARALLELISM No 10 Decimal integer 1–200

readConfig parses every supplied component env value. Blank and malformed values raise WEB_PUSH_NOT_CONFIGURED, including in test mode. Missing credentials never enable test mode. Client testMode: true or environment true enables simulation; client false cannot disable an enabled environment. Otherwise operations are live, and a live operation without VAPID configuration raises WEB_PUSH_NOT_CONFIGURED.

VAPID keys have no live/test marker and push services provide no shared sandbox. Test mode makes no push request with any configured pair. Live actions verify that the configured key pair matches before sending.

Quick start

Public application functions must authenticate callers and derive userId from identity.tokenIdentifier. The component trusts application authorization. Send to other users only from authorized application functions.

import { WebPush, pushSubscriptionValidator } from "@operatornest/convex-web-push";
import { v } from "convex/values";
import { components } from "./_generated/api";
import { mutation, query } from "./_generated/server";

const webPush = new WebPush(components.webPush);

export const getConfig = query({
  args: {},
  returns: v.object({ applicationServerKey: v.union(v.string(), v.null()) }),
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not signed in");
    return webPush.config.get(ctx);
  },
});

export const recordSubscription = mutation({
  args: { subscription: pushSubscriptionValidator },
  returns: v.object({ subscriptionId: v.string(), created: v.boolean() }),
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not signed in");
    return webPush.subscriptions.record(ctx, {
      userId: identity.tokenIdentifier,
      subscription: args.subscription,
    });
  },
});

export const notifyMe = mutation({
  args: { title: v.string() },
  returns: v.union(v.string(), v.null()),
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not signed in");
    return webPush.notifications.send(ctx, {
      userId: identity.tokenIdentifier,
      notification: { title: args.title },
      ttlSeconds: 3600,
      urgency: "normal",
    });
  },
});

Subscribe from a button click after signing in:

import { subscribe } from "@operatornest/convex-web-push/browser";
const { applicationServerKey } = await convex.query(api.push.getConfig, {});
if (!applicationServerKey) throw new Error("Push is not configured");
const subscription = await subscribe({ applicationServerKey, serviceWorkerPath: "/sw.js" });
await convex.mutation(api.push.recordSubscription, { subscription });

Concepts

Vocabulary follows the W3C Push API, RFC 8030, RFC 8291 and RFC 8292.

Term Meaning
config Component configuration: the applicationServerKey for browsers and runtime verification without a push request
subscriptions Stored push subscriptions belonging to an application user and test mode
notifications Stored notification payloads and their aggregate delivery progress
deliveries Stored attempts to submit a notification to a subscription’s push service
users Per-user removal of every subscription, notification, delivery and registration generation row the component stores for one test mode
userId Opaque application user identifier, derived from authenticated tokenIdentifier in public wrappers
subscriptionId, notificationId, deliveryId, batchId Component row identifiers; endpoints identify provider subscriptions
endpoint HTTPS push resource URL in a PushSubscriptionJSON, the serialized W3C PushSubscription
expirationTime Push API subscription expiry in Unix milliseconds or null; stored only when known
keys, p256dh, auth Serialized P-256 encryption public key and 16-byte authentication secret
applicationServerKey VAPID public key passed to the browser’s PushManager
VAPID Application server identification using a P-256 signing pair and contact URI
publicKey, privateKey A newly generated VAPID pair returned by generateVapidKeys; deployed private keys are never returned
subject RFC 8292 contact URI bound to WEB_PUSH_VAPID_SUBJECT
pushService Provider inferred from the endpoint: fcm, mozilla, apple, wns or other
userAgent Optional browser description, truncated to 256 UTF-16 code units
notification Display data: title, body, icon, badge, image, url, tag, renotify, requireInteraction, silent, timestamp, actions and data
defaultTitle, defaultIcon, defaultBadge, defaultUrl Service worker fallback display fields and same-origin click destination
title, body Notification heading and message text
icon, badge, image Notification image URLs
url Same-origin destination opened on notification click
tag, renotify Display replacement identifier and whether replacement alerts again
requireInteraction, silent Browser display behavior; neither switches the send operation
timestamp Notifications API display timestamp in Unix milliseconds
actions, action, title, icon Notification buttons with their action identifier, title and optional icon
data Caller data serialized into the notification payload; the service worker shows the notification with data set to { url, extra }, where url is the resolved click destination and extra is the caller data
payload, payloadEncoding UTF-8 message text or canonical base64url bytes for a custom worker
ttlSeconds Explicit lifetime, integer seconds 0–2419200; zero allows one attempt; a live final fraction sends with TTL 0
urgency Explicit RFC 8030 priority: very-low, low, normal or high
topic RFC 8030 replacement identifier, 1–32 URL-safe base64 characters; separate from display tag
idempotencyKey Per-user and test-mode send key; changed arguments raise a conflict
testMode Resolved simulated-provider decision stored as true or false on affected rows; unset in both client and environment means live
allowedPushHosts Up to 16 exact DNS names or wildcard DNS suffixes extending endpoint admission
paginationOpts, page, isDone, continueCursor Convex pagination input and bounded stored history result
numItems, cursor, endCursor, maximumRowsRead, maximumBytesRead Nested Convex pagination fields; server limits override caller row and byte budgets
code, message, retryable, providerCode, errorCode Fixed package error identifier and sentence, safe repetition of a transient provider failure and bounded provider error identifier
onNotificationComplete, onBatchComplete Constructor options referencing internal mutations returning null
WebPushNotificationCompleteArgs Terminal notificationId, userId, testMode, status and delivery counts
WebPushBatchCompleteArgs batchId, testMode, terminal status, total, processed, notificationIds and optional errorCode
counts queued, sent, failed and gone delivery totals
active, paused, gone Subscription states: recording activates, pause pauses, resume activates; expiry, provider 404/410, key rotation or cap retirement makes it gone
activeCount, pausedCount Numbers of active and paused subscriptions returned by subscriptions.getStatus; active means recorded and not paused, so a subscription past its expirationTime counts as active until the next send marks it gone
queued, partial, delivered, failed Notification states: send queues; a settled subset makes it partial; no queued attempts and at least one sent makes it delivered; no sent attempts makes it failed
queued, sending, retry, sent, failed, gone Delivery states: enqueue queues; an eligible attempt sends; retryable failure schedules retry; provider acceptance makes it sent; permanent failure makes it failed; unavailable subscription makes it gone
running, done, failed Batch states: enqueueing starts running; all users processed makes it done; a package error in a continuation step, such as changed configuration or an idempotency conflict, makes it failed after saving the users already enqueued
created, removed, done Registration insertion indicator, first deletion-batch count and enqueueing/deletion completion indicator
total, processed, results, notificationIds Batch audience size, processed count, per-user enqueue results and created notification row IDs
revision, generation Registration versions protecting refreshed subscriptions and later registrations from earlier work
endpointHash, vapidPublicKeyHash SHA-256 endpoint hash stored on subscriptions and on endpoint-restricted notifications, and application server key fingerprint
createdAt, updatedAt, sentAt, lastSuccessAt, lastFailureAt Unix millisecond timestamps for row creation, update, acceptance and subscription health
consecutiveFailures, attempts, subscriptionRevision Attempt health and captured registration revision
providerStatus, retryAfterMs, errorKind, error Provider HTTP status, retry delay in milliseconds, attempt reason from Delivery error kinds and fixed package error data
ok, config, configured, problem, checks, name Verification result, configuration presence, fixed problem and named cryptographic checks
registration, serviceWorkerPath Existing service worker registration or script path; default script /sw.js
granted, denied, default, unsupported Browser permission state after granting, denying, before a decision or without Push API support

The aggregate groups are application records over the Push API subscription and RFC message-delivery concepts. Notifications describe the package’s displayed-message payload; raw messages use notifications.sendRaw.

Idempotency keys are unique per user and test mode. A repeated notifications.send or notifications.sendRaw with the same key and identical payload, encoding, lifetime, urgency, topic, allowed hosts, callback and endpoint returns the original notificationId and sends nothing; changed arguments raise WEB_PUSH_IDEMPOTENCY_CONFLICT. notifications.sendBatch applies the key to each user’s notification: a repeated batch creates a new batch whose results carry the original notificationIds, and the batch callback is not compared. A send that finds no eligible subscription returns null and claims no key. A notification that ends failed releases its key, so a repeated send creates a new notification; partial and delivered notifications keep their key. Only that failure releases a key; callers cannot release one. A key lives as long as its notification row: cleanup deletes terminal notifications after 7 days and unfinished notifications after 35 days.

Delivery error kinds

errorKind is one of DELIVERY_ERROR_KINDS, typed DeliveryErrorKind and validated by deliveryErrorKindValidator. Kinds produced by a provider response store providerStatus.

Kind Meaning
delivery_closed The delivery row is missing or already terminal when an attempt begins
notification_missing The delivery’s notification row no longer exists
subscription_removed The delivery’s subscription row no longer exists
reassigned The subscription now belongs to another user or test mode
subscription_gone The subscription is gone, or the push service answered 404 or 410
subscription_expired The subscription’s expirationTime has passed
subscription_paused The subscription is paused
ttl_expired ttlSeconds elapsed before an attempt, a zero ttlSeconds already had its one attempt, or the next retry would fall after expiry
vapid_not_configured A live attempt found VAPID configuration missing or malformed
vapid_key_mismatch The configured public key differs from the one the notification was enqueued with
invalid_vapid_key The configured private key does not import or does not match the public key
endpoint_not_allowed Endpoint admission rejected the subscription’s endpoint at send time
payload_too_large The payload exceeds the encryption bound, or the push service answered 413
invalid_subscription_keys The subscription’s p256dh or auth key is malformed for encryption
crypto_unsupported A WebCrypto operation needed for encryption or signing failed
timeout The push request was aborted after its time limit
network_error The push request failed without a response
rate_limited The push service answered 429
server_error The push service answered 408 or 5xx
vapid_rejected The push service answered 401 or 403
unexpected_redirect The push service answered 3xx; redirects are never followed
bad_request The push service answered any other non-2xx status
invalid_result The delivery action returned a value that is not a send outcome
action_failed The delivery action threw
canceled The workpool canceled the delivery action
max_attempts Five attempts failed with retryable reasons

Service worker

Copy node_modules/@operatornest/convex-web-push/sw/convex-web-push-sw.js to public/sw.js, or bundle:

import { registerPushHandlers } from "@operatornest/convex-web-push/sw";
registerPushHandlers(self, { defaultIcon: "/icon-192.png", defaultUrl: "/" });

Defaults are title Notification, URL /, with icon and badge unset. The copied worker and registerPushHandlers display and route notifications identically; an empty-string title or URL in the payload is kept, not replaced. To set defaults in the copied worker, edit its DEFAULTS object, which accepts title, icon, badge and url. Push events display notifications. Clicks focus a window already showing the destination; otherwise they navigate an open window and focus it, or open a new window when no window exists, the window cannot navigate or navigation is rejected. The shown notification’s data is { url, extra }. Destinations must share the worker’s origin; external fallbacks resolve to /.

subscribe requests permission, waits up to 10 seconds for worker activation and replaces a subscription when its application server key changes. Browser exports also include isSupported, getPushPermission, getSubscription, unsubscribe, urlBase64ToUint8Array and the types PushSubscriptionJSON, PushPermission, ServiceWorkerScopeOptions and SubscribeOptions. Existing-subscription helpers use the registration covering the page unless a registration or path is supplied. unsubscribe returns the removed endpoint so the app can remove the stored row.

API reference

Construct new WebPush(component, options?). Options are testMode, allowedPushHosts, onNotificationComplete and onBatchComplete. Callback references must target internal mutations returning null and validated with webPushNotificationCompleteArgsValidator or webPushBatchCompleteArgsValidator.

Method Context Arguments Result
subscriptions.record MutationContext userId, subscription, userAgent? subscriptionId and created; refreshes by endpoint and test mode, can reassign a user
subscriptions.remove MutationContext userId, endpoint whether a matching row was removed
subscriptions.removeAll MutationContext userId removed and done; removes earlier generations in bounded steps
config.get QueryContext ctx only applicationServerKey: configured public key, or null in unconfigured test mode
config.verify ActionContext ctx only ok, testMode, config and cryptographic checks; no push request
subscriptions.get QueryContext userId, endpoint subscriptionId, status, pushService, health and timestamps, or null when the endpoint is not the user’s
subscriptions.getStatus QueryContext userId activeCount, pausedCount and lastSuccessAt?
subscriptions.pause MutationContext userId active subscriptions paused
subscriptions.resume MutationContext userId paused subscriptions resumed
notifications.send MutationContext userId, notification, ttlSeconds, urgency, topic?, idempotencyKey?, endpoint? notificationId or null without eligible subscriptions; endpoint restricts fan-out to that subscription
notifications.sendRaw MutationContext userId, payload, ttlSeconds, urgency, topic?, idempotencyKey?, endpoint? notificationId or null; payload is string or Uint8Array
notifications.sendBatch MutationContext userIds, notification, ttlSeconds, urgency, topic?, idempotencyKey? batchId, results and done
notifications.get QueryContext userId, notificationId stored row; NOT_FOUND for a missing row or mismatched user/test mode
notifications.list QueryContext userId, paginationOpts page, isDone and continueCursor, newest first; cursor and endCursor contain at most five values
notifications.getBatch QueryContext batchId status, errorCode?, total, processed and notificationIds, NOT_FOUND for a missing row or mismatched test mode
deliveries.list QueryContext userId, notificationId at most 100 stored attempts, NOT_FOUND for a missing or mismatched notification
users.purge MutationContext userId removed and done; deletes the user’s rows in bounded steps

Methods take (ctx, args), or only ctx when they have no argument fields. Each group calls its same-named component module.

subscriptions.get tells an app whether the current browser’s endpoint is registered to the signed-in user. It returns null for an endpoint registered to another user or test mode, so it never reveals another user’s registration, and it returns no endpoint or keys. A gone subscription is returned with status gone; an expired subscription stays active until the next send marks it gone. notifications.send and notifications.sendRaw with endpoint create deliveries only for that subscription, and return null unless it is active, unexpired and belongs to the user. The notification stores the endpoint only as endpointHash. Context types pick the matching Convex runQuery, runMutation or runAction capability.

generateVapidKeys creates a new pair without a component call. Types include WebPushOptions, SendOptions, PushSubscriptionJSON, PushNotification, VapidKeys, Urgency, PushService, NotificationId, SubscriptionStatus, NotificationStatus, DeliveryStatus, BatchStatus, DeliveryErrorKind, WebPushNotificationCompleteArgs and WebPushBatchCompleteArgs. Validators include pushSubscriptionValidator, deliveryErrorKindValidator, webPushNotificationCompleteArgsValidator and webPushBatchCompleteArgsValidator; DELIVERY_ERROR_KINDS lists every delivery error kind.

A repeated idempotency key returns the original row only when payload, encoding, lifetime, urgency, topic, allowed hosts, callback and endpoint match. Terminal failed notifications release the key. Completion callbacks run in scheduled transactions and do not undo delivery counts when they fail. Batch callbacks run once after enqueueing finishes or fails, including an empty audience; they do not wait for delivery. A package error in the first batch step, raised inside notifications.sendBatch, throws and stores no batch; in a scheduled continuation it fails the batch and keeps the users already enqueued. Keep multi-user batch IDs private from end users.

Errors

Errors are ConvexError values carrying WebPushErrorData: code, one fixed message and optional retryable, providerStatus and providerCode. Only provider and network codes carry retryable. It is true only for a transient failure whose identical repetition cannot create a second provider effect. Push POSTs have no provider-deduplicated key: only HTTP 429 sets retryable to true; network failures, timeouts, HTTP 408 and 5xx set it to false even when the internal schedule retries. Provider codes are bounded to 64 characters. isWebPushError validates the code, exact fixed message and optional details. WEB_PUSH_ERROR_CODES and both error types are exported.

Code Message When
WEB_PUSH_NOT_CONFIGURED Component configuration is missing, malformed or changed during a batch. Missing required or malformed component env, mismatched VAPID pair or changed batch configuration
WEB_PUSH_INVALID_ARGUMENT An argument is missing, malformed or out of bounds. Malformed subscription/payload/topic/cursor/callback handle, cursor with more than five values or out-of-bounds arguments
WEB_PUSH_NOT_FOUND The referenced row does not exist for this user and test mode. Referenced row does not exist for the caller and test mode
WEB_PUSH_IDEMPOTENCY_CONFLICT The idempotency key was reused with different arguments. A repeated send key has changed arguments
WEB_PUSH_PROVIDER_ERROR The push service rejected the message. Push service returned a failing HTTP status
WEB_PUSH_NETWORK_ERROR The request to the push service failed before a response arrived. Push request failed without a response
WEB_PUSH_PAYLOAD_TOO_LARGE The plaintext exceeds 3993 bytes or the encoded input exceeds 5324 UTF-16 code units. Payload exceeds plaintext or encoded bounds
WEB_PUSH_CRYPTO_UNSUPPORTED The runtime cannot complete the required WebCrypto operation. Required WebCrypto operation failed
WEB_PUSH_UNSUPPORTED Web Push is unavailable in this browser. Browser lacks Web Push APIs
WEB_PUSH_PERMISSION_DENIED Notification permission was not granted. Notification permission was not granted
WEB_PUSH_SERVICE_WORKER_FAILED A service worker operation failed; verify its scope and notification options. Worker registration, activation or notification operation failed
WEB_PUSH_BROWSER_FAILED The browser could not complete the push subscription operation. Browser subscription operation failed

Testing

Use new WebPush(component, { testMode: true }) or WEB_PUSH_TEST_MODE=true to simulate acceptance; with neither, operations are live. Every affected row stores the resolved boolean; simulated deliveries omit providerStatus and make no push request. Live deliveries store false. Subscription and history indexes isolate user and test mode.

For convex-test, import register from @operatornest/convex-web-push/test and call it after convexTest(schema, modules). Use fake timers and t.finishAllScheduledFunctions(vi.runAllTimers) to settle work. config.verify never throws for a configuration problem: malformed configuration, a live call without configuration or a configured mismatched key pair returns ok: false with config.configured: false and the WEB_PUSH_NOT_CONFIGURED message in config.problem. It also checks SHA-256, ECDH, the RFC 8291 vector and VAPID sign/verify. Test mode without configuration returns ok: true with config.configured: false. Configuration problems and check errors contain fixed messages.

Limits and retention

Input Limit
Payload plaintext 3993 bytes
Encoded payload input 5324 UTF-16 code units
User ID Nonempty, at most 256 UTF-8 bytes
Idempotency key 1–128 characters from A–Z, a–z, 0–9, _ and -
Endpoint At most 4096 UTF-16 code units
Subscription keys Valid P-256 encryption point and 16-byte auth secret
Subscriptions per user and test mode 50 active plus paused; recording retires the oldest excess
Allowed host pattern At most 253 UTF-8 bytes; no URL, port, whitespace or trailing dot; wildcard suffixes have at least two DNS labels
History page size 1–100 items; server budgets are numItems + 1 rows and 1 MiB, including endCursor requests
History cursor At most 4096 characters; a JSON array of at most five primitive values (three declared index fields plus _creationTime and _id); shorter prefix cursors are valid
Batch user IDs At most 100 supplied IDs before deduplication
Batch step At most 150 subscriptions examined, reserving 50 before another user
Delivery attempts At most 5, within ttlSeconds

An attempt expires when now reaches createdAt + ttlSeconds * 1000. Before that deadline, the outbound TTL rounds the remaining seconds down, including to zero during the final fraction of a second.

Registration stores canonical base64url keys. Removal deletes 100 earlier-generation rows per transaction and preserves later registrations. A removal continuation whose generation is newer than the user’s current registration generation, because users.purge deleted and a later registration recreated the generation row, stops without deleting. A bounded endCursor page can return numItems + 1 rows. Expired batch candidates consume the step budget. Every batch continuation preserves test mode and checks configuration and the public-key fingerprint.

Retries use Retry-After and exponential backoff with jitter. HTTP 408, 429 and 5xx, network failures and timeouts can schedule another attempt independently of error.retryable. Redirects and other failures are permanent; 404/410 retire only the attempted subscription revision. Sent means push service acceptance or simulated acceptance; it does not prove device display. Retries permit repeated delivery. Each push service response body is read up to 4096 bytes and never stored.

Cleanup retains terminal notifications, deliveries and batches for 7 days, removes unfinished work after 35 days and removes gone subscriptions after 7 days. Delivery deletion and cleanup use bounded continuations. Cleanup never deletes subscriptionOwners rows: the table keeps one row per user and test mode, created by the first registration or removal, holding the registration generation counter that lets removal delete only earlier generations.

Purging a user

users.purge removes what the component stores about one user in the client’s resolved test mode, for account deletion. Each transaction deletes at most 100 rows: first the user’s subscriptions from earlier registration generations, then notifications created at or before the purge time together with their deliveries. A step that reaches the bound schedules a continuation and returns done: false. The last step deletes the user’s subscriptionOwners row when no subscription of the user remains. A registration recorded after the purge began survives with its owner row, and so does a notification created after the purge time. A delivery attempt already running finds its row missing and ends without restoring rows; purged notifications never invoke onNotificationComplete. Batch rows keep the user ID in userIds until cleanup deletes the batch.

Security

The deployed VAPID private key is read only through component env and never appears in arguments, stored rows, returns or logs. Endpoint admission runs at registration and send time; only HTTPS on allowed hosts is accepted, with no IP literals, credentials, custom ports or redirects. Encryption uses a fresh ephemeral key and salt per message. Errors retain no provider body, endpoint, payload, key or native exception text.

Public app wrappers authenticate with tokenIdentifier. Subscription revision and user/test-mode checks prevent an old completion from changing a refreshed or reassigned subscription. Rotating the application server key requires browsers to subscribe and record again. iOS Web Push requires an installed web app and a permission gesture. See SECURITY.md for vulnerability reporting.

Development

Use Node 24 and pnpm 12.9.1 through mise. Initialize an anonymous local backend, regenerate bindings and run:

CONVEX_AGENT_MODE=anonymous pnpm exec convex init
pnpm build:codegen
pnpm check
pnpm smoke

Check includes formatting, build, lint, typechecking, unused-export checks, source checks and coverage. Smoke installs a packed package into an isolated anonymous local backend. Neither smoke nor stubbed tests prove live push service or physical browser behavior. See CONTRIBUTING.md and AGENTS.md.

License

MIT; see LICENSE.

About

Web Push for Convex: VAPID notifications with WebCrypto only, durable delivery and subscription pruning.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages