@djangocfg/crypto

Client-side AES-256-GCM decryption for Django-CFG encrypted API responses using Web Crypto API.

Installation

``bash
pnpm add @djangocfg/crypto
`

Features

- AES-256-GCM authenticated decryption
- PBKDF2 key derivation (matches Django-CFG backend)
- Zero dependencies (uses native Web Crypto API)
- TypeScript support with full type inference
- React hooks for declarative decryption
- Per-user and per-session key isolation

Usage

$3

`typescript
import { createDecryptionClient } from '@djangocfg/crypto';

// Create a decryption client
const crypto = await createDecryptionClient({
secretKey: 'your-django-secret-key',
userId: 123, // optional, for per-user encryption
});

// Fetch encrypted data
const response = await fetch('/api/products/?encrypt=true');
const encryptedData = await response.json();

// Decrypt all encrypted fields
const data = await crypto.decryptObject(encryptedData);
console.log(data.price); // decrypted value
`

$3

`typescript
import { useDecrypt } from '@djangocfg/crypto/react';

function ProductPrice({ product }: { product: Product }) {
const { data, isLoading, error } = useDecrypt(product, {
secretKey: process.env.NEXT_PUBLIC_DECRYPT_KEY!,
userId: user.id,
});

if (isLoading) return ;
if (error) return ;

return ${data.price};
}
`

$3

`typescript
import { useLazyDecrypt } from '@djangocfg/crypto/react';

function LazyProduct({ product }: { product: Product }) {
const { decrypt, data, isLoading } = useLazyDecrypt({
secretKey: process.env.NEXT_PUBLIC_DECRYPT_KEY!,
});

return (



);
}
`

API Reference

$3

#### createDecryptionClient(config)

Creates a decryption client with pre-derived key.

`typescript
const crypto = await createDecryptionClient({
secretKey: string; // Django SECRET_KEY
userId?: string|number; // Optional user ID
sessionId?: string; // Optional session ID
iterations?: number; // PBKDF2 iterations (default: 100000)
keyPrefix?: string; // Key prefix (default: "djangocfg_encryption")
});

// Methods
await crypto.decryptField(encryptedField); // Decrypt single field
await crypto.decryptObject(data); // Decrypt all fields recursively
crypto.isEncryptedField(value); // Type guard
`

#### decryptField(field, key)

Decrypt a single encrypted field.

#### decryptObject(data, key)

Recursively decrypt all encrypted fields in an object.

$3

#### useDecrypt(data, config)

Decrypt data on mount.

#### useDecryptionClient(config)

Create a memoized decryption client.

#### useLazyDecrypt(config)

Decrypt data on demand with manual trigger.

#### useIsEncrypted(value)

Check if a value is encrypted.

Types

`typescript
interface EncryptedField {
encrypted: true;
field?: string;
algorithm: 'AES-256-GCM';
iv: string; // base64
data: string; // base64
auth_tag: string; // base64
}

interface DecryptionConfig {
secretKey: string;
userId?: string | number;
sessionId?: string;
iterations?: number;
keyPrefix?: string;
}
`

Security Notes

- Never expose your Django SECRET_KEY` directly in frontend code
- Use a dedicated decryption key or derive one securely
- Consider per-user keys for sensitive data isolation
- PBKDF2 iterations must match backend configuration

License

MIT