token-guardian/dist/canary/CanaryService.d.ts

A comprehensive solution for protecting and managing API tokens and secrets

/// <reference types="node" />
import { EventEmitter } from 'events';
/**
 * Interface representing the structure of canary token alert data
 */
interface AlertData {
    /**
     * Name of the token that was detected
     */
    tokenName: string;
    /**
     * ISO timestamp when the alert was generated
     */
    timestamp: string;
    /**
     * Method used to detect the canary token
     */
    detectionMethod: string;
    /**
     * Information about the source of the detection
     */
    source: {
        /**
         * IP address where the token was detected
         */
        ipAddress: string;
        /**
         * User agent information
         */
        userAgent: string;
        /**
         * ISO timestamp of the detection
         */
        timestamp: string;
    };
    /**
     * Masked/partial version of the detected token for safe logging
     */
    partialToken: string;
}
/**
 * Service for managing canary tokens
 */
export declare class CanaryService extends EventEmitter {
    private enabled;
    private canaries;
    private webhookUrl;
    private alertEndpoints;
    /**
     * Creates a new CanaryService
     * @param enabled Whether canary tokens are enabled
     */
    constructor(enabled: boolean);
    /**
     * Configure webhook for canary notifications
     * @param webhookUrl URL to send notifications to
     */
    configureWebhook(webhookUrl: string): void;
    /**
     * Add an alert endpoint for specific tokens
     * @param tokenName Token to monitor
     * @param endpointUrl URL to notify on detection
     */
    addAlertEndpoint(tokenName: string, endpointUrl: string): void;
    /**
     * Embeds a canary marker in a token
     * @param token The original token
     * @param tokenName The name/identifier of the token
     * @returns Token with embedded canary marker
     */
    embedCanary(token: string, tokenValue: string): string;
    /**
     * Generates a unique canary ID
     * @param tokenName The name/identifier of the token
     * @returns Unique canary ID
     */
    private generateCanaryId;
    /**
     * Embeds a canary ID in a JWT token
     * @param token The JWT token
     * @param canaryId The canary ID to embed
     * @returns Modified JWT with embedded canary
     */
    private embedInJWT;
    /**
     * Embeds a marker in base64 encoded data
     * @param base64Data The base64 data to modify
     * @param marker The marker to embed
     * @returns Modified base64 data
     */
    private embedBase64Marker;
    /**
     * Embeds a canary ID in a generic token
     * @param token The token
     * @param canaryId The canary ID to embed
     * @returns Modified token with embedded canary
     */
    private embedInGenericToken;
    /**
     * Embeds a canary ID in a base64-encoded token
     * @param token The base64 token
     * @param canaryId The canary ID to embed
     * @returns Modified token with embedded canary
     */
    private embedBase64Token;
    /**
     * Embeds a canary ID in a hex token
     * @param token The hex token
     * @param canaryId The canary ID to embed
     * @returns Modified token with embedded canary
     */
    private embedHexToken;
    /**
     * Embeds a canary ID in a mixed-character token
     * @param token The mixed-character token
     * @param canaryId The canary ID to embed
     * @returns Modified token with embedded canary
     */
    private embedMixedToken;
    /**
     * Checks if a token contains a canary marker
     * @param token The token to check
     * @returns The token name if a canary was found, null otherwise
     */
    detectCanary(token: string): string | null;
    /**
     * Extract canary ID from JWT payload
     * @param payload The JWT payload object
     * @returns Extracted canary ID or null
     */
    private extractJWTCanary;
    /**
     * Extract canary marker from base64 data
     * @param base64Data The base64 data to check
     * @returns Extracted canary ID or null
     */
    private extractBase64Marker;
    /**
     * Extract canary ID from a base64 token
     * @param token The base64 token
     * @returns Extracted canary ID or null
     */
    private extractBase64TokenCanary;
    /**
     * Extract canary ID from a hex token
     * @param token The hex token
     * @returns Extracted canary ID or null
     */
    private extractHexTokenCanary;
    /**
     * Extract canary ID from a mixed-character token
     * @param token The mixed-character token
     * @returns Extracted canary ID or null
     */
    private extractMixedTokenCanary;
    /**
     * Calculate Hamming distance between two strings
     * @param str1 First string
     * @param str2 Second string
     * @returns Number of differing characters
     */
    private hammingDistance;
    /**
     * Triggers alert for a detected canary
     * @param tokenName The name of the detected token
     * @param token The actual token that was detected
     * @param detectionMethod How the canary was detected
     */
    private triggerAlert;
    /**
     * Gets source information for alerts
     * @returns Object with source info
     */
    private getSourceInfo;
    /**
     * Masks a token for safe logging
     * @param token The token to mask
     * @returns Masked token
     */
    private maskToken;
    /**
     * Sends a webhook alert
     * @param alertData Data to send in the alert
     */
    private sendWebhookAlert;
    /**
     * Sends an alert to a custom endpoint
     * @param endpoint Endpoint URL
     * @param alertData Data to send in the alert
     */
    private sendEndpointAlert;
    /**
     * Registers a callback for canary alerts
     * @param callback Function to call when a canary is triggered
     */
    onCanaryTriggered(callback: (tokenName: string, context: AlertData) => void): void;
    /**
     * Logs an error with context
     * @param message Error context message
     * @param error The caught error
     */
    private logError;
}
export {};