[MMMikeM]

Summary

Hardens input validation and error handling across the send path: rejects invalid timeoutMs, ttl, and vapidExpiration before any network request, validates VAPID and subscription keys early to avoid wasted ECDSA signatures, caps push service response bodies to 4 KB to prevent unbounded buffering, and re-signs VAPID tokens at half their lifetime in batch sends to avoid expiry mid-batch.

Key changes

• Input validation moved upfront. timeoutMs must be a whole number from 1 to 2^31 − 1 (the ceiling AbortSignal.timeout honors); ttl must be a whole number of seconds ≥ 0; vapidExpiration rejects NaN. All three are checked once per send before any network I/O, rather than per-subscription or on the wire.

• Subscription key decoding separated from encryption. New decodeSubscriptionKeys() validates p256dh and auth once per send before the VAPID JWT signature, avoiding wasted ECDSA work on bad input. encryptPayload() now takes pre-decoded keys and a SubscriptionKeyBytes struct.

• VAPID public key validation extracted. New decodeVapidPublicKey() in encoding.ts checks that a key is a 65-byte uncompressed P-256 point, with consistent error messages across subscribe(), createVapidJwt(), and the send path. Catches malformed keys (unset env vars, quoted strings, private keys by mistake) before the permission prompt or any subscription is touched.

• Response body capped at 4 KB. New readBodyPrefix() reads push service responses in chunks and cancels the stream once 4 KB is reached, preventing hostile endpoints from streaming unbounded bodies into memory. WebPushError.body now documents this limit.

• VAPID tokens re-signed at half their lifetime in batch sends. The JWT cache now tracks expiry and re-signs when half the lifetime has elapsed, so a batch that outlasts vapidExpiration never sends an expired token. Fixes 401/403 fills in failed on long batches.

• subscribe() returns replacedEndpoint on key rotation. When a stale-key subscription is unsubscribed and replaced, its endpoint is returned so the server can delete that record immediately, rather than waiting for a send to report it gone.

• subscribe() validates the VAPID key before the permission prompt. A malformed key no longer unsubscribes a working subscription as a "rotation"; the key is checked first and throws if invalid.

• Null rows in sendPushBatch land in failed instead of rejecting the batch. The error handler now safely handles null rows with an empty endpoint.

• Per-message ECDH key pair is non-extractable. Only the public half is exported; private keys stay locked in the HSM.

• New encoding.ts module. Centralizes base64url codec and P-256 key decoders, re-exported from vapid.ts for the public API.

Implementation notes

• assertValidSendOptions() consolidates validation of topic, ttl, and timeoutMs into one call, reducing duplication between sendPushNotification() and sendPushBatch().
• MAX_TIMEOUT_MS = 2^31 − 1 is documented as the ceiling both Node and browsers enforce for AbortSignal.timeout().
• The JWT cache in sendPushBatch() now stores { jwt: Promise<string>; refreshAt: number } tuples to track expiry per origin.
• readBodyPrefix() uses a TextDecoder stream to handle multi-byte UTF-8 sequences correctly at the 4 KB boundary.

https://claude.ai/code/session_01DWSBBC6tKja4b8eyAVN38V

[MMMikeM]

Superseded: the branch predates 1.4.0 and conflicts, so its changes were reworked onto the 1.4 line instead of merged.

• Done separately in 1.4.0: the VAPID key check before subscribe touches an existing subscription, a plain Error for a malformed subscription, and rejecting a NaN vapidExpiration.
• Ported in 1.4.1 (167f25f): batch VAPID tokens re-signed at half their lifetime, response bodies capped at 4 KB, the non-extractable ECDH key, null batch rows landing in failed, and timeoutMs/ttl checks. Fractional values are rounded rather than rejected, to keep it a patch release.
• Not taken: replacedEndpoint, which is new API and may come in a minor release, and the encoding.ts refactor.