@pushforge/builder 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Raphi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# PushForge Builder
+
+A robust, cross-platform Web Push notification library that handles VAPID authentication and payload encryption following the Web Push Protocol standard.
+
+## Installation
+
+Choose your preferred package manager:
+
+```bash
+# NPM
+npm install @pushforge/builder
+
+# Yarn
+yarn add @pushforge/builder
+
+# pnpm
+pnpm add @pushforge/builder
+```
+
+## Features
+
+- 🔑 Compliant VAPID authentication
+- 🔒 Web Push Protocol encryption
+- 🌐 Cross-platform compatibility (Node.js 16+, Browsers, Deno, Bun, Cloudflare Workers)
+- 🧩 TypeScript definitions included
+- 🛠️ Zero dependencies
+
+## Getting Started
+
+### Step 1: Generate VAPID Keys
+
+PushForge includes a built-in CLI tool to generate VAPID keys for Web Push Authentication:
+
+```bash
+# Generate VAPID keys using npx
+npx @pushforge/builder generate-vapid-keys
+
+# Using yarn
+yarn dlx @pushforge/builder generate-vapid-keys
+
+# Using pnpm
+pnpm dlx @pushforge/builder generate-vapid-keys
+```
+
+This will output a public key and private key that you can use for VAPID authentication:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                                                            │
+│ 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.  │
+│                                                            │
+└────────────────────────────────────────────────────────────┘
+```
+
+**Requirements:**
+
+- Node.js 16.0.0 or later
+- The command uses the WebCrypto API which is built-in to Node.js 16+
+
+### Step 2: Set Up Push Notifications in Your Web Application
+
+To implement push notifications in your web application, you'll need to:
+
+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
+
+When implementing your service worker, handle push events to display notifications when they arrive:
+
+1. Listen for `push` events
+2. Parse the notification data
+3. Display the notification to the user
+4. Handle notification click events
+
+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.
+
+### Step 3: Send Push Notifications from Your Server
+
+On your backend server, use the VAPID private key to send push notifications:
+
+```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;
+
+// User subscription from browser push API
+const subscription = {
+  endpoint: "https://fcm.googleapis.com/fcm/send/DEVICE_TOKEN",
+  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
+};
+
+// Build the push notification request
+const {endpoint, headers, body} = await buildPushHTTPRequest({
+  privateJWK,
+  message,
+  subscription,
+});
+
+// Send the push notification
+const response = await fetch(endpoint, {
+  method: "POST",
+  headers,
+  body,
+});
+
+if (response.status === 201) {
+  console.log("Push notification sent successfully");
+} else {
+  console.error("Failed to send push notification", await response.text());
+}
+```
+
+## Cross-Platform Support
+
+PushForge works in all major JavaScript environments:
+
+### Node.js 16+
+
+```js
+import { buildPushHTTPRequest } from "@pushforge/builder";
+// OR
+const { buildPushHTTPRequest } = require("@pushforge/builder");
+
+// Use normally - Node.js 16+ has Web Crypto API built-in
+```
+
+### Browsers
+
+```js
+import { buildPushHTTPRequest } from "@pushforge/builder";
+
+// Use in a service worker for push notification handling
+```
+
+### Deno
+
+```js
+// Import from npm CDN
+import { buildPushHTTPRequest } from "https://cdn.jsdelivr.net/npm/@pushforge/builder/dist/lib/main.js";
+
+// Run with --allow-net permissions
+```
+
+### Bun
+
+```js
+import { buildPushHTTPRequest } from "@pushforge/builder";
+
+// Works natively in Bun with no special configuration
+```
+
+### Cloudflare Workers
+
+```js
+import { buildPushHTTPRequest } from "@pushforge/builder";
+```
+
+## License
+
+MIT

package/dist/lib/base64.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Encodes a string, ArrayBuffer, or Uint8Array into a Base64 URL format.
+ *
+ * This function handles both browser and Node.js environments by using
+ * the appropriate encoding method based on the environment.
+ *
+ * @param {string | ArrayBuffer | Uint8Array} input - The input to encode.
+ * @returns {string} The Base64 URL encoded string.
+ */
+export declare const base64UrlEncode: (input: string | ArrayBuffer | Uint8Array) => string;
+/**
+ * Decodes a Base64 URL encoded string back to its original format.
+ *
+ * This function handles both browser and Node.js environments by using
+ * the appropriate decoding method based on the environment.
+ *
+ * @param {string | undefined} s - The Base64 URL encoded string to decode.
+ * @returns {string} The decoded data as a string.
+ * @throws {Error} Throws an error if the input string is invalid.
+ */
+export declare const base64UrlDecodeString: (s: string | undefined) => string;
+/**
+ * Decodes a Base64 URL encoded string into an ArrayBuffer.
+ *
+ * This function handles both browser and Node.js environments by using
+ * the appropriate decoding method based on the environment.
+ *
+ * @param {string} input - The Base64 URL encoded string to decode.
+ * @returns {ArrayBuffer} The decoded data as an ArrayBuffer.
+ */
+export declare const base64UrlDecode: (input: string) => ArrayBuffer;

package/dist/lib/base64.js

@@ -0,0 +1,67 @@
+import { stringFromArrayBuffer } from './utils.js';
+/**
+ * Encodes a string, ArrayBuffer, or Uint8Array into a Base64 URL format.
+ *
+ * This function handles both browser and Node.js environments by using
+ * the appropriate encoding method based on the environment.
+ *
+ * @param {string | ArrayBuffer | Uint8Array} input - The input to encode.
+ * @returns {string} The Base64 URL encoded string.
+ */
+export const base64UrlEncode = (input) => {
+    // Convert input to string if it's binary
+    const text = typeof input === 'string' ? input : stringFromArrayBuffer(input);
+    // Use environment-specific encoding
+    let base64;
+    if (typeof globalThis !== 'undefined' && 'btoa' in globalThis) {
+        // Browser environment
+        base64 = globalThis.btoa(text);
+    }
+    else {
+        // Node.js environment
+        base64 = Buffer.from(text, 'binary').toString('base64');
+    }
+    // Convert base64 to base64url format
+    return base64.replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+};
+/**
+ * Decodes a Base64 URL encoded string back to its original format.
+ *
+ * This function handles both browser and Node.js environments by using
+ * the appropriate decoding method based on the environment.
+ *
+ * @param {string | undefined} s - The Base64 URL encoded string to decode.
+ * @returns {string} The decoded data as a string.
+ * @throws {Error} Throws an error if the input string is invalid.
+ */
+export const base64UrlDecodeString = (s) => {
+    if (!s)
+        throw new Error('Invalid input');
+    return (s.replace(/-/g, '+').replace(/_/g, '/') +
+        '='.repeat((4 - (s.length % 4)) % 4));
+};
+/**
+ * Decodes a Base64 URL encoded string into an ArrayBuffer.
+ *
+ * This function handles both browser and Node.js environments by using
+ * the appropriate decoding method based on the environment.
+ *
+ * @param {string} input - The Base64 URL encoded string to decode.
+ * @returns {ArrayBuffer} The decoded data as an ArrayBuffer.
+ */
+export const base64UrlDecode = (input) => {
+    // Convert from base64url to base64
+    const base64 = base64UrlDecodeString(input);
+    // Decode based on environment
+    if (typeof globalThis !== 'undefined' && 'atob' in globalThis) {
+        // Browser environment
+        const binaryString = globalThis.atob(base64);
+        const bytes = new Uint8Array(binaryString.length);
+        for (let i = 0; i < binaryString.length; i++) {
+            bytes[i] = binaryString.charCodeAt(i);
+        }
+        return bytes.buffer;
+    }
+    // Node.js environment
+    return Buffer.from(base64, 'base64').buffer;
+};

package/dist/lib/commandLine/keys.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/lib/commandLine/keys.js

@@ -0,0 +1,61 @@
+#!/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.");
+    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);
+        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);
+    }
+    catch (error) {
+        console.error('Error generating VAPID keys:');
+        if (error instanceof Error) {
+            console.error(error.message);
+        }
+        else {
+            console.error('An unknown error occurred.');
+        }
+        console.error('\nThis tool requires Node.js v16.0.0 or later with WebCrypto 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 {
+    console.log(`
+PushForge CLI Tools
+
+Usage:
+  npx @pushforge/builder generate-vapid-keys   Generate VAPID key pair for Web Push Authentication
+
+For more information, visit: https://github.com/draphy/pushforge
+  `);
+}

package/dist/lib/crypto.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A cryptographic interface that provides methods for generating random values
+ * and accessing subtle cryptographic operations.
+ */
+export declare const crypto: {
+    /**
+     * Fills the given typed array with cryptographically secure random values.
+     *
+     * @param {T} array - The typed array to fill with random values.
+     * @returns {T} The filled typed array.
+     * @template T - The type of the typed array (e.g., Uint8Array).
+     */
+    getRandomValues<T extends Uint8Array>(array: T): T;
+    /**
+     * Provides access to subtle cryptographic operations.
+     *
+     * @type {SubtleCrypto} The subtle cryptographic interface.
+     */
+    subtle: SubtleCrypto;
+};

package/dist/lib/crypto.js

@@ -0,0 +1,48 @@
+/// <reference lib="webworker" />
+/// <reference types="node" />
+/**
+ * A module that provides a cross-platform cryptographic interface.
+ *
+ * @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.');
+}
+/**
+ * A cryptographic interface that provides methods for generating random values
+ * and accessing subtle cryptographic operations.
+ */
+export const crypto = {
+    /**
+     * Fills the given typed array with cryptographically secure random values.
+     *
+     * @param {T} array - The typed array to fill with random values.
+     * @returns {T} The filled typed array.
+     * @template T - The type of the typed array (e.g., Uint8Array).
+     */
+    getRandomValues(array) {
+        return isomorphicCrypto.getRandomValues(array);
+    },
+    /**
+     * Provides access to subtle cryptographic operations.
+     *
+     * @type {SubtleCrypto} The subtle cryptographic interface.
+     */
+    subtle: isomorphicCrypto.subtle,
+};

package/dist/lib/jwt.d.ts

@@ -0,0 +1,19 @@
+import type { JwtData } from './types.js';
+/**
+ * Creates a JSON Web Token (JWT) using the ECDSA algorithm.
+ *
+ * This function takes a JSON Web Key (JWK) and JWT data, encodes them,
+ * and signs the token using the specified algorithm and hash function.
+ *
+ * In the Web Push protocol, the VAPID JWT includes an `exp` (expiration) claim
+ * that specifies the token's validity period. According to the VAPID specification,
+ * the `exp` value must not exceed 24 hours from the time of the request. If it does,
+ * the push service (like FCM) will reject the request with a 403 Forbidden error.
+ *
+ * @param {JsonWebKey} jwk - The JSON Web Key used for signing the JWT.
+ * @param {JwtData} jwtData - The data to be included in the JWT payload.
+ * @returns {Promise<string>} A promise that resolves to the signed JWT as a string.
+ *
+ * @throws {Error} Throws an error if the key import or signing process fails.
+ */
+export declare const createJwt: (jwk: JsonWebKey, jwtData: JwtData) => Promise<string>;

package/dist/lib/jwt.js

@@ -0,0 +1,38 @@
+import { base64UrlEncode } from './base64.js';
+import { crypto } from './crypto.js';
+/**
+ * Creates a JSON Web Token (JWT) using the ECDSA algorithm.
+ *
+ * This function takes a JSON Web Key (JWK) and JWT data, encodes them,
+ * and signs the token using the specified algorithm and hash function.
+ *
+ * In the Web Push protocol, the VAPID JWT includes an `exp` (expiration) claim
+ * that specifies the token's validity period. According to the VAPID specification,
+ * the `exp` value must not exceed 24 hours from the time of the request. If it does,
+ * the push service (like FCM) will reject the request with a 403 Forbidden error.
+ *
+ * @param {JsonWebKey} jwk - The JSON Web Key used for signing the JWT.
+ * @param {JwtData} jwtData - The data to be included in the JWT payload.
+ * @returns {Promise<string>} A promise that resolves to the signed JWT as a string.
+ *
+ * @throws {Error} Throws an error if the key import or signing process fails.
+ */
+export const createJwt = async (jwk, jwtData) => {
+    // JWT header information
+    const jwtInfo = {
+        typ: 'JWT', // Type of the token
+        alg: 'ES256', // Algorithm used for signing
+    };
+    // Encode the JWT header and payload
+    const base64JwtInfo = base64UrlEncode(JSON.stringify(jwtInfo));
+    const base64JwtData = base64UrlEncode(JSON.stringify(jwtData));
+    const unsignedToken = `${base64JwtInfo}.${base64JwtData}`;
+    // Import the private key from the JWK
+    const privateKey = await crypto.subtle.importKey('jwk', jwk, { name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign']);
+    // Sign the token using the ECDSA algorithm and SHA-256 hash
+    const signature = await crypto.subtle
+        .sign({ name: 'ECDSA', hash: { name: 'SHA-256' } }, privateKey, new TextEncoder().encode(unsignedToken))
+        .then((token) => base64UrlEncode(token));
+    // Return the complete JWT
+    return `${base64JwtInfo}.${base64JwtData}.${signature}`;
+};

package/dist/lib/main.d.ts

@@ -0,0 +1,2 @@
+export type { PushMessage, PushSubscription, BuilderOptions, PushOptions, } from './types.js';
+export { buildPushHTTPRequest } from './request.js';

package/dist/lib/main.js

@@ -0,0 +1 @@
+export { buildPushHTTPRequest } from './request.js';

package/dist/lib/payload.d.ts

@@ -0,0 +1,11 @@
+import type { PushSubscription } from './types.js';
+/**
+ * Encrypts the payload for a push notification using the provided keys and context.
+ *
+ * @param {CryptoKeyPair} localKeys - The local key pair used for encryption.
+ * @param {Uint8Array} salt - The salt used in the encryption process.
+ * @param {string} payload - The original payload to encrypt.
+ * @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>;

package/dist/lib/payload.js

@@ -0,0 +1,151 @@
+import { base64UrlDecode, base64UrlDecodeString, base64UrlEncode, } from './base64.js';
+import { crypto } from './crypto.js';
+import { deriveSharedSecret } from './shared-secret.js';
+import { concatTypedArrays } from './utils.js';
+/**
+ * Imports and validates the client's public and authentication keys from a PushSubscriptionKey.
+ *
+ * @param {PushSubscriptionKey} keys - The keys associated with the push subscription.
+ * @returns {Promise<{ auth: ArrayBuffer, p256: CryptoKey }>} A promise that resolves to an object containing the authentication key and the imported public key.
+ * @throws {Error} Throws an error if the authentication key length is incorrect.
+ */
+const importClientKeys = async (keys) => {
+    const auth = base64UrlDecode(keys.auth);
+    if (auth.byteLength !== 16) {
+        throw new Error(`Incorrect auth length, expected 16 bytes but got ${auth.byteLength}`);
+    }
+    let decodedKey;
+    const base64Key = base64UrlDecodeString(keys.p256dh);
+    if (typeof globalThis !== 'undefined' && 'atob' in globalThis) {
+        // Browser environment
+        const binaryStr = globalThis.atob(base64Key);
+        decodedKey = new Uint8Array(binaryStr.length);
+        for (let i = 0; i < binaryStr.length; i++) {
+            decodedKey[i] = binaryStr.charCodeAt(i);
+        }
+    }
+    else {
+        // Node.js environment
+        decodedKey = new Uint8Array(Buffer.from(base64Key, 'base64'));
+    }
+    const p256 = await crypto.subtle.importKey('jwk', {
+        kty: 'EC',
+        crv: 'P-256',
+        x: base64UrlEncode(decodedKey.slice(1, 33)),
+        y: base64UrlEncode(decodedKey.slice(33, 65)),
+        ext: true,
+    }, { name: 'ECDH', namedCurve: 'P-256' }, true, []);
+    return { auth, p256 };
+};
+/**
+ * Derives a pseudo-random key using HKDF from the shared secret and authentication key.
+ *
+ * @param {ArrayBuffer} auth - The authentication key used as salt in the derivation process.
+ * @param {CryptoKey} sharedSecret - The shared secret derived from the client's public key and local private key.
+ * @returns {Promise<CryptoKey>} A promise that resolves to the derived pseudo-random key.
+ */
+const derivePseudoRandomKey = async (auth, sharedSecret) => {
+    const pseudoRandomKeyBytes = await crypto.subtle.deriveBits({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt: auth,
+        // Adding Content-Encoding data info here is required by the Web Push API
+        info: new TextEncoder().encode('Content-Encoding: auth\0'),
+    }, sharedSecret, 256);
+    return crypto.subtle.importKey('raw', pseudoRandomKeyBytes, 'HKDF', false, [
+        'deriveBits',
+    ]);
+};
+/**
+ * Creates a context for the ECDH key exchange using the client's and local public keys.
+ *
+ * @param {CryptoKey} clientPublicKey - The client's public key.
+ * @param {CryptoKey} localPublicKey - The local public key.
+ * @returns {Promise<Uint8Array>} A promise that resolves to a concatenated context array.
+ */
+const createContext = async (clientPublicKey, localPublicKey) => {
+    const [clientKeyBytes, localKeyBytes] = await Promise.all([
+        crypto.subtle.exportKey('raw', clientPublicKey),
+        crypto.subtle.exportKey('raw', localPublicKey),
+    ]);
+    return concatTypedArrays([
+        new TextEncoder().encode('P-256\0'),
+        new Uint8Array([0, clientKeyBytes.byteLength]),
+        new Uint8Array(clientKeyBytes),
+        new Uint8Array([0, localKeyBytes.byteLength]),
+        new Uint8Array(localKeyBytes),
+    ]);
+};
+/**
+ * Derives a nonce for encryption using HKDF from the pseudo-random key, salt, and context.
+ *
+ * @param {CryptoKey} pseudoRandomKey - The pseudo-random key derived from the shared secret.
+ * @param {Uint8Array} salt - The salt used in the derivation process.
+ * @param {Uint8Array} context - The context for the nonce derivation.
+ * @returns {Promise<ArrayBuffer>} A promise that resolves to the derived nonce.
+ */
+const deriveNonce = async (pseudoRandomKey, salt, context) => {
+    const nonceInfo = concatTypedArrays([
+        new TextEncoder().encode('Content-Encoding: nonce\0'),
+        context,
+    ]);
+    return crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt, info: nonceInfo }, pseudoRandomKey, 12 * 8);
+};
+/**
+ * Derives a content encryption key using HKDF from the pseudo-random key, salt, and context.
+ *
+ * @param {CryptoKey} pseudoRandomKey - The pseudo-random key derived from the shared secret.
+ * @param {Uint8Array} salt - The salt used in the derivation process.
+ * @param {Uint8Array} context - The context for the key derivation.
+ * @returns {Promise<CryptoKey>} A promise that resolves to the derived content encryption key.
+ */
+const deriveContentEncryptionKey = async (pseudoRandomKey, salt, context) => {
+    const info = concatTypedArrays([
+        new TextEncoder().encode('Content-Encoding: aesgcm\0'),
+        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']);
+};
+/**
+ * Pads the payload to ensure it fits within the maximum allowed size for web push notifications.
+ *
+ * Web push payloads have an overall max size of 4KB (4096 bytes). With the
+ * 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.
+ */
+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 paddingArray = new ArrayBuffer(2 + 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]);
+};
+/**
+ * Encrypts the payload for a push notification using the provided keys and context.
+ *
+ * @param {CryptoKeyPair} localKeys - The local key pair used for encryption.
+ * @param {Uint8Array} salt - The salt used in the encryption process.
+ * @param {string} payload - The original payload to encrypt.
+ * @param {PushSubscription} target - The target push subscription containing client keys.
+ * @returns {Promise<ArrayBuffer>} A promise that resolves to the encrypted payload.
+ */
+export const encryptPayload = async (localKeys, salt, payload, target) => {
+    const clientKeys = await importClientKeys(target.keys);
+    const sharedSecret = await deriveSharedSecret(clientKeys.p256, localKeys.privateKey);
+    const pseudoRandomKey = await derivePseudoRandomKey(clientKeys.auth, sharedSecret);
+    const context = await createContext(clientKeys.p256, localKeys.publicKey);
+    const nonce = await deriveNonce(pseudoRandomKey, salt, context);
+    const contentEncryptionKey = await deriveContentEncryptionKey(pseudoRandomKey, salt, context);
+    const encodedPayload = new TextEncoder().encode(payload);
+    const paddedPayload = padPayload(encodedPayload);
+    return crypto.subtle.encrypt({ name: 'AES-GCM', iv: nonce }, contentEncryptionKey, paddedPayload);
+};

package/dist/lib/request.d.ts

@@ -0,0 +1,60 @@
+import type { BuilderOptions } from './types.js';
+/**
+ * Builds an HTTP request body and headers for sending a push notification.
+ *
+ * This function constructs the necessary components for a push notification request,
+ * including the payload, headers, and any required cryptographic operations.
+ *
+ * @param {BuilderOptions} options - The options for building the push notification request.
+ * @param {JsonWebKey | string} options.privateJWK - The private JSON Web Key (JWK) used for signing.
+ * @param {PushMessage} options.message - The message to be sent in the push notification, including user-defined options.
+ * @param {PushSubscription} options.subscription - The subscription details for the push notification.
+ * @returns {Promise<{ endpoint: string, body: ArrayBuffer, headers: Record<string, string> | Headers }>} A promise that resolves to an object containing the endpoint, encrypted body, and headers for the push notification.
+ *
+ * @throws {Error} Throws an error if the privateJWK is invalid, if the request fails, or if the payload encryption fails.
+ *
+ * @example
+ * // Example usage
+ * const privateJWK = '{"kty":"EC","crv":"P-256","d":"_eQ..."}'; // Your private VAPID key
+ *
+ * const message = {
+ *   payload: {
+ *     title: "New Message",
+ *     body: "You have a new message!",
+ *     icon: "/images/icon.png"
+ *   },
+ *   options: {
+ *     ttl: 3600, // 1 hour in seconds
+ *     urgency: "high",
+ *     topic: "new-messages"
+ *   },
+ *   adminContact: "mailto:admin@example.com"
+ * };
+ *
+ * const subscription = {
+ *   endpoint: "https://fcm.googleapis.com/fcm/send/...",
+ *   keys: {
+ *     p256dh: "BNn5....",
+ *     auth: "tBHI...."
+ *   }
+ * };
+ *
+ * // Build the request
+ * const request = await buildPushHTTPRequest({
+ *   privateJWK,
+ *   message,
+ *   subscription
+ * });
+ *
+ * // Send the push notification
+ * const response = await fetch(request.endpoint, {
+ *   method: 'POST',
+ *   headers: request.headers,
+ *   body: request.body
+ * });
+ */
+export declare function buildPushHTTPRequest({ privateJWK, message, subscription, }: BuilderOptions): Promise<{
+    endpoint: string;
+    body: ArrayBuffer;
+    headers: Record<string, string> | Headers;
+}>;

package/dist/lib/request.js

@@ -0,0 +1,98 @@
+import { crypto } from './crypto.js';
+import { encryptPayload } from './payload.js';
+import { vapidHeaders } from './vapid.js';
+/**
+ * Builds an HTTP request body and headers for sending a push notification.
+ *
+ * This function constructs the necessary components for a push notification request,
+ * including the payload, headers, and any required cryptographic operations.
+ *
+ * @param {BuilderOptions} options - The options for building the push notification request.
+ * @param {JsonWebKey | string} options.privateJWK - The private JSON Web Key (JWK) used for signing.
+ * @param {PushMessage} options.message - The message to be sent in the push notification, including user-defined options.
+ * @param {PushSubscription} options.subscription - The subscription details for the push notification.
+ * @returns {Promise<{ endpoint: string, body: ArrayBuffer, headers: Record<string, string> | Headers }>} A promise that resolves to an object containing the endpoint, encrypted body, and headers for the push notification.
+ *
+ * @throws {Error} Throws an error if the privateJWK is invalid, if the request fails, or if the payload encryption fails.
+ *
+ * @example
+ * // Example usage
+ * const privateJWK = '{"kty":"EC","crv":"P-256","d":"_eQ..."}'; // Your private VAPID key
+ *
+ * const message = {
+ *   payload: {
+ *     title: "New Message",
+ *     body: "You have a new message!",
+ *     icon: "/images/icon.png"
+ *   },
+ *   options: {
+ *     ttl: 3600, // 1 hour in seconds
+ *     urgency: "high",
+ *     topic: "new-messages"
+ *   },
+ *   adminContact: "mailto:admin@example.com"
+ * };
+ *
+ * const subscription = {
+ *   endpoint: "https://fcm.googleapis.com/fcm/send/...",
+ *   keys: {
+ *     p256dh: "BNn5....",
+ *     auth: "tBHI...."
+ *   }
+ * };
+ *
+ * // Build the request
+ * const request = await buildPushHTTPRequest({
+ *   privateJWK,
+ *   message,
+ *   subscription
+ * });
+ *
+ * // Send the push notification
+ * const response = await fetch(request.endpoint, {
+ *   method: 'POST',
+ *   headers: request.headers,
+ *   body: request.body
+ * });
+ */
+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;
+    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');
+    }
+    // Determine the time-to-live (TTL) for the push notification
+    const ttl = message.options?.ttl && message.options.ttl > 0
+        ? message.options.ttl
+        : MAX_TTL; // Default to 24 hours
+    // Create the JWT payload
+    const jwt = {
+        aud: new URL(subscription.endpoint).origin,
+        exp: Math.floor(Date.now() / 1000) + ttl,
+        sub: message.adminContact,
+    };
+    // Construct the options for the push notification
+    const options = {
+        jwk,
+        jwt,
+        payload: JSON.stringify(message.payload),
+        ttl,
+        ...(message.options?.urgency && {
+            urgency: message.options.urgency,
+        }),
+        ...(message.options?.topic && {
+            topic: message.options.topic,
+        }),
+    };
+    // Generate a random salt for encryption
+    const salt = crypto.getRandomValues(new Uint8Array(16));
+    // Generate local keys for encryption
+    const localKeys = await crypto.subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']);
+    // Encrypt the payload for the push notification
+    const body = await encryptPayload(localKeys, salt, options.payload, subscription);
+    // Construct the VAPID headers for the push notification request
+    const headers = await vapidHeaders(options, body.byteLength, salt, localKeys.publicKey);
+    // Return the constructed request components
+    return { endpoint: subscription.endpoint, body, headers };
+}

package/dist/lib/shared-secret.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Derives a shared secret from a client's public key and a local private key using the ECDH algorithm.
+ *
+ * This function uses the Web Crypto API to derive a shared secret, which can then be used
+ * for further cryptographic operations, such as key derivation using HKDF.
+ *
+ * @param {CryptoKey} clientPublicKey - The public key of the client, used to derive the shared secret.
+ * @param {CryptoKey} localPrivateKey - The local private key used in the derivation process.
+ * @returns {Promise<CryptoKey>} A promise that resolves to a CryptoKey representing the derived shared secret.
+ *
+ * @throws {Error} Throws an error if the key derivation fails.
+ */
+export declare const deriveSharedSecret: (clientPublicKey: CryptoKey, localPrivateKey: CryptoKey) => Promise<CryptoKey>;

package/dist/lib/shared-secret.js

@@ -0,0 +1,17 @@
+import { crypto } from './crypto.js';
+/**
+ * Derives a shared secret from a client's public key and a local private key using the ECDH algorithm.
+ *
+ * This function uses the Web Crypto API to derive a shared secret, which can then be used
+ * for further cryptographic operations, such as key derivation using HKDF.
+ *
+ * @param {CryptoKey} clientPublicKey - The public key of the client, used to derive the shared secret.
+ * @param {CryptoKey} localPrivateKey - The local private key used in the derivation process.
+ * @returns {Promise<CryptoKey>} A promise that resolves to a CryptoKey representing the derived shared secret.
+ *
+ * @throws {Error} Throws an error if the key derivation fails.
+ */
+export const deriveSharedSecret = async (clientPublicKey, localPrivateKey) => {
+    const sharedSecretBytes = await crypto.subtle.deriveBits({ name: 'ECDH', public: clientPublicKey }, localPrivateKey, 256);
+    return crypto.subtle.importKey('raw', sharedSecretBytes, { name: 'HKDF' }, false, ['deriveBits', 'deriveKey']);
+};

package/dist/lib/types.d.ts

@@ -0,0 +1,137 @@
+import type { Jsonifiable, RequireAtLeastOne } from './utils.js';
+/**
+ * Options for configuring the builder.
+ */
+export interface BuilderOptions {
+    /**
+     * The private JSON Web Key (JWK) used for signing.
+     */
+    privateJWK: JsonWebKey | string;
+    /**
+     * The subscription details for push notifications.
+     */
+    subscription: PushSubscription;
+    /**
+     * The message to be sent in the push notification.
+     */
+    message: PushMessage;
+}
+/**
+ * Represents a push message to be sent.
+ *
+ * @template T - The type of the payload, which must be JSON-compatible.
+ */
+export interface PushMessage<T extends Jsonifiable = Jsonifiable> {
+    /**
+     * The payload of the push message, which can be any JSON-compatible value.
+     */
+    payload: T;
+    /**
+     * The contact information of the administrator, typically a URL or email address.
+     */
+    adminContact: JwtData['sub'];
+    /**
+     * Optional settings for the push message.
+     * At least one of the specified options must be provided.
+     */
+    options?: RequireAtLeastOne<{
+        /**
+         * The time-to-live for the push message in seconds.
+         * Must be a positive number greater than 0.
+         * Default value is 24 * 60 * 60 (24 hours).
+         * If set to 0, undefined, or a negative value, it will default to 24 hours.
+         * The VAPID JWT expiration claim (`exp`) must not exceed 24 hours from the time of the request.
+         * If it does, the push service (like FCM) will reject the request with a 403 Forbidden error.
+         */
+        ttl?: PushOptions['ttl'];
+        /**
+         * The topic of the push message.
+         */
+        topic?: PushOptions['topic'];
+        /**
+         * The urgency level of the push message.
+         */
+        urgency?: PushOptions['urgency'];
+    }>;
+}
+/**
+ * Represents the data contained in a JSON Web Token (JWT).
+ */
+export interface JwtData {
+    /**
+     * The audience for the JWT, typically the origin of the push service.
+     */
+    aud: string;
+    /**
+     * The expiration time of the JWT, in seconds.
+     * This prevents reuse of the JWT after it has expired.
+     * The `exp` value must not exceed 24 hours from the time of the request.
+     * If it does, the push service (like FCM) will reject the request with a 403 Forbidden error.
+     */
+    exp: number;
+    /**
+     * The subject of the JWT, which should be a URL or a mailto email address.
+     * This is used for contact information if the push service needs to reach out to the sender.
+     */
+    sub: string;
+}
+/**
+ * Options for configuring a push notification.
+ */
+export interface PushOptions {
+    /**
+     * The JSON Web Key (JWK) used for signing the push notification.
+     */
+    jwk: JsonWebKey;
+    /**
+     * The JWT data associated with the push notification.
+     */
+    jwt: JwtData;
+    /**
+     * The payload of the push notification, typically a string.
+     */
+    payload: string;
+    /**
+     * The time-to-live for the push notification in seconds.
+     * Must be a positive number greater than 0.
+     * Default value is 24 * 60 * 60 (24 hours).
+     * If set to 0, undefined, or a negative value, it will default to 24 hours.
+     * The VAPID JWT expiration claim (`exp`) must not exceed 24 hours from the time of the request.
+     * If it does, the push service (like FCM) will reject the request with a 403 Forbidden error.
+     */
+    ttl: number;
+    /**
+     * The topic of the push notification (optional).
+     */
+    topic?: string;
+    /**
+     * The urgency level of the push notification.
+     */
+    urgency?: 'very-low' | 'low' | 'normal' | 'high';
+}
+/**
+ * Represents the keys used for push subscription encryption.
+ */
+export interface PushSubscriptionKey {
+    /**
+     * The public key used for encrypting messages.
+     */
+    p256dh: string;
+    /**
+     * The authentication secret used for encrypting messages.
+     */
+    auth: string;
+}
+/**
+ * Represents a push subscription, which includes the endpoint and keys.
+ */
+export interface PushSubscription {
+    /**
+     * The endpoint URL for the push service to send notifications.
+     */
+    endpoint: string;
+    /**
+     * The keys used for encrypting message data sent with the push notification.
+     */
+    keys: PushSubscriptionKey;
+}

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/utils.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Represents any value that can be handled by JSON.stringify without loss.
+ * This includes primitive types such as strings, numbers, booleans, and null.
+ */
+export type JsonPrimitive = string | number | boolean | null;
+/**
+ * Represents a JSON-compatible value, which can be a primitive,
+ * an array of Jsonifiable values, or an object with string keys
+ * and Jsonifiable values.
+ */
+export type Jsonifiable = JsonPrimitive | Jsonifiable[] | {
+    [key: string]: Jsonifiable;
+};
+/**
+ * A utility type that requires at least one of the specified keys from type T.
+ * This is useful for creating types that enforce the presence of certain properties
+ * while allowing others to be optional.
+ *
+ * @template T - The base type from which keys are required.
+ * @template Keys - The keys of T that are required.
+ */
+export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = {
+    [K in Keys]: Required<Pick<T, K>> & Partial<Omit<T, K>>;
+}[Keys] & Omit<T, Keys>;
+/**
+ * Converts an ArrayBuffer or Uint8Array to a string.
+ *
+ * @param {ArrayBuffer | Uint8Array} s - The input array to convert.
+ * @returns {string} The resulting string representation of the input.
+ */
+export declare const stringFromArrayBuffer: (s: ArrayBuffer | Uint8Array) => string;
+/**
+ * Cross-platform function to decode a Base64 string into a binary string.
+ * Works in both browser and Node.js environments.
+ *
+ * @param {string} base64String - The Base64 encoded string to decode.
+ * @returns {string} The decoded binary string.
+ */
+export declare const base64Decode: (base64String: string) => string;
+/**
+ * Extracts the public key from a JSON Web Key (JWK) and encodes it in base64 URL format.
+ *
+ * @param {JsonWebKey} jwk - The JSON Web Key from which to extract the public key.
+ * @returns {string} The base64 URL encoded public key.
+ */
+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.
+ */
+export declare const concatTypedArrays: (arrays: Uint8Array[]) => Uint8Array;

package/dist/lib/utils.js

@@ -0,0 +1,74 @@
+import { base64UrlDecodeString, base64UrlEncode } from './base64.js';
+/**
+ * Converts an ArrayBuffer or Uint8Array to a string.
+ *
+ * @param {ArrayBuffer | Uint8Array} s - The input array to convert.
+ * @returns {string} The resulting string representation of the input.
+ */
+export const stringFromArrayBuffer = (s) => {
+    let result = '';
+    for (const code of new Uint8Array(s))
+        result += String.fromCharCode(code);
+    return result;
+};
+/**
+ * Cross-platform function to decode a Base64 string into a binary string.
+ * Works in both browser and Node.js environments.
+ *
+ * @param {string} base64String - The Base64 encoded string to decode.
+ * @returns {string} The decoded binary string.
+ */
+export const base64Decode = (base64String) => {
+    // Add padding if needed
+    const paddedBase64 = base64String.padEnd(base64String.length + ((4 - (base64String.length % 4 || 4)) % 4), '=');
+    // Node.js environment
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(paddedBase64, 'base64').toString('binary');
+    }
+    // Browser environment
+    if (typeof atob === 'function') {
+        return atob(paddedBase64);
+    }
+    // Pure JavaScript implementation for environments without atob or Buffer
+    const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=';
+    let result = '';
+    let i = 0;
+    while (i < paddedBase64.length) {
+        const enc1 = characters.indexOf(paddedBase64.charAt(i++));
+        const enc2 = characters.indexOf(paddedBase64.charAt(i++));
+        const enc3 = characters.indexOf(paddedBase64.charAt(i++));
+        const enc4 = characters.indexOf(paddedBase64.charAt(i++));
+        const char1 = (enc1 << 2) | (enc2 >> 4);
+        const char2 = ((enc2 & 15) << 4) | (enc3 >> 2);
+        const char3 = ((enc3 & 3) << 6) | enc4;
+        result += String.fromCharCode(char1);
+        if (enc3 !== 64)
+            result += String.fromCharCode(char2);
+        if (enc4 !== 64)
+            result += String.fromCharCode(char3);
+    }
+    return result;
+};
+/**
+ * Extracts the public key from a JSON Web Key (JWK) and encodes it in base64 URL format.
+ *
+ * @param {JsonWebKey} jwk - The JSON Web Key from which to extract the public key.
+ * @returns {string} The base64 URL encoded public key.
+ */
+export const getPublicKeyFromJwk = (jwk) => base64UrlEncode(`\x04${base64Decode(base64UrlDecodeString(jwk.x))}${base64Decode(base64UrlDecodeString(jwk.y))}`);
+/**
+ * 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.
+ */
+export const concatTypedArrays = (arrays) => {
+    const length = arrays.reduce((accumulator, current) => accumulator + current.byteLength, 0);
+    let index = 0;
+    const targetArray = new Uint8Array(length);
+    for (const array of arrays) {
+        targetArray.set(array, index);
+        index += array.byteLength;
+    }
+    return targetArray;
+};

package/dist/lib/vapid.d.ts

@@ -0,0 +1,16 @@
+import type { PushOptions } from './types.js';
+/**
+ * Constructs the VAPID headers for a push notification request.
+ *
+ * This function generates the necessary headers for sending a push notification
+ * using the VAPID protocol, including authentication and encryption information.
+ *
+ * @param {PushOptions} options - The options for the push notification, including the JSON Web Key (JWK) and JWT data.
+ * @param {number} payloadLength - The length of the payload being sent in the push notification.
+ * @param {Uint8Array} salt - A salt value used in the encryption process.
+ * @param {CryptoKey} localPublicKey - The local public key used for encryption.
+ * @returns {Promise<Record<string, string> | Headers>} A promise that resolves to an object containing the VAPID headers.
+ *
+ * @throws {Error} Throws an error if the JWT creation fails or if key export fails.
+ */
+export declare const vapidHeaders: (options: PushOptions, payloadLength: number, salt: Uint8Array, localPublicKey: CryptoKey) => Promise<Record<string, string> | Headers>;

package/dist/lib/vapid.js

@@ -0,0 +1,54 @@
+import { base64UrlEncode } from './base64.js';
+import { crypto } from './crypto.js';
+import { createJwt } from './jwt.js';
+import { getPublicKeyFromJwk } from './utils.js';
+/**
+ * Constructs the VAPID headers for a push notification request.
+ *
+ * This function generates the necessary headers for sending a push notification
+ * using the VAPID protocol, including authentication and encryption information.
+ *
+ * @param {PushOptions} options - The options for the push notification, including the JSON Web Key (JWK) and JWT data.
+ * @param {number} payloadLength - The length of the payload being sent in the push notification.
+ * @param {Uint8Array} salt - A salt value used in the encryption process.
+ * @param {CryptoKey} localPublicKey - The local public key used for encryption.
+ * @returns {Promise<Record<string, string> | Headers>} A promise that resolves to an object containing the VAPID headers.
+ *
+ * @throws {Error} Throws an error if the JWT creation fails or if key export fails.
+ */
+export const vapidHeaders = async (options, payloadLength, salt, localPublicKey) => {
+    // Export the local public key to a raw format and encode it in Base64 URL format
+    const localPublicKeyBase64 = await crypto.subtle
+        .exportKey('raw', localPublicKey)
+        .then((bytes) => base64UrlEncode(bytes));
+    // Get the server public key from the JWK
+    const serverPublicKey = getPublicKeyFromJwk(options.jwk);
+    // Create the JWT for authentication
+    const jwt = await createJwt(options.jwk, options.jwt);
+    // Construct the header values for the VAPID request
+    const headerValues = {
+        Encryption: `salt=${base64UrlEncode(salt)}`,
+        'Crypto-Key': `dh=${localPublicKeyBase64}`,
+        'Content-Length': payloadLength.toString(),
+        'Content-Type': 'application/octet-stream',
+        'Content-Encoding': 'aesgcm',
+        Authorization: `vapid t=${jwt}, k=${serverPublicKey}`,
+    };
+    let headers;
+    // Add optional headers if they are defined
+    if (options.ttl !== undefined)
+        headerValues.TTL = options.ttl.toString();
+    if (options.topic !== undefined)
+        headerValues.Topic = options.topic;
+    if (options.urgency !== undefined)
+        headerValues.Urgency = options.urgency;
+    // Create Headers object if available (for browser or Node.js 18+)
+    if (typeof Headers !== 'undefined') {
+        headers = new Headers(headerValues);
+    }
+    else {
+        // Fallback for Node.js < 18 without polyfill
+        headers = headerValues;
+    }
+    return headers; // Return the constructed headers
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@pushforge/builder",
+  "version": "1.0.0",
+  "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",
+  "module": "dist/lib/main.js",
+  "types": "dist/lib/main.d.ts",
+  "author": "David Raphi",
+  "bugs": {
+    "url": "https://github.com/draphy/pushforge/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/draphy/pushforge"
+  },
+  "homepage": "https://github.com/draphy/pushforge",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/lib/main.d.ts",
+      "default": "./dist/lib/main.js"
+    }
+  },
+  "files": [
+    "dist/lib/**/*.js",
+    "dist/lib/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "semantic-release": "semantic-release"
+  },
+  "bin": {
+    "generate-vapid-keys": "./dist/lib/commandLine/keys.js"
+  },
+  "devDependencies": {
+    "@semantic-release/commit-analyzer": "^11.1.0",
+    "@semantic-release/github": "^9.2.6",
+    "@semantic-release/npm": "^11.0.3",
+    "@semantic-release/release-notes-generator": "^12.1.0",
+    "@types/node": "^22.14.1",
+    "semantic-release": "^24.2.3",
+    "vitest": "^3.1.2"
+  },
+  "keywords": [
+    "web-push",
+    "webcrypto",
+    "vapid",
+    "web-push-protocol",
+    "typescript",
+    "node",
+    "cloudflare",
+    "browser",
+    "ecdh",
+    "hkdf",
+    "push-service"
+  ]
+}