@djangocfg/crypto 2.1.111

package/dist/index.d.cts

@@ -0,0 +1,297 @@
+/**
+ * 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;
+
+/**
+ * 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);
+ * ```
+ */
+declare function deriveKey(password: string, salt: Uint8Array, iterations?: number, keyLength?: number): Promise<CryptoKey>;
+/**
+ * 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
+ */
+declare function deriveKeyBytes(password: string, salt: Uint8Array, iterations?: number, keyLength?: number): Promise<Uint8Array>;
+/**
+ * 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)
+ */
+declare function buildSalt(keyPrefix?: string, userId?: string | number, sessionId?: string): Promise<Uint8Array>;
+/**
+ * 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
+ * });
+ * ```
+ */
+declare function deriveKeyFromConfig(config: {
+    secretKey: string;
+    userId?: string | number;
+    sessionId?: string;
+    iterations?: number;
+    keyPrefix?: string;
+}): Promise<CryptoKey>;
+
+/**
+ * AES-256-GCM decryption using Web Crypto API.
+ *
+ * Decrypts data encrypted by Django-CFG backend.
+ */
+
+/**
+ * Decrypt AES-256-GCM ciphertext.
+ *
+ * @param ciphertext - Encrypted data bytes
+ * @param key - CryptoKey for decryption
+ * @param iv - Initialization vector
+ * @param authTag - Authentication tag
+ * @returns Promise resolving to decrypted bytes
+ */
+declare function decryptAES256GCM(ciphertext: Uint8Array, key: CryptoKey, iv: Uint8Array, authTag: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decrypt a single encrypted field value.
+ *
+ * @param field - Encrypted field envelope
+ * @param key - CryptoKey for decryption
+ * @returns Promise resolving to decrypted value
+ *
+ * @example
+ * ```typescript
+ * const key = await deriveKeyFromConfig({ secretKey: '...' });
+ * const price = await decryptField(response.price, key);
+ * console.log(price); // 99.99
+ * ```
+ */
+declare function decryptField<T = unknown>(field: EncryptedField, key: CryptoKey): Promise<T>;
+/**
+ * Decrypt an entire encrypted response.
+ *
+ * @param response - Encrypted response envelope
+ * @param secretKey - Secret key for key derivation
+ * @param config - Additional config (userId, sessionId, etc.)
+ * @returns Promise resolving to decrypted response data
+ */
+declare function decryptResponse<T = unknown>(response: EncryptedResponse, secretKey: string, config?: Partial<Omit<DecryptionConfig, 'secretKey'>>): Promise<T>;
+/**
+ * Recursively decrypt all encrypted fields in an object.
+ *
+ * @param data - Object potentially containing encrypted fields
+ * @param key - CryptoKey for decryption
+ * @returns Promise resolving to object with all fields decrypted
+ *
+ * @example
+ * ```typescript
+ * const key = await deriveKeyFromConfig({ secretKey: '...' });
+ * const product = await decryptObject(response, key);
+ * // product.price is now decrypted
+ * ```
+ */
+declare function decryptObject<T>(data: unknown, key: CryptoKey): Promise<T>;
+/**
+ * Create a decryption client with pre-configured key.
+ *
+ * @param config - Decryption configuration
+ * @returns Object with decryption methods
+ *
+ * @example
+ * ```typescript
+ * const crypto = await createDecryptionClient({
+ *   secretKey: 'django-secret-key',
+ *   userId: currentUser.id
+ * });
+ *
+ * const response = await fetch('/api/products/?encrypt=true');
+ * const data = await crypto.decryptObject(await response.json());
+ * ```
+ */
+declare function createDecryptionClient(config: DecryptionConfig): Promise<{
+    /**
+     * Decrypt a single encrypted field.
+     */
+    decryptField: <T = unknown>(field: EncryptedField) => Promise<T>;
+    /**
+     * Recursively decrypt all encrypted fields in an object.
+     */
+    decryptObject: <T>(data: unknown) => Promise<T>;
+    /**
+     * Check if a value is an encrypted field.
+     */
+    isEncryptedField: typeof isEncryptedField;
+    /**
+     * Check if a value is an encrypted response.
+     */
+    isEncryptedResponse: typeof isEncryptedResponse;
+}>;
+/**
+ * Safe decryption wrapper that returns result or error.
+ *
+ * @param fn - Async function to execute
+ * @returns Promise resolving to DecryptionResult or DecryptionError
+ */
+declare function safeDecrypt<T>(fn: () => Promise<T>): Promise<DecryptionResult<T> | DecryptionError>;
+
+export { type DecryptionConfig, type DecryptionError, type DecryptionResult, type EncryptedField, type EncryptedResponse, buildSalt, createDecryptionClient, decryptAES256GCM, decryptField, decryptObject, decryptResponse, deriveKey, deriveKeyBytes, deriveKeyFromConfig, isEncryptedField, isEncryptedResponse, safeDecrypt };

package/dist/index.d.ts

@@ -0,0 +1,297 @@
+/**
+ * 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;
+
+/**
+ * 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);
+ * ```
+ */
+declare function deriveKey(password: string, salt: Uint8Array, iterations?: number, keyLength?: number): Promise<CryptoKey>;
+/**
+ * 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
+ */
+declare function deriveKeyBytes(password: string, salt: Uint8Array, iterations?: number, keyLength?: number): Promise<Uint8Array>;
+/**
+ * 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)
+ */
+declare function buildSalt(keyPrefix?: string, userId?: string | number, sessionId?: string): Promise<Uint8Array>;
+/**
+ * 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
+ * });
+ * ```
+ */
+declare function deriveKeyFromConfig(config: {
+    secretKey: string;
+    userId?: string | number;
+    sessionId?: string;
+    iterations?: number;
+    keyPrefix?: string;
+}): Promise<CryptoKey>;
+
+/**
+ * AES-256-GCM decryption using Web Crypto API.
+ *
+ * Decrypts data encrypted by Django-CFG backend.
+ */
+
+/**
+ * Decrypt AES-256-GCM ciphertext.
+ *
+ * @param ciphertext - Encrypted data bytes
+ * @param key - CryptoKey for decryption
+ * @param iv - Initialization vector
+ * @param authTag - Authentication tag
+ * @returns Promise resolving to decrypted bytes
+ */
+declare function decryptAES256GCM(ciphertext: Uint8Array, key: CryptoKey, iv: Uint8Array, authTag: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decrypt a single encrypted field value.
+ *
+ * @param field - Encrypted field envelope
+ * @param key - CryptoKey for decryption
+ * @returns Promise resolving to decrypted value
+ *
+ * @example
+ * ```typescript
+ * const key = await deriveKeyFromConfig({ secretKey: '...' });
+ * const price = await decryptField(response.price, key);
+ * console.log(price); // 99.99
+ * ```
+ */
+declare function decryptField<T = unknown>(field: EncryptedField, key: CryptoKey): Promise<T>;
+/**
+ * Decrypt an entire encrypted response.
+ *
+ * @param response - Encrypted response envelope
+ * @param secretKey - Secret key for key derivation
+ * @param config - Additional config (userId, sessionId, etc.)
+ * @returns Promise resolving to decrypted response data
+ */
+declare function decryptResponse<T = unknown>(response: EncryptedResponse, secretKey: string, config?: Partial<Omit<DecryptionConfig, 'secretKey'>>): Promise<T>;
+/**
+ * Recursively decrypt all encrypted fields in an object.
+ *
+ * @param data - Object potentially containing encrypted fields
+ * @param key - CryptoKey for decryption
+ * @returns Promise resolving to object with all fields decrypted
+ *
+ * @example
+ * ```typescript
+ * const key = await deriveKeyFromConfig({ secretKey: '...' });
+ * const product = await decryptObject(response, key);
+ * // product.price is now decrypted
+ * ```
+ */
+declare function decryptObject<T>(data: unknown, key: CryptoKey): Promise<T>;
+/**
+ * Create a decryption client with pre-configured key.
+ *
+ * @param config - Decryption configuration
+ * @returns Object with decryption methods
+ *
+ * @example
+ * ```typescript
+ * const crypto = await createDecryptionClient({
+ *   secretKey: 'django-secret-key',
+ *   userId: currentUser.id
+ * });
+ *
+ * const response = await fetch('/api/products/?encrypt=true');
+ * const data = await crypto.decryptObject(await response.json());
+ * ```
+ */
+declare function createDecryptionClient(config: DecryptionConfig): Promise<{
+    /**
+     * Decrypt a single encrypted field.
+     */
+    decryptField: <T = unknown>(field: EncryptedField) => Promise<T>;
+    /**
+     * Recursively decrypt all encrypted fields in an object.
+     */
+    decryptObject: <T>(data: unknown) => Promise<T>;
+    /**
+     * Check if a value is an encrypted field.
+     */
+    isEncryptedField: typeof isEncryptedField;
+    /**
+     * Check if a value is an encrypted response.
+     */
+    isEncryptedResponse: typeof isEncryptedResponse;
+}>;
+/**
+ * Safe decryption wrapper that returns result or error.
+ *
+ * @param fn - Async function to execute
+ * @returns Promise resolving to DecryptionResult or DecryptionError
+ */
+declare function safeDecrypt<T>(fn: () => Promise<T>): Promise<DecryptionResult<T> | DecryptionError>;
+
+export { type DecryptionConfig, type DecryptionError, type DecryptionResult, type EncryptedField, type EncryptedResponse, buildSalt, createDecryptionClient, decryptAES256GCM, decryptField, decryptObject, decryptResponse, deriveKey, deriveKeyBytes, deriveKeyFromConfig, isEncryptedField, isEncryptedResponse, safeDecrypt };