safe-link-checker 1.0.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,156 @@
+import { normalizeLink, validateUrl, validateShortener, validateIp, validateHeuristics, traceRedirects, validatePunycode, validateHttps } from './chunk-CS7EDB5I.js';
+export { LRUCache, LRUCache as MemoryCache, OpenPhishProvider, SafeLinkChecker, SafeLinkError, TimeoutError, URLHausProvider, defaultCache, normalizeLink, traceRedirects, validateHeuristics, validateHttps, validateIp, validatePunycode, validateShortener, validateUrl } from './chunk-CS7EDB5I.js';
+
+// src/utils/score.ts
+function calculateScore(validators) {
+  let totalPenalty = 0;
+  let safe = true;
+  const reasons = [];
+  const recommendations = [];
+  for (const v of validators) {
+    if (!v.safe) {
+      safe = false;
+      if (v.message) {
+        reasons.push(`[${v.name}] ${v.message}`);
+      }
+      switch (v.name) {
+        case "IP Validator":
+          recommendations.push("Avoid interacting with URLs that resolve to private or local network addresses.");
+          break;
+        case "Punycode Validator":
+          recommendations.push("Be cautious of potential homograph attacks; visually inspect the domain name.");
+          break;
+        case "HTTPS Validator":
+          recommendations.push("Prefer links that use secure HTTPS connections to protect your data.");
+          break;
+        case "Shortener Validator":
+          recommendations.push("URL shorteners can mask malicious destinations; verify the expanded URL before trusting it.");
+          break;
+        case "Heuristics Validator":
+          recommendations.push("The URL contains suspicious patterns, excessive subdomains, or lookalike domain traits; verify the source carefully.");
+          break;
+        case "URL Validator":
+          recommendations.push("Ensure the URL is correctly formatted and uses a supported protocol (http/https).");
+          break;
+      }
+    }
+    const weight = v.weight ?? 1;
+    totalPenalty += v.scoreImpact * weight;
+  }
+  let score = 100 - totalPenalty;
+  if (score < 0) {
+    score = 0;
+  } else if (score > 100) {
+    score = 100;
+  }
+  let riskLevel = "SAFE";
+  if (score <= 49) {
+    riskLevel = "DANGEROUS";
+  } else if (score <= 89) {
+    riskLevel = "SUSPICIOUS";
+  }
+  return {
+    score,
+    riskLevel,
+    safe,
+    reasons,
+    recommendations: [...new Set(recommendations)]
+  };
+}
+
+// src/verify.ts
+async function verifyLink(url, options = {}) {
+  const normalizedUrl = normalizeLink(url, options);
+  const urlVal = validateUrl(normalizedUrl);
+  if (!urlVal.safe) {
+    const scoreInfo2 = calculateScore([urlVal]);
+    return {
+      url,
+      normalizedUrl,
+      safe: scoreInfo2.safe,
+      score: scoreInfo2.score,
+      confidence: 100,
+      riskLevel: scoreInfo2.riskLevel,
+      reasons: scoreInfo2.reasons,
+      recommendations: scoreInfo2.recommendations,
+      redirectChain: [],
+      redirectTrace: { chain: [], finalUrl: normalizedUrl, redirectCount: 0, anomalies: [] },
+      checks: [urlVal],
+      fromCache: false
+    };
+  }
+  const shortVal = validateShortener(normalizedUrl, options.customShorteners);
+  const isShortener = shortVal.metadata?.isShortener === true;
+  const initialIpVal = validateIp(normalizedUrl);
+  if (!initialIpVal.safe) {
+    const heurVal2 = validateHeuristics(normalizedUrl);
+    const checks2 = [urlVal, shortVal, initialIpVal, heurVal2];
+    const scoreInfo2 = calculateScore(checks2);
+    return {
+      url,
+      normalizedUrl,
+      safe: scoreInfo2.safe,
+      score: scoreInfo2.score,
+      confidence: 100,
+      riskLevel: scoreInfo2.riskLevel,
+      reasons: scoreInfo2.reasons,
+      recommendations: scoreInfo2.recommendations,
+      redirectChain: [],
+      redirectTrace: { chain: [], finalUrl: normalizedUrl, redirectCount: 0, anomalies: [] },
+      checks: checks2,
+      fromCache: false
+    };
+  }
+  const redirectTrace = await traceRedirects(normalizedUrl, options);
+  const targetUrl = isShortener ? redirectTrace.finalUrl : normalizedUrl;
+  let ipVal = initialIpVal;
+  if (isShortener && targetUrl !== normalizedUrl) {
+    ipVal = validateIp(targetUrl);
+    if (!ipVal.safe) {
+      const heurVal2 = validateHeuristics(targetUrl);
+      const checks2 = [urlVal, shortVal, ipVal, heurVal2];
+      const scoreInfo2 = calculateScore(checks2);
+      return {
+        url,
+        normalizedUrl,
+        safe: scoreInfo2.safe,
+        score: scoreInfo2.score,
+        confidence: 100,
+        riskLevel: scoreInfo2.riskLevel,
+        reasons: scoreInfo2.reasons,
+        recommendations: scoreInfo2.recommendations,
+        redirectChain: redirectTrace.chain,
+        redirectTrace,
+        checks: checks2,
+        fromCache: false
+      };
+    }
+  }
+  const punyVal = validatePunycode(targetUrl);
+  const heurVal = validateHeuristics(targetUrl);
+  let checks = [urlVal, shortVal, ipVal, punyVal, heurVal];
+  if (options.checkHttps !== false) {
+    const timeout = options.timeout ?? 5e3;
+    const httpsVal = await validateHttps(targetUrl, timeout, options.signal);
+    checks.push(httpsVal);
+  }
+  const scoreInfo = calculateScore(checks);
+  return {
+    url,
+    normalizedUrl,
+    safe: scoreInfo.safe,
+    score: scoreInfo.score,
+    confidence: 100,
+    riskLevel: scoreInfo.riskLevel,
+    reasons: scoreInfo.reasons,
+    recommendations: scoreInfo.recommendations,
+    redirectChain: redirectTrace.chain,
+    redirectTrace,
+    checks,
+    fromCache: false
+  };
+}
+
+export { verifyLink };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/score.ts","../src/verify.ts"],"names":["scoreInfo","heurVal","checks"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * SafeLinkChecker\n * Copyright (c) 2026\n *\n * This source code is licensed under the MIT license found in the\n * LICENSE file in the root directory of this source tree.\n */\n\nimport type { RiskLevel, CheckResult } from '../types/index.js';\n\nexport function calculateScore(validators: CheckResult[]): {\n  score: number;\n  riskLevel: RiskLevel;\n  safe: boolean;\n  reasons: string[];\n  recommendations: string[];\n} {\n  let totalPenalty = 0;\n  let safe = true;\n  const reasons: string[] = [];\n  const recommendations: string[] = [];\n\n  for (const v of validators) {\n    if (!v.safe) {\n      safe = false;\n      if (v.message) {\n        reasons.push(`[${v.name}] ${v.message}`);\n      }\n\n      // Generate standard recommendations based on the validator that flagged the URL\n      switch (v.name) {\n        case 'IP Validator':\n          recommendations.push('Avoid interacting with URLs that resolve to private or local network addresses.');\n          break;\n        case 'Punycode Validator':\n          recommendations.push('Be cautious of potential homograph attacks; visually inspect the domain name.');\n          break;\n        case 'HTTPS Validator':\n          recommendations.push('Prefer links that use secure HTTPS connections to protect your data.');\n          break;\n        case 'Shortener Validator':\n          recommendations.push('URL shorteners can mask malicious destinations; verify the expanded URL before trusting it.');\n          break;\n        case 'Heuristics Validator':\n          recommendations.push('The URL contains suspicious patterns, excessive subdomains, or lookalike domain traits; verify the source carefully.');\n          break;\n        case 'URL Validator':\n          recommendations.push('Ensure the URL is correctly formatted and uses a supported protocol (http/https).');\n          break;\n      }\n    }\n\n    // Apply weighted scoring. Default weight is 1 if not specified by the validator.\n    const weight = v.weight ?? 1;\n    totalPenalty += v.scoreImpact * weight;\n  }\n\n  // Calculate final score based on a starting score of 100 minus the weighted penalty sum\n  let score = 100 - totalPenalty;\n  if (score < 0) {\n    score = 0;\n  } else if (score > 100) {\n    score = 100;\n  }\n\n  let riskLevel: RiskLevel = 'SAFE';\n  if (score <= 49) {\n    riskLevel = 'DANGEROUS';\n  } else if (score <= 89) {\n    riskLevel = 'SUSPICIOUS';\n  }\n\n  return {\n    score,\n    riskLevel,\n    safe,\n    reasons,\n    recommendations: [...new Set(recommendations)],\n  };\n}\n","/**\n * SafeLinkChecker\n * Copyright (c) 2026\n *\n * This source code is licensed under the MIT license found in the\n * LICENSE file in the root directory of this source tree.\n */\n\nimport type { VerifyOptions, VerificationResult } from './types/index.js';\nimport { normalizeLink } from './utils/normalize.js';\nimport { calculateScore } from './utils/score.js';\nimport { validateUrl } from './validators/url.js';\nimport { validateIp } from './validators/ip.js';\nimport { validateHttps } from './validators/https.js';\nimport { traceRedirects } from './validators/redirect.js';\nimport { validatePunycode } from './validators/punycode.js';\nimport { validateShortener } from './validators/shortener.js';\nimport { validateHeuristics } from './validators/heuristic.js';\n\nexport async function verifyLink(\n  url: string,\n  options: VerifyOptions = {}\n): Promise<VerificationResult> {\n  const normalizedUrl = normalizeLink(url, options);\n  const urlVal = validateUrl(normalizedUrl);\n\n  // Short-circuit: malformed / unsupported-protocol URLs skip all further checks\n  if (!urlVal.safe) {\n    const scoreInfo = calculateScore([urlVal]);\n    return {\n      url,\n      normalizedUrl,\n      safe: scoreInfo.safe,\n      score: scoreInfo.score, confidence: 100,\n      riskLevel: scoreInfo.riskLevel,\n      reasons: scoreInfo.reasons,\n      recommendations: scoreInfo.recommendations,\n      redirectChain: [],\n      redirectTrace: { chain: [], finalUrl: normalizedUrl, redirectCount: 0, anomalies: [] },\n      checks: [urlVal],\n      fromCache: false,\n    };\n  }\n\n  const shortVal = validateShortener(normalizedUrl, options.customShorteners);\n  const isShortener = shortVal.metadata?.isShortener === true;\n\n  const initialIpVal = validateIp(normalizedUrl);\n\n  // If the host is private/local, skip the outbound redirect trace\n  if (!initialIpVal.safe) {\n    const heurVal = validateHeuristics(normalizedUrl);\n    const checks = [urlVal, shortVal, initialIpVal, heurVal];\n    const scoreInfo = calculateScore(checks);\n    return {\n      url,\n      normalizedUrl,\n      safe: scoreInfo.safe,\n      score: scoreInfo.score, confidence: 100,\n      riskLevel: scoreInfo.riskLevel,\n      reasons: scoreInfo.reasons,\n      recommendations: scoreInfo.recommendations,\n      redirectChain: [],\n      redirectTrace: { chain: [], finalUrl: normalizedUrl, redirectCount: 0, anomalies: [] },\n      checks,\n      fromCache: false,\n    };\n  }\n\n  const redirectTrace = await traceRedirects(normalizedUrl, options);\n  \n  // If it's a shortener, we score the final expanded URL. Otherwise we score the initial URL.\n  const targetUrl = isShortener ? redirectTrace.finalUrl : normalizedUrl;\n  \n  let ipVal = initialIpVal;\n  if (isShortener && targetUrl !== normalizedUrl) {\n    ipVal = validateIp(targetUrl);\n    if (!ipVal.safe) {\n      // The shortener resolved to a local IP\n      const heurVal = validateHeuristics(targetUrl);\n      const checks = [urlVal, shortVal, ipVal, heurVal];\n      const scoreInfo = calculateScore(checks);\n      return {\n        url,\n        normalizedUrl,\n        safe: scoreInfo.safe,\n        score: scoreInfo.score, confidence: 100,\n        riskLevel: scoreInfo.riskLevel,\n        reasons: scoreInfo.reasons,\n        recommendations: scoreInfo.recommendations,\n        redirectChain: redirectTrace.chain,\n        redirectTrace,\n        checks,\n        fromCache: false,\n      };\n    }\n  }\n\n  const punyVal = validatePunycode(targetUrl);\n  const heurVal = validateHeuristics(targetUrl);\n  let checks = [urlVal, shortVal, ipVal, punyVal, heurVal];\n\n  // HTTPS check — opt-out via checkHttps:false; defaults to enabled\n  if (options.checkHttps !== false) {\n    const timeout = options.timeout ?? 5000;\n    const httpsVal = await validateHttps(targetUrl, timeout, options.signal);\n    checks.push(httpsVal);\n  }\n\n  const scoreInfo = calculateScore(checks);\n\n  return {\n    url,\n    normalizedUrl,\n    safe: scoreInfo.safe,\n    score: scoreInfo.score, confidence: 100,\n    riskLevel: scoreInfo.riskLevel,\n    reasons: scoreInfo.reasons,\n    recommendations: scoreInfo.recommendations,\n    redirectChain: redirectTrace.chain,\n    redirectTrace,\n    checks,\n    fromCache: false,\n  };\n}\n\n\n"]}