feat: [WPN-14] Derive methods to build headers for VAPID using JWT (#26)

Author: draphy

packages/builder/lib/request.ts

@@ -1,35 +1,49 @@
 import { crypto } from './crypto.js';
 import { encryptPayload } from './payload.js';
 import type { BuilderOptions, PushOptions } from './types.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 with user defined options.
+ * @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 or if the request fails.
+ * @throws {Error} Throws an error if the privateJWK is invalid, if the request fails, or if the payload encryption fails.
  */
 export async function buildPushHTTPRequest({
   privateJWK,
   message,
   subscription,
-}: BuilderOptions) {
+}: BuilderOptions): Promise<{
+  endpoint: string;
+  body: ArrayBuffer;
+  headers: Record<string, string> | Headers;
+}> {
+  // Parse the private JWK if it's a string
   const jwk: JsonWebKey =
     typeof privateJWK === 'string' ? JSON.parse(privateJWK) : privateJWK;
 
+  // Determine the time-to-live (TTL) for the push notification
   const ttl =
     message.options?.ttl && message.options.ttl > 0
       ? message.options.ttl
       : 24 * 60 * 60; // 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: PushOptions = {
     jwk,
     jwt,
@@ -43,17 +57,32 @@ export async function buildPushHTTPRequest({
     }),
   };
 
+  // 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 };
 }

packages/builder/lib/vapid.ts

@@ -0,0 +1,64 @@
+import { base64UrlEncode } from './base64.js';
+import { crypto } from './crypto.js';
+import { createJwt } from './jwt.js';
+import type { PushOptions } from './types.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: PushOptions,
+  payloadLength: number,
+  salt: Uint8Array,
+  localPublicKey: CryptoKey,
+) => {
+  // 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: Record<string, string> = {
+    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: Record<string, string> | 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
+};