feat: [WPN-11, WPN-12, WPN-13] Derive Encrypt payload methods using HKDF and ECDH (#24)

* feat: derive shared secret method

* feat: [WPN-12] Derive encoding and decoding methods for base64 which supports Browser and Node

* feat: [WPN-13] Derive methods to create JWT using ES256

* docs: updated the docs for jwt and formatting

* feat: [WPN-11, WPN-12, WPN-13] Derive Encrypt payload methods using HKDF and ECDH

Author: draphy

packages/builder/lib/base64.ts

@@ -0,0 +1,75 @@
+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: string | ArrayBuffer | Uint8Array,
+): string => {
+  // Convert input to string if it's binary
+  const text = typeof input === 'string' ? input : stringFromArrayBuffer(input);
+
+  // Use environment-specific encoding
+  let base64: string;
+  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: string | undefined): string => {
+  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: string): ArrayBuffer => {
+  // 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;
+};

packages/builder/lib/jwt.ts

@@ -0,0 +1,52 @@
+import { base64UrlEncode } from './base64.js';
+import { crypto } from './crypto.js';
+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.
+ *
+ * @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: JsonWebKey,
+  jwtData: JwtData,
+): Promise<string> => {
+  // 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}`;
+};

packages/builder/lib/payload.ts

@@ -0,0 +1,234 @@
+import {
+  base64UrlDecode,
+  base64UrlDecodeString,
+  base64UrlEncode,
+} from './base64.js';
+import { crypto } from './crypto.js';
+import { deriveSharedSecret } from './shared-secret.js';
+import type { PushSubscription, PushSubscriptionKey } from './types.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: PushSubscriptionKey,
+): Promise<{ auth: ArrayBuffer; p256: CryptoKey }> => {
+  const auth = base64UrlDecode(keys.auth);
+  if (auth.byteLength !== 16) {
+    throw new Error(
+      `Incorrect auth length, expected 16 bytes but got ${auth.byteLength}`,
+    );
+  }
+
+  let decodedKey: Uint8Array;
+  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: ArrayBuffer,
+  sharedSecret: CryptoKey,
+): Promise<CryptoKey> => {
+  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: CryptoKey,
+  localPublicKey: CryptoKey,
+): Promise<Uint8Array> => {
+  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: CryptoKey,
+  salt: Uint8Array,
+  context: Uint8Array,
+): Promise<ArrayBuffer> => {
+  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, // 12 bytes for the nonce
+  );
+};
+
+/**
+ * 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: CryptoKey,
+  salt: Uint8Array,
+  context: Uint8Array,
+): Promise<CryptoKey> => {
+  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, // 16 bytes for the AES-GCM key
+  );
+
+  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: Uint8Array): Uint8Array => {
+  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: CryptoKeyPair,
+  salt: Uint8Array,
+  payload: string,
+  target: PushSubscription,
+): Promise<ArrayBuffer> => {
+  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,
+  );
+};

packages/builder/lib/request.ts

@@ -1,4 +1,5 @@
 import { crypto } from './crypto.js';
+import { encryptPayload } from './payload.js';
 import type { BuilderOptions, PushOptions } from './types.js';
 
 /**
@@ -8,7 +9,6 @@ import type { BuilderOptions, PushOptions } from './types.js';
  * @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 {PushSubscription} options.subscription - The subscription details for the push notification.
- * @returns {Promise<Response>} A promise that resolves to the response of the HTTP request.
  *
  * @throws {Error} Throws an error if the privateJWK is invalid or if the request fails.
  */
@@ -50,4 +50,10 @@ export async function buildPushHTTPRequest({
     true,
     ['deriveBits'],
   );
+  const body = await encryptPayload(
+    localKeys,
+    salt,
+    options.payload,
+    subscription,
+  );
 }