@djangocfg/layouts 2.1.35 → 2.1.37

package/src/snippets/PWA/utils/vapid.ts

@@ -0,0 +1,226 @@
+/**
+ * VAPID Key Utilities
+ *
+ * Provides validation and conversion utilities for VAPID public keys
+ * used in push notification subscriptions.
+ *
+ * VAPID keys must be:
+ * - Base64url encoded
+ * - 65 bytes after decoding (P-256 uncompressed public key)
+ * - Start with 0x04 (uncompressed point indicator)
+ */
+
+/**
+ * Custom error class for VAPID key validation failures
+ */
+export class VapidKeyError extends Error {
+  constructor(
+    message: string,
+    public readonly code: VapidKeyErrorCode
+  ) {
+    super(message);
+    this.name = 'VapidKeyError';
+  }
+}
+
+/**
+ * Error codes for VAPID key validation
+ */
+export type VapidKeyErrorCode =
+  | 'VAPID_EMPTY'
+  | 'VAPID_INVALID_TYPE'
+  | 'VAPID_INVALID_BASE64'
+  | 'VAPID_INVALID_LENGTH'
+  | 'VAPID_INVALID_FORMAT';
+
+/**
+ * Convert base64url VAPID public key to Uint8Array
+ *
+ * Validates and converts a VAPID public key from base64url format
+ * to Uint8Array for use with PushManager.subscribe().
+ *
+ * @param base64String - VAPID public key in base64url format
+ * @returns Uint8Array ready for pushManager.subscribe()
+ * @throws VapidKeyError if key is invalid
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const key = urlBase64ToUint8Array(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY);
+ *   await registration.pushManager.subscribe({
+ *     userVisibleOnly: true,
+ *     applicationServerKey: key,
+ *   });
+ * } catch (e) {
+ *   if (e instanceof VapidKeyError) {
+ *     console.error('Invalid VAPID key:', e.message, e.code);
+ *   }
+ * }
+ * ```
+ */
+export function urlBase64ToUint8Array(base64String: string): Uint8Array {
+  // 1. Validate input
+  if (!base64String) {
+    throw new VapidKeyError('VAPID public key is required', 'VAPID_EMPTY');
+  }
+
+  if (typeof base64String !== 'string') {
+    throw new VapidKeyError('VAPID public key must be a string', 'VAPID_INVALID_TYPE');
+  }
+
+  // 2. Convert base64url to base64
+  // base64url uses '-' and '_' instead of '+' and '/'
+  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
+
+  // 3. Decode base64
+  let rawData: string;
+  try {
+    rawData = window.atob(base64);
+  } catch (e) {
+    throw new VapidKeyError(
+      `Invalid base64url format: ${e instanceof Error ? e.message : String(e)}`,
+      'VAPID_INVALID_BASE64'
+    );
+  }
+
+  // 4. Convert to Uint8Array
+  const outputArray = new Uint8Array(rawData.length);
+  for (let i = 0; i < rawData.length; i++) {
+    outputArray[i] = rawData.charCodeAt(i);
+  }
+
+  // 5. Validate length (P-256 uncompressed = 65 bytes)
+  // Format: 0x04 (1 byte) + X coordinate (32 bytes) + Y coordinate (32 bytes)
+  if (outputArray.length !== 65) {
+    throw new VapidKeyError(
+      `Invalid key length: expected 65 bytes (P-256 uncompressed), got ${outputArray.length} bytes`,
+      'VAPID_INVALID_LENGTH'
+    );
+  }
+
+  // 6. Validate format (must start with 0x04 for uncompressed P-256 point)
+  if (outputArray[0] !== 0x04) {
+    throw new VapidKeyError(
+      `Invalid key format: must start with 0x04 (uncompressed P-256 point), got 0x${outputArray[0]
+        .toString(16)
+        .padStart(2, '0')}`,
+      'VAPID_INVALID_FORMAT'
+    );
+  }
+
+  return outputArray;
+}
+
+/**
+ * Validate VAPID key without conversion
+ *
+ * Checks if a VAPID key is valid without converting it.
+ * Useful for validation before attempting subscription.
+ *
+ * @param base64String - VAPID public key to validate
+ * @returns true if key is valid
+ *
+ * @example
+ * ```typescript
+ * if (isValidVapidKey(vapidKey)) {
+ *   // Proceed with subscription
+ * } else {
+ *   console.error('Invalid VAPID key configuration');
+ * }
+ * ```
+ */
+export function isValidVapidKey(base64String: string): boolean {
+  try {
+    urlBase64ToUint8Array(base64String);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get VAPID key information for debugging
+ *
+ * Returns detailed information about a VAPID key for troubleshooting.
+ *
+ * @param base64String - VAPID public key to inspect
+ * @returns Key information object
+ *
+ * @example
+ * ```typescript
+ * const info = getVapidKeyInfo(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY);
+ * console.log('VAPID Key Info:', info);
+ * // {
+ * //   valid: true,
+ * //   length: 65,
+ * //   firstByte: '0x04',
+ * //   format: 'P-256 uncompressed'
+ * // }
+ * ```
+ */
+export function getVapidKeyInfo(base64String: string): {
+  valid: boolean;
+  length?: number;
+  firstByte?: string;
+  format?: string;
+  error?: string;
+  errorCode?: VapidKeyErrorCode;
+} {
+  try {
+    const key = urlBase64ToUint8Array(base64String);
+    return {
+      valid: true,
+      length: key.length,
+      firstByte: `0x${key[0].toString(16).padStart(2, '0')}`,
+      format: key[0] === 0x04 ? 'P-256 uncompressed' : 'Unknown',
+    };
+  } catch (e) {
+    if (e instanceof VapidKeyError) {
+      return {
+        valid: false,
+        error: e.message,
+        errorCode: e.code,
+      };
+    }
+    return {
+      valid: false,
+      error: String(e),
+    };
+  }
+}
+
+/**
+ * Safe VAPID key conversion with error handling
+ *
+ * Attempts to convert a VAPID key with detailed error logging.
+ * Returns null on failure instead of throwing.
+ *
+ * @param base64String - VAPID public key
+ * @param onError - Optional error callback
+ * @returns Uint8Array or null if conversion fails
+ *
+ * @example
+ * ```typescript
+ * const key = safeUrlBase64ToUint8Array(vapidKey, (error) => {
+ *   console.error('VAPID conversion failed:', error.message, error.code);
+ * });
+ *
+ * if (key) {
+ *   // Use key for subscription
+ * }
+ * ```
+ */
+export function safeUrlBase64ToUint8Array(
+  base64String: string,
+  onError?: (error: VapidKeyError) => void
+): Uint8Array | null {
+  try {
+    return urlBase64ToUint8Array(base64String);
+  } catch (e) {
+    if (e instanceof VapidKeyError) {
+      onError?.(e);
+    }
+    return null;
+  }
+}

package/src/snippets/index.ts

@@ -43,3 +43,33 @@ export type {
   UseMcpChatReturn,
   AskAIButtonProps,
 } from './McpChat';
+
+// PWA (Progressive Web App)
+export {
+  PwaProvider,
+  useInstall,
+  PushProvider,
+  usePush,
+  A2HSHint,
+  PushPrompt,
+  useIsPWA,
+  usePushNotifications,
+  DEFAULT_VAPID_PUBLIC_KEY,
+  clearAllPWAData,
+} from './PWA';
+export type {
+  PlatformInfo,
+  InstallPromptState,
+  BeforeInstallPromptEvent,
+  InstallOutcome,
+  IOSGuideState,
+  PushNotificationState,
+  PushNotificationOptions,
+  InstallContextType,
+  InstallManagerProps,
+  AndroidInstallButtonProps,
+  IOSGuideModalProps,
+  InstallStep,
+  PushMessage,
+  PushContextValue,
+} from './PWA';