atomic-lockfile 0.0.1-security → 1.4.2

package/src/utils/fs.ts

@@ -0,0 +1,93 @@
+import { promises as fsp, constants as fsConstants, accessSync, statSync } from 'node:fs';
+import { IOError } from '../errors/IOError.js';
+
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fsp.access(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function fileExistsSync(filePath: string): boolean {
+  try {
+    accessSync(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isReadable(filePath: string): Promise<boolean> {
+  try {
+    await fsp.access(filePath, fsConstants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isWritable(filePath: string): Promise<boolean> {
+  try {
+    await fsp.access(filePath, fsConstants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readFileSafe(filePath: string, path: string, lockPath: string): Promise<string> {
+  try {
+    return await fsp.readFile(filePath, 'utf-8');
+  } catch (err) {
+    throw new IOError(path, lockPath, 'read', err as Error);
+  }
+}
+
+export async function writeFileSafe(
+  filePath: string,
+  content: string,
+  path: string,
+  lockPath: string,
+): Promise<void> {
+  try {
+    await fsp.writeFile(filePath, content, { encoding: 'utf-8', flag: 'wx' });
+  } catch (err) {
+    throw new IOError(path, lockPath, 'write', err as Error);
+  }
+}
+
+export async function unlinkSafe(filePath: string): Promise<void> {
+  try {
+    await fsp.unlink(filePath);
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code !== 'ENOENT') throw err;
+  }
+}
+
+export async function getFileMtimeMs(filePath: string): Promise<number | null> {
+  try {
+    const stat = await fsp.stat(filePath);
+    return stat.mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+export function getFileMtimeMsSync(filePath: string): number | null {
+  try {
+    return statSync(filePath).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  await fsp.mkdir(dirPath, { recursive: true });
+}
+
+export async function renameSafe(oldPath: string, newPath: string): Promise<void> {
+  await fsp.rename(oldPath, newPath);
+}

package/src/utils/hash.ts

@@ -0,0 +1,25 @@
+import { createHash } from 'node:crypto';
+
+export function sha256(input: string): string {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+export function md5(input: string): string {
+  return createHash('md5').update(input).digest('hex');
+}
+
+export function sha1(input: string): string {
+  return createHash('sha1').update(input).digest('hex');
+}
+
+export function hashLockPath(lockPath: string): string {
+  return sha256(lockPath).slice(0, 12);
+}
+
+export function hashContent(content: string): string {
+  return sha256(content);
+}
+
+export function buildLockFingerprint(pid: number, hostname: string, nonce: string): string {
+  return sha256(`${pid}:${hostname}:${nonce}`).slice(0, 16);
+}

package/src/utils/hostname.ts

@@ -0,0 +1,31 @@
+import { hostname as osHostname } from 'node:os';
+
+let cachedHostname: string | undefined;
+
+export function getHostname(): string {
+  if (cachedHostname === undefined) {
+    cachedHostname = osHostname();
+  }
+  return cachedHostname;
+}
+
+export function clearHostnameCache(): void {
+  cachedHostname = undefined;
+}
+
+export function isSameHost(hostname: string): boolean {
+  return hostname === getHostname();
+}
+
+export function formatHostPid(hostname: string, pid: number): string {
+  return `${hostname}:${pid}`;
+}
+
+export function parseHostPid(formatted: string): { hostname: string; pid: number } | null {
+  const idx = formatted.lastIndexOf(':');
+  if (idx === -1) return null;
+  const hostname = formatted.slice(0, idx);
+  const pid = parseInt(formatted.slice(idx + 1), 10);
+  if (isNaN(pid)) return null;
+  return { hostname, pid };
+}

package/src/utils/index.ts

@@ -0,0 +1,13 @@
+export * from './path.js';
+export * from './fs.js';
+export * from './pid.js';
+export * from './time.js';
+export * from './retry.js';
+export * from './backoff.js';
+export * from './random.js';
+export * from './hash.js';
+export * from './hostname.js';
+export * from './platform.js';
+export * from './validate.js';
+export * from './serialize.js';
+export * from './parse.js';

package/src/utils/parse.ts

@@ -0,0 +1,43 @@
+import type { LockData } from '../types/lock.js';
+import { safeDeserializeLockData } from './serialize.js';
+
+export function parseLockFile(raw: string): LockData | null {
+  if (!raw || !raw.trim()) return null;
+  return safeDeserializeLockData(raw);
+}
+
+export function parseRetries(value: unknown, fallback: number): number {
+  const n = Number(value);
+  return isNaN(n) || n < 0 ? fallback : Math.floor(n);
+}
+
+export function parseMs(value: unknown, fallback: number): number {
+  const n = Number(value);
+  return isNaN(n) || n <= 0 ? fallback : n;
+}
+
+export function parseBool(value: unknown, fallback: boolean): boolean {
+  if (typeof value === 'boolean') return value;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  return fallback;
+}
+
+export function parseCliArgs(args: string[]): Record<string, string | boolean> {
+  const result: Record<string, string | boolean> = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg) continue;
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith('--')) {
+        result[key] = next;
+        i++;
+      } else {
+        result[key] = true;
+      }
+    }
+  }
+  return result;
+}

package/src/utils/path.ts

@@ -0,0 +1,43 @@
+import { resolve, dirname, basename, extname, join } from 'node:path';
+import { DEFAULT_LOCK_EXTENSION } from '../constants/defaults.js';
+
+export function resolveLockPath(filePath: string, extension = DEFAULT_LOCK_EXTENSION): string {
+  return resolve(filePath) + extension;
+}
+
+export function getLockDir(lockPath: string): string {
+  return dirname(lockPath);
+}
+
+export function getLockBasename(lockPath: string): string {
+  return basename(lockPath);
+}
+
+export function stripLockExtension(lockPath: string, extension = DEFAULT_LOCK_EXTENSION): string {
+  if (lockPath.endsWith(extension)) {
+    return lockPath.slice(0, -extension.length);
+  }
+  return lockPath;
+}
+
+export function isAbsolutePath(filePath: string): boolean {
+  return filePath.startsWith('/') || /^[A-Za-z]:[\\/]/.test(filePath);
+}
+
+export function toAbsolutePath(filePath: string): string {
+  return isAbsolutePath(filePath) ? filePath : resolve(process.cwd(), filePath);
+}
+
+export function buildTmpPath(lockPath: string, nonce: string): string {
+  const dir = dirname(lockPath);
+  const base = basename(lockPath);
+  return join(dir, `.atomic-${nonce}-${base}`);
+}
+
+export function getFileExtension(filePath: string): string {
+  return extname(filePath);
+}
+
+export function sanitizePath(filePath: string): string {
+  return filePath.replace(/\0/g, '').trim();
+}

package/src/utils/pid.ts

@@ -0,0 +1,36 @@
+export function getCurrentPid(): number {
+  return process.pid;
+}
+
+export function isProcessAlive(pid: number): boolean {
+  if (pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === 'EPERM') return true;
+    return false;
+  }
+}
+
+export function isSamePid(pid: number): boolean {
+  return pid === process.pid;
+}
+
+export function isOrphanedPid(pid: number): boolean {
+  return !isProcessAlive(pid);
+}
+
+export function getPidInfo(pid: number): { alive: boolean; owned: boolean; orphaned: boolean } {
+  const alive = isProcessAlive(pid);
+  return {
+    alive,
+    owned: pid === process.pid,
+    orphaned: !alive,
+  };
+}
+
+export function formatPid(pid: number): string {
+  return `PID:${pid}`;
+}

package/src/utils/platform.ts

@@ -0,0 +1,45 @@
+export type Platform = 'linux' | 'darwin' | 'win32' | 'freebsd' | 'openbsd' | 'unknown';
+
+export function getPlatform(): Platform {
+  const p = process.platform;
+  if (p === 'linux' || p === 'darwin' || p === 'win32' || p === 'freebsd' || p === 'openbsd') {
+    return p;
+  }
+  return 'unknown';
+}
+
+export function isWindows(): boolean {
+  return process.platform === 'win32';
+}
+
+export function isMacOS(): boolean {
+  return process.platform === 'darwin';
+}
+
+export function isLinux(): boolean {
+  return process.platform === 'linux';
+}
+
+export function isUnix(): boolean {
+  return !isWindows();
+}
+
+export function supportsHardLinks(): boolean {
+  return isUnix();
+}
+
+export function supportsSymlinks(): boolean {
+  return true;
+}
+
+export function getPathSeparator(): string {
+  return isWindows() ? '\\' : '/';
+}
+
+export function getUid(): number | null {
+  return typeof process.getuid === 'function' ? process.getuid() : null;
+}
+
+export function getGid(): number | null {
+  return typeof process.getgid === 'function' ? process.getgid() : null;
+}

package/src/utils/random.ts

@@ -0,0 +1,31 @@
+import { randomBytes, randomUUID as nodeRandomUUID } from 'node:crypto';
+
+export function generateNonce(byteLength = 16): string {
+  return randomBytes(byteLength).toString('hex');
+}
+
+export function randomJitter(maxMs: number): number {
+  return Math.floor(Math.random() * maxMs);
+}
+
+export function randomInt(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+export function randomUUID(): string {
+  return nodeRandomUUID();
+}
+
+export function randomChoice<T>(arr: readonly T[]): T {
+  const index = Math.floor(Math.random() * arr.length);
+  return arr[index] as T;
+}
+
+export function shuffleArray<T>(arr: T[]): T[] {
+  const copy = [...arr];
+  for (let i = copy.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [copy[i], copy[j]] = [copy[j] as T, copy[i] as T];
+  }
+  return copy;
+}

package/src/utils/retry.ts

@@ -0,0 +1,59 @@
+import { sleep } from './time.js';
+import { computeBackoffDelay } from './backoff.js';
+import type { AcquireOptions } from '../types/options.js';
+
+export interface RetryState {
+  attempt: number;
+  totalElapsedMs: number;
+  lastError: Error | null;
+  startedAt: number;
+}
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: Pick<AcquireOptions, 'retries' | 'retryDelay' | 'retryBackoff' | 'retryMaxDelay' | 'timeout' | 'signal' | 'onRetry'>,
+): Promise<T> {
+  const maxAttempts = (options.retries ?? 5) + 1;
+  const startedAt = Date.now();
+  const timeout = options.timeout;
+  let lastError: Error = new Error('Unknown error');
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (options.signal?.aborted) {
+      throw new Error('Aborted');
+    }
+
+    if (timeout !== undefined && Date.now() - startedAt >= timeout) {
+      throw new Error(`Timeout after ${timeout}ms`);
+    }
+
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err as Error;
+
+      if (attempt < maxAttempts - 1) {
+        const delay = computeBackoffDelay(
+          attempt,
+          options.retryDelay ?? 100,
+          options.retryBackoff ?? 'exponential',
+          options.retryMaxDelay ?? 5000,
+        );
+
+        options.onRetry?.(attempt + 1, lastError);
+        await sleep(delay, options.signal);
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+export function createRetryState(): RetryState {
+  return {
+    attempt: 0,
+    totalElapsedMs: 0,
+    lastError: null,
+    startedAt: Date.now(),
+  };
+}

package/src/utils/serialize.ts

@@ -0,0 +1,31 @@
+import type { LockData } from '../types/lock.js';
+import { LOCK_FILE_MAGIC } from '../constants/index.js';
+
+export function serializeLockData(data: LockData): string {
+  return JSON.stringify({ _magic: LOCK_FILE_MAGIC, ...data }, null, 2);
+}
+
+export function deserializeLockData(raw: string): LockData {
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  if (parsed['_magic'] !== LOCK_FILE_MAGIC) {
+    throw new Error(`Invalid lock file: missing or wrong magic header`);
+  }
+  const { _magic: _m, ...data } = parsed;
+  return data as unknown as LockData;
+}
+
+export function safeDeserializeLockData(raw: string): LockData | null {
+  try {
+    return deserializeLockData(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function serializeToBase64(data: LockData): string {
+  return Buffer.from(serializeLockData(data)).toString('base64');
+}
+
+export function deserializeFromBase64(encoded: string): LockData {
+  return deserializeLockData(Buffer.from(encoded, 'base64').toString('utf-8'));
+}

package/src/utils/time.ts

@@ -0,0 +1,51 @@
+export function now(): number {
+  return Date.now();
+}
+
+export function hrNow(): bigint {
+  return process.hrtime.bigint();
+}
+
+export function elapsedMs(startMs: number): number {
+  return Date.now() - startMs;
+}
+
+export function elapsedHrMs(startNs: bigint): number {
+  return Number(process.hrtime.bigint() - startNs) / 1_000_000;
+}
+
+export function isExpired(createdAt: number, ttlMs: number): boolean {
+  return Date.now() - createdAt > ttlMs;
+}
+
+export function isStale(updatedAt: number, staleAgeMs: number): boolean {
+  return Date.now() - updatedAt > staleAgeMs;
+}
+
+export function ageMs(timestamp: number): number {
+  return Date.now() - timestamp;
+}
+
+export function expiresAt(createdAt: number, ttlMs: number): number {
+  return createdAt + ttlMs;
+}
+
+export function remainingTtlMs(createdAt: number, ttlMs: number): number {
+  return Math.max(0, expiresAt(createdAt, ttlMs) - Date.now());
+}
+
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timeout);
+      reject(new Error('Aborted'));
+    });
+  });
+}
+
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60_000).toFixed(1)}m`;
+}

package/src/utils/validate.ts

@@ -0,0 +1,45 @@
+import { ValidationError } from '../errors/ValidationError.js';
+import type { AcquireOptions } from '../types/options.js';
+
+export function validatePath(filePath: string, lockPath: string): void {
+  if (!filePath || typeof filePath !== 'string') {
+    throw new ValidationError(filePath, lockPath, 'path', filePath, 'must be a non-empty string');
+  }
+  if (filePath.includes('\0')) {
+    throw new ValidationError(filePath, lockPath, 'path', filePath, 'must not contain null bytes');
+  }
+}
+
+export function validateOptions(path: string, lockPath: string, opts: AcquireOptions): void {
+  if (opts.retries !== undefined && (opts.retries < 0 || !Number.isInteger(opts.retries))) {
+    throw new ValidationError(path, lockPath, 'retries', opts.retries, 'must be a non-negative integer');
+  }
+  if (opts.retryDelay !== undefined && opts.retryDelay < 0) {
+    throw new ValidationError(path, lockPath, 'retryDelay', opts.retryDelay, 'must be >= 0');
+  }
+  if (opts.timeout !== undefined && opts.timeout <= 0) {
+    throw new ValidationError(path, lockPath, 'timeout', opts.timeout, 'must be > 0');
+  }
+  if (opts.ttl !== undefined && opts.ttl <= 0) {
+    throw new ValidationError(path, lockPath, 'ttl', opts.ttl, 'must be > 0');
+  }
+  if (opts.staleAge !== undefined && opts.staleAge <= 0) {
+    throw new ValidationError(path, lockPath, 'staleAge', opts.staleAge, 'must be > 0');
+  }
+  if (opts.heartbeatInterval !== undefined && opts.heartbeatInterval <= 0) {
+    throw new ValidationError(path, lockPath, 'heartbeatInterval', opts.heartbeatInterval, 'must be > 0');
+  }
+}
+
+export function validateLockData(path: string, lockPath: string, data: unknown): void {
+  if (!data || typeof data !== 'object') {
+    throw new ValidationError(path, lockPath, 'lockData', data, 'must be an object');
+  }
+  const d = data as Record<string, unknown>;
+  if (typeof d['pid'] !== 'number') {
+    throw new ValidationError(path, lockPath, 'lockData.pid', d['pid'], 'must be a number');
+  }
+  if (typeof d['hostname'] !== 'string') {
+    throw new ValidationError(path, lockPath, 'lockData.hostname', d['hostname'], 'must be a string');
+  }
+}