harper 5.1.20 → 5.2.0-alpha.5

package/utility/logging/logRotator.ts

@@ -67,23 +67,23 @@ function logRotator({ logger, maxSize, interval, retention, enabled, path: rotat
 	let lastRotationTime = Date.now();
 	hdbLogger.trace('Log rotate enabled, maxSize:', maxSize, 'interval:', interval);
 	const setIntervalId = setInterval(async () => {
+		// A missing/relocated active log file only invalidates the rotation checks below — retention cleanup
+		// must still run. So skip the individual check on ENOENT rather than returning from the whole tick.
 		if (maxBytes) {
 			let fileStats;
 			try {
 				fileStats = await fsProm.stat(logger.path);
 			} catch (err) {
-				// If the log file doesn't exist, skip rotation check
-				if (err.code === 'ENOENT') return;
-				throw err;
+				// If the log file doesn't exist, skip the size-based rotation check
+				if (err.code !== 'ENOENT') throw err;
 			}
 
-			if (fileStats.size >= maxBytes) {
+			if (fileStats && fileStats.size >= maxBytes) {
 				try {
-					lastRotatedLogPath = await moveLogFile(logger.path, rotatedLogDir);
+					lastRotatedLogPath = await moveLogFile(logger.path, rotatedLogDir, logger);
 				} catch (err) {
 					// If the log file doesn't exist, skip rotation
-					if (err.code === 'ENOENT') return;
-					throw err;
+					if (err.code !== 'ENOENT') throw err;
 				}
 			}
 		}
@@ -92,12 +92,11 @@ function logRotator({ logger, maxSize, interval, retention, enabled, path: rotat
 			const minSinceLastRotate = Date.now() - lastRotationTime;
 			if (minSinceLastRotate >= maxInterval) {
 				try {
-					lastRotatedLogPath = await moveLogFile(logger.path, rotatedLogDir);
+					lastRotatedLogPath = await moveLogFile(logger.path, rotatedLogDir, logger);
 					lastRotationTime = Date.now();
 				} catch (err) {
 					// If the log file doesn't exist, skip rotation
-					if (err.code === 'ENOENT') return;
-					throw err;
+					if (err.code !== 'ENOENT') throw err;
 				}
 			}
 		}
@@ -106,7 +105,14 @@ function logRotator({ logger, maxSize, interval, retention, enabled, path: rotat
 			// adjust retention time if there is a reclamation priority in place
 			const retentionMs = convertToMS(retention ?? '1M') / (1 + reclamationPriority);
 			reclamationPriority = 0; // reset it after use
-			const files = await fsProm.readdir(rotatedLogDir);
+			let files;
+			try {
+				files = await fsProm.readdir(rotatedLogDir);
+			} catch (err) {
+				// The rotated log dir may not exist yet (nothing rotated so far); nothing to clean up
+				if (err.code !== 'ENOENT') hdbLogger.error('Error reading rotated log directory', rotatedLogDir, err);
+				files = [];
+			}
 			for (const file of files) {
 				try {
 					const fileStats = await fsProm.stat(path.join(rotatedLogDir, file));
@@ -129,7 +135,7 @@ function logRotator({ logger, maxSize, interval, retention, enabled, path: rotat
 	};
 }
 
-async function moveLogFile(logPath: string, rotatedLogPath: string) {
+async function moveLogFile(logPath: string, rotatedLogPath: string, logger?: any) {
 	const compress = envMgr.get(CONFIG_PARAMS.LOGGING_ROTATION_COMPRESS);
 	let fullRotateLogPath = path.join(
 		rotatedLogPath,
@@ -138,6 +144,12 @@ async function moveLogFile(logPath: string, rotatedLogPath: string) {
 	// Move log file to rotated log path first (if we crash
 	// during compression, we don't want to restart the compression with a new file)
 	await fsProm.rename(logPath, fullRotateLogPath);
+	// Close the rotating logger's own file descriptor now that the file has moved. This must be the
+	// logger's own closeLogFile (which resets its internal logFD), not the module-global one — otherwise
+	// the descriptor stays open on the moved (and, when compressing, subsequently unlinked) inode until the
+	// logger's safety timeout fires, pinning disk space and sending any writes in that window into the
+	// rotated/deleted file. Closing it here makes the next write reopen a fresh log file immediately.
+	(logger?.closeLogFile ?? hdbLogger.closeLogFile)();
 	if (compress) {
 		logPath = fullRotateLogPath;
 		fullRotateLogPath += '.gz';
@@ -145,8 +157,6 @@ async function moveLogFile(logPath: string, rotatedLogPath: string) {
 		await fsProm.unlink(logPath);
 	}
 
-	// Close old log file.
-	hdbLogger.closeLogFile();
 	// This notify log will create a new log file after the previous one has been rotated. It's important to keep this log as notify
 	hdbLogger.notify(`hdb.log rotated, old log moved to ${fullRotateLogPath}`);
 	return fullRotateLogPath;

package/utility/logging/readLog.ts

@@ -9,6 +9,7 @@ import { once } from 'events';
 import { getConfigPath } from '../../config/configUtils.ts';
 import { handleHDBError, hdbErrors } from '../errors/hdbError.ts';
 import { server } from '../../server/Server.ts';
+import { StringDecoder } from 'string_decoder';
 
 const DEFAULT_READ_LOG_LIMIT = 1000;
 const ESTIMATED_AVERAGE_ENTRY_SIZE = 200;
@@ -33,8 +34,10 @@ async function readLog(request: any) {
 			true
 		);
 	}
-	// start pulling logs from the other nodes now so it can be done in parallel
-	let whenReplicatedResponse = server.replication.replicateOperation(request);
+	// Start pulling logs from the other nodes now so it can be done in parallel. A live SSE
+	// tail (below) is local-only and never fans out, so skip replication on that path — the
+	// buffered read still aggregates the cluster for point-in-time queries.
+	let whenReplicatedResponse = isStreamingRequest(request) ? undefined : server.replication.replicateOperation(request);
 
 	const logPath = getConfigPath(hdbTerms.HDB_SETTINGS_NAMES.LOG_PATH_KEY);
 	const rawLogName = request.log_name === undefined ? hdbTerms.LOG_NAMES.HDB : request.log_name;
@@ -57,6 +60,26 @@ async function readLog(request: any) {
 	const start = request.start === undefined ? 0 : request.start;
 	const max = start + limit;
 	const filter = request.filter;
+
+	// SSE mode: the server attached a ProgressEmitter as `request.progress` (see
+	// serverHandlers.js) because the client sent `Accept: text/event-stream`. Instead of a
+	// one-shot array, stream the recent backlog and then tail new lines live until the client
+	// disconnects. Scoped to this node's log file; the buffered path above is what aggregates
+	// the cluster for point-in-time reads.
+	if (isStreamingRequest(request)) {
+		return streamLogTail(request.progress, {
+			readLogPath,
+			level,
+			levelDefined,
+			from,
+			fromDefined,
+			to,
+			toDefined,
+			limit,
+			filter,
+		});
+	}
+
 	let fileStart = 0;
 	if (order === 'desc' && !from && !to) {
 		fileStart = Math.max(fs.statSync(readLogPath).size - (max + 5) * ESTIMATED_AVERAGE_ENTRY_SIZE, 0);
@@ -348,3 +371,301 @@ function insertAscending(value: any, result: any[]) {
 
 	result.splice(low, 0, value);
 }
+
+interface LogEntry {
+	timestamp: string;
+	thread: string;
+	level: string;
+	tags: string[];
+	message: string;
+}
+
+interface TailFilterParams {
+	readLogPath: string;
+	level: string | undefined;
+	levelDefined: boolean;
+	from: Date | undefined;
+	fromDefined: boolean;
+	to: Date | undefined;
+	toDefined: boolean;
+	limit: number;
+	filter: string | undefined;
+}
+
+// The marker that begins every log line — `TIMESTAMP [thread] [level]...: ` — matching the
+// buffered reader's regex so the two paths parse identically.
+const LOG_ENTRY_MARKER = /(?:^|\n)(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:[\d.]+Z) \[(.+?)]: /g;
+// How often a live tail polls the log file for appended bytes. fs.watchFile is stat-poll
+// based, which is far more robust across platforms and log rotation than fs.watch's rename
+// events; sub-second latency is plenty for a human watching logs.
+const TAIL_POLL_INTERVAL_MS = 250;
+// Cap the live-tail backlog regardless of a caller-supplied `limit`, so an unbounded `limit`
+// can neither seek-read a huge slice into memory nor drive an O(n·limit) eviction on connect.
+// Deeper history is the buffered read_log's job; the tail is about what happens next.
+const MAX_SSE_BACKLOG_ENTRIES = 1000;
+// A transient delta-read failure is retried this many times (with this delay) before the tail
+// gives up and emits a terminal error so the client can fall back to polling.
+const TAIL_READ_MAX_RETRIES = 3;
+const TAIL_READ_RETRY_MS = 250;
+
+function isStreamingRequest(request: any): boolean {
+	return !!request.progress && typeof request.progress.emit === 'function';
+}
+
+function makeLogEntry(timestamp: string, tagsString: string, message: string): LogEntry {
+	const tags = tagsString.split('] [');
+	const thread = tags[0];
+	const level = tags[1];
+	tags.splice(0, 2);
+	return { timestamp, thread, level, tags, message };
+}
+
+function matchesLogFilters(entry: LogEntry, params: TailFilterParams): boolean {
+	const { level, levelDefined, from, fromDefined, to, toDefined, filter } = params;
+	if (filter !== undefined) {
+		const hit = (['timestamp', 'thread', 'level', 'tags', 'message'] as const).some((attr) => {
+			const value = entry[attr];
+			if (Array.isArray(value)) return value.some((v) => v.includes(filter));
+			return typeof value === 'string' && value.includes(filter);
+		});
+		if (!hit) return false;
+	}
+	if (levelDefined && entry.level !== level) return false;
+	if (fromDefined || toDefined) {
+		const when = new Date(entry.timestamp);
+		if (fromDefined && when < (from as Date)) return false;
+		if (toDefined && when > (to as Date)) return false;
+	}
+	return true;
+}
+
+// Stateful incremental parser: fed appended chunks over time, it emits an entry only once the
+// next marker delimits its (possibly multi-line) message. It never force-emits a pending
+// entry — the same instance spans the backlog read and the live tail (see streamLogTail), so a
+// line torn across the snapshot boundary stays pending and is completed by the tail's next
+// read rather than emitted truncated with its continuation dropped. `reset()` clears state on
+// log rotation.
+function createIncrementalLogParser(onEntry: (entry: LogEntry) => void) {
+	let remaining = '';
+	let pending: { timestamp: string; tagsString: string } | undefined;
+	// One RegExp per parser instance. Each push runs `exec` to completion (until null), which
+	// resets lastIndex to 0; we also reset it explicitly at the top of push for robustness.
+	const reader = new RegExp(LOG_ENTRY_MARKER);
+	return {
+		push(text: string) {
+			const data = remaining + text;
+			reader.lastIndex = 0;
+			let lastPosition = 0;
+			let parsed;
+			while ((parsed = reader.exec(data))) {
+				if (pending) {
+					onEntry(makeLogEntry(pending.timestamp, pending.tagsString, data.slice(lastPosition, parsed.index)));
+				}
+				const [intro, timestamp, tagsString] = parsed;
+				pending = { timestamp, tagsString };
+				lastPosition = parsed.index + intro.length;
+			}
+			remaining = data.slice(lastPosition);
+		},
+		reset() {
+			pending = undefined;
+			remaining = '';
+		},
+	};
+}
+
+/**
+ * Stream the local log over SSE: replay the recent (bounded) backlog, then tail newly-appended
+ * lines until the client disconnects (the emitter's `signal` aborts) — or, if reads fail past
+ * retry, emit a terminal `error` so the client falls back to polling instead of watching a
+ * silently-stalled "live" stream. Resolves when the tail ends so the SSE wrapper can close.
+ *
+ * A single parser and decoder span both the backlog read and the live tail with no flush at
+ * the seam, so a line (or multi-byte character) torn across the snapshot boundary stays pending
+ * and is completed by the tail's next read — never emitted truncated with its continuation
+ * dropped. (A consequence: the newest backlog line is delivered once the following line
+ * delimits it, matching how the tail delimits every entry.)
+ */
+function streamLogTail(progress: any, params: TailFilterParams): Promise<void> {
+	const { readLogPath, limit } = params;
+	const signal: AbortSignal | undefined = progress.signal;
+	const emit = (entry: LogEntry) => progress.emit('log', entry);
+	// The tail never shows more backlog than this, whatever `limit` asks for (see the constant).
+	const backlogLimit = Math.min(limit, MAX_SSE_BACKLOG_ENTRIES);
+
+	return new Promise<void>((resolve) => {
+		if (signal?.aborted) return resolve();
+
+		let offset = 0;
+		let pumping = false;
+		let pumpQueued = false;
+		let watching = false;
+		let finished = false;
+		let readFailures = 0;
+		// While replaying the backlog, matching entries are collected here (capped) rather than
+		// emitted; once the boundary is passed `backlogPhase` flips and entries emit live.
+		let backlogPhase = true;
+		const backlogEntries: LogEntry[] = [];
+		// One decoder + one parser for the whole session (backlog + tail): a multi-byte char (or a
+		// line) split across the boundary is held/pending and finished by the next read, not
+		// flushed as U+FFFD or truncated. Reset together only on rotation.
+		let decoder = new StringDecoder('utf8');
+		const parser = createIncrementalLogParser((entry) => {
+			if (!matchesLogFilters(entry, params)) return;
+			if (backlogPhase) {
+				backlogEntries.push(entry);
+				if (backlogEntries.length > backlogLimit) backlogEntries.shift();
+			} else {
+				emit(entry);
+			}
+		});
+
+		function finish() {
+			if (finished) return;
+			finished = true;
+			if (watching) fs.unwatchFile(readLogPath, onChange);
+			resolve();
+		}
+
+		// Wait `ms`, or resolve early on disconnect so a retry delay never outlives the connection.
+		const abortableDelay = (ms: number) =>
+			new Promise<void>((res) => {
+				if (signal?.aborted) return res();
+				const timer = setTimeout(() => {
+					signal?.removeEventListener('abort', onAbort);
+					res();
+				}, ms);
+				timer.unref?.();
+				const onAbort = () => {
+					clearTimeout(timer);
+					res();
+				};
+				signal?.addEventListener('abort', onAbort, { once: true });
+			});
+
+		// Stream [offset, end] inclusive through the session decoder + shared parser, decoding and
+		// pushing each fs chunk as it arrives (never materializing the whole delta) and advancing
+		// `offset` per chunk, so peak memory is one chunk and a mid-range error simply resumes from
+		// where it stopped. Yields to backpressure between chunks. Returns false if the read errored.
+		async function drainTo(end: number): Promise<boolean> {
+			const rs = fs.createReadStream(readLogPath, { start: offset, end });
+			try {
+				for await (const chunk of rs) {
+					if (signal?.aborted) {
+						rs.destroy();
+						return true;
+					}
+					parser.push(decoder.write(chunk as Buffer));
+					offset += (chunk as Buffer).length;
+					if (progress.paused) await progress.whenWritable();
+				}
+				return true;
+			} catch (err: any) {
+				hdbLogger.warn(
+					`read_log SSE tail: failed reading ${readLogPath} near offset ${offset}: ${err?.message ?? err}`
+				);
+				return false;
+			}
+		}
+
+		// Single-flight pump: drain all appended bytes into the parser. A change arriving while a
+		// pump runs sets `pumpQueued` so the loop runs once more, rather than being missed in the
+		// window between "caught up" and clearing `pumping`.
+		async function pump() {
+			if (pumping) {
+				pumpQueued = true;
+				return;
+			}
+			pumping = true;
+			try {
+				do {
+					pumpQueued = false;
+					while (!signal?.aborted) {
+						let size: number;
+						try {
+							size = (await fs.promises.stat(readLogPath)).size;
+						} catch {
+							break;
+						}
+						if (size < offset) {
+							// Truncation or rotation: restart from the new file and reset decode/parse state.
+							offset = 0;
+							decoder = new StringDecoder('utf8');
+							parser.reset();
+						}
+						if (size <= offset) break;
+						if (progress.paused) {
+							await progress.whenWritable();
+							continue;
+						}
+						const ok = await drainTo(size - 1);
+						if (signal?.aborted) break;
+						if (!ok) {
+							if (++readFailures > TAIL_READ_MAX_RETRIES) {
+								// Don't leave the client staring at a silently-stalled "live" stream: a
+								// terminal error is its cue to fall back to polling.
+								progress.emit('error', {
+									message: `read_log live tail could not read ${readLogPath} after ${TAIL_READ_MAX_RETRIES} retries`,
+									code: 'READ_LOG_TAIL_READ_ERROR',
+								});
+								finish();
+								return;
+							}
+							await abortableDelay(TAIL_READ_RETRY_MS);
+							continue; // resume from the advanced offset
+						}
+						readFailures = 0;
+					}
+				} while (pumpQueued && !signal?.aborted);
+			} finally {
+				pumping = false;
+			}
+		}
+
+		function onChange() {
+			void pump();
+		}
+
+		const startTail = () => {
+			// `offset` is already the backlog boundary, so the tail picks up strictly from there.
+			// Without a disconnect signal we can't safely tail forever; degrade to backlog-only so
+			// the client polls instead.
+			if (!signal || signal.aborted) return finish();
+			fs.watchFile(readLogPath, { interval: TAIL_POLL_INTERVAL_MS }, onChange);
+			watching = true;
+			signal.addEventListener('abort', finish, { once: true });
+			// Catch anything appended between the backlog snapshot and arming the watcher.
+			void pump();
+		};
+
+		// Replay the backlog through the shared parser/decoder, then tail from the same boundary.
+		(async () => {
+			let startSize = 0;
+			try {
+				startSize = fs.statSync(readLogPath).size;
+			} catch {
+				startSize = 0;
+			}
+			if (startSize > 0) {
+				// Bound the backlog read to roughly the last `backlogLimit` entries so a large log
+				// file can't be seek-read into memory all at once (mirrors the buffered path). A
+				// partial first line the seek lands in is dropped by the parser, as in that path.
+				offset = Math.max(startSize - (backlogLimit + 5) * ESTIMATED_AVERAGE_ENTRY_SIZE, 0);
+				await drainTo(startSize - 1); // collects into backlogEntries; read errors are logged, best-effort
+			}
+			// Hand off to the live tail: flip to emit mode and deliver the collected backlog. The
+			// parser's pending entry (the newest, possibly boundary-torn line) is deliberately left
+			// pending — the tail finishes it — so nothing is emitted truncated.
+			backlogPhase = false;
+			for (const entry of backlogEntries) {
+				if (signal?.aborted) break;
+				emit(entry);
+				if (progress.paused) await progress.whenWritable();
+			}
+			startTail();
+		})().catch((err) => {
+			hdbLogger.warn(`read_log SSE tail: backlog replay failed for ${readLogPath}: ${err?.message ?? err}`);
+			startTail();
+		});
+	});
+}

package/utility/operationPermissions.ts

@@ -76,10 +76,44 @@ export const OPERATION_PERMISSION_GROUPS = {
 		OPERATIONS_ENUM.CSV_URL_LOAD,
 		OPERATIONS_ENUM.IMPORT_FROM_S3,
 	],
+	/**
+	 * Drive the built-in agent (#626): send prompts, read/list sessions, and approve/cancel
+	 * runs. Grants a scoped, non-super_user "delegation" role access to the agent without full
+	 * super_user (all agent ops are super_user by default). Deliberately EXCLUDES set_agent_config
+	 * — changing the agent's model/approval policy stays an operator (super_user) action.
+	 */
+	agent: [
+		OPERATIONS_ENUM.AGENT_PROMPT,
+		OPERATIONS_ENUM.GET_AGENT_SESSION,
+		OPERATIONS_ENUM.LIST_AGENT_SESSIONS,
+		OPERATIONS_ENUM.CANCEL_AGENT_RUN,
+		OPERATIONS_ENUM.APPROVE_AGENT_ACTION,
+	],
 } as const;
 
 const validOps: Set<string> = new Set(Object.values(OPERATIONS_ENUM));
 const validGroups: Set<string> = new Set(Object.keys(OPERATION_PERMISSION_GROUPS));
+// Operations registered dynamically at runtime (server.registerOperation with a declared
+// permission) whose names may fall outside OPERATIONS_ENUM. Tracked so they're grantable in a
+// role's `operations` allowlist (add_role/alter_role/impersonation validate against this set too).
+const dynamicallyRegisteredOps: Set<string> = new Set();
+
+/**
+ * Mark a dynamically-registered operation name as a valid target for role `operations` grants.
+ * Called by registerOperationPermission so a component op declaring a permission can actually be
+ * granted (not just enforced). Enum-backed op names are already valid; this covers custom names.
+ */
+export function registerGrantableOperation(name: string): void {
+	dynamicallyRegisteredOps.add(name);
+}
+
+/**
+ * Remove a dynamically-registered grantable operation name. Mirrors registerGrantableOperation;
+ * primarily for tests that register throwaway ops and must not leak them into the global set.
+ */
+export function unregisterGrantableOperation(name: string): void {
+	dynamicallyRegisteredOps.delete(name);
+}
 
 /**
  * Validates that every entry in an operations array is a known operation name or group name.
@@ -87,7 +121,7 @@ const validGroups: Set<string> = new Set(Object.keys(OPERATION_PERMISSION_GROUPS
  */
 export function validateOperations(operations: readonly unknown[]): string | null {
 	for (const op of operations) {
-		if (typeof op !== 'string' || (!validOps.has(op) && !validGroups.has(op))) {
+		if (typeof op !== 'string' || (!validOps.has(op) && !validGroups.has(op) && !dynamicallyRegisteredOps.has(op))) {
 			return String(op);
 		}
 	}

package/utility/operation_authorization.ts

@@ -25,7 +25,11 @@ import readLog from '../utility/logging/readLog.ts';
 import * as commonUtils from './common_utils.ts';
 import * as restart from '../bin/restart.ts';
 import * as terms from './hdbTerms.ts';
-import { expandOperationsPerms } from './operationPermissions.ts';
+import {
+	expandOperationsPerms,
+	registerGrantableOperation,
+	unregisterGrantableOperation,
+} from './operationPermissions.ts';
 import * as permsTranslator from '../security/permissionsTranslator.js';
 import { systemInformation } from '../utility/environment/systemInformation.ts';
 import * as tokenAuthentication from '../security/tokenAuthentication.ts';
@@ -41,6 +45,7 @@ import { handleHDBError, hdbErrors } from '../utility/errors/hdbError.ts';
 
 import * as regDeprecated from '../resources/registrationDeprecated.ts';
 import * as deploymentOperations from '../components/deploymentOperations.ts';
+import * as secretOperations from '../components/secretOperations.ts';
 
 const requiredPermissions = new Map();
 const DELETE_PERM = 'delete';
@@ -108,6 +113,33 @@ class permission {
 	}
 }
 
+/**
+ * Register an authorization entry for a dynamically-registered operation (via
+ * server.registerOperation), so it flows through verifyPerms and the role `operations`
+ * allowlist exactly like a built-in op — instead of hand-rolling an inline super_user check.
+ * Keyed by the snake_case API operation name (which registerOperation also forces onto the
+ * handler's `.name`, the key verifyPerms looks up). SU-only by default.
+ */
+export function registerOperationPermission(
+	apiName: string,
+	{ requiresSu = false, perms = [] }: { requiresSu?: boolean; perms?: string[] } = {}
+) {
+	requiredPermissions.set(apiName, new (permission as any)(requiresSu, perms, apiName));
+	// Also make the op grantable in a role's `operations` allowlist (validateOperations), so a
+	// declared permission can be both enforced AND granted — not just enforced.
+	registerGrantableOperation(apiName);
+}
+
+/**
+ * Remove an authorization entry registered via registerOperationPermission (both the verifyPerms
+ * entry and the grantable-op mark). Mirrors registerOperationPermission; primarily for tests that
+ * register throwaway ops and must not leak them into the process-global registries.
+ */
+export function unregisterOperationPermission(apiName: string) {
+	requiredPermissions.delete(apiName);
+	unregisterGrantableOperation(apiName);
+}
+
 requiredPermissions.set(write.insert.name, new (permission as any)(false, [INSERT_PERM], terms.OPERATIONS_ENUM.INSERT));
 requiredPermissions.set(write.update.name, new (permission as any)(false, [UPDATE_PERM], terms.OPERATIONS_ENUM.UPDATE));
 requiredPermissions.set(
@@ -231,6 +263,18 @@ requiredPermissions.set(
 	new (permission as any)(true, [], terms.OPERATIONS_ENUM.GET_COMPONENT_FILE)
 );
 requiredPermissions.set(functionsOperations.setComponentFile.name, new (permission as any)(true, []));
+requiredPermissions.set(
+	functionsOperations.getEnvKeys.name,
+	new (permission as any)(true, [], terms.OPERATIONS_ENUM.GET_ENV_KEYS)
+);
+requiredPermissions.set(
+	functionsOperations.setEnvValue.name,
+	new (permission as any)(true, [], terms.OPERATIONS_ENUM.SET_ENV_VALUE)
+);
+requiredPermissions.set(
+	functionsOperations.deleteEnvValue.name,
+	new (permission as any)(true, [], terms.OPERATIONS_ENUM.DELETE_ENV_VALUE)
+);
 requiredPermissions.set(functionsOperations.dropComponent.name, new (permission as any)(true, []));
 requiredPermissions.set(
 	functionsOperations.getCustomFunction.name,
@@ -251,6 +295,33 @@ requiredPermissions.set(
 	new (permission as any)(true, [], terms.OPERATIONS_ENUM.GET_DEPLOYMENT)
 );
 
+// Secrets-store operations. All SU-only; the handlers ALSO enforce super_user directly, so these
+// cannot be delegated through a role's `operations` allowlist (gate-2 bypass below).
+requiredPermissions.set(
+	secretOperations.setSecret.name,
+	new (permission as any)(true, [], terms.OPERATIONS_ENUM.SET_SECRET)
+);
+requiredPermissions.set(
+	secretOperations.grantSecret.name,
+	new (permission as any)(true, [], terms.OPERATIONS_ENUM.GRANT_SECRET)
+);
+requiredPermissions.set(
+	secretOperations.revokeSecret.name,
+	new (permission as any)(true, [], terms.OPERATIONS_ENUM.REVOKE_SECRET)
+);
+requiredPermissions.set(
+	secretOperations.listSecrets.name,
+	new (permission as any)(true, [], terms.OPERATIONS_ENUM.LIST_SECRETS)
+);
+requiredPermissions.set(
+	secretOperations.deleteSecret.name,
+	new (permission as any)(true, [], terms.OPERATIONS_ENUM.DELETE_SECRET)
+);
+requiredPermissions.set(
+	secretOperations.getSecretsPublicKey.name,
+	new (permission as any)(true, [], terms.OPERATIONS_ENUM.GET_SECRETS_PUBLIC_KEY)
+);
+
 //Below are functions that are currently open to all roles
 requiredPermissions.set(regDeprecated.getRegistrationInfo.name, new (permission as any)(false, []));
 requiredPermissions.set(user.userInfo.name, new (permission as any)(false, [], terms.OPERATIONS_ENUM.USER_INFO));
@@ -299,6 +370,8 @@ module.exports = {
 	verifyPerms,
 	verifyPermsAST,
 	verifyBulkLoadAttributePerms,
+	registerOperationPermission,
+	unregisterOperationPermission,
 };
 
 /**