@tantainnovative/ndpr-toolkit/dist/breach.d.mts

Nigeria Data Protection Toolkit — enterprise-grade compliance components for the Nigeria Data Protection Act (NDPA) 2023

import * as React_2 from 'react';
import React__default from 'react';

export declare const Breach: {
    Provider: React_2.FC<BreachProviderProps>;
    ReportForm: React_2.FC<BreachReportFormProps>;
    RiskAssessment: React_2.FC<BreachRiskAssessmentProps>;
    NotificationManager: React_2.FC<BreachNotificationManagerProps>;
    ReportGenerator: React_2.FC<RegulatoryReportGeneratorProps>;
};

/**
 * Breach notification types aligned with NDPA 2023 Section 40
 * Data controllers must notify the NDPC within 72 hours of becoming aware of a breach
 * Data subjects must be notified without undue delay when breach is likely to result in high risk
 */
/**
 * Represents a data breach category
 */
export declare interface BreachCategory {
    /** Unique identifier for the category */
    id: string;
    /** Display name for the category */
    name: string;
    /** Description of this breach category */
    description: string;
    /** Default severity level for this category */
    defaultSeverity: 'low' | 'medium' | 'high' | 'critical';
}

declare type BreachCompositeState = {
    reports: BreachReport[];
    assessments: RiskAssessment[];
    notifications: RegulatoryNotification[];
};

declare interface BreachContextValue extends UseBreachReturn {
    categories: BreachCategory[];
}

/**
 * Represents the data submitted by the breach report form.
 */
export declare interface BreachFormSubmission {
    /** Title/summary of the breach */
    title: string;
    /** Detailed description of the breach */
    description: string;
    /** Breach category identifier */
    category: string;
    /** Timestamp (ms) when the breach was discovered */
    discoveredAt: number;
    /** Timestamp (ms) when the breach occurred (if known) */
    occurredAt?: number;
    /** Timestamp (ms) when the form was submitted */
    reportedAt: number;
    /** Person reporting the breach */
    reporter: {
        name: string;
        email: string;
        department: string;
        phone?: string;
    };
    /** Systems or applications affected by the breach */
    affectedSystems: string[];
    /** Types of data involved in the breach */
    dataTypes: string[];
    /** Estimated number of affected data subjects */
    estimatedAffectedSubjects?: number;
    /**
     * Approximate number of personal data RECORDS concerned. Distinct from
     * subject count (one subject may have many records). NDPA Section 40(2).
     */
    approximateRecordCount?: number;
    /**
     * Categories of data subjects affected (e.g. customers, employees, minors).
     * NDPA Section 40(2).
     */
    dataSubjectCategories?: string[];
    /** Whether sensitive personal data (NDPA Section 30) is involved */
    involvesSensitiveData?: boolean;
    /**
     * Likely consequences of the breach for affected data subjects.
     * Required content for the NDPC report and Section 40(3) communications.
     */
    likelyConsequences?: string;
    /**
     * Measures taken or proposed to mitigate adverse effects.
     * NDPA Section 40(3).
     */
    mitigationMeasures?: string;
    /**
     * Data Protection Officer contact details (Section 32(3)(c) — DPO is the
     * named NDPC contact). Falls back to organisation-level DPO if omitted.
     */
    dpoContact?: {
        name: string;
        email: string;
        phone?: string;
    };
    /**
     * Whether this is a phased / interim report submitted under Section 40(2)
     * before complete information is available.
     */
    isPhasedReport?: boolean;
    /** ID of the prior phased report this report supplements, if any. */
    supplementsReportId?: string;
    /** Current status of the breach */
    status: 'ongoing' | 'contained' | 'resolved';
    /** Initial actions taken to address the breach */
    initialActions?: string;
    /** File attachments included with the report */
    attachments: Array<{
        name: string;
        type: string;
        size: number;
        file: File;
    }>;
}

/**
 * Breach notification management component. Implements NDPA Section 40 requirements for
 * managing breach notifications, tracking 72-hour NDPC reporting deadlines, and coordinating
 * data subject notifications.
 */
export declare const BreachNotificationManager: React__default.FC<BreachNotificationManagerProps>;

export declare interface BreachNotificationManagerClassNames {
    root?: string;
    header?: string;
    title?: string;
    breachList?: string;
    breachItem?: string;
    statusBadge?: string;
    timeline?: string;
    timelineStep?: string;
    detailPanel?: string;
}

declare interface BreachNotificationManagerProps {
    /**
     * List of breach reports to manage
     */
    breachReports: BreachReport[];
    /**
     * List of risk assessments
     */
    riskAssessments: RiskAssessment[];
    /**
     * List of regulatory notifications
     */
    regulatoryNotifications: RegulatoryNotification[];
    /**
     * Callback function called when a breach is selected
     */
    onSelectBreach?: (breachId: string) => void;
    /**
     * Callback function called when a risk assessment is requested
     */
    onRequestAssessment?: (breachId: string) => void;
    /**
     * Callback function called when a notification is requested
     */
    onRequestNotification?: (breachId: string) => void;
    /**
     * Title displayed on the manager
     * @default "Breach Notification Manager"
     */
    title?: string;
    /**
     * Description text displayed on the manager
     * @default "Manage data breach notifications and track compliance with NDPA Section 40 requirements."
     */
    description?: string;
    /**
     * Custom CSS class for the manager
     */
    className?: string;
    /**
     * Custom CSS class for the buttons
     */
    buttonClassName?: string;
    /**
     * Override class names for individual elements
     */
    classNames?: BreachNotificationManagerClassNames;
    /**
     * Remove all default styles, only applying classNames overrides
     */
    unstyled?: boolean;
    /**
     * Whether to show the breach details
     * @default true
     */
    showBreachDetails?: boolean;
    /**
     * Whether to show the notification timeline
     * @default true
     */
    showNotificationTimeline?: boolean;
    /**
     * Whether to show the deadline alerts
     * @default true
     */
    showDeadlineAlerts?: boolean;
}

export declare const BreachProvider: React__default.FC<BreachProviderProps>;

export declare interface BreachProviderProps {
    categories: BreachCategory[];
    adapter?: StorageAdapter<{
        reports: BreachReport[];
        assessments: RiskAssessment[];
        notifications: RegulatoryNotification[];
    }>;
    storageKey?: string;
    useLocalStorage?: boolean;
    initialReports?: BreachReport[];
    onReport?: (report: BreachReport) => void;
    onAssessment?: (assessment: RiskAssessment) => void;
    onNotification?: (notification: RegulatoryNotification) => void;
    children: React__default.ReactNode;
}

/**
 * Represents a data breach report
 */
export declare interface BreachReport {
    /** Unique identifier for the breach report */
    id: string;
    /** Title/summary of the breach */
    title: string;
    /** Detailed description of the breach */
    description: string;
    /** Category of the breach */
    category: string;
    /** Timestamp when the breach was discovered */
    discoveredAt: number;
    /** Timestamp when the breach occurred (if known) */
    occurredAt?: number;
    /** Timestamp when the breach was reported internally */
    reportedAt: number;
    /** Person who reported the breach */
    reporter: {
        name: string;
        email: string;
        department: string;
        phone?: string;
    };
    /** Systems or data affected by the breach */
    affectedSystems: string[];
    /** Types of data involved in the breach */
    dataTypes: string[];
    /** Whether sensitive personal data is involved (NDPA Section 30) */
    involvesSensitiveData?: boolean;
    /** Estimated number of data subjects affected */
    estimatedAffectedSubjects?: number;
    /**
     * Approximate number of personal data RECORDS concerned (distinct from subject count).
     * Required content under NDPA Section 40(1)(a) and Section 40(2).
     */
    approximateRecordCount?: number;
    /**
     * Categories of data subjects affected (e.g. customers, employees, minors, patients).
     * Required content under NDPA Section 40(1)(a) and Section 40(2).
     */
    dataSubjectCategories?: string[];
    /**
     * Likely consequences of the breach for affected data subjects (e.g. identity theft,
     * financial loss, reputational damage). Reported to the NDPC and, where applicable,
     * communicated to data subjects under Section 40(3).
     */
    likelyConsequences?: string;
    /**
     * Measures taken or proposed to mitigate adverse effects of the breach.
     * Required content for Section 40(3) communications to data subjects.
     */
    mitigationMeasures?: string;
    /**
     * Whether this is a phased / interim report submitted before full investigation
     * is complete. The NDPC permits phased reporting where complete information is
     * not available within 72 hours.
     */
    isPhasedReport?: boolean;
    /**
     * ID of the prior phased report this report supplements, if any.
     */
    supplementsReportId?: string;
    /**
     * Data Protection Officer contact details. The DPO is the named contact point
     * for the NDPC per NDPA Section 32(3)(c). Required content in the regulatory
     * report (Section 40(2)).
     */
    dpoContact?: {
        name: string;
        email: string;
        phone?: string;
    };
    /** Whether the breach is ongoing or contained */
    status: 'ongoing' | 'contained' | 'resolved';
    /** Initial actions taken to address the breach */
    initialActions?: string;
    /** Attachments related to the breach */
    attachments?: Array<{
        id: string;
        name: string;
        type: string;
        url: string;
        addedAt: number;
    }>;
}

/**
 * Breach report form component. Implements NDPA Section 40 breach notification requirements,
 * enabling organizations to document and report data breaches within the mandated 72-hour window.
 */
export declare const BreachReportForm: React__default.FC<BreachReportFormProps>;

export declare interface BreachReportFormClassNames {
    root?: string;
    title?: string;
    form?: string;
    fieldGroup?: string;
    label?: string;
    input?: string;
    select?: string;
    textarea?: string;
    submitButton?: string;
    /** Alias for submitButton */
    primaryButton?: string;
    notice?: string;
    /** Custom class applied when isSubmitting is true (e.g. a loading overlay) */
    loadingOverlay?: string;
    /** Live NDPC-notification completeness panel */
    completeness?: string;
}

declare interface BreachReportFormProps {
    /**
     * Available breach categories
     */
    categories: BreachCategory[];
    /**
     * Callback function called when form is submitted
     */
    onSubmit: (data: BreachFormSubmission) => void;
    /**
     * Callback function called when form validation fails
     */
    onValidationError?: (errors: Record<string, string>) => void;
    /**
     * Title displayed on the form
     * @default "Report a Data Breach"
     */
    title?: string;
    /**
     * Description text displayed on the form.
     *
     * @default "Use this form to report a suspected or confirmed data breach in accordance with NDPA Section 40. All fields marked with * are required."
     */
    description?: string;
    /**
     * Text for the submit button
     * @default "Submit Report"
     */
    submitButtonText?: string;
    /**
     * Custom CSS class for the form
     */
    className?: string;
    /**
     * Custom CSS class for the submit button
     */
    buttonClassName?: string;
    /**
     * Override class names for individual elements
     */
    classNames?: BreachReportFormClassNames;
    /**
     * Remove all default styles, only applying classNames overrides
     */
    unstyled?: boolean;
    /**
     * Whether the form is currently submitting.
     * When true, the submit button is disabled and shows "Submitting..." text.
     */
    isSubmitting?: boolean;
    /**
     * Whether to show a confirmation message after submission
     * @default true
     */
    showConfirmation?: boolean;
    /**
     * Confirmation message to display after submission
     * @default "Your breach report has been submitted successfully. The data protection team has been notified."
     */
    confirmationMessage?: string;
    /**
     * Whether to allow file attachments
     * @default true
     */
    allowAttachments?: boolean;
    /**
     * Maximum number of attachments allowed
     * @default 5
     */
    maxAttachments?: number;
    /**
     * Maximum file size for attachments (in bytes)
     * @default 5242880 (5MB)
     */
    maxFileSize?: number;
    /**
     * Allowed file types for attachments
     * @default ['.pdf', '.jpg', '.jpeg', '.png', '.doc', '.docx', '.xls', '.xlsx', '.txt']
     */
    allowedFileTypes?: string[];
    /**
     * Default values to pre-fill form fields.
     * Useful for editing existing breach reports or pre-populating known data.
     */
    defaultValues?: Partial<BreachFormSubmission>;
    /**
     * Callback fired when the form is reset via the Reset button.
     * To fully remount the component (clearing all internal state),
     * change the `key` prop from the parent.
     */
    onReset?: () => void;
    /**
     * Show a live NDPC-notification readiness panel that scores the form against
     * the NDPA S. 40 / GAID 2025 Article 33 mandated content and the 72-hour
     * deadline as the user fills it in.
     * @default true
     */
    showCompleteness?: boolean;
}

/**
 * Breach risk assessment component. Implements NDPA Section 40 requirements for assessing
 * breach severity and determining whether NDPC notification is required within 72 hours.
 */
export declare const BreachRiskAssessment: React__default.FC<BreachRiskAssessmentProps>;

export declare interface BreachRiskAssessmentClassNames {
    root?: string;
    header?: string;
    title?: string;
    slider?: string;
    riskBadge?: string;
    riskScore?: string;
    notificationStatus?: string;
    submitButton?: string;
    /** Alias for submitButton */
    primaryButton?: string;
}

declare interface BreachRiskAssessmentProps {
    /**
     * The breach data to assess
     */
    breachData: BreachReport;
    /**
     * Initial assessment data (if editing an existing assessment)
     */
    initialAssessment?: Partial<RiskAssessment>;
    /**
     * Callback function called when assessment is completed
     */
    onComplete: (assessment: RiskAssessment) => void;
    /**
     * Title displayed on the assessment form
     * @default "Breach Risk Assessment"
     */
    title?: string;
    /**
     * Description text displayed on the assessment form
     * @default "Assess the risk level of this data breach to determine notification requirements under NDPA Section 40."
     */
    description?: string;
    /**
     * Text for the submit button
     * @default "Complete Assessment"
     */
    submitButtonText?: string;
    /**
     * Custom CSS class for the form
     */
    className?: string;
    /**
     * Custom CSS class for the submit button
     */
    buttonClassName?: string;
    /**
     * Override class names for individual elements
     */
    classNames?: BreachRiskAssessmentClassNames;
    /**
     * Remove all default styles, only applying classNames overrides
     */
    unstyled?: boolean;
    /**
     * Whether to show the breach summary
     * @default true
     */
    showBreachSummary?: boolean;
    /**
     * Whether to show notification requirements after assessment
     * @default true
     */
    showNotificationRequirements?: boolean;
}

/**
 * Calculates the severity of a data breach based on various factors
 * @param report The breach report
 * @param assessment The risk assessment (if available)
 * @returns The calculated severity and notification requirements
 */
export declare function calculateBreachSeverity(report: BreachReport, assessment?: RiskAssessment): {
    severityLevel: 'low' | 'medium' | 'high' | 'critical';
    notificationRequired: boolean;
    urgentNotificationRequired: boolean;
    timeframeHours: number;
    justification: string;
};

/**
 * Represents notification requirements for a data breach per NDPA Section 40
 */
export declare interface NotificationRequirement {
    /**
     * Whether NDPC notification is required
     * Per NDPA Section 40, notification to NDPC is required for all breaches
     * that pose a risk to data subjects' rights and freedoms
     */
    ndpcNotificationRequired: boolean;
    /**
     * Deadline for NDPC notification (72 hours from discovery)
     * NDPA Section 40(1)
     */
    ndpcNotificationDeadline: number;
    /**
     * Whether data subject notification is required
     * Per NDPA Section 40(4), required when breach is likely to result in
     * high risk to rights and freedoms of data subjects
     */
    dataSubjectNotificationRequired: boolean;
    /** Justification for the notification decision */
    justification: string;
    /**
     * @deprecated Use ndpcNotificationRequired instead. Kept for backward compatibility.
     */
    nitdaNotificationRequired?: boolean;
    /**
     * @deprecated Use ndpcNotificationDeadline instead. Kept for backward compatibility.
     */
    nitdaNotificationDeadline?: number;
}

declare interface OrganizationInfo {
    /**
     * Name of the organization
     */
    name: string;
    /**
     * Registration number or business ID
     */
    registrationNumber?: string;
    /**
     * Physical address of the organization
     */
    address: string;
    /**
     * Website URL
     */
    website?: string;
    /**
     * Name of the Data Protection Officer
     */
    dpoName: string;
    /**
     * Email of the Data Protection Officer
     */
    dpoEmail: string;
    /**
     * Phone number of the Data Protection Officer
     */
    dpoPhone?: string;
}

/**
 * Represents a notification sent to the NDPC (Nigeria Data Protection Commission)
 */
export declare interface RegulatoryNotification {
    /** Unique identifier for the notification */
    id: string;
    /** ID of the breach this notification is for */
    breachId: string;
    /** Timestamp when the notification was sent */
    sentAt: number;
    /** Method used to send the notification */
    method: 'email' | 'portal' | 'letter' | 'other';
    /** Reference number assigned by the NDPC (if available) */
    referenceNumber?: string;
    /** Contact person at the NDPC */
    ndpcContact?: {
        name: string;
        email: string;
        phone?: string;
    };
    /** Content of the notification */
    content: string;
    /** Attachments included with the notification */
    attachments?: Array<{
        id: string;
        name: string;
        type: string;
        url: string;
    }>;
    /** Follow-up communications with the NDPC */
    followUps?: Array<{
        timestamp: number;
        direction: 'sent' | 'received';
        content: string;
        attachments?: Array<{
            id: string;
            name: string;
            type: string;
            url: string;
        }>;
    }>;
    /**
     * @deprecated Use ndpcContact instead. Kept for backward compatibility.
     */
    nitdaContact?: {
        name: string;
        email: string;
        phone?: string;
    };
}

/**
 * Regulatory report generator component. Implements NDPA Section 40 requirements for
 * generating formal breach notification reports for submission to the NDPC.
 */
export declare const RegulatoryReportGenerator: React__default.FC<RegulatoryReportGeneratorProps>;

export declare interface RegulatoryReportGeneratorClassNames {
    root?: string;
    header?: string;
    title?: string;
    reportPreview?: string;
    field?: string;
    fieldLabel?: string;
    fieldValue?: string;
    generateButton?: string;
    /** Alias for generateButton */
    primaryButton?: string;
    downloadButton?: string;
    /** Alias for downloadButton */
    secondaryButton?: string;
}

declare interface RegulatoryReportGeneratorProps {
    /**
     * The breach data to include in the report
     */
    breachData: BreachReport;
    /**
     * The risk assessment data
     */
    assessmentData?: RiskAssessment;
    /**
     * Organization information to include in the report
     */
    organizationInfo: OrganizationInfo;
    /**
     * Callback function called when the report is generated
     */
    onGenerate: (report: RegulatoryNotification) => void;
    /**
     * Title displayed on the generator form
     * @default "Generate NDPC Notification Report"
     */
    title?: string;
    /**
     * Description text displayed on the generator form
     * @default "Generate a report for submission to the NDPC in compliance with NDPA Section 40 breach notification requirements."
     */
    description?: string;
    /**
     * Text for the generate button
     * @default "Generate Report"
     */
    generateButtonText?: string;
    /**
     * Custom CSS class for the form
     */
    className?: string;
    /**
     * Custom CSS class for the buttons
     */
    buttonClassName?: string;
    /**
     * Override class names for individual elements
     */
    classNames?: RegulatoryReportGeneratorClassNames;
    /**
     * Remove all default styles, only applying classNames overrides
     */
    unstyled?: boolean;
    /**
     * Whether to show a preview of the generated report
     * @default true
     */
    showPreview?: boolean;
    /**
     * Whether to allow editing the report content
     * @default true
     */
    allowEditing?: boolean;
    /**
     * Whether to allow downloading the report
     * @default true
     */
    allowDownload?: boolean;
    /**
     * Format for downloading the report
     * @default "pdf"
     */
    downloadFormat?: 'pdf' | 'docx' | 'html';
}

/**
 * Represents a risk assessment for a data breach
 */
export declare interface RiskAssessment {
    /** Unique identifier for the risk assessment */
    id: string;
    /** ID of the breach this assessment is for */
    breachId: string;
    /** Timestamp when the assessment was conducted */
    assessedAt: number;
    /** Person who conducted the assessment */
    assessor: {
        name: string;
        role: string;
        email: string;
    };
    /** Confidentiality impact (1-5) */
    confidentialityImpact: number;
    /** Integrity impact (1-5) */
    integrityImpact: number;
    /** Availability impact (1-5) */
    availabilityImpact: number;
    /** Likelihood of harm to data subjects (1-5) */
    harmLikelihood: number;
    /** Severity of potential harm to data subjects (1-5) */
    harmSeverity: number;
    /** Overall risk score */
    overallRiskScore: number;
    /** Risk level based on the overall score */
    riskLevel: 'low' | 'medium' | 'high' | 'critical';
    /** Whether the breach is likely to result in a risk to rights and freedoms */
    risksToRightsAndFreedoms: boolean;
    /** Whether the breach is likely to result in a high risk to rights and freedoms */
    highRisksToRightsAndFreedoms: boolean;
    /** Justification for the risk assessment */
    justification: string;
}

export declare interface StorageAdapter<T = unknown> {
    /** Load persisted data. Called once on hook mount. */
    load(): T | null | Promise<T | null>;
    /** Persist data. Called on every state change. */
    save(data: T): void | Promise<void>;
    /** Clear persisted data. Called on reset. */
    remove(): void | Promise<void>;
}

/**
 * Hook for managing data breach notifications in compliance with the NDPA (Section 40).
 *
 * @example
 * ```tsx
 * import { useBreach } from '@tantainnovative/ndpr-toolkit/hooks';
 *
 * function BreachConsole() {
 *   const { reports, reportBreach } = useBreach({
 *     categories: [{ id: 'unauthorized-access', name: 'Unauthorised access', description: '' }],
 *   });
 *   return <p>{reports.length} breach report(s) on record.</p>;
 * }
 * ```
 */
export declare function useBreach({ categories, initialReports, adapter, storageKey, useLocalStorage, onReport, onAssessment, onNotification, }: UseBreachOptions): UseBreachReturn;

export declare function useBreachCompound(): BreachContextValue;

declare interface UseBreachOptions {
    /**
     * Available breach categories
     */
    categories: BreachCategory[];
    /**
     * Initial breach reports
     */
    initialReports?: BreachReport[];
    /**
     * Pluggable storage adapter. When provided, takes precedence over storageKey/useLocalStorage.
     */
    adapter?: StorageAdapter<BreachCompositeState>;
    /**
     * Storage key for breach data
     * @default "ndpr_breach_data"
     * @deprecated Use adapter instead
     */
    storageKey?: string;
    /**
     * Whether to use local storage to persist breach data
     * @default true
     * @deprecated Use adapter instead
     */
    useLocalStorage?: boolean;
    /**
     * Callback function called when a breach is reported
     */
    onReport?: (report: BreachReport) => void;
    /**
     * Callback function called when a risk assessment is completed
     */
    onAssessment?: (assessment: RiskAssessment) => void;
    /**
     * Callback function called when a notification is sent
     */
    onNotification?: (notification: RegulatoryNotification) => void;
}

declare interface UseBreachReturn {
    /**
     * All breach reports
     */
    reports: BreachReport[];
    /**
     * All risk assessments
     */
    assessments: RiskAssessment[];
    /**
     * All regulatory notifications
     */
    notifications: RegulatoryNotification[];
    /**
     * Submit a new breach report
     */
    reportBreach: (reportData: Omit<BreachReport, 'id' | 'reportedAt'>) => BreachReport;
    /**
     * Update an existing breach report
     */
    updateReport: (id: string, updates: Partial<BreachReport>) => BreachReport | null;
    /**
     * Get a breach report by ID
     */
    getReport: (id: string) => BreachReport | null;
    /**
     * Conduct a risk assessment for a breach
     */
    assessRisk: (breachId: string, assessmentData: Omit<RiskAssessment, 'id' | 'breachId' | 'assessedAt'>) => RiskAssessment;
    /**
     * Get a risk assessment for a breach
     */
    getAssessment: (breachId: string) => RiskAssessment | null;
    /**
     * Calculate notification requirements based on a risk assessment
     */
    calculateNotificationRequirements: (breachId: string) => NotificationRequirement | null;
    /**
     * Send a regulatory notification
     */
    sendNotification: (breachId: string, notificationData: Omit<RegulatoryNotification, 'id' | 'breachId' | 'sentAt'>) => RegulatoryNotification;
    /**
     * Get a regulatory notification for a breach
     */
    getNotification: (breachId: string) => RegulatoryNotification | null;
    /**
     * Get breaches that require notification within the next X hours
     */
    getBreachesRequiringNotification: (hoursThreshold?: number) => Array<{
        report: BreachReport;
        assessment: RiskAssessment;
        requirements: NotificationRequirement;
        hoursRemaining: number;
    }>;
    /**
     * Clear all breach data
     */
    clearBreachData: () => void;
    /**
     * Whether the adapter is still loading data (relevant for async adapters)
     */
    isLoading: boolean;
}

export { }