@mondaydotcomorg/atp-providers 0.17.14

package/src/cache/file.ts

@@ -0,0 +1,330 @@
+import type { CacheProvider } from '@mondaydotcomorg/atp-protocol';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+
+interface CacheEntry {
+	value: unknown;
+	expiresAt: number;
+}
+
+export interface FileCacheOptions {
+	cacheDir?: string;
+	maxKeys?: number;
+	defaultTTL?: number;
+	cleanupInterval?: number;
+}
+
+/**
+ * File-based cache provider for persistent local caching
+ * Good for single-server deployments that need persistence across restarts
+ * Supports cross-pod scenarios when using a shared filesystem (NFS, EFS, etc.)
+ */
+export class FileCache implements CacheProvider {
+	name = 'file';
+	private cacheDir: string;
+	private maxKeys: number;
+	private defaultTTL: number;
+	private cleanupInterval: number;
+	private cleanupTimer?: NodeJS.Timeout;
+	private initPromise?: Promise<void>;
+
+	constructor(options: FileCacheOptions = {}) {
+		this.cacheDir = options.cacheDir || path.join(os.tmpdir(), 'atp-cache');
+		this.maxKeys = options.maxKeys || 1000;
+		this.defaultTTL = options.defaultTTL || 3600;
+		this.cleanupInterval = options.cleanupInterval || 300; // 5 minutes
+
+		// Initialize asynchronously
+		this.initPromise = this.initialize();
+	}
+
+	private async initialize(): Promise<void> {
+		try {
+			await fs.mkdir(this.cacheDir, { recursive: true });
+			// Start periodic cleanup
+			this.startCleanup();
+		} catch (error) {
+			console.error(
+				'[FileCache] Failed to initialize cache directory:',
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+
+	private async ensureInitialized(): Promise<void> {
+		if (this.initPromise) {
+			await this.initPromise;
+		}
+	}
+
+	private getFilePath(key: string): string {
+		// Sanitize key to be filesystem-safe
+		const sanitizedKey = key.replace(/[^a-zA-Z0-9_-]/g, '_');
+		return path.join(this.cacheDir, `${sanitizedKey}.json`);
+	}
+
+	private startCleanup(): void {
+		if (this.cleanupInterval > 0) {
+			this.cleanupTimer = setInterval(() => {
+				this.cleanExpired().catch((error) => {
+					console.error('[FileCache] Cleanup error:', error);
+				});
+			}, this.cleanupInterval * 1000);
+
+			// Don't prevent process exit
+			if (this.cleanupTimer.unref) {
+				this.cleanupTimer.unref();
+			}
+		}
+	}
+
+	private async cleanExpired(): Promise<void> {
+		try {
+			await this.ensureInitialized();
+			const files = await fs.readdir(this.cacheDir);
+			const now = Date.now();
+
+			for (const file of files) {
+				if (!file.endsWith('.json')) continue;
+
+				const filePath = path.join(this.cacheDir, file);
+				try {
+					const content = await fs.readFile(filePath, 'utf-8');
+					const entry: CacheEntry = JSON.parse(content);
+
+					if (entry.expiresAt !== -1 && now > entry.expiresAt) {
+						await fs.unlink(filePath);
+					}
+				} catch {
+					// If we can't read or parse a file, delete it
+					try {
+						await fs.unlink(filePath);
+					} catch {
+						// Ignore deletion errors
+					}
+				}
+			}
+
+			// Enforce max keys limit
+			await this.enforceMaxKeys();
+		} catch (error) {
+			console.error(
+				'[FileCache] Failed to clean expired entries:',
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+
+	private async enforceMaxKeys(): Promise<void> {
+		try {
+			const files = await fs.readdir(this.cacheDir);
+			const jsonFiles = files.filter((f) => f.endsWith('.json'));
+
+			if (jsonFiles.length > this.maxKeys) {
+				// Sort by modification time and remove oldest
+				const fileStats = await Promise.all(
+					jsonFiles.map(async (file) => {
+						const filePath = path.join(this.cacheDir, file);
+						const stats = await fs.stat(filePath);
+						return { file, mtime: stats.mtime.getTime() };
+					})
+				);
+
+				fileStats.sort((a, b) => a.mtime - b.mtime);
+
+				const toDelete = fileStats.slice(0, jsonFiles.length - this.maxKeys);
+				await Promise.all(
+					toDelete.map((item) => {
+						const filePath = path.join(this.cacheDir, item.file);
+						return fs.unlink(filePath).catch(() => {
+							// Ignore errors
+						});
+					})
+				);
+			}
+		} catch (error) {
+			console.error(
+				'[FileCache] Failed to enforce max keys:',
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+
+	async get<T>(key: string): Promise<T | null> {
+		try {
+			await this.ensureInitialized();
+			const filePath = this.getFilePath(key);
+			const content = await fs.readFile(filePath, 'utf-8');
+			const entry: CacheEntry = JSON.parse(content);
+
+			if (entry.expiresAt !== -1 && Date.now() > entry.expiresAt) {
+				await this.delete(key);
+				return null;
+			}
+
+			return entry.value as T;
+		} catch (error: any) {
+			if (error.code === 'ENOENT') {
+				return null;
+			}
+			console.error(
+				'[FileCache] Failed to get key:',
+				key,
+				error instanceof Error ? error.message : error
+			);
+			return null;
+		}
+	}
+
+	async set(key: string, value: unknown, ttl?: number): Promise<void> {
+		try {
+			await this.ensureInitialized();
+			await this.enforceMaxKeys();
+
+			const expiresAt = ttl
+				? Date.now() + ttl * 1000
+				: this.defaultTTL > 0
+					? Date.now() + this.defaultTTL * 1000
+					: -1;
+
+			const entry: CacheEntry = { value, expiresAt };
+			const filePath = this.getFilePath(key);
+
+			await fs.writeFile(filePath, JSON.stringify(entry), 'utf-8');
+		} catch (error) {
+			console.error(
+				'[FileCache] Failed to set key:',
+				key,
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+
+	async delete(key: string): Promise<void> {
+		try {
+			await this.ensureInitialized();
+			const filePath = this.getFilePath(key);
+			await fs.unlink(filePath);
+		} catch (error: any) {
+			if (error.code !== 'ENOENT') {
+				console.error(
+					'[FileCache] Failed to delete key:',
+					key,
+					error instanceof Error ? error.message : error
+				);
+			}
+		}
+	}
+
+	async has(key: string): Promise<boolean> {
+		const value = await this.get(key);
+		return value !== null;
+	}
+
+	async clear(pattern?: string): Promise<void> {
+		try {
+			await this.ensureInitialized();
+			const files = await fs.readdir(this.cacheDir);
+
+			if (!pattern) {
+				// Clear all cache files
+				await Promise.all(
+					files
+						.filter((f) => f.endsWith('.json'))
+						.map((file) => {
+							const filePath = path.join(this.cacheDir, file);
+							return fs.unlink(filePath).catch(() => {
+								// Ignore errors
+							});
+						})
+				);
+				return;
+			}
+
+			// Convert glob pattern to regex
+			const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+
+			// Read all files and check if they match the pattern
+			for (const file of files) {
+				if (!file.endsWith('.json')) continue;
+
+				// Extract original key from filename (reverse sanitization is approximate)
+				const keyBase = file.replace('.json', '');
+
+				// We need to read the file to get the original key
+				// For now, use a simple pattern match on the sanitized filename
+				if (regex.test(keyBase)) {
+					const filePath = path.join(this.cacheDir, file);
+					await fs.unlink(filePath).catch(() => {
+						// Ignore errors
+					});
+				}
+			}
+		} catch (error) {
+			console.error(
+				'[FileCache] Failed to clear cache:',
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+
+	async mget(keys: string[]): Promise<Array<unknown | null>> {
+		return Promise.all(keys.map((key) => this.get(key)));
+	}
+
+	async mset(entries: Array<[string, unknown, number?]>): Promise<void> {
+		await Promise.all(entries.map(([key, value, ttl]) => this.set(key, value, ttl)));
+	}
+
+	async disconnect(): Promise<void> {
+		if (this.cleanupTimer) {
+			clearInterval(this.cleanupTimer);
+			this.cleanupTimer = undefined;
+		}
+		// Don't delete cache files on disconnect - they should persist
+	}
+
+	/** Get cache statistics */
+	async getStats() {
+		try {
+			await this.ensureInitialized();
+			const files = await fs.readdir(this.cacheDir);
+			const jsonFiles = files.filter((f) => f.endsWith('.json'));
+
+			// Calculate total size
+			let totalSize = 0;
+			for (const file of jsonFiles) {
+				const filePath = path.join(this.cacheDir, file);
+				try {
+					const stats = await fs.stat(filePath);
+					totalSize += stats.size;
+				} catch {
+					// Ignore errors
+				}
+			}
+
+			return {
+				keys: jsonFiles.length,
+				maxKeys: this.maxKeys,
+				utilization: (jsonFiles.length / this.maxKeys) * 100,
+				sizeBytes: totalSize,
+				cacheDir: this.cacheDir,
+			};
+		} catch (error) {
+			console.error('[FileCache] Failed to get stats:', error);
+			return {
+				keys: 0,
+				maxKeys: this.maxKeys,
+				utilization: 0,
+				sizeBytes: 0,
+				cacheDir: this.cacheDir,
+			};
+		}
+	}
+
+	/** Manually trigger cleanup of expired entries */
+	async cleanup(): Promise<void> {
+		await this.cleanExpired();
+	}
+}

package/src/cache/memory.ts

@@ -0,0 +1,105 @@
+import type { CacheProvider } from '@mondaydotcomorg/atp-protocol';
+
+interface CacheEntry {
+	value: unknown;
+	expiresAt: number;
+}
+
+/**
+ * In-memory cache provider with LRU eviction
+ * Good for development and single-server deployments
+ */
+export class MemoryCache implements CacheProvider {
+	name = 'memory';
+	private cache: Map<string, CacheEntry>;
+	private maxKeys: number;
+	private defaultTTL: number;
+
+	constructor(options: { maxKeys?: number; defaultTTL?: number } = {}) {
+		this.cache = new Map();
+		this.maxKeys = options.maxKeys || 1000;
+		this.defaultTTL = options.defaultTTL || 3600;
+	}
+
+	async get<T>(key: string): Promise<T | null> {
+		const entry = this.cache.get(key);
+
+		if (!entry) {
+			return null;
+		}
+
+		if (entry.expiresAt !== -1 && Date.now() > entry.expiresAt) {
+			this.cache.delete(key);
+			return null;
+		}
+
+		this.cache.delete(key);
+		this.cache.set(key, entry);
+
+		return entry.value as T;
+	}
+
+	async set(key: string, value: unknown, ttl?: number): Promise<void> {
+		if (this.cache.size >= this.maxKeys && !this.cache.has(key)) {
+			const firstKey = this.cache.keys().next().value;
+			if (firstKey) {
+				this.cache.delete(firstKey);
+			}
+		}
+
+		const expiresAt = ttl
+			? Date.now() + ttl * 1000
+			: this.defaultTTL > 0
+				? Date.now() + this.defaultTTL * 1000
+				: -1;
+
+		this.cache.set(key, { value, expiresAt });
+	}
+
+	async delete(key: string): Promise<void> {
+		this.cache.delete(key);
+	}
+
+	async has(key: string): Promise<boolean> {
+		const value = await this.get(key);
+		return value !== null;
+	}
+
+	async clear(pattern?: string): Promise<void> {
+		if (!pattern) {
+			this.cache.clear();
+			return;
+		}
+
+		const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+
+		for (const key of this.cache.keys()) {
+			if (regex.test(key)) {
+				this.cache.delete(key);
+			}
+		}
+	}
+
+	async mget(keys: string[]): Promise<Array<unknown | null>> {
+		return Promise.all(keys.map((key) => this.get(key)));
+	}
+
+	async mset(entries: Array<[string, unknown, number?]>): Promise<void> {
+		for (const [key, value, ttl] of entries) {
+			await this.set(key, value, ttl);
+		}
+	}
+
+	async disconnect(): Promise<void> {
+		this.cache.clear();
+	}
+
+	/** Get cache statistics */
+	getStats() {
+		return {
+			keys: this.cache.size,
+			maxKeys: this.maxKeys,
+			utilization: (this.cache.size / this.maxKeys) * 100,
+		};
+	}
+}

package/src/cache/redis.ts

@@ -0,0 +1,160 @@
+import type { CacheProvider } from '@mondaydotcomorg/atp-protocol';
+import type Redis from 'ioredis';
+
+export interface RedisCacheOptions {
+	redis: Redis;
+	keyPrefix?: string;
+	defaultTTL?: number;
+}
+
+/**
+ * Redis-backed cache provider for distributed systems
+ * Enables cross-pod state sharing and resume capabilities
+ */
+export class RedisCache implements CacheProvider {
+	name = 'redis';
+	private redis: Redis;
+	private keyPrefix: string;
+	private defaultTTL?: number;
+
+	constructor(options: RedisCacheOptions) {
+		this.redis = options.redis;
+		this.keyPrefix = options.keyPrefix || 'atp:cache:';
+		this.defaultTTL = options.defaultTTL;
+	}
+
+	private getFullKey(key: string): string {
+		return `${this.keyPrefix}${key}`;
+	}
+
+	async get<T>(key: string): Promise<T | null> {
+		try {
+			const value = await this.redis.get(this.getFullKey(key));
+			if (!value) return null;
+			return JSON.parse(value) as T;
+		} catch (error) {
+			console.error(
+				'[RedisCache] Failed to get key:',
+				key,
+				error instanceof Error ? error.message : error
+			);
+			return null;
+		}
+	}
+
+	async set(key: string, value: unknown, ttl?: number): Promise<void> {
+		try {
+			const serialized = JSON.stringify(value);
+			const fullKey = this.getFullKey(key);
+			const effectiveTTL = ttl ?? this.defaultTTL;
+
+			if (effectiveTTL) {
+				await this.redis.setex(fullKey, effectiveTTL, serialized);
+			} else {
+				await this.redis.set(fullKey, serialized);
+			}
+		} catch (error) {
+			console.error(
+				'[RedisCache] Failed to set key:',
+				key,
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+
+	async delete(key: string): Promise<void> {
+		try {
+			await this.redis.del(this.getFullKey(key));
+		} catch (error) {
+			console.error(
+				'[RedisCache] Failed to delete key:',
+				key,
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+
+	async has(key: string): Promise<boolean> {
+		try {
+			const exists = await this.redis.exists(this.getFullKey(key));
+			return exists === 1;
+		} catch (error) {
+			console.error(
+				'[RedisCache] Failed to check key:',
+				key,
+				error instanceof Error ? error.message : error
+			);
+			return false;
+		}
+	}
+
+	async clear(pattern?: string): Promise<void> {
+		try {
+			if (pattern) {
+				const fullPattern = this.getFullKey(pattern);
+				const keys = await this.redis.keys(fullPattern);
+				if (keys.length > 0) {
+					await this.redis.del(...keys);
+				}
+			} else {
+				const keys = await this.redis.keys(this.getFullKey('*'));
+				if (keys.length > 0) {
+					await this.redis.del(...keys);
+				}
+			}
+		} catch (error) {
+			console.error(
+				'[RedisCache] Failed to clear cache:',
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+
+	async mget(keys: string[]): Promise<Array<unknown | null>> {
+		try {
+			const fullKeys = keys.map((key) => this.getFullKey(key));
+			const values = await this.redis.mget(...fullKeys);
+			return values.map((value) => (value ? JSON.parse(value) : null));
+		} catch (error) {
+			console.error(
+				'[RedisCache] Failed to mget keys:',
+				error instanceof Error ? error.message : error
+			);
+			return keys.map(() => null);
+		}
+	}
+
+	async mset(entries: Array<[string, unknown, number?]>): Promise<void> {
+		try {
+			const pipeline = this.redis.pipeline();
+			for (const [key, value, ttl] of entries) {
+				const serialized = JSON.stringify(value);
+				const fullKey = this.getFullKey(key);
+				const effectiveTTL = ttl ?? this.defaultTTL;
+
+				if (effectiveTTL) {
+					pipeline.setex(fullKey, effectiveTTL, serialized);
+				} else {
+					pipeline.set(fullKey, serialized);
+				}
+			}
+			await pipeline.exec();
+		} catch (error) {
+			console.error(
+				'[RedisCache] Failed to mset entries:',
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+
+	async disconnect(): Promise<void> {
+		try {
+			await this.redis.quit();
+		} catch (error) {
+			console.error(
+				'[RedisCache] Failed to disconnect:',
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+export { MemoryCache } from './cache/memory.js';
+export { RedisCache } from './cache/redis.js';
+export { FileCache } from './cache/file.js';
+
+export { EnvAuthProvider } from './auth/env.js';
+
+export * from './oauth/index.js';
+
+export { JSONLAuditSink } from './audit/jsonl.js';
+export { OpenTelemetryAuditSink } from './audit/opentelemetry.js';
+
+export {
+	OTelCounter,
+	OTelHistogram,
+	OTelSpan,
+	OTelAttribute,
+	METRIC_CONFIGS,
+	OTEL_SERVICE_NAME,
+	OTEL_TRACER_NAME,
+	OTEL_METER_NAME,
+	ATTRIBUTE_PREFIX_TOOL,
+	ATTRIBUTE_PREFIX_METADATA,
+} from './audit/otel-metrics.js';
+
+export type {
+	CacheProvider,
+	AuthProvider,
+	AuditSink,
+	AuditEvent,
+	AuditFilter,
+	UserCredentialData,
+} from '@mondaydotcomorg/atp-protocol';

package/src/oauth/index.ts

@@ -0,0 +1 @@
+export { ScopeCheckerRegistry } from './scope-checkers.js';