@socketsecurity/lib/dist/dlx.d.ts

Core utilities and infrastructure for Socket.dev security tools

/**
 * Generate a cache directory name using npm/npx approach.
 * Uses first 16 characters of SHA-512 hash (like npm/npx).
 *
 * Rationale for SHA-512 truncated (vs full SHA-256):
 * - Matches npm/npx ecosystem behavior
 * - Shorter paths for Windows MAX_PATH compatibility (260 chars)
 * - 16 hex chars = 64 bits = acceptable collision risk for local cache
 * - Collision probability ~1 in 18 quintillion with 1000 entries
 *
 * Input strategy (aligned with npx):
 * - npx uses package spec strings (e.g., '@scope/pkg@1.0.0', 'prettier@3.0.0')
 * - Caller provides complete spec string with version for accurate cache keying
 * - For package installs: Use PURL-style spec with version
 *   Examples: 'npm:prettier@3.0.0', 'pypi:requests@2.31.0', 'gem:rails@7.0.0'
 *   Note: Socket uses shorthand format without 'pkg:' prefix
 *   (handled by @socketregistry/packageurl-js)
 * - For binary downloads: Use URL:name for uniqueness
 *
 * Reference: npm/cli v11.6.2 libnpmexec/lib/index.js#L233-L244
 * https://github.com/npm/cli/blob/v11.6.2/workspaces/libnpmexec/lib/index.js#L233-L244
 * Implementation: packages.map().sort().join('\n') → SHA-512 → slice(0,16)
 * npx hashes the package spec (name@version), not just name
 */
export declare function generateCacheKey(spec: string): string;
/**
 * Clear all DLX package installations.
 */
export declare function clearDlx(): Promise<void>;
/**
 * Clear all DLX package installations synchronously.
 */
export declare function clearDlxSync(): void;
/**
 * Check if the DLX directory exists.
 */
export declare function dlxDirExists(): boolean;
/**
 * Check if the DLX directory exists asynchronously.
 */
export declare function dlxDirExistsAsync(): Promise<boolean>;
/**
 * Ensure the DLX directory exists, creating it if necessary.
 */
export declare function ensureDlxDir(): Promise<void>;
/**
 * Ensure the DLX directory exists synchronously, creating it if necessary.
 */
export declare function ensureDlxDirSync(): void;
/**
 * Get the installed package directory within DLX node_modules.
 */
export declare function getDlxInstalledPackageDir(packageName: string): string;
/**
 * Get the DLX installation directory for a specific package.
 */
export declare function getDlxPackageDir(packageName: string): string;
/**
 * Get the package.json path for a DLX installed package.
 */
export declare function getDlxPackageJsonPath(packageName: string): string;
/**
 * Get the node_modules directory for a DLX package installation.
 */
export declare function getDlxPackageNodeModulesDir(packageName: string): string;
/**
 * Check if a file path is within the Socket DLX directory.
 * This is useful for determining if a binary or file is managed by Socket's DLX system.
 *
 * @param filePath - Absolute or relative path to check
 * @returns true if the path is within ~/.socket/_dlx/, false otherwise
 *
 * @example
 * ```typescript
 * isInSocketDlx('/home/user/.socket/_dlx/abc123/bin/socket') // true
 * isInSocketDlx('/usr/local/bin/socket') // false
 * isInSocketDlx(process.argv[0]) // Check if current binary is in DLX
 * ```
 */
export declare function isInSocketDlx(filePath: string): boolean;
/**
 * Check if a package is installed in DLX.
 */
export declare function isDlxPackageInstalled(packageName: string): boolean;
/**
 * Check if a package is installed in DLX asynchronously.
 */
export declare function isDlxPackageInstalledAsync(packageName: string): Promise<boolean>;
/**
 * List all packages installed in DLX.
 */
export declare function listDlxPackages(): string[];
/**
 * List all packages installed in DLX asynchronously.
 */
export declare function listDlxPackagesAsync(): Promise<string[]>;
/**
 * Remove a DLX package installation.
 */
export declare function removeDlxPackage(packageName: string): Promise<void>;
/**
 * Remove a DLX package installation synchronously.
 */
export declare function removeDlxPackageSync(packageName: string): void;