@djangocfg/crypto 2.1.111

package/src/index.ts

@@ -0,0 +1,66 @@
+/**
+ * @djangocfg/crypto
+ *
+ * Client-side AES-256-GCM decryption for Django-CFG encrypted API responses.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - decrypt a single field
+ * import { createDecryptionClient } from '@djangocfg/crypto';
+ *
+ * const crypto = await createDecryptionClient({
+ *   secretKey: 'your-django-secret-key',
+ *   userId: 123  // optional, for per-user encryption
+ * });
+ *
+ * const response = await fetch('/api/products/?encrypt=true');
+ * const data = await crypto.decryptObject(await response.json());
+ * console.log(data.price); // decrypted value
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // React usage
+ * import { useDecrypt } from '@djangocfg/crypto/react';
+ *
+ * function ProductPrice({ product }) {
+ *   const { data, isLoading } = useDecrypt(product, {
+ *     secretKey: process.env.NEXT_PUBLIC_DECRYPT_KEY!
+ *   });
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   return <span>{data.price}</span>;
+ * }
+ * ```
+ */
+
+// Types
+export type {
+  EncryptedField,
+  EncryptedResponse,
+  DecryptionConfig,
+  DecryptionResult,
+  DecryptionError,
+} from './types';
+
+export { isEncryptedField, isEncryptedResponse } from './types';
+
+// Key derivation
+export {
+  deriveKey,
+  deriveKeyBytes,
+  deriveKeyFromConfig,
+  buildSalt,
+} from './key-derivation';
+
+// Decryption
+export {
+  decryptAES256GCM,
+  decryptField,
+  decryptResponse,
+  decryptObject,
+  createDecryptionClient,
+  safeDecrypt,
+} from './decryption';

package/src/key-derivation.ts

@@ -0,0 +1,168 @@
+/**
+ * PBKDF2 key derivation using Web Crypto API.
+ *
+ * Matches Django-CFG backend key derivation for decryption compatibility.
+ */
+
+/**
+ * Derive an encryption key using PBKDF2.
+ *
+ * Uses Web Crypto API for secure key derivation that matches
+ * the Django-CFG backend implementation.
+ *
+ * @param password - The password/secret key to derive from
+ * @param salt - Salt bytes for key derivation
+ * @param iterations - Number of PBKDF2 iterations (default: 100000)
+ * @param keyLength - Desired key length in bytes (default: 32 for AES-256)
+ * @returns Promise resolving to derived key as CryptoKey
+ *
+ * @example
+ * ```typescript
+ * const salt = new TextEncoder().encode('my-salt');
+ * const key = await deriveKey('secret', salt, 100000);
+ * ```
+ */
+export async function deriveKey(
+  password: string,
+  salt: Uint8Array,
+  iterations: number = 100000,
+  keyLength: number = 32
+): Promise<CryptoKey> {
+  const encoder = new TextEncoder();
+  const passwordBuffer = encoder.encode(password);
+
+  // Import password as raw key material
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    passwordBuffer,
+    'PBKDF2',
+    false,
+    ['deriveBits', 'deriveKey']
+  );
+
+  // Derive AES-GCM key using PBKDF2
+  return crypto.subtle.deriveKey(
+    {
+      name: 'PBKDF2',
+      salt: salt.buffer as ArrayBuffer,
+      iterations: iterations,
+      hash: 'SHA-256',
+    },
+    keyMaterial,
+    { name: 'AES-GCM', length: keyLength * 8 },
+    false,
+    ['decrypt']
+  );
+}
+
+/**
+ * Derive raw key bytes using PBKDF2.
+ *
+ * @param password - The password/secret key to derive from
+ * @param salt - Salt bytes for key derivation
+ * @param iterations - Number of PBKDF2 iterations (default: 100000)
+ * @param keyLength - Desired key length in bytes (default: 32 for AES-256)
+ * @returns Promise resolving to derived key as Uint8Array
+ */
+export async function deriveKeyBytes(
+  password: string,
+  salt: Uint8Array,
+  iterations: number = 100000,
+  keyLength: number = 32
+): Promise<Uint8Array> {
+  const encoder = new TextEncoder();
+  const passwordBuffer = encoder.encode(password);
+
+  // Import password as raw key material
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    passwordBuffer,
+    'PBKDF2',
+    false,
+    ['deriveBits']
+  );
+
+  // Derive raw bits
+  const keyBits = await crypto.subtle.deriveBits(
+    {
+      name: 'PBKDF2',
+      salt: salt.buffer as ArrayBuffer,
+      iterations: iterations,
+      hash: 'SHA-256',
+    },
+    keyMaterial,
+    keyLength * 8
+  );
+
+  return new Uint8Array(keyBits);
+}
+
+/**
+ * Build a deterministic salt from context components.
+ *
+ * Matches Django-CFG backend salt generation for key derivation.
+ *
+ * @param keyPrefix - Key prefix (default: "djangocfg_encryption")
+ * @param userId - Optional user ID for per-user keys
+ * @param sessionId - Optional session ID for per-session keys
+ * @returns Salt as Uint8Array (first 16 bytes of SHA-256 hash)
+ */
+export async function buildSalt(
+  keyPrefix: string = 'djangocfg_encryption',
+  userId?: string | number,
+  sessionId?: string
+): Promise<Uint8Array> {
+  const parts = [keyPrefix];
+
+  if (sessionId) {
+    parts.push(`session:${sessionId}`);
+  } else if (userId !== undefined) {
+    parts.push(`user:${userId}`);
+  } else {
+    parts.push('global');
+  }
+
+  const saltInput = parts.join(':');
+  const encoder = new TextEncoder();
+  const inputBuffer = encoder.encode(saltInput);
+
+  // SHA-256 hash and take first 16 bytes
+  const hashBuffer = await crypto.subtle.digest('SHA-256', inputBuffer);
+  return new Uint8Array(hashBuffer).slice(0, 16);
+}
+
+/**
+ * Derive encryption key from Django-CFG config.
+ *
+ * Convenience function that matches backend key derivation.
+ *
+ * @param config - Configuration object with secretKey and optional context
+ * @returns Promise resolving to CryptoKey for decryption
+ *
+ * @example
+ * ```typescript
+ * const key = await deriveKeyFromConfig({
+ *   secretKey: 'django-secret-key',
+ *   userId: 123,
+ *   iterations: 100000
+ * });
+ * ```
+ */
+export async function deriveKeyFromConfig(config: {
+  secretKey: string;
+  userId?: string | number;
+  sessionId?: string;
+  iterations?: number;
+  keyPrefix?: string;
+}): Promise<CryptoKey> {
+  const {
+    secretKey,
+    userId,
+    sessionId,
+    iterations = 100000,
+    keyPrefix = 'djangocfg_encryption',
+  } = config;
+
+  const salt = await buildSalt(keyPrefix, userId, sessionId);
+  return deriveKey(secretKey, salt, iterations);
+}

package/src/react/hooks.ts

@@ -0,0 +1,236 @@
+/**
+ * React hooks for Django-CFG encryption.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { DecryptionConfig, EncryptedField } from '../types';
+import { isEncryptedField } from '../types';
+import { createDecryptionClient, decryptObject } from '../decryption';
+import { deriveKeyFromConfig } from '../key-derivation';
+
+/**
+ * Hook state for decryption operations.
+ */
+interface UseDecryptState<T> {
+  /** Decrypted data */
+  data: T | undefined;
+  /** Loading state */
+  isLoading: boolean;
+  /** Error if decryption failed */
+  error: Error | undefined;
+  /** Whether data has been decrypted */
+  isDecrypted: boolean;
+}
+
+/**
+ * Hook to decrypt data on mount or when dependencies change.
+ *
+ * @param encryptedData - Data potentially containing encrypted fields
+ * @param config - Decryption configuration
+ * @returns Decrypted data state
+ *
+ * @example
+ * ```typescript
+ * function ProductPrice({ product }: { product: Product }) {
+ *   const { data, isLoading, error } = useDecrypt(product, {
+ *     secretKey: process.env.NEXT_PUBLIC_DECRYPT_KEY!,
+ *     userId: user.id
+ *   });
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   if (error) return <ErrorMessage error={error} />;
+ *   return <span>{data.price}</span>;
+ * }
+ * ```
+ */
+export function useDecrypt<T>(
+  encryptedData: unknown,
+  config: DecryptionConfig
+): UseDecryptState<T> {
+  const [state, setState] = useState<UseDecryptState<T>>({
+    data: undefined,
+    isLoading: true,
+    error: undefined,
+    isDecrypted: false,
+  });
+
+  // Cache the key to avoid re-deriving on every render
+  const keyRef = useRef<CryptoKey | null>(null);
+  const configRef = useRef(config);
+
+  // Check if config changed
+  const configChanged =
+    configRef.current.secretKey !== config.secretKey ||
+    configRef.current.userId !== config.userId ||
+    configRef.current.sessionId !== config.sessionId;
+
+  if (configChanged) {
+    configRef.current = config;
+    keyRef.current = null;
+  }
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function decrypt() {
+      try {
+        setState((s) => ({ ...s, isLoading: true, error: undefined }));
+
+        // Get or derive key
+        if (!keyRef.current) {
+          keyRef.current = await deriveKeyFromConfig(config);
+        }
+
+        const decrypted = await decryptObject<T>(encryptedData, keyRef.current);
+
+        if (!cancelled) {
+          setState({
+            data: decrypted,
+            isLoading: false,
+            error: undefined,
+            isDecrypted: true,
+          });
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setState({
+            data: undefined,
+            isLoading: false,
+            error: err instanceof Error ? err : new Error('Decryption failed'),
+            isDecrypted: false,
+          });
+        }
+      }
+    }
+
+    decrypt();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [encryptedData, config.secretKey, config.userId, config.sessionId]);
+
+  return state;
+}
+
+/**
+ * Hook to create a memoized decryption client.
+ *
+ * @param config - Decryption configuration
+ * @returns Decryption client or undefined while loading
+ *
+ * @example
+ * ```typescript
+ * function App() {
+ *   const crypto = useDecryptionClient({
+ *     secretKey: process.env.NEXT_PUBLIC_DECRYPT_KEY!
+ *   });
+ *
+ *   const handleFetch = async () => {
+ *     const response = await fetch('/api/products/?encrypt=true');
+ *     const data = await response.json();
+ *     const decrypted = await crypto?.decryptObject(data);
+ *   };
+ * }
+ * ```
+ */
+export function useDecryptionClient(config: DecryptionConfig) {
+  const [client, setClient] = useState<Awaited<
+    ReturnType<typeof createDecryptionClient>
+  > | null>(null);
+
+  useEffect(() => {
+    createDecryptionClient(config).then(setClient);
+  }, [config.secretKey, config.userId, config.sessionId]);
+
+  return client;
+}
+
+/**
+ * Hook for lazy decryption with manual trigger.
+ *
+ * @param config - Decryption configuration
+ * @returns Decrypt function and state
+ *
+ * @example
+ * ```typescript
+ * function LazyProduct({ product }: { product: Product }) {
+ *   const { decrypt, data, isLoading } = useLazyDecrypt({
+ *     secretKey: process.env.NEXT_PUBLIC_DECRYPT_KEY!
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => decrypt(product)}>Show Price</button>
+ *       {isLoading && <Spinner />}
+ *       {data && <span>{data.price}</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useLazyDecrypt<T>(config: DecryptionConfig) {
+  const [state, setState] = useState<UseDecryptState<T>>({
+    data: undefined,
+    isLoading: false,
+    error: undefined,
+    isDecrypted: false,
+  });
+
+  const keyRef = useRef<CryptoKey | null>(null);
+
+  const decrypt = useCallback(
+    async (encryptedData: unknown): Promise<T | undefined> => {
+      try {
+        setState((s) => ({ ...s, isLoading: true, error: undefined }));
+
+        if (!keyRef.current) {
+          keyRef.current = await deriveKeyFromConfig(config);
+        }
+
+        const decrypted = await decryptObject<T>(encryptedData, keyRef.current);
+
+        setState({
+          data: decrypted,
+          isLoading: false,
+          error: undefined,
+          isDecrypted: true,
+        });
+
+        return decrypted;
+      } catch (err) {
+        const error =
+          err instanceof Error ? err : new Error('Decryption failed');
+        setState({
+          data: undefined,
+          isLoading: false,
+          error,
+          isDecrypted: false,
+        });
+        return undefined;
+      }
+    },
+    [config.secretKey, config.userId, config.sessionId]
+  );
+
+  const reset = useCallback(() => {
+    setState({
+      data: undefined,
+      isLoading: false,
+      error: undefined,
+      isDecrypted: false,
+    });
+  }, []);
+
+  return { ...state, decrypt, reset };
+}
+
+/**
+ * Hook to check if a value needs decryption.
+ *
+ * @param value - Value to check
+ * @returns Whether the value is encrypted
+ */
+export function useIsEncrypted(value: unknown): boolean {
+  return useMemo(() => isEncryptedField(value), [value]);
+}

package/src/react/index.ts

@@ -0,0 +1,21 @@
+/**
+ * React integration for @djangocfg/crypto.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  useDecrypt,
+  useDecryptionClient,
+  useLazyDecrypt,
+  useIsEncrypted,
+} from './hooks';
+
+// Re-export types for convenience
+export type {
+  DecryptionConfig,
+  DecryptionResult,
+  DecryptionError,
+  EncryptedField,
+  EncryptedResponse,
+} from '../types';

package/src/types.ts

@@ -0,0 +1,159 @@
+/**
+ * TypeScript interfaces for Django-CFG encryption.
+ *
+ * These types match the encrypted response format from Django-CFG backend.
+ */
+
+/**
+ * Encrypted field envelope returned by Django-CFG API.
+ *
+ * When a serializer field is encrypted, it returns this structure
+ * instead of the plain value.
+ *
+ * @example
+ * ```json
+ * {
+ *   "encrypted": true,
+ *   "field": "price",
+ *   "algorithm": "AES-256-GCM",
+ *   "iv": "base64...",
+ *   "data": "base64...",
+ *   "auth_tag": "base64..."
+ * }
+ * ```
+ */
+export interface EncryptedField {
+  /** Always true for encrypted fields */
+  encrypted: true;
+  /** Field name that was encrypted */
+  field?: string;
+  /** Encryption algorithm used */
+  algorithm: 'AES-256-GCM' | 'AES-256-CBC';
+  /** Base64-encoded initialization vector */
+  iv: string;
+  /** Base64-encoded ciphertext */
+  data: string;
+  /** Base64-encoded authentication tag (GCM only) */
+  auth_tag: string;
+}
+
+/**
+ * Full encrypted response envelope.
+ *
+ * When response-level encryption is enabled, the entire response
+ * body is wrapped in this structure.
+ *
+ * @example
+ * ```json
+ * {
+ *   "encrypted": true,
+ *   "algorithm": "AES-256-GCM",
+ *   "salt": "base64...",
+ *   "iv": "base64...",
+ *   "data": "base64...",
+ *   "auth_tag": "base64..."
+ * }
+ * ```
+ */
+export interface EncryptedResponse {
+  /** Always true for encrypted responses */
+  encrypted: true;
+  /** Encryption algorithm used */
+  algorithm: 'AES-256-GCM' | 'AES-256-CBC';
+  /** Base64-encoded salt for key derivation */
+  salt: string;
+  /** Base64-encoded initialization vector */
+  iv: string;
+  /** Base64-encoded ciphertext */
+  data: string;
+  /** Base64-encoded authentication tag (GCM only) */
+  auth_tag: string;
+}
+
+/**
+ * Configuration for the decryption client.
+ */
+export interface DecryptionConfig {
+  /**
+   * Secret key for key derivation.
+   * Should match the Django SECRET_KEY or a derived key.
+   */
+  secretKey: string;
+
+  /**
+   * User ID for per-user key derivation (optional).
+   * When provided, keys are derived per-user for isolation.
+   */
+  userId?: string | number;
+
+  /**
+   * Session ID for per-session key derivation (optional).
+   * Takes precedence over userId if both provided.
+   */
+  sessionId?: string;
+
+  /**
+   * Number of PBKDF2 iterations (default: 100000).
+   * Must match backend configuration.
+   */
+  iterations?: number;
+
+  /**
+   * Key prefix for derivation (default: "djangocfg_encryption").
+   * Must match backend configuration.
+   */
+  keyPrefix?: string;
+}
+
+/**
+ * Result of a decryption operation.
+ */
+export interface DecryptionResult<T = unknown> {
+  /** Decrypted data */
+  data: T;
+  /** Whether decryption was successful */
+  success: true;
+}
+
+/**
+ * Error from a decryption operation.
+ */
+export interface DecryptionError {
+  /** Error message */
+  message: string;
+  /** Error code */
+  code: 'INVALID_FORMAT' | 'DECRYPTION_FAILED' | 'AUTH_FAILED' | 'KEY_ERROR';
+  /** Whether decryption was successful */
+  success: false;
+}
+
+/**
+ * Type guard to check if a value is an encrypted field.
+ */
+export function isEncryptedField(value: unknown): value is EncryptedField {
+  if (typeof value !== 'object' || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    obj.encrypted === true &&
+    typeof obj.algorithm === 'string' &&
+    typeof obj.iv === 'string' &&
+    typeof obj.data === 'string' &&
+    typeof obj.auth_tag === 'string'
+  );
+}
+
+/**
+ * Type guard to check if a value is an encrypted response.
+ */
+export function isEncryptedResponse(value: unknown): value is EncryptedResponse {
+  if (typeof value !== 'object' || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    obj.encrypted === true &&
+    typeof obj.algorithm === 'string' &&
+    typeof obj.salt === 'string' &&
+    typeof obj.iv === 'string' &&
+    typeof obj.data === 'string' &&
+    typeof obj.auth_tag === 'string'
+  );
+}