/**
 * 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'
  );
}