@djangocfg/crypto 2.1.111

package/dist/react.d.cts

@@ -0,0 +1,234 @@
+/**
+ * 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..."
+ * }
+ * ```
+ */
+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..."
+ * }
+ * ```
+ */
+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.
+ */
+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.
+ */
+interface DecryptionResult<T = unknown> {
+    /** Decrypted data */
+    data: T;
+    /** Whether decryption was successful */
+    success: true;
+}
+/**
+ * Error from a decryption operation.
+ */
+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.
+ */
+declare function isEncryptedField(value: unknown): value is EncryptedField;
+/**
+ * Type guard to check if a value is an encrypted response.
+ */
+declare function isEncryptedResponse(value: unknown): value is EncryptedResponse;
+
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useDecrypt<T>(encryptedData: unknown, config: DecryptionConfig): UseDecryptState<T>;
+/**
+ * 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);
+ *   };
+ * }
+ * ```
+ */
+declare function useDecryptionClient(config: DecryptionConfig): {
+    decryptField: <T = unknown>(field: EncryptedField) => Promise<T>;
+    decryptObject: <T>(data: unknown) => Promise<T>;
+    isEncryptedField: typeof isEncryptedField;
+    isEncryptedResponse: typeof isEncryptedResponse;
+} | null;
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+declare function useLazyDecrypt<T>(config: DecryptionConfig): {
+    decrypt: (encryptedData: unknown) => Promise<T | undefined>;
+    reset: () => void;
+    /** 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 check if a value needs decryption.
+ *
+ * @param value - Value to check
+ * @returns Whether the value is encrypted
+ */
+declare function useIsEncrypted(value: unknown): boolean;
+
+export { type DecryptionConfig, type DecryptionError, type DecryptionResult, type EncryptedField, type EncryptedResponse, useDecrypt, useDecryptionClient, useIsEncrypted, useLazyDecrypt };

package/dist/react.d.ts

@@ -0,0 +1,234 @@
+/**
+ * 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..."
+ * }
+ * ```
+ */
+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..."
+ * }
+ * ```
+ */
+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.
+ */
+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.
+ */
+interface DecryptionResult<T = unknown> {
+    /** Decrypted data */
+    data: T;
+    /** Whether decryption was successful */
+    success: true;
+}
+/**
+ * Error from a decryption operation.
+ */
+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.
+ */
+declare function isEncryptedField(value: unknown): value is EncryptedField;
+/**
+ * Type guard to check if a value is an encrypted response.
+ */
+declare function isEncryptedResponse(value: unknown): value is EncryptedResponse;
+
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useDecrypt<T>(encryptedData: unknown, config: DecryptionConfig): UseDecryptState<T>;
+/**
+ * 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);
+ *   };
+ * }
+ * ```
+ */
+declare function useDecryptionClient(config: DecryptionConfig): {
+    decryptField: <T = unknown>(field: EncryptedField) => Promise<T>;
+    decryptObject: <T>(data: unknown) => Promise<T>;
+    isEncryptedField: typeof isEncryptedField;
+    isEncryptedResponse: typeof isEncryptedResponse;
+} | null;
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+declare function useLazyDecrypt<T>(config: DecryptionConfig): {
+    decrypt: (encryptedData: unknown) => Promise<T | undefined>;
+    reset: () => void;
+    /** 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 check if a value needs decryption.
+ *
+ * @param value - Value to check
+ * @returns Whether the value is encrypted
+ */
+declare function useIsEncrypted(value: unknown): boolean;
+
+export { type DecryptionConfig, type DecryptionError, type DecryptionResult, type EncryptedField, type EncryptedResponse, useDecrypt, useDecryptionClient, useIsEncrypted, useLazyDecrypt };