@pushforge/builder 1.1.2 → 2.0.1

package/README.md

@@ -1,198 +1,360 @@
-# PushForge Builder
+<div align="center">
 
-A robust, cross-platform Web Push notification library that handles VAPID authentication and payload encryption following the Web Push Protocol standard.
+<img src="https://raw.githubusercontent.com/draphy/pushforge/master/images/logo.webp" alt="PushForge Logo" width="120" />
 
-## Installation
+# PushForge Builder
 
-Choose your preferred package manager:
+**A lightweight, dependency-free Web Push library built on the standard Web Crypto API.**
 
-```bash
-# NPM
-npm install @pushforge/builder
+[![npm version](https://img.shields.io/npm/v/@pushforge/builder.svg)](https://www.npmjs.com/package/@pushforge/builder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-first--class-blue.svg)](https://www.typescriptlang.org/)
 
-# Yarn
-yarn add @pushforge/builder
+Send push notifications from any JavaScript runtime · Zero dependencies
 
-# pnpm
-pnpm add @pushforge/builder
-```
+[GitHub](https://github.com/draphy/pushforge) · [npm](https://www.npmjs.com/package/@pushforge/builder) · [Report Bug](https://github.com/draphy/pushforge/issues)
 
-## Features
+**[Try the Live Demo →](https://pushforge.draphy.org)**
 
-- 🔑 Compliant VAPID authentication
-- 🔒 Web Push Protocol encryption
-- 🌐 Cross-platform compatibility (Node.js 16+, Browsers, Deno, Bun, Cloudflare Workers)
-- 🧩 TypeScript definitions included
-- 🛠️ Zero dependencies
+</div>
 
-## Getting Started
+---
 
-### Step 1: Generate VAPID Keys
+```bash
+npm install @pushforge/builder
+```
 
-PushForge includes a built-in CLI tool to generate VAPID keys for Web Push Authentication:
+## Live Demo
 
-```bash
-# Generate VAPID keys using npx
-npx @pushforge/builder generate-vapid-keys
+Try PushForge in your browser at **[pushforge.draphy.org](https://pushforge.draphy.org)** — a live test site running on Cloudflare Workers.
 
-# Using yarn
-yarn dlx @pushforge/builder generate-vapid-keys
+- Toggle push notifications on, send a test message, and see it arrive in real time
+- Works across all supported browsers — Chrome, Firefox, Edge, Safari 16+
+- The backend is a single Cloudflare Worker using `buildPushHTTPRequest()` with zero additional dependencies
+- Subscriptions auto-expire after 5 minutes — no permanent data stored
 
-# Using pnpm
-pnpm dlx @pushforge/builder generate-vapid-keys
-```
+## Why PushForge?
 
-This will output a public key and private key that you can use for VAPID authentication:
+| | PushForge | web-push |
+|---|:---:|:---:|
+| Dependencies | **0** | 5+ (with nested deps) |
+| Cloudflare Workers | Yes | [No](https://github.com/web-push-libs/web-push/issues/718) |
+| Vercel Edge | Yes | No |
+| Convex | Yes | No |
+| Deno / Bun | Yes | Limited |
+| TypeScript | First-class | @types package |
 
-```
-┌────────────────────────────────────────────────────────────┐
-│                                                            │
-│ VAPID Keys Generated Successfully                          │
-│                                                            │
-│ Public Key:                                                │
-│ BDd0DtL3qQmnI7-JPwKMuGuFBC7VW9GjKP0qR-4C9Y9lJ2LLWR0pSI... │
-│                                                            │
-│ Private Key (JWK):                                         │
-│ {                                                          │
-│   "alg": "ES256",                                          │
-│   "kty": "EC",                                             │
-│   "crv": "P-256",                                          │
-│   "x": "N3QO0vepCacjv4k_AoyYa4UELtVb0aMo_SpH7gL1j2U",     │
-│   "y": "ZSdiy1kdKUiOGjuoVgMbp4HwmQDz0nhHxPJLbFYh1j8",     │
-│   "d": "8M9F5JCaEsXdTU1OpD4ODq-o5qZQcDmCYS6EHrC1o8E"      │
-│ }                                                          │
-│                                                            │
-│ Store these keys securely. Never expose your private key.  │
-│                                                            │
-└────────────────────────────────────────────────────────────┘
-```
+Traditional web push libraries rely on Node.js-specific APIs (`crypto.createECDH`, `https.request`) that don't work in modern edge runtimes. PushForge uses the standard [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API), making it portable across all JavaScript environments.
 
-**Requirements:**
+## Quick Start
 
-- Node.js 16.0.0 or later
-- The command uses the WebCrypto API which is built-in to Node.js 16+
+### 1. Generate VAPID Keys
 
-### Step 2: Set Up Push Notifications in Your Web Application
+```bash
+npx @pushforge/builder vapid
+```
 
-To implement push notifications in your web application, you'll need to:
+This outputs a public key (for your frontend) and a private key in JWK format (for your server).
 
-1. Use the VAPID public key generated in Step 1
-2. Request notification permission from the user
-3. Subscribe to push notifications using the Push API
-4. Save the subscription information in your backend
+### 2. Subscribe Users (Frontend)
 
-When implementing your service worker, handle push events to display notifications when they arrive:
+Use the VAPID public key to subscribe users to push notifications:
 
-1. Listen for `push` events
-2. Parse the notification data
-3. Display the notification to the user
-4. Handle notification click events
+```javascript
+// In your frontend application
+const registration = await navigator.serviceWorker.ready;
 
-Refer to the [Push API documentation](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) and [Notifications API documentation](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API) for detailed implementation.
+const subscription = await registration.pushManager.subscribe({
+  userVisibleOnly: true,
+  applicationServerKey: 'YOUR_VAPID_PUBLIC_KEY' // From step 1
+});
 
-### Step 3: Send Push Notifications from Your Server
+// Send this subscription to your server
+// subscription.toJSON() returns:
+// {
+//   endpoint: "https://fcm.googleapis.com/fcm/send/...",
+//   keys: {
+//     p256dh: "BNcRd...",
+//     auth: "tBHI..."
+//   }
+// }
+await fetch('/api/subscribe', {
+  method: 'POST',
+  body: JSON.stringify(subscription)
+});
+```
 
-On your backend server, use the VAPID private key to send push notifications:
+### 3. Send Notifications (Server)
 
 ```typescript
 import { buildPushHTTPRequest } from "@pushforge/builder";
 
-// Load the private key from your secure environment
-// This should be the private key from your VAPID key generation
-const privateJWK = process.env.VAPID_PRIVATE_KEY;
+// Your VAPID private key (JWK format from step 1)
+const privateJWK = {
+  kty: "EC",
+  crv: "P-256",
+  x: "...",
+  y: "...",
+  d: "..."
+};
 
-// User subscription from browser push API
+// The subscription object from the user's browser
 const subscription = {
-  endpoint: "https://fcm.googleapis.com/fcm/send/DEVICE_TOKEN",
+  endpoint: "https://fcm.googleapis.com/fcm/send/...",
   keys: {
-    p256dh: "USER_PUBLIC_KEY",
-    auth: "USER_AUTH_SECRET",
-  },
-};
-
-// Create message with payload
-const message = {
-  payload: {
-    title: "New Message",
-    body: "You have a new message!",
-    icon: "/images/icon.png",
-  },
-  options: {
-    //Default value is 24 * 60 * 60 (24 hours).
-    //The VAPID JWT expiration claim (`exp`) must not exceed 24 hours from the time of the request.
-    ttl: 3600, // Time-to-live in seconds
-    urgency: "normal", // Options: "very-low", "low", "normal", "high"
-    topic: "updates", // Optional topic for replacing notifications
-  },
-  adminContact: "mailto:admin@example.com", //The contact information of the administrator
+    p256dh: "BNcRd...",
+    auth: "tBHI..."
+  }
 };
 
-// Build the push notification request
-const {endpoint, headers, body} = await buildPushHTTPRequest({
+// Build and send the notification
+const { endpoint, headers, body } = await buildPushHTTPRequest({
   privateJWK,
-  message,
   subscription,
+  message: {
+    payload: {
+      title: "New Message",
+      body: "You have a new notification!",
+      icon: "/icon.png"
+    },
+    adminContact: "mailto:admin@example.com"
+  }
 });
 
-// Send the push notification
 const response = await fetch(endpoint, {
   method: "POST",
   headers,
-  body,
+  body
 });
 
 if (response.status === 201) {
-  console.log("Push notification sent successfully");
-} else {
-  console.error("Failed to send push notification", await response.text());
+  console.log("Notification sent");
 }
 ```
 
-## Cross-Platform Support
+## Understanding Push Subscriptions
 
-PushForge works in all major JavaScript environments:
+When a user subscribes to push notifications, the browser returns a `PushSubscription` object:
 
-### Node.js 16+
+```javascript
+{
+  // The unique URL for this user's browser push service
+  endpoint: "https://fcm.googleapis.com/fcm/send/dAPT...",
 
-```js
-import { buildPushHTTPRequest } from "@pushforge/builder";
-// OR
-const { buildPushHTTPRequest } = require("@pushforge/builder");
+  keys: {
+    // Public key for encrypting messages (base64url)
+    p256dh: "BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA...",
+
+    // Authentication secret (base64url)
+    auth: "tBHItJI5svbpez7KI4CCXg=="
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `endpoint` | The push service URL. Each browser vendor has their own (Google FCM, Mozilla autopush, Apple APNs). |
+| `p256dh` | The user's public key for ECDH P-256 message encryption. |
+| `auth` | A shared 16-byte authentication secret. |
+
+Store these securely on your server. You'll need them to send notifications to this user.
+
+## API Reference
+
+### `buildPushHTTPRequest(options)`
+
+Builds an HTTP request for sending a push notification.
 
-// Use normally - Node.js 16+ has Web Crypto API built-in
+```typescript
+const { endpoint, headers, body } = await buildPushHTTPRequest({
+  privateJWK,    // Your VAPID private key (JWK object or JSON string)
+  subscription,  // User's push subscription
+  message: {
+    payload,       // Any JSON-serializable data
+    adminContact,  // Contact email (mailto:...) or URL
+    options: {     // Optional
+      ttl,         // Time-to-live in seconds (default: 86400)
+      urgency,     // "very-low" | "low" | "normal" | "high"
+      topic        // Topic for notification coalescing
+    }
+  }
+});
+```
+
+**Returns:** `{ endpoint: string, headers: Headers, body: ArrayBuffer }`
+
+## Platform Examples
+
+### Cloudflare Workers
+
+```javascript
+export default {
+  async fetch(request, env) {
+    const subscription = await request.json();
+
+    const { endpoint, headers, body } = await buildPushHTTPRequest({
+      privateJWK: JSON.parse(env.VAPID_PRIVATE_KEY),
+      subscription,
+      message: {
+        payload: { title: "Hello from the Edge!" },
+        adminContact: "mailto:admin@example.com"
+      }
+    });
+
+    return fetch(endpoint, { method: "POST", headers, body });
+  }
+};
 ```
 
-### Browsers
+### Vercel Edge Functions
 
-```js
+```typescript
 import { buildPushHTTPRequest } from "@pushforge/builder";
 
-// Use in a service worker for push notification handling
+export const config = { runtime: "edge" };
+
+export default async function handler(request: Request) {
+  const subscription = await request.json();
+
+  const { endpoint, headers, body } = await buildPushHTTPRequest({
+    privateJWK: JSON.parse(process.env.VAPID_PRIVATE_KEY!),
+    subscription,
+    message: {
+      payload: { title: "Edge Notification" },
+      adminContact: "mailto:admin@example.com"
+    }
+  });
+
+  await fetch(endpoint, { method: "POST", headers, body });
+  return new Response("Sent", { status: 200 });
+}
+```
+
+### Convex
+
+```typescript
+import { action } from "./_generated/server";
+import { buildPushHTTPRequest } from "@pushforge/builder";
+import { v } from "convex/values";
+
+export const sendPush = action({
+  args: { subscription: v.any(), title: v.string(), body: v.string() },
+  handler: async (ctx, { subscription, title, body }) => {
+    const { endpoint, headers, body: reqBody } = await buildPushHTTPRequest({
+      privateJWK: JSON.parse(process.env.VAPID_PRIVATE_KEY!),
+      subscription,
+      message: {
+        payload: { title, body },
+        adminContact: "mailto:admin@example.com"
+      }
+    });
+
+    await fetch(endpoint, { method: "POST", headers, body: reqBody });
+  }
+});
 ```
 
 ### Deno
 
-```js
-// Import from npm CDN
-import { buildPushHTTPRequest } from "https://cdn.jsdelivr.net/npm/@pushforge/builder/dist/lib/main.js";
+```typescript
+import { buildPushHTTPRequest } from "npm:@pushforge/builder";
+
+const { endpoint, headers, body } = await buildPushHTTPRequest({
+  privateJWK: JSON.parse(Deno.env.get("VAPID_PRIVATE_KEY")!),
+  subscription,
+  message: {
+    payload: { title: "Hello from Deno!" },
+    adminContact: "mailto:admin@example.com"
+  }
+});
 
-// Run with --allow-net permissions
+await fetch(endpoint, { method: "POST", headers, body });
 ```
 
 ### Bun
 
-```js
+```typescript
 import { buildPushHTTPRequest } from "@pushforge/builder";
 
-// Works natively in Bun with no special configuration
+const { endpoint, headers, body } = await buildPushHTTPRequest({
+  privateJWK: JSON.parse(Bun.env.VAPID_PRIVATE_KEY!),
+  subscription,
+  message: {
+    payload: { title: "Hello from Bun!" },
+    adminContact: "mailto:admin@example.com"
+  }
+});
+
+await fetch(endpoint, { method: "POST", headers, body });
 ```
 
-### Cloudflare Workers
+## Service Worker Setup
+
+Handle incoming push notifications in your service worker:
+
+```javascript
+// sw.js
+self.addEventListener('push', (event) => {
+  const data = event.data?.json() ?? {};
+
+  event.waitUntil(
+    self.registration.showNotification(data.title, {
+      body: data.body,
+      icon: data.icon,
+      badge: data.badge,
+      data: data.url
+    })
+  );
+});
+
+self.addEventListener('notificationclick', (event) => {
+  event.notification.close();
+
+  if (event.notification.data) {
+    event.waitUntil(clients.openWindow(event.notification.data));
+  }
+});
+```
+
+## Requirements
+
+**Node.js 20+** or any runtime with Web Crypto API support.
+
+| Environment | Status |
+|-------------|--------|
+| Node.js 20+ | Fully supported |
+| Cloudflare Workers | Fully supported |
+| Vercel Edge | Fully supported |
+| Deno | Fully supported |
+| Bun | Fully supported |
+| Convex | Fully supported |
+| Modern Browsers | Fully supported |
+
+<details>
+<summary>Node.js 18 (requires polyfill)</summary>
+
+```javascript
+import { webcrypto } from "node:crypto";
+globalThis.crypto = webcrypto;
 
-```js
 import { buildPushHTTPRequest } from "@pushforge/builder";
 ```
 
+Or: `node --experimental-global-webcrypto your-script.js`
+
+</details>
+
+## Security
+
+PushForge validates all inputs before processing:
+
+- VAPID key structure (EC P-256 curve with required x, y, d parameters)
+- Subscription endpoint (must be valid HTTPS URL)
+- p256dh key format (65-byte uncompressed P-256 point)
+- Auth secret length (exactly 16 bytes)
+- Payload size (max 4KB per Web Push spec)
+- TTL bounds (max 24 hours per VAPID spec)
+
 ## License
 
 MIT

package/dist/lib/commandLine/keys.js

@@ -1,35 +1,23 @@
 #!/usr/bin/env node
 import { getPublicKeyFromJwk } from '../utils.js';
-let webcrypto;
-try {
-    const nodeCrypto = await import('node:crypto');
-    webcrypto = nodeCrypto.webcrypto;
-}
-catch {
-    console.error('Error: This command requires Node.js environment.');
-    console.error("Please ensure you're running Node.js 16.0.0 or later.");
+if (!globalThis.crypto?.subtle) {
+    console.error('Error: Web Crypto API not available.');
+    console.error('Please ensure you are running Node.js 20.0.0 or later.');
     process.exit(1);
 }
 async function generateVapidKeys() {
     try {
-        console.log('Generating VAPID keys...');
-        const keypair = await webcrypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign', 'verify']);
-        const privateJWK = await webcrypto.subtle.exportKey('jwk', keypair.privateKey);
+        console.log('Generating VAPID keys...\n');
+        const keypair = await globalThis.crypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign', 'verify']);
+        const privateJWK = await globalThis.crypto.subtle.exportKey('jwk', keypair.privateKey);
         const privateJWKWithAlg = { alg: 'ES256', ...privateJWK };
         const publicKey = getPublicKeyFromJwk(privateJWKWithAlg);
-        // Display in a nice formatted output
-        const resultText = `
-VAPID Keys Generated Successfully
-
-Public Key: 
-${publicKey}
-
-Private Key (JWK): 
-${JSON.stringify(privateJWKWithAlg, null, 2)}
-
-Store these keys securely. Never expose your private key.
-`;
-        console.log(resultText);
+        console.log('VAPID Keys Generated Successfully\n');
+        console.log('Public Key:');
+        console.log(publicKey);
+        console.log('\nPrivate Key (JWK):');
+        console.log(JSON.stringify(privateJWKWithAlg));
+        console.log('\nStore these keys securely. Never expose your private key.');
     }
     catch (error) {
         console.error('Error generating VAPID keys:');
@@ -39,23 +27,39 @@ Store these keys securely. Never expose your private key.
         else {
             console.error('An unknown error occurred.');
         }
-        console.error('\nThis tool requires Node.js v16.0.0 or later with WebCrypto API support.');
+        console.error('\nThis tool requires Node.js 20.0.0 or later with Web Crypto API support.');
         process.exit(1);
     }
 }
-// Simple command parsing
-const args = process.argv.slice(2);
-const command = args[0];
-if (command === 'generate-vapid-keys') {
-    generateVapidKeys();
-}
-else {
+function showHelp() {
     console.log(`
-PushForge CLI Tools
+PushForge CLI
+
+Usage: npx @pushforge/builder <command>
+
+Commands:
+  vapid   Generate VAPID key pair for Web Push authentication
+  help    Show this help message
 
-Usage:
-  npx @pushforge/builder generate-vapid-keys   Generate VAPID key pair for Web Push Authentication
+Examples:
+  npx @pushforge/builder vapid
 
-For more information, visit: https://github.com/draphy/pushforge
-  `);
+Documentation: https://github.com/draphy/pushforge#readme
+`);
+}
+// Parse command
+const args = process.argv.slice(2);
+const command = args[0]?.toLowerCase();
+switch (command) {
+    case 'vapid':
+        generateVapidKeys();
+        break;
+    case 'help':
+    case '--help':
+    case '-h':
+        showHelp();
+        break;
+    default:
+        showHelp();
+        process.exit(command ? 1 : 0);
 }

package/dist/lib/crypto.js

@@ -2,28 +2,20 @@
 /// <reference types="node" />
 /**
  * A module that provides a cross-platform cryptographic interface.
+ * Uses globalThis.crypto which is available in:
+ * - Node.js 20+ (current LTS)
+ * - Browsers
+ * - Cloudflare Workers
+ * - Deno
+ * - Bun
+ * - Convex
  *
  * @module crypto
  */
-let isomorphicCrypto;
-// Cloudflare Worker, Deno, Bun and Browser environments have crypto globally available
-if (globalThis.crypto?.subtle) {
-    isomorphicCrypto = globalThis.crypto;
-}
-// Node.js requires importing the webcrypto module
-else if (typeof process !== 'undefined' && process.versions?.node) {
-    try {
-        const { webcrypto } = await import('node:crypto');
-        isomorphicCrypto = webcrypto;
-    }
-    catch {
-        throw new Error('Crypto API not available in this Node.js environment. Please use Node.js 16+ which supports the Web Crypto API.');
-    }
-}
-// Fallback error for unsupported environments
-else {
-    throw new Error('No Web Crypto API implementation available in this environment.');
+if (!globalThis.crypto?.subtle) {
+    throw new Error('Web Crypto API not available. Ensure you are using Node.js 20+ or a modern runtime with globalThis.crypto support.');
 }
+const isomorphicCrypto = globalThis.crypto;
 /**
  * A cryptographic interface that provides methods for generating random values
  * and accessing subtle cryptographic operations.

package/dist/lib/payload.d.ts

@@ -8,4 +8,4 @@ import type { PushSubscription } from './types.js';
  * @param {PushSubscription} target - The target push subscription containing client keys.
  * @returns {Promise<ArrayBuffer>} A promise that resolves to the encrypted payload.
  */
-export declare const encryptPayload: (localKeys: CryptoKeyPair, salt: Uint8Array, payload: string, target: PushSubscription) => Promise<ArrayBuffer>;
+export declare const encryptPayload: (localKeys: CryptoKeyPair, salt: Uint8Array<ArrayBuffer>, payload: string, target: PushSubscription) => Promise<ArrayBuffer>;

package/dist/lib/payload.js

@@ -28,6 +28,14 @@ const importClientKeys = async (keys) => {
         // Node.js environment
         decodedKey = new Uint8Array(Buffer.from(base64Key, 'base64'));
     }
+    // Validate p256dh key format: must be 65 bytes (uncompressed P-256 point)
+    // Format: 0x04 (1 byte) + x coordinate (32 bytes) + y coordinate (32 bytes)
+    if (decodedKey.byteLength !== 65) {
+        throw new Error(`Invalid p256dh key: expected 65 bytes but got ${decodedKey.byteLength} bytes`);
+    }
+    if (decodedKey[0] !== 0x04) {
+        throw new Error(`Invalid p256dh key: expected uncompressed point format (0x04 prefix) but got 0x${decodedKey[0].toString(16).padStart(2, '0')}`);
+    }
     const p256 = await crypto.subtle.importKey('jwk', {
         kty: 'EC',
         crv: 'P-256',
@@ -107,6 +115,17 @@ const deriveContentEncryptionKey = async (pseudoRandomKey, salt, context) => {
     const bits = await crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt, info }, pseudoRandomKey, 16 * 8);
     return crypto.subtle.importKey('raw', bits, 'AES-GCM', false, ['encrypt']);
 };
+/**
+ * Maximum payload size after accounting for encryption overhead.
+ * Web push payloads have an overall max size of 4KB (4096 bytes).
+ * With the required overhead (16 bytes auth tag + 2 bytes padding length),
+ * the actual max payload size is 4078 bytes.
+ */
+const MAX_PAYLOAD_SIZE = 4078;
+/**
+ * Minimum required size for padding length prefix (2 bytes).
+ */
+const PADDING_LENGTH_PREFIX_SIZE = 2;
 /**
  * Pads the payload to ensure it fits within the maximum allowed size for web push notifications.
  *
@@ -114,17 +133,22 @@ const deriveContentEncryptionKey = async (pseudoRandomKey, salt, context) => {
  * required overhead for encryption, the actual max payload size is 4078 bytes.
  *
  * @param {Uint8Array} payload - The original payload to be padded.
- * @returns {Uint8Array} The padded payload, including length information.
+ * @returns {Uint8Array<ArrayBuffer>} The padded payload, including length information.
+ * @throws {Error} Throws an error if the payload exceeds the maximum allowed size.
  */
 const padPayload = (payload) => {
-    const MAX_PAYLOAD_SIZE = 4078; // Maximum payload size after encryption overhead
-    let paddingSize = Math.round(Math.random() * 100); // Random padding size
-    const payloadSizeWithPadding = payload.byteLength + 2 + paddingSize;
-    if (payloadSizeWithPadding > MAX_PAYLOAD_SIZE) {
-        // Adjust padding size if the total exceeds the maximum allowed size
-        paddingSize -= payloadSizeWithPadding - MAX_PAYLOAD_SIZE;
+    const maxPayloadContentSize = MAX_PAYLOAD_SIZE - PADDING_LENGTH_PREFIX_SIZE;
+    if (payload.byteLength > maxPayloadContentSize) {
+        throw new Error(`Payload too large. Maximum size is ${maxPayloadContentSize} bytes, but received ${payload.byteLength} bytes`);
     }
-    const paddingArray = new ArrayBuffer(2 + paddingSize);
+    // Calculate available space for padding
+    const availableSpace = MAX_PAYLOAD_SIZE - PADDING_LENGTH_PREFIX_SIZE - payload.byteLength;
+    // Generate random padding size, clamped to available space
+    const maxRandomPadding = Math.min(100, availableSpace);
+    const paddingSize = maxRandomPadding > 0
+        ? Math.floor(Math.random() * (maxRandomPadding + 1))
+        : 0;
+    const paddingArray = new ArrayBuffer(PADDING_LENGTH_PREFIX_SIZE + paddingSize);
     new DataView(paddingArray).setUint16(0, paddingSize); // Store the length of the padding
     // Return the new payload with padding added
     return concatTypedArrays([new Uint8Array(paddingArray), payload]);

package/dist/lib/request.js

@@ -1,6 +1,47 @@
 import { crypto } from './crypto.js';
 import { encryptPayload } from './payload.js';
 import { vapidHeaders } from './vapid.js';
+/**
+ * Validates that a JWK has the required properties for ECDSA P-256.
+ *
+ * @param {JsonWebKey} jwk - The JSON Web Key to validate.
+ * @throws {Error} Throws if the JWK is missing required properties or has invalid values.
+ */
+const validatePrivateJWK = (jwk) => {
+    if (jwk.kty !== 'EC') {
+        throw new Error(`Invalid JWK: 'kty' must be 'EC', received '${jwk.kty ?? 'undefined'}'`);
+    }
+    if (jwk.crv !== 'P-256') {
+        throw new Error(`Invalid JWK: 'crv' must be 'P-256', received '${jwk.crv ?? 'undefined'}'`);
+    }
+    if (!jwk.x || typeof jwk.x !== 'string') {
+        throw new Error("Invalid JWK: missing or invalid 'x' coordinate");
+    }
+    if (!jwk.y || typeof jwk.y !== 'string') {
+        throw new Error("Invalid JWK: missing or invalid 'y' coordinate");
+    }
+    if (!jwk.d || typeof jwk.d !== 'string') {
+        throw new Error("Invalid JWK: missing or invalid 'd' (private key)");
+    }
+};
+/**
+ * Validates that the subscription endpoint is a valid HTTPS URL.
+ *
+ * @param {string} endpoint - The push subscription endpoint URL.
+ * @throws {Error} Throws if the endpoint is not a valid HTTPS URL.
+ */
+const validateEndpoint = (endpoint) => {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error(`Invalid subscription endpoint: '${endpoint}' is not a valid URL`);
+    }
+    if (url.protocol !== 'https:') {
+        throw new Error(`Invalid subscription endpoint: push endpoints must use HTTPS, received '${url.protocol}'`);
+    }
+};
 /**
  * Builds an HTTP request body and headers for sending a push notification.
  *
@@ -57,7 +98,17 @@ import { vapidHeaders } from './vapid.js';
  */
 export async function buildPushHTTPRequest({ privateJWK, message, subscription, }) {
     // Parse the private JWK if it's a string
-    const jwk = typeof privateJWK === 'string' ? JSON.parse(privateJWK) : privateJWK;
+    let jwk;
+    try {
+        jwk = typeof privateJWK === 'string' ? JSON.parse(privateJWK) : privateJWK;
+    }
+    catch {
+        throw new Error('Invalid privateJWK: failed to parse JSON string');
+    }
+    // Validate the JWK structure
+    validatePrivateJWK(jwk);
+    // Validate the subscription endpoint
+    validateEndpoint(subscription.endpoint);
     const MAX_TTL = 24 * 60 * 60;
     if (message.options?.ttl && message.options.ttl > MAX_TTL) {
         throw new Error('TTL must be less than 24 hours');

package/dist/lib/utils.d.ts

@@ -48,6 +48,6 @@ export declare const getPublicKeyFromJwk: (jwk: JsonWebKey) => string;
  * Concatenates multiple Uint8Array instances into a single Uint8Array.
  *
  * @param {Uint8Array[]} arrays - An array of Uint8Array instances to concatenate.
- * @returns {Uint8Array} A new Uint8Array containing all the concatenated data.
+ * @returns {Uint8Array<ArrayBuffer>} A new Uint8Array containing all the concatenated data.
  */
-export declare const concatTypedArrays: (arrays: Uint8Array[]) => Uint8Array;
+export declare const concatTypedArrays: (arrays: readonly Uint8Array[]) => Uint8Array<ArrayBuffer>;

package/dist/lib/utils.js

@@ -60,7 +60,7 @@ export const getPublicKeyFromJwk = (jwk) => base64UrlEncode(`\x04${base64Decode(
  * Concatenates multiple Uint8Array instances into a single Uint8Array.
  *
  * @param {Uint8Array[]} arrays - An array of Uint8Array instances to concatenate.
- * @returns {Uint8Array} A new Uint8Array containing all the concatenated data.
+ * @returns {Uint8Array<ArrayBuffer>} A new Uint8Array containing all the concatenated data.
  */
 export const concatTypedArrays = (arrays) => {
     const length = arrays.reduce((accumulator, current) => accumulator + current.byteLength, 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushforge/builder",
-  "version": "1.1.2",
+  "version": "2.0.1",
   "description": "A robust, cross-platform Web Push notification library that handles VAPID authentication and payload encryption following the Web Push Protocol standard. Works in Node.js 16+, Browsers, Deno, Bun and Cloudflare Workers.",
   "private": false,
   "main": "dist/lib/main.js",
@@ -14,7 +14,7 @@
     "url": "https://github.com/draphy/pushforge/issues"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=20.0.0"
   },
   "repository": {
     "type": "git",
@@ -45,7 +45,7 @@
     "semantic-release": "semantic-release"
   },
   "bin": {
-    "generate-vapid-keys": "./dist/lib/commandLine/keys.js"
+    "pushforge": "./dist/lib/commandLine/keys.js"
   },
   "devDependencies": {
     "@semantic-release/commit-analyzer": "^11.1.0",