alepha 0.15.1 → 0.15.3

package/dist/api/users/index.js

@@ -1,22 +1,28 @@
-import { $atom, $context, $hook, $inject, $module, Alepha, AlephaError, t } from "alepha";
+import { $atom, $context, $inject, $module, Alepha, AlephaError, Json, isFileLike, t } from "alepha";
 import { $notification, AlephaApiNotifications } from "alepha/api/notifications";
 import { AlephaApiVerification } from "alepha/api/verifications";
 import { AlephaEmail } from "alepha/email";
 import { AlephaServerCompress } from "alepha/server/compress";
 import { AlephaServerHelmet } from "alepha/server/helmet";
-import { $action, BadRequestError, ConflictError, HttpError, UnauthorizedError, okSchema } from "alepha/server";
-import { $entity, $repository, db, pageQuerySchema, parseQueryString } from "alepha/orm";
+import { $action, BadRequestError, ConflictError, ForbiddenError, HttpError, NotFoundError, UnauthorizedError, okSchema } from "alepha/server";
+import { $entity, $repository, db, pageQuerySchema, parseQueryString, sql } from "alepha/orm";
 import { AlephaApiAudits, AuditService } from "alepha/api/audits";
 import { $logger } from "alepha/logger";
 import { $bucket } from "alepha/bucket";
 import { $client } from "alepha/server/links";
 import { $authCredentials, $authGithub, $authGoogle, ServerAuthProvider, authenticationProviderSchema } from "alepha/server/auth";
-import { randomInt, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomInt, randomUUID } from "node:crypto";
 import { $cache } from "alepha/cache";
 import { DateTimeProvider } from "alepha/datetime";
 import { $issuer, CryptoProvider, InvalidCredentialsError, SecurityProvider } from "alepha/security";
-import { FileSystemProvider } from "alepha/file";
+import { join } from "node:path";
+import { createReadStream } from "node:fs";
+import { access, copyFile, cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { PassThrough, Readable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { exec, spawn } from "node:child_process";
 import { AlephaApiFiles } from "alepha/api/files";
+import { AlephaApiJobs } from "alepha/api/jobs";
 
 //#region ../../src/api/users/schemas/identityQuerySchema.ts
 const identityQuerySchema = t.extend(pageQuerySchema, {
@@ -184,16 +190,6 @@ var RealmProvider = class {
 			"image/webp"
 		]
 	});
-	onConfigure = $hook({
-		on: "configure",
-		handler: () => {
-			this.alepha.store.set("alepha.server.security.system.user", {
-				id: "00000000-0000-0000-0000-000000000000",
-				name: "system",
-				roles: ["admin"]
-			});
-		}
-	});
 	register(realmName, realmOptions = {}) {
 		this.realms.set(realmName, {
 			name: realmName,
@@ -1901,222 +1897,2062 @@ var UserController = class {
 };
 
 //#endregion
-//#region ../../src/api/users/services/SessionService.ts
-var SessionService = class {
-	alepha = $inject(Alepha);
-	fsp = $inject(FileSystemProvider);
-	dateTimeProvider = $inject(DateTimeProvider);
-	cryptoProvider = $inject(CryptoProvider);
-	log = $logger();
-	realmProvider = $inject(RealmProvider);
-	fileController = $client();
-	auditService = $inject(AuditService);
-	users(userRealmName) {
-		return this.realmProvider.userRepository(userRealmName);
+//#region ../../src/system/providers/FileSystemProvider.ts
+/**
+* FileSystem interface providing utilities for working with files.
+*/
+var FileSystemProvider = class {};
+
+//#endregion
+//#region ../../src/system/providers/MemoryFileSystemProvider.ts
+/**
+* In-memory implementation of FileSystemProvider for testing.
+*
+* This provider stores all files and directories in memory, making it ideal for
+* unit tests that need to verify file operations without touching the real file system.
+*
+* @example
+* ```typescript
+* // In tests, substitute the real FileSystemProvider with MemoryFileSystemProvider
+* const alepha = Alepha.create().with({
+*   provide: FileSystemProvider,
+*   use: MemoryFileSystemProvider,
+* });
+*
+* // Run code that uses FileSystemProvider
+* const service = alepha.inject(MyService);
+* await service.saveFile("test.txt", "Hello World");
+*
+* // Verify the file was written
+* const memoryFs = alepha.inject(MemoryFileSystemProvider);
+* expect(memoryFs.files.get("test.txt")?.toString()).toBe("Hello World");
+* ```
+*/
+var MemoryFileSystemProvider = class {
+	json = $inject(Json);
+	/**
+	* In-memory storage for files (path -> content)
+	*/
+	files = /* @__PURE__ */ new Map();
+	/**
+	* In-memory storage for directories
+	*/
+	directories = /* @__PURE__ */ new Set();
+	/**
+	* Track mkdir calls for test assertions
+	*/
+	mkdirCalls = [];
+	/**
+	* Track writeFile calls for test assertions
+	*/
+	writeFileCalls = [];
+	/**
+	* Track readFile calls for test assertions
+	*/
+	readFileCalls = [];
+	/**
+	* Track rm calls for test assertions
+	*/
+	rmCalls = [];
+	/**
+	* Track join calls for test assertions
+	*/
+	joinCalls = [];
+	/**
+	* Error to throw on mkdir (for testing error handling)
+	*/
+	mkdirError = null;
+	/**
+	* Error to throw on writeFile (for testing error handling)
+	*/
+	writeFileError = null;
+	/**
+	* Error to throw on readFile (for testing error handling)
+	*/
+	readFileError = null;
+	constructor(options = {}) {
+		this.mkdirError = options.mkdirError ?? null;
+		this.writeFileError = options.writeFileError ?? null;
+		this.readFileError = options.readFileError ?? null;
 	}
-	sessions(userRealmName) {
-		return this.realmProvider.sessionRepository(userRealmName);
+	/**
+	* Join path segments using forward slashes.
+	* Uses Node's path.join for proper normalization (handles .. and .)
+	*/
+	join(...paths) {
+		this.joinCalls.push(paths);
+		return join(...paths);
 	}
-	identities(userRealmName) {
-		return this.realmProvider.identityRepository(userRealmName);
+	/**
+	* Create a FileLike object from various sources.
+	*/
+	createFile(options) {
+		if ("path" in options) {
+			const filePath = options.path;
+			const buffer = this.files.get(filePath);
+			if (buffer === void 0) throw new Error(`ENOENT: no such file or directory, open '${filePath}'`);
+			return {
+				name: options.name ?? filePath.split("/").pop() ?? "file",
+				type: options.type ?? "application/octet-stream",
+				size: buffer.byteLength,
+				lastModified: Date.now(),
+				stream: () => {
+					throw new Error("Stream not implemented in MemoryFileSystemProvider");
+				},
+				arrayBuffer: async () => buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
+				text: async () => buffer.toString("utf-8")
+			};
+		}
+		if ("buffer" in options) {
+			const buffer = options.buffer;
+			return {
+				name: options.name ?? "file",
+				type: options.type ?? "application/octet-stream",
+				size: buffer.byteLength,
+				lastModified: Date.now(),
+				stream: () => {
+					throw new Error("Stream not implemented in MemoryFileSystemProvider");
+				},
+				arrayBuffer: async () => buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
+				text: async () => buffer.toString("utf-8")
+			};
+		}
+		if ("text" in options) {
+			const buffer = Buffer.from(options.text, "utf-8");
+			return {
+				name: options.name ?? "file.txt",
+				type: options.type ?? "text/plain",
+				size: buffer.byteLength,
+				lastModified: Date.now(),
+				stream: () => {
+					throw new Error("Stream not implemented in MemoryFileSystemProvider");
+				},
+				arrayBuffer: async () => buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
+				text: async () => options.text
+			};
+		}
+		throw new Error("MemoryFileSystemProvider.createFile: unsupported options. Only buffer and text are supported.");
 	}
 	/**
-	* Random delay to prevent timing attacks (50-200ms)
-	* Uses cryptographically secure random number generation
+	* Remove a file or directory from memory.
 	*/
-	randomDelay() {
-		return new Promise((resolve) => setTimeout(resolve, randomInt(50, 201)));
+	async rm(path, options) {
+		this.rmCalls.push({
+			path,
+			options
+		});
+		if (!(this.files.has(path) || this.directories.has(path)) && !options?.force) throw new Error(`ENOENT: no such file or directory, rm '${path}'`);
+		if (this.directories.has(path)) if (options?.recursive) {
+			this.directories.delete(path);
+			for (const filePath of this.files.keys()) if (filePath.startsWith(`${path}/`)) this.files.delete(filePath);
+			for (const dirPath of this.directories) if (dirPath.startsWith(`${path}/`)) this.directories.delete(dirPath);
+		} else throw new Error(`EISDIR: illegal operation on a directory, rm '${path}'`);
+		else this.files.delete(path);
 	}
 	/**
-	* Validate user credentials and return the user if valid.
+	* Copy a file or directory in memory.
 	*/
-	async login(provider, username, password, userRealmName) {
-		const { settings, name } = this.realmProvider.getRealm(userRealmName);
-		const isEmail = username.includes("@");
-		const isPhone = /^[+\d][\d\s()-]+$/.test(username);
-		const isUsername = !isEmail && !isPhone;
-		const identities = this.identities(userRealmName);
-		const users = this.users(userRealmName);
-		await this.randomDelay();
-		try {
-			const where = users.createQueryWhere();
-			where.realm = name;
-			if (settings.usernameEnabled !== false && isUsername) {
-				if (settings.usernameRegExp) {
-					if (!new RegExp(settings.usernameRegExp).test(username)) {
-						this.log.warn("Username does not match required format", {
-							provider,
-							username,
-							realm: name
-						});
-						await this.auditService.recordAuth("login_failed", {
-							userRealm: name,
-							description: "Username does not match required format",
-							metadata: {
-								provider,
-								username
-							}
-						});
-						throw new InvalidCredentialsError();
-					}
-				}
-				where.username = username;
-			} else if (settings.emailEnabled !== false && isEmail) where.email = username;
-			else if (settings.phoneEnabled === true && isPhone) where.phoneNumber = username;
-			else {
-				this.log.warn("Invalid login identifier format", {
-					provider,
-					username,
-					realm: name
-				});
-				await this.auditService.recordAuth("login_failed", {
-					userRealm: name,
-					description: "Invalid login identifier format",
-					metadata: {
-						provider,
-						username
-					}
-				});
-				throw new InvalidCredentialsError();
-			}
-			const user = await users.findOne({ where }).catch(() => void 0);
-			if (!user) {
-				this.log.warn("User not found during login attempt", {
-					provider,
-					username,
-					realm: name
-				});
-				await this.auditService.recordAuth("login_failed", {
-					userRealm: name,
-					description: "User not found",
-					metadata: {
-						provider,
-						username
-					}
-				});
-				throw new InvalidCredentialsError();
-			}
-			const identity = await identities.findOne({ where: {
-				provider: { eq: provider },
-				userId: { eq: user.id }
-			} });
-			const storedPassword = identity.password;
-			if (!storedPassword) {
-				this.log.error("Identity has no password configured", {
-					provider,
-					username,
-					identityId: identity.id,
-					realm: name
-				});
-				throw new InvalidCredentialsError();
+	async cp(src, dest, options) {
+		if (this.directories.has(src)) {
+			if (!options?.recursive) throw new Error(`Cannot copy directory without recursive option: ${src}`);
+			this.directories.add(dest);
+			for (const [filePath, content] of this.files) if (filePath.startsWith(`${src}/`)) {
+				const newPath = filePath.replace(src, dest);
+				this.files.set(newPath, Buffer.from(content));
 			}
-			if (!await this.cryptoProvider.verifyPassword(password, storedPassword)) {
-				this.log.warn("Invalid password during login attempt", {
-					provider,
-					username,
-					realm: name
-				});
-				await this.auditService.recordAuth("login_failed", {
-					userRealm: name,
-					resourceId: user.id,
-					description: "Invalid password",
-					metadata: {
-						provider,
-						username
-					}
-				});
-				throw new InvalidCredentialsError();
+		} else if (this.files.has(src)) {
+			const content = this.files.get(src);
+			this.files.set(dest, Buffer.from(content));
+		} else throw new Error(`ENOENT: no such file or directory, cp '${src}'`);
+	}
+	/**
+	* Move/rename a file or directory in memory.
+	*/
+	async mv(src, dest) {
+		if (this.directories.has(src)) {
+			this.directories.delete(src);
+			this.directories.add(dest);
+			for (const [filePath, content] of this.files) if (filePath.startsWith(`${src}/`)) {
+				const newPath = filePath.replace(src, dest);
+				this.files.delete(filePath);
+				this.files.set(newPath, content);
 			}
-			await this.auditService.recordAuth("login", {
-				userId: user.id,
-				userEmail: user.email ?? void 0,
-				userRealm: name,
-				resourceId: user.id,
-				description: `User logged in via ${provider}`,
-				metadata: {
-					provider,
-					username
-				}
-			});
-			return user;
-		} catch (error) {
-			if (error instanceof InvalidCredentialsError) throw error;
-			this.log.warn("Error during login attempt", error);
-			throw new InvalidCredentialsError();
-		}
+		} else if (this.files.has(src)) {
+			const content = this.files.get(src);
+			this.files.delete(src);
+			this.files.set(dest, content);
+		} else throw new Error(`ENOENT: no such file or directory, mv '${src}'`);
 	}
-	async createSession(user, expiresIn, userRealmName) {
-		this.log.trace("Creating session", {
-			userId: user.id,
-			expiresIn
-		});
-		const request = this.alepha.context.get("request");
-		const refreshToken = this.cryptoProvider.randomUUID();
-		const expiresAt = this.dateTimeProvider.now().add(expiresIn, "seconds").toISOString();
-		const session = await this.sessions(userRealmName).create({
-			userId: user.id,
-			expiresAt,
-			ip: request?.ip,
-			userAgent: request?.userAgent,
-			refreshToken
-		});
-		this.log.info("Session created", {
-			sessionId: session.id,
-			userId: user.id,
-			ip: request?.ip
+	/**
+	* Create a directory in memory.
+	*/
+	async mkdir(path, options) {
+		this.mkdirCalls.push({
+			path,
+			options
 		});
-		return {
-			refreshToken,
-			sessionId: session.id
-		};
-	}
-	async refreshSession(refreshToken, userRealmName) {
-		this.log.trace("Refreshing session");
-		const session = await this.sessions(userRealmName).findOne({ where: { refreshToken: { eq: refreshToken } } });
-		const now = this.dateTimeProvider.now();
-		const expiresAt = this.dateTimeProvider.of(session.expiresAt);
-		if (this.dateTimeProvider.of(session.expiresAt) < now) {
-			this.log.debug("Session expired during refresh", {
-				sessionId: session.id,
-				userId: session.userId
-			});
-			await this.sessions(userRealmName).deleteById(refreshToken);
-			throw new UnauthorizedError("Session expired");
+		if (this.mkdirError) throw this.mkdirError;
+		if (this.directories.has(path) && !options?.recursive) throw new Error(`EEXIST: file already exists, mkdir '${path}'`);
+		this.directories.add(path);
+		if (options?.recursive) {
+			const parts = path.split("/").filter(Boolean);
+			let current = "";
+			for (const part of parts) {
+				current = current ? `${current}/${part}` : part;
+				this.directories.add(current);
+			}
 		}
-		const user = await this.users(userRealmName).findOne({ where: { id: { eq: session.userId } } });
-		this.log.debug("Session refreshed", {
-			sessionId: session.id,
-			userId: session.userId
-		});
-		return {
-			user,
-			expiresIn: expiresAt.unix() - now.unix(),
-			sessionId: session.id
-		};
 	}
-	async deleteSession(refreshToken, userRealmName) {
-		this.log.trace("Deleting session");
-		const session = await this.sessions(userRealmName).findOne({ where: { refreshToken: { eq: refreshToken } } }).catch(() => void 0);
-		await this.sessions(userRealmName).deleteOne({ refreshToken });
-		this.log.debug("Session deleted");
-		if (session) {
-			const { name } = this.realmProvider.getRealm(userRealmName);
-			await this.auditService.recordAuth("logout", {
-				userId: session.userId,
-				userRealm: name,
-				sessionId: session.id,
-				description: "User logged out"
-			});
+	/**
+	* List files in a directory.
+	*/
+	async ls(path, options) {
+		const normalizedPath = path.replace(/\/$/, "");
+		const entries = /* @__PURE__ */ new Set();
+		for (const filePath of this.files.keys()) if (filePath.startsWith(`${normalizedPath}/`)) {
+			const relativePath = filePath.slice(normalizedPath.length + 1);
+			const parts = relativePath.split("/");
+			if (options?.recursive) entries.add(relativePath);
+			else entries.add(parts[0]);
+		}
+		for (const dirPath of this.directories) if (dirPath.startsWith(`${normalizedPath}/`) && dirPath !== normalizedPath) {
+			const relativePath = dirPath.slice(normalizedPath.length + 1);
+			const parts = relativePath.split("/");
+			if (options?.recursive) entries.add(relativePath);
+			else if (parts.length === 1) entries.add(parts[0]);
 		}
+		let result = Array.from(entries);
+		if (!options?.hidden) result = result.filter((entry) => !entry.startsWith("."));
+		return result.sort();
 	}
-	async link(provider, profile, userRealmName) {
-		this.log.trace("Linking OAuth2 profile", {
-			provider,
-			profileSub: profile.sub,
-			email: profile.email
-		});
-		const realm = this.realmProvider.getRealm(userRealmName);
-		const identities = this.identities(userRealmName);
+	/**
+	* Check if a file or directory exists in memory.
+	*/
+	async exists(path) {
+		return this.files.has(path) || this.directories.has(path);
+	}
+	/**
+	* Read a file from memory.
+	*/
+	async readFile(path) {
+		this.readFileCalls.push(path);
+		if (this.readFileError) throw this.readFileError;
+		const content = this.files.get(path);
+		if (!content) throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+		return content;
+	}
+	/**
+	* Read a file from memory as text.
+	*/
+	async readTextFile(path) {
+		return (await this.readFile(path)).toString("utf-8");
+	}
+	/**
+	* Read a file from memory as JSON.
+	*/
+	async readJsonFile(path) {
+		const text = await this.readTextFile(path);
+		return this.json.parse(text);
+	}
+	/**
+	* Write a file to memory.
+	*/
+	async writeFile(path, data) {
+		const dataStr = typeof data === "string" ? data : data instanceof Buffer || data instanceof Uint8Array ? data.toString("utf-8") : await data.text();
+		this.writeFileCalls.push({
+			path,
+			data: dataStr
+		});
+		if (this.writeFileError) throw this.writeFileError;
+		const buffer = typeof data === "string" ? Buffer.from(data, "utf-8") : data instanceof Buffer ? data : data instanceof Uint8Array ? Buffer.from(data) : Buffer.from(await data.text(), "utf-8");
+		this.files.set(path, buffer);
+	}
+	/**
+	* Reset all in-memory state (useful between tests).
+	*/
+	reset() {
+		this.files.clear();
+		this.directories.clear();
+		this.mkdirCalls = [];
+		this.writeFileCalls = [];
+		this.readFileCalls = [];
+		this.rmCalls = [];
+		this.joinCalls = [];
+		this.mkdirError = null;
+		this.writeFileError = null;
+		this.readFileError = null;
+	}
+	/**
+	* Check if a file was written during the test.
+	*
+	* @example
+	* ```typescript
+	* expect(fs.wasWritten("/project/tsconfig.json")).toBe(true);
+	* ```
+	*/
+	wasWritten(path) {
+		return this.writeFileCalls.some((call) => call.path === path);
+	}
+	/**
+	* Check if a file was written with content matching a pattern.
+	*
+	* @example
+	* ```typescript
+	* expect(fs.wasWrittenMatching("/project/tsconfig.json", /extends/)).toBe(true);
+	* ```
+	*/
+	wasWrittenMatching(path, pattern) {
+		const call = this.writeFileCalls.find((c) => c.path === path);
+		return call ? pattern.test(call.data) : false;
+	}
+	/**
+	* Check if a file was read during the test.
+	*
+	* @example
+	* ```typescript
+	* expect(fs.wasRead("/project/package.json")).toBe(true);
+	* ```
+	*/
+	wasRead(path) {
+		return this.readFileCalls.includes(path);
+	}
+	/**
+	* Check if a file was deleted during the test.
+	*
+	* @example
+	* ```typescript
+	* expect(fs.wasDeleted("/project/old-file.txt")).toBe(true);
+	* ```
+	*/
+	wasDeleted(path) {
+		return this.rmCalls.some((call) => call.path === path);
+	}
+	/**
+	* Get the content of a file as a string (convenience method for testing).
+	*/
+	getFileContent(path) {
+		return this.files.get(path)?.toString("utf-8");
+	}
+};
+
+//#endregion
+//#region ../../src/system/providers/MemoryShellProvider.ts
+/**
+* In-memory implementation of ShellProvider for testing.
+*
+* Records all commands that would be executed without actually running them.
+* Can be configured to return specific outputs or throw errors for testing.
+*
+* @example
+* ```typescript
+* // In tests, substitute the real ShellProvider with MemoryShellProvider
+* const alepha = Alepha.create().with({
+*   provide: ShellProvider,
+*   use: MemoryShellProvider,
+* });
+*
+* // Configure mock behavior
+* const shell = alepha.inject(MemoryShellProvider);
+* shell.configure({
+*   outputs: { "echo hello": "hello\n" },
+*   errors: { "failing-cmd": "Command failed" },
+* });
+*
+* // Or use the fluent API
+* shell.outputs.set("another-cmd", "output");
+* shell.errors.set("another-error", "Error message");
+*
+* // Run code that uses ShellProvider
+* const service = alepha.inject(MyService);
+* await service.doSomething();
+*
+* // Verify commands were called
+* expect(shell.calls).toHaveLength(2);
+* expect(shell.calls[0].command).toBe("yarn install");
+* ```
+*/
+var MemoryShellProvider = class {
+	/**
+	* All recorded shell calls.
+	*/
+	calls = [];
+	/**
+	* Simulated outputs for specific commands.
+	*/
+	outputs = /* @__PURE__ */ new Map();
+	/**
+	* Commands that should throw an error.
+	*/
+	errors = /* @__PURE__ */ new Map();
+	/**
+	* Commands considered installed in the system PATH.
+	*/
+	installedCommands = /* @__PURE__ */ new Set();
+	/**
+	* Configure the mock with predefined outputs, errors, and installed commands.
+	*/
+	configure(options) {
+		if (options.outputs) for (const [cmd, output] of Object.entries(options.outputs)) this.outputs.set(cmd, output);
+		if (options.errors) for (const [cmd, error] of Object.entries(options.errors)) this.errors.set(cmd, error);
+		if (options.installedCommands) for (const cmd of options.installedCommands) this.installedCommands.add(cmd);
+		return this;
+	}
+	/**
+	* Record command and return simulated output.
+	*/
+	async run(command, options = {}) {
+		this.calls.push({
+			command,
+			options
+		});
+		const errorMsg = this.errors.get(command);
+		if (errorMsg) throw new Error(errorMsg);
+		return this.outputs.get(command) ?? "";
+	}
+	/**
+	* Check if a specific command was called.
+	*/
+	wasCalled(command) {
+		return this.calls.some((call) => call.command === command);
+	}
+	/**
+	* Check if a command matching a pattern was called.
+	*/
+	wasCalledMatching(pattern) {
+		return this.calls.some((call) => pattern.test(call.command));
+	}
+	/**
+	* Get all calls matching a pattern.
+	*/
+	getCallsMatching(pattern) {
+		return this.calls.filter((call) => pattern.test(call.command));
+	}
+	/**
+	* Check if a command is installed.
+	*/
+	async isInstalled(command) {
+		return this.installedCommands.has(command);
+	}
+	/**
+	* Reset all recorded state.
+	*/
+	reset() {
+		this.calls = [];
+		this.outputs.clear();
+		this.errors.clear();
+		this.installedCommands.clear();
+	}
+};
+
+//#endregion
+//#region ../../src/system/services/FileDetector.ts
+/**
+* Service for detecting file types and getting content types.
+*
+* @example
+* ```typescript
+* const detector = alepha.inject(FileDetector);
+*
+* // Get content type from filename
+* const mimeType = detector.getContentType("image.png"); // "image/png"
+*
+* // Detect file type by magic bytes
+* const stream = createReadStream('image.png');
+* const result = await detector.detectFileType(stream, 'image.png');
+* console.log(result.mimeType); // 'image/png'
+* console.log(result.verified); // true if magic bytes match
+* ```
+*/
+var FileDetector = class FileDetector {
+	/**
+	* Magic byte signatures for common file formats.
+	* Each signature is represented as an array of bytes or null (wildcard).
+	*/
+	static MAGIC_BYTES = {
+		png: [{
+			signature: [
+				137,
+				80,
+				78,
+				71,
+				13,
+				10,
+				26,
+				10
+			],
+			mimeType: "image/png"
+		}],
+		jpg: [
+			{
+				signature: [
+					255,
+					216,
+					255,
+					224
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					225
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					226
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					227
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					232
+				],
+				mimeType: "image/jpeg"
+			}
+		],
+		jpeg: [
+			{
+				signature: [
+					255,
+					216,
+					255,
+					224
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					225
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					226
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					227
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					232
+				],
+				mimeType: "image/jpeg"
+			}
+		],
+		gif: [{
+			signature: [
+				71,
+				73,
+				70,
+				56,
+				55,
+				97
+			],
+			mimeType: "image/gif"
+		}, {
+			signature: [
+				71,
+				73,
+				70,
+				56,
+				57,
+				97
+			],
+			mimeType: "image/gif"
+		}],
+		webp: [{
+			signature: [
+				82,
+				73,
+				70,
+				70,
+				null,
+				null,
+				null,
+				null,
+				87,
+				69,
+				66,
+				80
+			],
+			mimeType: "image/webp"
+		}],
+		bmp: [{
+			signature: [66, 77],
+			mimeType: "image/bmp"
+		}],
+		ico: [{
+			signature: [
+				0,
+				0,
+				1,
+				0
+			],
+			mimeType: "image/x-icon"
+		}],
+		tiff: [{
+			signature: [
+				73,
+				73,
+				42,
+				0
+			],
+			mimeType: "image/tiff"
+		}, {
+			signature: [
+				77,
+				77,
+				0,
+				42
+			],
+			mimeType: "image/tiff"
+		}],
+		tif: [{
+			signature: [
+				73,
+				73,
+				42,
+				0
+			],
+			mimeType: "image/tiff"
+		}, {
+			signature: [
+				77,
+				77,
+				0,
+				42
+			],
+			mimeType: "image/tiff"
+		}],
+		pdf: [{
+			signature: [
+				37,
+				80,
+				68,
+				70,
+				45
+			],
+			mimeType: "application/pdf"
+		}],
+		zip: [
+			{
+				signature: [
+					80,
+					75,
+					3,
+					4
+				],
+				mimeType: "application/zip"
+			},
+			{
+				signature: [
+					80,
+					75,
+					5,
+					6
+				],
+				mimeType: "application/zip"
+			},
+			{
+				signature: [
+					80,
+					75,
+					7,
+					8
+				],
+				mimeType: "application/zip"
+			}
+		],
+		rar: [{
+			signature: [
+				82,
+				97,
+				114,
+				33,
+				26,
+				7
+			],
+			mimeType: "application/vnd.rar"
+		}],
+		"7z": [{
+			signature: [
+				55,
+				122,
+				188,
+				175,
+				39,
+				28
+			],
+			mimeType: "application/x-7z-compressed"
+		}],
+		tar: [{
+			signature: [
+				117,
+				115,
+				116,
+				97,
+				114
+			],
+			mimeType: "application/x-tar"
+		}],
+		gz: [{
+			signature: [31, 139],
+			mimeType: "application/gzip"
+		}],
+		tgz: [{
+			signature: [31, 139],
+			mimeType: "application/gzip"
+		}],
+		mp3: [
+			{
+				signature: [255, 251],
+				mimeType: "audio/mpeg"
+			},
+			{
+				signature: [255, 243],
+				mimeType: "audio/mpeg"
+			},
+			{
+				signature: [255, 242],
+				mimeType: "audio/mpeg"
+			},
+			{
+				signature: [
+					73,
+					68,
+					51
+				],
+				mimeType: "audio/mpeg"
+			}
+		],
+		wav: [{
+			signature: [
+				82,
+				73,
+				70,
+				70,
+				null,
+				null,
+				null,
+				null,
+				87,
+				65,
+				86,
+				69
+			],
+			mimeType: "audio/wav"
+		}],
+		ogg: [{
+			signature: [
+				79,
+				103,
+				103,
+				83
+			],
+			mimeType: "audio/ogg"
+		}],
+		flac: [{
+			signature: [
+				102,
+				76,
+				97,
+				67
+			],
+			mimeType: "audio/flac"
+		}],
+		mp4: [
+			{
+				signature: [
+					null,
+					null,
+					null,
+					null,
+					102,
+					116,
+					121,
+					112
+				],
+				mimeType: "video/mp4"
+			},
+			{
+				signature: [
+					null,
+					null,
+					null,
+					null,
+					102,
+					116,
+					121,
+					112,
+					105,
+					115,
+					111,
+					109
+				],
+				mimeType: "video/mp4"
+			},
+			{
+				signature: [
+					null,
+					null,
+					null,
+					null,
+					102,
+					116,
+					121,
+					112,
+					109,
+					112,
+					52,
+					50
+				],
+				mimeType: "video/mp4"
+			}
+		],
+		webm: [{
+			signature: [
+				26,
+				69,
+				223,
+				163
+			],
+			mimeType: "video/webm"
+		}],
+		avi: [{
+			signature: [
+				82,
+				73,
+				70,
+				70,
+				null,
+				null,
+				null,
+				null,
+				65,
+				86,
+				73,
+				32
+			],
+			mimeType: "video/x-msvideo"
+		}],
+		mov: [{
+			signature: [
+				null,
+				null,
+				null,
+				null,
+				102,
+				116,
+				121,
+				112,
+				113,
+				116,
+				32,
+				32
+			],
+			mimeType: "video/quicktime"
+		}],
+		mkv: [{
+			signature: [
+				26,
+				69,
+				223,
+				163
+			],
+			mimeType: "video/x-matroska"
+		}],
+		docx: [{
+			signature: [
+				80,
+				75,
+				3,
+				4
+			],
+			mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+		}],
+		xlsx: [{
+			signature: [
+				80,
+				75,
+				3,
+				4
+			],
+			mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+		}],
+		pptx: [{
+			signature: [
+				80,
+				75,
+				3,
+				4
+			],
+			mimeType: "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+		}],
+		doc: [{
+			signature: [
+				208,
+				207,
+				17,
+				224,
+				161,
+				177,
+				26,
+				225
+			],
+			mimeType: "application/msword"
+		}],
+		xls: [{
+			signature: [
+				208,
+				207,
+				17,
+				224,
+				161,
+				177,
+				26,
+				225
+			],
+			mimeType: "application/vnd.ms-excel"
+		}],
+		ppt: [{
+			signature: [
+				208,
+				207,
+				17,
+				224,
+				161,
+				177,
+				26,
+				225
+			],
+			mimeType: "application/vnd.ms-powerpoint"
+		}]
+	};
+	/**
+	* All possible format signatures for checking against actual file content
+	*/
+	static ALL_SIGNATURES = Object.entries(FileDetector.MAGIC_BYTES).flatMap(([ext, signatures]) => signatures.map((sig) => ({
+		ext,
+		...sig
+	})));
+	/**
+	* MIME type map for file extensions.
+	*
+	* Can be used to get the content type of file based on its extension.
+	* Feel free to add more mime types in your project!
+	*/
+	static mimeMap = {
+		json: "application/json",
+		txt: "text/plain",
+		html: "text/html",
+		htm: "text/html",
+		xml: "application/xml",
+		csv: "text/csv",
+		pdf: "application/pdf",
+		md: "text/markdown",
+		markdown: "text/markdown",
+		rtf: "application/rtf",
+		css: "text/css",
+		js: "application/javascript",
+		mjs: "application/javascript",
+		ts: "application/typescript",
+		jsx: "text/jsx",
+		tsx: "text/tsx",
+		zip: "application/zip",
+		rar: "application/vnd.rar",
+		"7z": "application/x-7z-compressed",
+		tar: "application/x-tar",
+		gz: "application/gzip",
+		tgz: "application/gzip",
+		png: "image/png",
+		jpg: "image/jpeg",
+		jpeg: "image/jpeg",
+		gif: "image/gif",
+		webp: "image/webp",
+		svg: "image/svg+xml",
+		bmp: "image/bmp",
+		ico: "image/x-icon",
+		tiff: "image/tiff",
+		tif: "image/tiff",
+		mp3: "audio/mpeg",
+		wav: "audio/wav",
+		ogg: "audio/ogg",
+		m4a: "audio/mp4",
+		aac: "audio/aac",
+		flac: "audio/flac",
+		mp4: "video/mp4",
+		webm: "video/webm",
+		avi: "video/x-msvideo",
+		mov: "video/quicktime",
+		wmv: "video/x-ms-wmv",
+		flv: "video/x-flv",
+		mkv: "video/x-matroska",
+		doc: "application/msword",
+		docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+		xls: "application/vnd.ms-excel",
+		xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+		ppt: "application/vnd.ms-powerpoint",
+		pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+		woff: "font/woff",
+		woff2: "font/woff2",
+		ttf: "font/ttf",
+		otf: "font/otf",
+		eot: "application/vnd.ms-fontobject"
+	};
+	/**
+	* Reverse MIME type map for looking up extensions from MIME types.
+	* Prefers shorter, more common extensions when multiple exist.
+	*/
+	static reverseMimeMap = (() => {
+		const reverse = {};
+		for (const [ext, mimeType] of Object.entries(FileDetector.mimeMap)) if (!reverse[mimeType]) reverse[mimeType] = ext;
+		return reverse;
+	})();
+	/**
+	* Returns the file extension for a given MIME type.
+	*
+	* @param mimeType - The MIME type to look up
+	* @returns The file extension (without dot), or "bin" if not found
+	*
+	* @example
+	* ```typescript
+	* const detector = alepha.inject(FileDetector);
+	* const ext = detector.getExtensionFromMimeType("image/png"); // "png"
+	* const ext2 = detector.getExtensionFromMimeType("application/octet-stream"); // "bin"
+	* ```
+	*/
+	getExtensionFromMimeType(mimeType) {
+		return FileDetector.reverseMimeMap[mimeType] || "bin";
+	}
+	/**
+	* Returns the content type of file based on its filename.
+	*
+	* @param filename - The filename to check
+	* @returns The MIME type
+	*
+	* @example
+	* ```typescript
+	* const detector = alepha.inject(FileDetector);
+	* const mimeType = detector.getContentType("image.png"); // "image/png"
+	* ```
+	*/
+	getContentType(filename) {
+		const ext = filename.toLowerCase().split(".").pop() || "";
+		return FileDetector.mimeMap[ext] || "application/octet-stream";
+	}
+	/**
+	* Detects the file type by checking magic bytes against the stream content.
+	*
+	* @param stream - The readable stream to check
+	* @param filename - The filename (used to get the extension)
+	* @returns File type information including MIME type, extension, and verification status
+	*
+	* @example
+	* ```typescript
+	* const detector = alepha.inject(FileDetector);
+	* const stream = createReadStream('image.png');
+	* const result = await detector.detectFileType(stream, 'image.png');
+	* console.log(result.mimeType); // 'image/png'
+	* console.log(result.verified); // true if magic bytes match
+	* ```
+	*/
+	async detectFileType(stream, filename) {
+		const expectedMimeType = this.getContentType(filename);
+		const lastDotIndex = filename.lastIndexOf(".");
+		const ext = lastDotIndex > 0 ? filename.substring(lastDotIndex + 1).toLowerCase() : "";
+		const { buffer, stream: newStream } = await this.peekBytes(stream, 16);
+		const expectedSignatures = FileDetector.MAGIC_BYTES[ext];
+		if (expectedSignatures) {
+			for (const { signature, mimeType } of expectedSignatures) if (this.matchesSignature(buffer, signature)) return {
+				mimeType,
+				extension: ext,
+				verified: true,
+				stream: newStream
+			};
+		}
+		for (const { ext: detectedExt, signature, mimeType } of FileDetector.ALL_SIGNATURES) if (detectedExt !== ext && this.matchesSignature(buffer, signature)) return {
+			mimeType,
+			extension: detectedExt,
+			verified: true,
+			stream: newStream
+		};
+		return {
+			mimeType: expectedMimeType,
+			extension: ext,
+			verified: false,
+			stream: newStream
+		};
+	}
+	/**
+	* Reads all bytes from a stream and returns the first N bytes along with a new stream containing all data.
+	* This approach reads the entire stream upfront to avoid complex async handling issues.
+	*
+	* @protected
+	*/
+	async peekBytes(stream, numBytes) {
+		const chunks = [];
+		for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+		const allData = Buffer.concat(chunks);
+		return {
+			buffer: allData.subarray(0, numBytes),
+			stream: Readable.from(allData)
+		};
+	}
+	/**
+	* Checks if a buffer matches a magic byte signature.
+	*
+	* @protected
+	*/
+	matchesSignature(buffer, signature) {
+		if (buffer.length < signature.length) return false;
+		for (let i = 0; i < signature.length; i++) if (signature[i] !== null && buffer[i] !== signature[i]) return false;
+		return true;
+	}
+};
+
+//#endregion
+//#region ../../src/system/providers/NodeFileSystemProvider.ts
+/**
+* Node.js implementation of FileSystem interface.
+*
+* @example
+* ```typescript
+* const fs = alepha.inject(NodeFileSystemProvider);
+*
+* // Create from URL
+* const file1 = fs.createFile({ url: "file:///path/to/file.png" });
+*
+* // Create from Buffer
+* const file2 = fs.createFile({ buffer: Buffer.from("hello"), name: "hello.txt" });
+*
+* // Create from text
+* const file3 = fs.createFile({ text: "Hello, world!", name: "greeting.txt" });
+*
+* // File operations
+* await fs.mkdir("/tmp/mydir", { recursive: true });
+* await fs.cp("/src/file.txt", "/dest/file.txt");
+* await fs.mv("/old/path.txt", "/new/path.txt");
+* const files = await fs.ls("/tmp");
+* await fs.rm("/tmp/file.txt");
+* ```
+*/
+var NodeFileSystemProvider = class {
+	detector = $inject(FileDetector);
+	json = $inject(Json);
+	join(...paths) {
+		return join(...paths);
+	}
+	/**
+	* Creates a FileLike object from various sources.
+	*
+	* @param options - Options for creating the file
+	* @returns A FileLike object
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // From URL
+	* const file1 = fs.createFile({ url: "https://example.com/image.png" });
+	*
+	* // From Buffer
+	* const file2 = fs.createFile({
+	*   buffer: Buffer.from("hello"),
+	*   name: "hello.txt",
+	*   type: "text/plain"
+	* });
+	*
+	* // From text
+	* const file3 = fs.createFile({ text: "Hello!", name: "greeting.txt" });
+	*
+	* // From stream with detection
+	* const stream = createReadStream("/path/to/file.png");
+	* const file4 = fs.createFile({ stream, name: "image.png" });
+	* ```
+	*/
+	createFile(options) {
+		if ("path" in options) {
+			const path = options.path;
+			const filename = path.split("/").pop() || "file";
+			return this.createFileFromUrl(`file://${path}`, {
+				type: options.type,
+				name: options.name || filename
+			});
+		}
+		if ("url" in options) return this.createFileFromUrl(options.url, {
+			type: options.type,
+			name: options.name
+		});
+		if ("response" in options) {
+			if (!options.response.body) throw new AlephaError("Response has no body stream");
+			const res = options.response;
+			const sizeHeader = res.headers.get("content-length");
+			const size = sizeHeader ? parseInt(sizeHeader, 10) : void 0;
+			let name = options.name;
+			const contentDisposition = res.headers.get("content-disposition");
+			if (contentDisposition && !name) {
+				const match = contentDisposition.match(/filename="?([^"]+)"?/);
+				if (match) name = match[1];
+			}
+			const type = options.type || res.headers.get("content-type") || void 0;
+			return this.createFileFromStream(options.response.body, {
+				type,
+				name,
+				size
+			});
+		}
+		if ("file" in options) return this.createFileFromWebFile(options.file, {
+			type: options.type,
+			name: options.name,
+			size: options.size
+		});
+		if ("buffer" in options) return this.createFileFromBuffer(options.buffer, {
+			type: options.type,
+			name: options.name
+		});
+		if ("arrayBuffer" in options) return this.createFileFromBuffer(Buffer.from(options.arrayBuffer), {
+			type: options.type,
+			name: options.name
+		});
+		if ("text" in options) return this.createFileFromBuffer(Buffer.from(options.text, "utf-8"), {
+			type: options.type || "text/plain",
+			name: options.name || "file.txt"
+		});
+		if ("stream" in options) return this.createFileFromStream(options.stream, {
+			type: options.type,
+			name: options.name,
+			size: options.size
+		});
+		throw new AlephaError("Invalid createFile options: no valid source provided");
+	}
+	/**
+	* Removes a file or directory.
+	*
+	* @param path - The path to remove
+	* @param options - Remove options
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // Remove a file
+	* await fs.rm("/tmp/file.txt");
+	*
+	* // Remove a directory recursively
+	* await fs.rm("/tmp/mydir", { recursive: true });
+	*
+	* // Remove with force (no error if doesn't exist)
+	* await fs.rm("/tmp/maybe-exists.txt", { force: true });
+	* ```
+	*/
+	async rm(path, options) {
+		await rm(path, options);
+	}
+	/**
+	* Copies a file or directory.
+	*
+	* @param src - Source path
+	* @param dest - Destination path
+	* @param options - Copy options
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // Copy a file
+	* await fs.cp("/src/file.txt", "/dest/file.txt");
+	*
+	* // Copy a directory recursively
+	* await fs.cp("/src/dir", "/dest/dir", { recursive: true });
+	*
+	* // Copy with force (overwrite existing)
+	* await fs.cp("/src/file.txt", "/dest/file.txt", { force: true });
+	* ```
+	*/
+	async cp(src, dest, options) {
+		if ((await stat(src)).isDirectory()) {
+			if (!options?.recursive) throw new Error(`Cannot copy directory without recursive option: ${src}`);
+			await cp(src, dest, {
+				recursive: true,
+				force: options?.force ?? false
+			});
+		} else await copyFile(src, dest);
+	}
+	/**
+	* Moves/renames a file or directory.
+	*
+	* @param src - Source path
+	* @param dest - Destination path
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // Move/rename a file
+	* await fs.mv("/old/path.txt", "/new/path.txt");
+	*
+	* // Move a directory
+	* await fs.mv("/old/dir", "/new/dir");
+	* ```
+	*/
+	async mv(src, dest) {
+		await rename(src, dest);
+	}
+	/**
+	* Creates a directory.
+	*
+	* @param path - The directory path to create
+	* @param options - Mkdir options
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // Create a directory
+	* await fs.mkdir("/tmp/mydir");
+	*
+	* // Create nested directories
+	* await fs.mkdir("/tmp/path/to/dir", { recursive: true });
+	*
+	* // Create with specific permissions
+	* await fs.mkdir("/tmp/mydir", { mode: 0o755 });
+	* ```
+	*/
+	async mkdir(path, options = {}) {
+		const p = mkdir(path, {
+			recursive: options.recursive ?? true,
+			mode: options.mode
+		});
+		if (options.force === false) await p;
+		else await p.catch(() => {});
+	}
+	/**
+	* Lists files in a directory.
+	*
+	* @param path - The directory path to list
+	* @param options - List options
+	* @returns Array of filenames
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // List files in a directory
+	* const files = await fs.ls("/tmp");
+	* console.log(files); // ["file1.txt", "file2.txt", "subdir"]
+	*
+	* // List with hidden files
+	* const allFiles = await fs.ls("/tmp", { hidden: true });
+	*
+	* // List recursively
+	* const allFilesRecursive = await fs.ls("/tmp", { recursive: true });
+	* ```
+	*/
+	async ls(path, options) {
+		const entries = await readdir(path);
+		const filteredEntries = options?.hidden ? entries : entries.filter((e) => !e.startsWith("."));
+		if (options?.recursive) {
+			const allFiles = [];
+			for (const entry of filteredEntries) {
+				const fullPath = join(path, entry);
+				if ((await stat(fullPath)).isDirectory()) {
+					allFiles.push(entry);
+					const subFiles = await this.ls(fullPath, options);
+					allFiles.push(...subFiles.map((f) => join(entry, f)));
+				} else allFiles.push(entry);
+			}
+			return allFiles;
+		}
+		return filteredEntries;
+	}
+	/**
+	* Checks if a file or directory exists.
+	*
+	* @param path - The path to check
+	* @returns True if the path exists, false otherwise
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* if (await fs.exists("/tmp/file.txt")) {
+	*   console.log("File exists");
+	* }
+	* ```
+	*/
+	async exists(path) {
+		try {
+			await access(path);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Reads the content of a file.
+	*
+	* @param path - The file path to read
+	* @returns The file content as a Buffer
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* const buffer = await fs.readFile("/tmp/file.txt");
+	* console.log(buffer.toString("utf-8"));
+	* ```
+	*/
+	async readFile(path) {
+		return await readFile(path);
+	}
+	/**
+	* Writes data to a file.
+	*
+	* @param path - The file path to write to
+	* @param data - The data to write (Buffer or string)
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // Write string
+	* await fs.writeFile("/tmp/file.txt", "Hello, world!");
+	*
+	* // Write Buffer
+	* await fs.writeFile("/tmp/file.bin", Buffer.from([0x01, 0x02, 0x03]));
+	* ```
+	*/
+	async writeFile(path, data) {
+		if (isFileLike(data)) {
+			await writeFile(path, Readable.from(data.stream()));
+			return;
+		}
+		await writeFile(path, data);
+	}
+	/**
+	* Reads the content of a file as a string.
+	*
+	* @param path - The file path to read
+	* @returns The file content as a string
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	* const content = await fs.readTextFile("/tmp/file.txt");
+	* ```
+	*/
+	async readTextFile(path) {
+		return (await this.readFile(path)).toString("utf-8");
+	}
+	/**
+	* Reads the content of a file as JSON.
+	*
+	* @param path - The file path to read
+	* @returns The parsed JSON content
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	* const config = await fs.readJsonFile<{ name: string }>("/tmp/config.json");
+	* ```
+	*/
+	async readJsonFile(path) {
+		const text = await this.readTextFile(path);
+		return this.json.parse(text);
+	}
+	/**
+	* Creates a FileLike object from a Web File.
+	*
+	* @protected
+	*/
+	createFileFromWebFile(source, options = {}) {
+		const name = options.name ?? source.name;
+		return {
+			name,
+			type: options.type ?? (source.type || this.detector.getContentType(name)),
+			size: options.size ?? source.size ?? 0,
+			lastModified: source.lastModified || Date.now(),
+			stream: () => source.stream(),
+			arrayBuffer: async () => {
+				return await source.arrayBuffer();
+			},
+			text: async () => {
+				return await source.text();
+			}
+		};
+	}
+	/**
+	* Creates a FileLike object from a Buffer.
+	*
+	* @protected
+	*/
+	createFileFromBuffer(source, options = {}) {
+		const name = options.name ?? "file";
+		return {
+			name,
+			type: options.type ?? this.detector.getContentType(options.name ?? name),
+			size: source.byteLength,
+			lastModified: Date.now(),
+			stream: () => Readable.from(source),
+			arrayBuffer: async () => {
+				return this.bufferToArrayBuffer(source);
+			},
+			text: async () => {
+				return source.toString("utf-8");
+			}
+		};
+	}
+	/**
+	* Creates a FileLike object from a stream.
+	*
+	* @protected
+	*/
+	createFileFromStream(source, options = {}) {
+		let buffer = null;
+		return {
+			name: options.name ?? "file",
+			type: options.type ?? this.detector.getContentType(options.name ?? "file"),
+			size: options.size ?? 0,
+			lastModified: Date.now(),
+			stream: () => source,
+			_buffer: null,
+			arrayBuffer: async () => {
+				buffer ??= await this.streamToBuffer(source);
+				return this.bufferToArrayBuffer(buffer);
+			},
+			text: async () => {
+				buffer ??= await this.streamToBuffer(source);
+				return buffer.toString("utf-8");
+			}
+		};
+	}
+	/**
+	* Creates a FileLike object from a URL.
+	*
+	* @protected
+	*/
+	createFileFromUrl(url, options = {}) {
+		const parsedUrl = new URL(url);
+		const filename = options.name || parsedUrl.pathname.split("/").pop() || "file";
+		let buffer = null;
+		return {
+			name: filename,
+			type: options.type ?? this.detector.getContentType(filename),
+			size: 0,
+			lastModified: Date.now(),
+			stream: () => this.createStreamFromUrl(url),
+			arrayBuffer: async () => {
+				buffer ??= await this.loadFromUrl(url);
+				return this.bufferToArrayBuffer(buffer);
+			},
+			text: async () => {
+				buffer ??= await this.loadFromUrl(url);
+				return buffer.toString("utf-8");
+			},
+			filepath: url
+		};
+	}
+	/**
+	* Gets a streaming response from a URL.
+	*
+	* @protected
+	*/
+	getStreamingResponse(url) {
+		const stream = new PassThrough();
+		fetch(url).then((res) => Readable.fromWeb(res.body).pipe(stream)).catch((err) => stream.destroy(err));
+		return stream;
+	}
+	/**
+	* Loads data from a URL.
+	*
+	* @protected
+	*/
+	async loadFromUrl(url) {
+		const parsedUrl = new URL(url);
+		if (parsedUrl.protocol === "file:") return await readFile(fileURLToPath(url));
+		else if (parsedUrl.protocol === "http:" || parsedUrl.protocol === "https:") {
+			const response = await fetch(url);
+			if (!response.ok) throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+			const arrayBuffer = await response.arrayBuffer();
+			return Buffer.from(arrayBuffer);
+		} else throw new Error(`Unsupported protocol: ${parsedUrl.protocol}`);
+	}
+	/**
+	* Creates a stream from a URL.
+	*
+	* @protected
+	*/
+	createStreamFromUrl(url) {
+		const parsedUrl = new URL(url);
+		if (parsedUrl.protocol === "file:") return createReadStream(fileURLToPath(url));
+		else if (parsedUrl.protocol === "http:" || parsedUrl.protocol === "https:") return this.getStreamingResponse(url);
+		else throw new AlephaError(`Unsupported protocol: ${parsedUrl.protocol}`);
+	}
+	/**
+	* Converts a stream-like object to a Buffer.
+	*
+	* @protected
+	*/
+	async streamToBuffer(streamLike) {
+		const stream = streamLike instanceof Readable ? streamLike : Readable.fromWeb(streamLike);
+		return new Promise((resolve, reject) => {
+			const buffer = [];
+			stream.on("data", (chunk) => buffer.push(Buffer.from(chunk)));
+			stream.on("end", () => resolve(Buffer.concat(buffer)));
+			stream.on("error", (err) => reject(new AlephaError("Error converting stream", { cause: err })));
+		});
+	}
+	/**
+	* Converts a Node.js Buffer to an ArrayBuffer.
+	*
+	* @protected
+	*/
+	bufferToArrayBuffer(buffer) {
+		return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+	}
+};
+
+//#endregion
+//#region ../../src/system/providers/NodeShellProvider.ts
+/**
+* Node.js implementation of ShellProvider.
+*
+* Executes shell commands using Node.js child_process module.
+* Supports binary resolution from node_modules/.bin for local packages.
+*/
+var NodeShellProvider = class {
+	log = $logger();
+	fs = $inject(FileSystemProvider);
+	/**
+	* Run a shell command or binary.
+	*/
+	async run(command, options = {}) {
+		const { resolve = false, capture = false, root, env } = options;
+		const cwd = root ?? process.cwd();
+		this.log.debug(`Shell: ${command}`, {
+			cwd,
+			resolve,
+			capture
+		});
+		let executable;
+		let args;
+		if (resolve) {
+			const [bin, ...rest] = command.split(" ");
+			executable = await this.resolveExecutable(bin, cwd);
+			args = rest;
+		} else [executable, ...args] = command.split(" ");
+		if (capture) return this.execCapture(command, {
+			cwd,
+			env
+		});
+		return this.execInherit(executable, args, {
+			cwd,
+			env
+		});
+	}
+	/**
+	* Execute command with inherited stdio (streams to terminal).
+	*/
+	async execInherit(executable, args, options) {
+		const proc = spawn(executable, args, {
+			stdio: "inherit",
+			cwd: options.cwd,
+			env: {
+				...process.env,
+				...options.env
+			}
+		});
+		return new Promise((resolve, reject) => {
+			proc.on("exit", (code) => {
+				if (code === 0 || code === null) resolve("");
+				else reject(new AlephaError(`Command exited with code ${code}`));
+			});
+			proc.on("error", reject);
+		});
+	}
+	/**
+	* Execute command and capture stdout.
+	*/
+	execCapture(command, options) {
+		return new Promise((resolve, reject) => {
+			exec(command, {
+				cwd: options.cwd,
+				env: {
+					...process.env,
+					LOG_FORMAT: "pretty",
+					...options.env
+				}
+			}, (err, stdout) => {
+				if (err) {
+					err.stdout = stdout;
+					reject(err);
+				} else resolve(stdout);
+			});
+		});
+	}
+	/**
+	* Resolve executable path from node_modules/.bin.
+	*
+	* Search order:
+	* 1. Local: node_modules/.bin/
+	* 2. Pnpm nested: node_modules/alepha/node_modules/.bin/
+	* 3. Monorepo: Walk up to 3 parent directories
+	*/
+	async resolveExecutable(name, root) {
+		const suffix = process.platform === "win32" ? ".cmd" : "";
+		let execPath = await this.findExecutable(root, `node_modules/.bin/${name}${suffix}`);
+		if (!execPath) execPath = await this.findExecutable(root, `node_modules/alepha/node_modules/.bin/${name}${suffix}`);
+		if (!execPath) {
+			let parentDir = this.fs.join(root, "..");
+			for (let i = 0; i < 3; i++) {
+				execPath = await this.findExecutable(parentDir, `node_modules/.bin/${name}${suffix}`);
+				if (execPath) break;
+				parentDir = this.fs.join(parentDir, "..");
+			}
+		}
+		if (!execPath) throw new AlephaError(`Could not find executable for '${name}'. Make sure the package is installed.`);
+		return execPath;
+	}
+	/**
+	* Check if executable exists at path.
+	*/
+	async findExecutable(root, relativePath) {
+		const fullPath = this.fs.join(root, relativePath);
+		if (await this.fs.exists(fullPath)) return fullPath;
+	}
+	/**
+	* Check if a command is installed and available in the system PATH.
+	*/
+	isInstalled(command) {
+		return new Promise((resolve) => {
+			exec(process.platform === "win32" ? `where ${command}` : `command -v ${command}`, (error) => resolve(!error));
+		});
+	}
+};
+
+//#endregion
+//#region ../../src/system/providers/ShellProvider.ts
+/**
+* Abstract provider for executing shell commands and binaries.
+*
+* Implementations:
+* - `NodeShellProvider` - Real shell execution using Node.js child_process
+* - `MemoryShellProvider` - In-memory mock for testing
+*
+* @example
+* ```typescript
+* class MyService {
+*   protected readonly shell = $inject(ShellProvider);
+*
+*   async build() {
+*     // Run shell command directly
+*     await this.shell.run("yarn install");
+*
+*     // Run local binary with resolution
+*     await this.shell.run("vite build", { resolve: true });
+*
+*     // Capture output
+*     const output = await this.shell.run("echo hello", { capture: true });
+*   }
+* }
+* ```
+*/
+var ShellProvider = class {};
+
+//#endregion
+//#region ../../src/system/index.ts
+/**
+* | type | quality | stability |
+* |------|---------|-----------|
+* | tooling | standard | stable |
+*
+* System-level abstractions for portable code across runtimes.
+*
+* **Features:**
+* - File system operations (read, write, exists, etc.)
+* - Shell command execution
+* - File type detection and MIME utilities
+* - Memory implementations for testing
+*
+* @module alepha.system
+*/
+const AlephaSystem = $module({
+	name: "alepha.system",
+	primitives: [],
+	services: [
+		FileDetector,
+		FileSystemProvider,
+		MemoryFileSystemProvider,
+		NodeFileSystemProvider,
+		ShellProvider,
+		MemoryShellProvider,
+		NodeShellProvider
+	],
+	register: (alepha) => alepha.with({
+		optional: true,
+		provide: FileSystemProvider,
+		use: NodeFileSystemProvider
+	}).with({
+		optional: true,
+		provide: ShellProvider,
+		use: alepha.isTest() ? MemoryShellProvider : NodeShellProvider
+	})
+});
+
+//#endregion
+//#region ../../src/api/users/services/SessionService.ts
+var SessionService = class {
+	alepha = $inject(Alepha);
+	fsp = $inject(FileSystemProvider);
+	dateTimeProvider = $inject(DateTimeProvider);
+	cryptoProvider = $inject(CryptoProvider);
+	log = $logger();
+	realmProvider = $inject(RealmProvider);
+	fileController = $client();
+	auditService = $inject(AuditService);
+	users(userRealmName) {
+		return this.realmProvider.userRepository(userRealmName);
+	}
+	sessions(userRealmName) {
+		return this.realmProvider.sessionRepository(userRealmName);
+	}
+	identities(userRealmName) {
+		return this.realmProvider.identityRepository(userRealmName);
+	}
+	/**
+	* Random delay to prevent timing attacks (50-200ms)
+	* Uses cryptographically secure random number generation
+	*/
+	randomDelay() {
+		return new Promise((resolve) => setTimeout(resolve, randomInt(50, 201)));
+	}
+	/**
+	* Validate user credentials and return the user if valid.
+	*/
+	async login(provider, username, password, userRealmName) {
+		const { settings, name } = this.realmProvider.getRealm(userRealmName);
+		const isEmail = username.includes("@");
+		const isPhone = /^[+\d][\d\s()-]+$/.test(username);
+		const isUsername = !isEmail && !isPhone;
+		const identities = this.identities(userRealmName);
+		const users = this.users(userRealmName);
+		await this.randomDelay();
+		try {
+			const where = users.createQueryWhere();
+			where.realm = name;
+			if (settings.usernameEnabled !== false && isUsername) {
+				if (settings.usernameRegExp) {
+					if (!new RegExp(settings.usernameRegExp).test(username)) {
+						this.log.warn("Username does not match required format", {
+							provider,
+							username,
+							realm: name
+						});
+						await this.auditService.recordAuth("login_failed", {
+							userRealm: name,
+							description: "Username does not match required format",
+							metadata: {
+								provider,
+								username
+							}
+						});
+						throw new InvalidCredentialsError();
+					}
+				}
+				where.username = username;
+			} else if (settings.emailEnabled !== false && isEmail) where.email = username;
+			else if (settings.phoneEnabled === true && isPhone) where.phoneNumber = username;
+			else {
+				this.log.warn("Invalid login identifier format", {
+					provider,
+					username,
+					realm: name
+				});
+				await this.auditService.recordAuth("login_failed", {
+					userRealm: name,
+					description: "Invalid login identifier format",
+					metadata: {
+						provider,
+						username
+					}
+				});
+				throw new InvalidCredentialsError();
+			}
+			const user = await users.findOne({ where }).catch(() => void 0);
+			if (!user) {
+				this.log.warn("User not found during login attempt", {
+					provider,
+					username,
+					realm: name
+				});
+				await this.auditService.recordAuth("login_failed", {
+					userRealm: name,
+					description: "User not found",
+					metadata: {
+						provider,
+						username
+					}
+				});
+				throw new InvalidCredentialsError();
+			}
+			const identity = await identities.findOne({ where: {
+				provider: { eq: provider },
+				userId: { eq: user.id }
+			} });
+			const storedPassword = identity.password;
+			if (!storedPassword) {
+				this.log.error("Identity has no password configured", {
+					provider,
+					username,
+					identityId: identity.id,
+					realm: name
+				});
+				throw new InvalidCredentialsError();
+			}
+			if (!await this.cryptoProvider.verifyPassword(password, storedPassword)) {
+				this.log.warn("Invalid password during login attempt", {
+					provider,
+					username,
+					realm: name
+				});
+				await this.auditService.recordAuth("login_failed", {
+					userRealm: name,
+					resourceId: user.id,
+					description: "Invalid password",
+					metadata: {
+						provider,
+						username
+					}
+				});
+				throw new InvalidCredentialsError();
+			}
+			await this.auditService.recordAuth("login", {
+				userId: user.id,
+				userEmail: user.email ?? void 0,
+				userRealm: name,
+				resourceId: user.id,
+				description: `User logged in via ${provider}`,
+				metadata: {
+					provider,
+					username
+				}
+			});
+			return user;
+		} catch (error) {
+			if (error instanceof InvalidCredentialsError) throw error;
+			this.log.warn("Error during login attempt", error);
+			throw new InvalidCredentialsError();
+		}
+	}
+	async createSession(user, expiresIn, userRealmName) {
+		this.log.trace("Creating session", {
+			userId: user.id,
+			expiresIn
+		});
+		const request = this.alepha.context.get("request");
+		const refreshToken = this.cryptoProvider.randomUUID();
+		const expiresAt = this.dateTimeProvider.now().add(expiresIn, "seconds").toISOString();
+		const session = await this.sessions(userRealmName).create({
+			userId: user.id,
+			expiresAt,
+			ip: request?.ip,
+			userAgent: request?.userAgent,
+			refreshToken
+		});
+		this.log.info("Session created", {
+			sessionId: session.id,
+			userId: user.id,
+			ip: request?.ip
+		});
+		return {
+			refreshToken,
+			sessionId: session.id
+		};
+	}
+	async refreshSession(refreshToken, userRealmName) {
+		this.log.trace("Refreshing session");
+		const session = await this.sessions(userRealmName).findOne({ where: { refreshToken: { eq: refreshToken } } });
+		const now = this.dateTimeProvider.now();
+		const expiresAt = this.dateTimeProvider.of(session.expiresAt);
+		if (this.dateTimeProvider.of(session.expiresAt) < now) {
+			this.log.debug("Session expired during refresh", {
+				sessionId: session.id,
+				userId: session.userId
+			});
+			await this.sessions(userRealmName).deleteById(refreshToken);
+			throw new UnauthorizedError("Session expired");
+		}
+		const user = await this.users(userRealmName).findOne({ where: { id: { eq: session.userId } } });
+		this.log.debug("Session refreshed", {
+			sessionId: session.id,
+			userId: session.userId
+		});
+		return {
+			user,
+			expiresIn: expiresAt.unix() - now.unix(),
+			sessionId: session.id
+		};
+	}
+	async deleteSession(refreshToken, userRealmName) {
+		this.log.trace("Deleting session");
+		const session = await this.sessions(userRealmName).findOne({ where: { refreshToken: { eq: refreshToken } } }).catch(() => void 0);
+		await this.sessions(userRealmName).deleteOne({ refreshToken });
+		this.log.debug("Session deleted");
+		if (session) {
+			const { name } = this.realmProvider.getRealm(userRealmName);
+			await this.auditService.recordAuth("logout", {
+				userId: session.userId,
+				userRealm: name,
+				sessionId: session.id,
+				description: "User logged out"
+			});
+		}
+	}
+	async link(provider, profile, userRealmName) {
+		this.log.trace("Linking OAuth2 profile", {
+			provider,
+			profileSub: profile.sub,
+			email: profile.email
+		});
+		const realm = this.realmProvider.getRealm(userRealmName);
+		const identities = this.identities(userRealmName);
 		const users = this.users(userRealmName);
 		const identity = await identities.findOne({ where: {
 			provider,
@@ -2242,6 +4078,472 @@ var SessionService = class {
 	}
 };
 
+//#endregion
+//#region ../../src/api/keys/schemas/adminApiKeyQuerySchema.ts
+const adminApiKeyQuerySchema = t.extend(pageQuerySchema, {
+	userId: t.optional(t.uuid()),
+	includeRevoked: t.optional(t.boolean())
+});
+
+//#endregion
+//#region ../../src/api/keys/schemas/adminApiKeyResourceSchema.ts
+const adminApiKeyResourceSchema = t.object({
+	id: t.uuid(),
+	userId: t.uuid(),
+	name: t.string(),
+	description: t.optional(t.string()),
+	tokenPrefix: t.string(),
+	tokenSuffix: t.string(),
+	roles: t.array(t.string()),
+	createdAt: t.datetime(),
+	lastUsedAt: t.optional(t.datetime()),
+	lastUsedIp: t.optional(t.string()),
+	expiresAt: t.optional(t.datetime()),
+	revokedAt: t.optional(t.datetime()),
+	usageCount: t.integer()
+});
+
+//#endregion
+//#region ../../src/api/keys/entities/apiKeyEntity.ts
+const apiKeyEntity = $entity({
+	name: "api_keys",
+	schema: t.object({
+		id: db.primaryKey(t.uuid()),
+		createdAt: db.createdAt(),
+		updatedAt: db.updatedAt(),
+		userId: t.uuid(),
+		name: t.text({ maxLength: 100 }),
+		description: t.optional(t.text({ maxLength: 500 })),
+		tokenHash: t.string({ maxLength: 256 }),
+		tokenPrefix: t.string({ maxLength: 10 }),
+		tokenSuffix: t.string({ maxLength: 8 }),
+		roles: db.default(t.array(t.string()), []),
+		lastUsedAt: t.optional(t.datetime()),
+		lastUsedIp: t.optional(t.string({ maxLength: 45 })),
+		usageCount: db.default(t.integer(), 0),
+		expiresAt: t.optional(t.datetime()),
+		revokedAt: t.optional(t.datetime())
+	}),
+	indexes: [{
+		columns: ["userId", "name"],
+		unique: true
+	}, {
+		columns: ["tokenHash"],
+		unique: true
+	}]
+});
+
+//#endregion
+//#region ../../src/api/keys/services/ApiKeyService.ts
+var ApiKeyService = class {
+	alepha = $inject(Alepha);
+	dateTimeProvider = $inject(DateTimeProvider);
+	log = $logger();
+	repo = $repository(apiKeyEntity);
+	/**
+	* Cache validated API keys for 15 minutes.
+	*/
+	validationCache = $cache({
+		name: "api-key-validation",
+		ttl: [15, "minutes"]
+	});
+	/**
+	* Create an issuer resolver for API key authentication.
+	* Lower priority means it runs before JWT resolver.
+	*
+	* @param options.priority - Priority of this resolver (default: 50, JWT is 100)
+	* @param options.prefix - API key prefix to match in Bearer header (default: "ak")
+	*/
+	createResolver(options = {}) {
+		const { priority = 50, prefix = "ak" } = options;
+		const prefixPattern = `${prefix}_`;
+		return {
+			priority,
+			onRequest: async (req) => {
+				let token = (typeof req.url === "string" ? new URL(req.url) : req.url).searchParams.get("api_key");
+				if (!token) {
+					const auth = req.headers.authorization;
+					if (auth?.startsWith("Bearer ")) {
+						const bearerToken = auth.slice(7);
+						if (bearerToken.startsWith(prefixPattern)) token = bearerToken;
+					}
+				}
+				if (!token) return null;
+				return this.validate(token);
+			}
+		};
+	}
+	/**
+	* Create a new API key for a user.
+	* Returns both the API key entity and the plain token (which is only available once).
+	*/
+	async create(options) {
+		const prefix = options.prefix ?? "ak";
+		const token = `${prefix}_${randomBytes(24).toString("base64url")}`;
+		const hash = this.hashToken(token);
+		const suffix = token.slice(-8);
+		const apiKey = await this.repo.create({
+			userId: options.userId,
+			name: options.name,
+			description: options.description,
+			tokenHash: hash,
+			tokenPrefix: prefix,
+			tokenSuffix: suffix,
+			roles: options.roles,
+			expiresAt: options.expiresAt?.toISOString()
+		});
+		this.log.info("API key created", {
+			apiKeyId: apiKey.id,
+			userId: options.userId,
+			name: options.name
+		});
+		return {
+			apiKey,
+			token
+		};
+	}
+	/**
+	* List all non-revoked API keys for a user.
+	*/
+	async list(userId) {
+		return this.repo.findMany({
+			where: {
+				userId: { eq: userId },
+				revokedAt: { isNull: true }
+			},
+			orderBy: {
+				column: "createdAt",
+				direction: "desc"
+			}
+		});
+	}
+	/**
+	* Find all API keys with optional filtering (admin only).
+	*/
+	async findAll(query) {
+		query.sort ??= "-createdAt";
+		const where = this.repo.createQueryWhere();
+		if (query.userId) where.userId = { eq: query.userId };
+		if (!query.includeRevoked) where.revokedAt = { isNull: true };
+		return this.repo.paginate(query, { where }, { count: true });
+	}
+	/**
+	* Get an API key by ID (admin only).
+	*/
+	async getById(id) {
+		const apiKey = await this.repo.findById(id).catch(() => null);
+		if (!apiKey) throw new NotFoundError("API key not found");
+		return apiKey;
+	}
+	/**
+	* Revoke any API key (admin only).
+	*/
+	async revokeByAdmin(id) {
+		const apiKey = await this.repo.findById(id).catch(() => null);
+		if (!apiKey) throw new NotFoundError("API key not found");
+		if (apiKey.revokedAt) return;
+		await this.validationCache.invalidate(apiKey.tokenHash);
+		await this.repo.updateById(id, { revokedAt: this.dateTimeProvider.now().toISOString() });
+		this.log.info("API key revoked by admin", {
+			apiKeyId: id,
+			userId: apiKey.userId
+		});
+	}
+	/**
+	* Revoke an API key. Only the owner can revoke their own keys.
+	*/
+	async revoke(id, userId) {
+		const apiKey = await this.repo.findById(id).catch(() => null);
+		if (!apiKey) throw new NotFoundError("API key not found");
+		if (apiKey.userId !== userId) throw new ForbiddenError("Not your API key");
+		await this.validationCache.invalidate(apiKey.tokenHash);
+		await this.repo.updateById(id, { revokedAt: this.dateTimeProvider.now().toISOString() });
+		this.log.info("API key revoked", {
+			apiKeyId: id,
+			userId
+		});
+	}
+	/**
+	* Validate an API key token and return user info if valid.
+	*/
+	async validate(token) {
+		if (!token.includes("_")) return null;
+		const hash = this.hashToken(token);
+		let apiKey = await this.validationCache.get(hash);
+		if (apiKey === void 0) {
+			apiKey = await this.repo.findOne({ where: { tokenHash: { eq: hash } } }).catch(() => null);
+			if (apiKey) await this.validationCache.set(hash, apiKey);
+		}
+		if (!apiKey) return null;
+		if (apiKey.revokedAt) return null;
+		if (apiKey.expiresAt && this.dateTimeProvider.now().isAfter(apiKey.expiresAt)) return null;
+		this.updateUsage(apiKey.id).catch((error) => {
+			this.log.warn("Failed to update API key usage", { error });
+		});
+		return {
+			id: apiKey.userId,
+			roles: apiKey.roles
+		};
+	}
+	/**
+	* Update usage statistics for an API key.
+	*/
+	async updateUsage(id) {
+		const request = this.alepha.context.get("request");
+		await this.repo.updateById(id, {
+			lastUsedAt: this.dateTimeProvider.now().toISOString(),
+			lastUsedIp: request?.ip,
+			usageCount: sql`${this.repo.table.usageCount} + 1`
+		});
+	}
+	/**
+	* Hash a token using SHA-256.
+	*/
+	hashToken(token) {
+		return createHash("sha256").update(token).digest("hex");
+	}
+};
+
+//#endregion
+//#region ../../src/api/keys/controllers/AdminApiKeyController.ts
+/**
+* REST API controller for admin API key management.
+* Admins can list, view, and revoke any API key.
+*/
+var AdminApiKeyController = class {
+	url = "/admin/api-keys";
+	group = "admin:api-keys";
+	apiKeyService = $inject(ApiKeyService);
+	/**
+	* Find all API keys with optional filtering.
+	*/
+	findApiKeys = $action({
+		path: this.url,
+		group: this.group,
+		secure: true,
+		description: "Find API keys with pagination and filtering",
+		schema: {
+			query: adminApiKeyQuerySchema,
+			response: t.page(adminApiKeyResourceSchema)
+		},
+		handler: ({ query }) => {
+			const { userId, includeRevoked, ...pagination } = query;
+			return this.apiKeyService.findAll({
+				userId,
+				includeRevoked,
+				...pagination
+			});
+		}
+	});
+	/**
+	* Get an API key by ID.
+	*/
+	getApiKey = $action({
+		path: `${this.url}/:id`,
+		group: this.group,
+		secure: true,
+		description: "Get an API key by ID",
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			response: adminApiKeyResourceSchema
+		},
+		handler: ({ params }) => this.apiKeyService.getById(params.id)
+	});
+	/**
+	* Revoke any API key.
+	*/
+	revokeApiKey = $action({
+		method: "DELETE",
+		path: `${this.url}/:id`,
+		group: this.group,
+		secure: true,
+		description: "Revoke an API key",
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			response: okSchema
+		},
+		handler: async ({ params }) => {
+			await this.apiKeyService.revokeByAdmin(params.id);
+			return {
+				ok: true,
+				id: params.id
+			};
+		}
+	});
+};
+
+//#endregion
+//#region ../../src/api/keys/schemas/createApiKeyBodySchema.ts
+const createApiKeyBodySchema = t.object({
+	name: t.text({
+		minLength: 1,
+		maxLength: 100
+	}),
+	description: t.optional(t.text({ maxLength: 500 })),
+	expiresAt: t.optional(t.datetime())
+});
+
+//#endregion
+//#region ../../src/api/keys/schemas/createApiKeyResponseSchema.ts
+const createApiKeyResponseSchema = t.object({
+	id: t.uuid(),
+	name: t.string(),
+	token: t.string(),
+	tokenSuffix: t.string(),
+	roles: t.array(t.string()),
+	createdAt: t.datetime(),
+	expiresAt: t.optional(t.datetime())
+});
+
+//#endregion
+//#region ../../src/api/keys/schemas/listApiKeyResponseSchema.ts
+const listApiKeyItemSchema = t.object({
+	id: t.uuid(),
+	name: t.string(),
+	tokenPrefix: t.string(),
+	tokenSuffix: t.string(),
+	roles: t.array(t.string()),
+	createdAt: t.datetime(),
+	lastUsedAt: t.optional(t.datetime()),
+	expiresAt: t.optional(t.datetime()),
+	usageCount: t.integer()
+});
+const listApiKeyResponseSchema = t.array(listApiKeyItemSchema);
+
+//#endregion
+//#region ../../src/api/keys/schemas/revokeApiKeyParamsSchema.ts
+const revokeApiKeyParamsSchema = t.object({ id: t.uuid() });
+
+//#endregion
+//#region ../../src/api/keys/schemas/revokeApiKeyResponseSchema.ts
+const revokeApiKeyResponseSchema = t.object({ ok: t.boolean() });
+
+//#endregion
+//#region ../../src/api/keys/controllers/ApiKeyController.ts
+/**
+* REST API controller for user's own API key management.
+* Users can create, list, and revoke their own API keys.
+*/
+var ApiKeyController = class {
+	url = "/api-keys";
+	group = "api-keys";
+	apiKeyService = $inject(ApiKeyService);
+	/**
+	* Create a new API key for the authenticated user.
+	* The token is only returned once upon creation.
+	*/
+	createApiKey = $action({
+		method: "POST",
+		path: this.url,
+		group: this.group,
+		description: "Create a new API key",
+		secure: true,
+		schema: {
+			body: createApiKeyBodySchema,
+			response: createApiKeyResponseSchema
+		},
+		handler: async (request) => {
+			const { apiKey, token } = await this.apiKeyService.create({
+				userId: request.user.id,
+				name: request.body.name,
+				description: request.body.description,
+				roles: request.user.roles ?? [],
+				expiresAt: request.body.expiresAt ? new Date(request.body.expiresAt) : void 0
+			});
+			return {
+				id: apiKey.id,
+				name: apiKey.name,
+				token,
+				tokenSuffix: apiKey.tokenSuffix,
+				roles: apiKey.roles,
+				createdAt: apiKey.createdAt,
+				expiresAt: apiKey.expiresAt
+			};
+		}
+	});
+	/**
+	* List all active API keys for the authenticated user.
+	* Does not return the actual tokens.
+	*/
+	listApiKeys = $action({
+		path: this.url,
+		group: this.group,
+		description: "List your API keys",
+		secure: true,
+		schema: { response: listApiKeyResponseSchema },
+		handler: async (request) => {
+			return (await this.apiKeyService.list(request.user.id)).map((apiKey) => ({
+				id: apiKey.id,
+				name: apiKey.name,
+				tokenPrefix: apiKey.tokenPrefix,
+				tokenSuffix: apiKey.tokenSuffix,
+				roles: apiKey.roles,
+				createdAt: apiKey.createdAt,
+				lastUsedAt: apiKey.lastUsedAt,
+				expiresAt: apiKey.expiresAt,
+				usageCount: apiKey.usageCount
+			}));
+		}
+	});
+	/**
+	* Revoke an API key. Only the owner can revoke their own keys.
+	*/
+	revokeApiKey = $action({
+		method: "DELETE",
+		path: `${this.url}/:id`,
+		group: this.group,
+		description: "Revoke an API key",
+		secure: true,
+		schema: {
+			params: revokeApiKeyParamsSchema,
+			response: revokeApiKeyResponseSchema
+		},
+		handler: async (request) => {
+			await this.apiKeyService.revoke(request.params.id, request.user.id);
+			return { ok: true };
+		}
+	});
+};
+
+//#endregion
+//#region ../../src/api/keys/index.ts
+/**
+* | type | quality | stability |
+* |------|---------|--------------|
+* | backend | good | experimental |
+*
+* API key management module for programmatic access.
+*
+* **Features:**
+* - Create API keys with role snapshots
+* - List and revoke API keys
+* - 15-minute validation caching
+* - Query param (?api_key=) and Bearer header support
+*
+* **Integration:**
+* To enable API key authentication for an issuer, register the resolver:
+*
+* ```ts
+* class MyApp {
+*   apiKeyService = $inject(ApiKeyService);
+*   issuer = $issuer({
+*     secret: env.APP_SECRET,
+*     resolvers: [this.apiKeyService.createResolver()],
+*   });
+* }
+* ```
+*
+* @module alepha.api.keys
+*/
+const AlephaApiKeys = $module({
+	name: "alepha.api.keys",
+	services: [
+		ApiKeyService,
+		ApiKeyController,
+		AdminApiKeyController
+	]
+});
+
 //#endregion
 //#region ../../src/api/users/primitives/$realm.ts
 /**
@@ -2270,10 +4572,18 @@ const $realm = (options = {}) => {
 	const realmRegistration = realmProvider.register(name, options);
 	alepha.with(AlephaApiFiles);
 	alepha.with(AlephaApiAudits);
+	alepha.with(AlephaApiJobs);
+	const customResolvers = [...options.issuer?.resolvers ?? []];
+	if (options.apiKeys) {
+		alepha.with(AlephaApiKeys);
+		const apiKeyService = alepha.inject(ApiKeyService);
+		customResolvers.push(apiKeyService.createResolver());
+	}
 	const realm = $issuer({
 		...options.issuer,
 		name,
 		secret: options.secret ?? securityProvider.secretKey,
+		resolvers: customResolvers,
 		roles: options.issuer?.roles ?? [{
 			name: "admin",
 			permissions: [{ name: "*" }]
@@ -2380,10 +4690,21 @@ const resetPasswordSchema = t.object({
 //#endregion
 //#region ../../src/api/users/index.ts
 /**
-* Provides user management API endpoints for Alepha applications.
+* | type | quality | stability |
+* |------|---------|-----------|
+* | backend | epic | stable |
+*
+* Complete user management with multi-realm support for multi-tenant applications.
 *
-* This module includes user CRUD operations, authentication endpoints,
-* password reset functionality, and user profile management capabilities.
+* **Features:**
+* - User registration, login, and profile management
+* - Password reset workflows
+* - Email verification
+* - Session management with multiple devices
+* - Identity management (social logins, SSO)
+* - Multi-realm support for tenant isolation
+* - Credential management
+* - Entities: `users`, `identities`, `sessions`
 *
 * @module alepha.api.users
 */