feat: [WPN-16, WPN-15] VAPID JWT expiration claim issue and Test the methods in different environments for compatibility (#29)

Author: draphy

packages/builder/lib/jwt.ts

@@ -8,6 +8,11 @@ import type { JwtData } from './types.js';
  * 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.

packages/builder/lib/main.ts

@@ -1 +1,7 @@
-// This is the main page
+export type {
+  PushMessage,
+  PushSubscription,
+  BuilderOptions,
+  PushOptions,
+} from './types.js';
+export { buildPushHTTPRequest } from './request.js';

packages/builder/lib/request.ts

@@ -16,6 +16,46 @@ import { vapidHeaders } from './vapid.js';
  * @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,
@@ -30,11 +70,17 @@ export async function buildPushHTTPRequest({
   const jwk: JsonWebKey =
     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
-      : 24 * 60 * 60; // Default to 24 hours
+      : MAX_TTL; // Default to 24 hours
 
   // Create the JWT payload
   const jwt = {

packages/builder/lib/types.ts

@@ -43,6 +43,11 @@ export interface PushMessage<T extends Jsonifiable = Jsonifiable> {
   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'];
 
@@ -70,6 +75,8 @@ export interface JwtData {
   /**
    * 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;
 
@@ -104,6 +111,8 @@ export interface PushOptions {
    * 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;