safe-link-checker 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,497 @@
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+type RiskLevel = 'SAFE' | 'SUSPICIOUS' | 'DANGEROUS';
+type HttpsStatus = 'HTTPS' | 'HTTP_ONLY' | 'CERT_ERROR' | 'TIMEOUT' | 'UNREACHABLE' | 'SKIPPED';
+type RedirectAnomalyKind = 'LOOP' | 'PROTOCOL_DOWNGRADE' | 'MAX_REDIRECTS_EXCEEDED';
+type RiskCategory = 'domain' | 'certificate' | 'redirect' | 'content' | 'network' | 'provider' | 'browser' | 'email' | 'qr' | 'download' | 'behavior' | 'ai' | 'other';
+type RiskSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+type DecisionAction = 'allow' | 'warn' | 'review' | 'block';
+interface VerifyOptions {
+    maxRedirects?: number;
+    timeout?: number;
+    customShorteners?: string[];
+    bypassCache?: boolean;
+    removeTrackingParams?: boolean;
+    checkHttps?: boolean;
+    signal?: AbortSignal;
+    policy?: string;
+}
+interface CheckResult {
+    name: string;
+    safe: boolean;
+    scoreImpact: number;
+    message: string;
+    weight?: number;
+    fatal?: boolean;
+    detector?: string;
+    category?: RiskCategory;
+    severity?: RiskSeverity;
+    confidence?: number;
+    scoreContribution?: number;
+    title?: string;
+    description?: string;
+    recommendation?: string;
+    references?: string[];
+    executionTime?: number;
+    timestamp?: number;
+    metadata?: Record<string, unknown>;
+}
+interface Provider {
+    name: string;
+    check(url: string, options?: VerifyOptions): Promise<CheckResult | null>;
+}
+interface RedirectHop {
+    url: string;
+    statusCode: number;
+}
+interface RedirectTrace$1 {
+    chain: string[];
+    finalUrl: string;
+    redirectCount: number;
+    anomalies: RedirectAnomalyKind[];
+}
+interface ExecutionTimeline {
+    phase: string;
+    startTime: number;
+    durationMs: number;
+    status: 'success' | 'error' | 'skipped';
+}
+interface RichMetadata {
+    favicon?: string;
+    title?: string;
+    description?: string;
+    openGraph?: Record<string, string>;
+    twitterCards?: Record<string, string>;
+    canonicalUrl?: string;
+    detectedBrand?: string;
+    detectedLanguage?: string;
+    contentType?: string;
+    server?: string;
+    country?: string;
+    hostingProvider?: string;
+    asn?: string;
+}
+interface ExecutionStats {
+    totalTimeMs: number;
+    startTime: number;
+    endTime: number;
+}
+interface VerificationResult {
+    url: string;
+    normalizedUrl: string;
+    safe: boolean;
+    score: number;
+    confidence: number;
+    riskLevel: RiskLevel;
+    reasons: string[];
+    recommendations: string[];
+    redirectChain: string[];
+    redirectTrace: RedirectTrace$1;
+    checks: CheckResult[];
+    fromCache: boolean;
+    decision?: DecisionAction;
+    trustScore?: number;
+    summary?: string;
+    action?: string;
+    policy?: string;
+    timeline?: ExecutionTimeline[];
+    evidence?: CheckResult[];
+    providerResults?: CheckResult[];
+    categories?: Record<string, number>;
+    execution?: ExecutionStats;
+    metadata?: RichMetadata | Record<string, unknown>;
+}
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare function verifyLink(url: string, options?: VerifyOptions): Promise<VerificationResult>;
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+interface MetadataResult {
+    title?: string;
+    description?: string;
+    image?: string;
+    favicon?: string;
+    url?: string;
+}
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+type EventCallback = (...args: unknown[]) => void;
+declare class EventEmitter {
+    private listeners;
+    on(event: string, callback: EventCallback): void;
+    off(event: string, callback: EventCallback): void;
+    emit(event: string, arg1?: unknown, arg2?: unknown): void;
+}
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+type PluginType = 'network' | 'content' | 'heuristic' | 'provider';
+interface RedirectTrace {
+    finalUrl: string;
+    redirectCount: number;
+    chain: string[];
+    anomalies: RedirectAnomalyKind[];
+}
+interface PluginState {
+    finalUrl?: string;
+    isShortener?: boolean;
+    redirectTrace?: RedirectTrace;
+    [key: string]: unknown;
+}
+interface PluginContext {
+    url: string;
+    normalizedUrl: string;
+    options: VerifyOptions;
+    state: PluginState;
+}
+interface VerificationPlugin {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    type: PluginType;
+    capabilities: string[];
+    priority: number;
+    weight?: number;
+    /**
+     * Initialization hook (e.g. connecting to DB, setting up local models)
+     */
+    initialize?(): Promise<void>;
+    /**
+     * Main execution hook.
+     * Returns a CheckResult or null if the plugin decides to skip.
+     */
+    execute(ctx: PluginContext): Promise<CheckResult | null>;
+    /**
+     * Optional teardown hook
+     */
+    dispose?(): Promise<void>;
+    /**
+     * Optional health check hook
+     */
+    health?(): Promise<boolean>;
+}
+declare class PluginManager {
+    private plugins;
+    register(plugin: VerificationPlugin): void;
+    initializeAll(): Promise<void>;
+    disposeAll(): Promise<void>;
+    getPluginsByType(type: PluginType): VerificationPlugin[];
+    getAll(): VerificationPlugin[];
+}
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+interface ConsensusConfig {
+    baseScore: number;
+    riskThresholds: {
+        suspicious: number;
+        dangerous: number;
+    };
+}
+interface ConsensusResult {
+    score: number;
+    trustScore: number;
+    confidence: number;
+    riskLevel: RiskLevel;
+    reasons: string[];
+    safe: boolean;
+    summary: string;
+}
+declare class ConsensusEngine {
+    private config;
+    constructor(config?: Partial<ConsensusConfig>);
+    evaluate(results: (CheckResult | null)[]): ConsensusResult;
+}
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+interface PolicyContext {
+    riskLevel: RiskLevel;
+    score: number;
+    confidence: number;
+}
+interface PolicyResult {
+    decision: DecisionAction;
+    action: string;
+}
+type PolicyDefinition = (ctx: PolicyContext) => PolicyResult;
+declare class PolicyEngine {
+    private policies;
+    constructor();
+    private registerBuiltIns;
+    register(name: string, policy: PolicyDefinition): void;
+    evaluate(policyName: string | undefined, ctx: PolicyContext): PolicyResult;
+}
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+interface CheckerOptions extends VerifyOptions {
+    mode?: 'local' | 'cloud';
+    apiKey?: string;
+    endpoint?: string;
+    cache?: boolean | {
+        get(url: string): VerificationResult | null;
+        set(url: string, result: VerificationResult): void;
+    };
+    providers?: (Provider | 'openphish' | 'urlhaus')[];
+    onStart?: (url: string) => void;
+    onComplete?: (result: VerificationResult) => void;
+    onError?: (error: Error, url: string) => void;
+}
+declare class SafeLinkError extends Error {
+    constructor(message: string);
+}
+declare class TimeoutError extends SafeLinkError {
+    constructor(message: string);
+}
+/**
+ * The main orchestrator for validating URLs.
+ * Allows configuration of caching, timeouts, concurrent provider plugins, and batch processing.
+ */
+declare class SafeLinkChecker extends EventEmitter {
+    private cache;
+    private metadataCache;
+    private options;
+    pluginManager: PluginManager;
+    consensusEngine: ConsensusEngine;
+    policyEngine: PolicyEngine;
+    constructor(options?: CheckerOptions);
+    /**
+     * Adds a legacy Provider or a new VerificationPlugin to the checker.
+     */
+    use(plugin: Provider | VerificationPlugin): this;
+    getMetadata(url: string): Promise<MetadataResult | null>;
+    /**
+     * Verifies a single URL through the core engine and any registered providers.
+     * Caches results if configured.
+     *
+     * @param url The URL to check.
+     * @param runtimeOptions Options overriding the global checker options for this specific call.
+     * @returns A detailed VerificationResult including the final risk score.
+     */
+    verify(url: string, runtimeOptions?: VerifyOptions): Promise<VerificationResult>;
+    private verifyCloud;
+    private verifyLocal;
+    /**
+     * Concurrently verifies multiple URLs with a bounded concurrency limit.
+     * Results are returned in the exact same order as the input array.
+     *
+     * @param urls Array of URLs to verify.
+     * @param runtimeOptions Options overriding the global checker options.
+     * @param concurrency The maximum number of concurrent verifications (defaults to 5).
+     * @returns Array of VerificationResult corresponding to the input URLs.
+     */
+    verifyLinks(urls: string[], runtimeOptions?: VerifyOptions, concurrency?: number): Promise<VerificationResult[]>;
+}
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+declare function normalizeLink(url: string, options?: {
+    removeTrackingParams?: boolean;
+}): string;
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+interface CacheOptions {
+    maxSize?: number;
+    ttlMs?: number;
+}
+declare class LRUCache<T> {
+    private cache;
+    private maxSize;
+    private ttlMs;
+    constructor(options?: CacheOptions);
+    get(url: string): T | null;
+    set(url: string, result: T): void;
+    clear(): void;
+    get size(): number;
+}
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare const defaultCache: LRUCache<VerificationResult>;
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare function validateUrl(urlStr: string): CheckResult;
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Probes the URL for HTTPS availability and certificate validity.
+ * Returns a CheckResult that is always fulfilled — never rejects.
+ *
+ * Score impact guide:
+ *   HTTPS       →  0  (good)
+ *   HTTP_ONLY   → 20  (SUSPICIOUS — no encryption)
+ *   CERT_ERROR  → 40  (DANGEROUS — cert problem, MITM risk)
+ *   TIMEOUT     →  0  (ambiguous; don't penalise for slow servers)
+ *   UNREACHABLE →  0  (ambiguous; server may be fine — just unreachable from CI)
+ *   SKIPPED     →  0  (opt-out)
+ */
+declare function validateHttps(urlStr: string, timeoutMs?: number, signal?: AbortSignal): Promise<CheckResult>;
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare function validateIp(urlStr: string): CheckResult;
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare function validatePunycode(urlStr: string): CheckResult;
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare function validateShortener(urlStr: string, customShorteners?: string[]): CheckResult;
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare function validateHeuristics(url: string): CheckResult;
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare function traceRedirects(urlStr: string, options?: VerifyOptions): Promise<RedirectTrace$1>;
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare class URLHausProvider implements Provider {
+    name: string;
+    private cache;
+    private offlineDataset;
+    private datasetLoaded;
+    private updateInterval;
+    init(): Promise<void>;
+    private updateDataset;
+    check(url: string, options?: VerifyOptions): Promise<CheckResult | null>;
+    private doCheckOnline;
+}
+
+/**
+ * SafeLinkChecker
+ * Copyright (c) 2026
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare class OpenPhishProvider implements Provider {
+    name: string;
+    private cache;
+    check(url: string, options?: VerifyOptions): Promise<CheckResult | null>;
+    private doCheck;
+}
+
+export { type CheckResult, type CheckerOptions, type DecisionAction, type ExecutionStats, type ExecutionTimeline, type HttpsStatus, LRUCache, LRUCache as MemoryCache, type MetadataResult, OpenPhishProvider, type Provider, type RedirectAnomalyKind, type RedirectHop, type RedirectTrace$1 as RedirectTrace, type RichMetadata, type RiskCategory, type RiskLevel, type RiskSeverity, SafeLinkChecker, SafeLinkError, TimeoutError, URLHausProvider, type VerificationResult, type VerifyOptions, defaultCache, normalizeLink, traceRedirects, validateHeuristics, validateHttps, validateIp, validatePunycode, validateShortener, validateUrl, verifyLink };