@promptbook/cli 0.113.0-1 → 0.113.0-11

package/apps/agents-server/src/utils/resourceMonitor/resolveServerResourceWarningStatus.ts

@@ -0,0 +1,72 @@
+import {
+    CPU_LOAD_WARNING_RATIO,
+    DISK_AVAILABLE_WARNING_BYTES,
+    DISK_AVAILABLE_WARNING_RATIO,
+    MEMORY_AVAILABLE_WARNING_RATIO,
+} from './resourceMonitorConstants';
+import { formatResourceBytes, formatResourcePercentage } from './formatResourceMonitorValue';
+import type {
+    CpuResourceUsage,
+    DiskResourceUsage,
+    MemoryResourceUsage,
+    ServerResourceWarningIssue,
+    ServerResourceWarningStatus,
+} from './resourceMonitorTypes';
+
+/**
+ * Inputs required to resolve resource warning status.
+ */
+type ResolveServerResourceWarningStatusOptions = {
+    readonly cpu: CpuResourceUsage;
+    readonly memory: MemoryResourceUsage;
+    readonly disk: DiskResourceUsage;
+};
+
+/**
+ * Resolves whether the server is low on operational resources.
+ *
+ * @param options - Current resource usage.
+ * @returns Warning status for the header and monitor page.
+ */
+export function resolveServerResourceWarningStatus({
+    cpu,
+    memory,
+    disk,
+}: ResolveServerResourceWarningStatusOptions): ServerResourceWarningStatus {
+    const issues: ServerResourceWarningIssue[] = [];
+
+    if (cpu.loadRatio !== null && cpu.loadRatio >= CPU_LOAD_WARNING_RATIO) {
+        issues.push({
+            resource: 'cpu',
+            message: `CPU load is ${formatResourcePercentage(cpu.loadRatio)} of ${cpu.coreCount} logical cores.`,
+        });
+    }
+
+    if (memory.availableRatio <= MEMORY_AVAILABLE_WARNING_RATIO) {
+        issues.push({
+            resource: 'memory',
+            message: `Free memory is ${formatResourcePercentage(memory.availableRatio)} (${formatResourceBytes(
+                memory.freeBytes,
+            )}) of ${formatResourceBytes(memory.totalBytes)}.`,
+        });
+    }
+
+    if (
+        disk.availableBytes !== null &&
+        disk.availableRatio !== null &&
+        (disk.availableRatio <= DISK_AVAILABLE_WARNING_RATIO || disk.availableBytes <= DISK_AVAILABLE_WARNING_BYTES)
+    ) {
+        issues.push({
+            resource: 'disk',
+            message: `Available disk space is ${formatResourcePercentage(disk.availableRatio)} (${formatResourceBytes(
+                disk.availableBytes,
+            )}) on ${disk.inspectedPath}.`,
+        });
+    }
+
+    return {
+        isWarningShown: issues.length > 0,
+        issues,
+        warningMessages: issues.map((issue) => issue.message),
+    };
+}

package/apps/agents-server/src/utils/resourceMonitor/resourceMonitorConstants.ts

@@ -0,0 +1,29 @@
+/**
+ * CPU load ratio that triggers a resource pressure warning.
+ */
+export const CPU_LOAD_WARNING_RATIO = 0.9;
+
+/**
+ * Free memory ratio that triggers a resource pressure warning.
+ */
+export const MEMORY_AVAILABLE_WARNING_RATIO = 0.1;
+
+/**
+ * Available disk ratio that triggers a resource pressure warning.
+ */
+export const DISK_AVAILABLE_WARNING_RATIO = 0.1;
+
+/**
+ * Available disk byte floor that triggers a resource pressure warning.
+ */
+export const DISK_AVAILABLE_WARNING_BYTES = 1024 * 1024 * 1024;
+
+/**
+ * Default CPU sample duration for process usage.
+ */
+export const DEFAULT_PROCESS_CPU_SAMPLE_DURATION_MS = 250;
+
+/**
+ * Default network sample duration for rate calculation.
+ */
+export const DEFAULT_NETWORK_SAMPLE_DURATION_MS = 250;

package/apps/agents-server/src/utils/resourceMonitor/resourceMonitorTypes.ts

@@ -0,0 +1,155 @@
+/**
+ * Resource key tracked by the server resource monitor.
+ */
+export type ResourceMonitorResource = 'cpu' | 'memory' | 'disk';
+
+/**
+ * One warning issue detected by the resource monitor.
+ */
+export type ServerResourceWarningIssue = {
+    /**
+     * Resource that crossed a warning threshold.
+     */
+    readonly resource: ResourceMonitorResource;
+
+    /**
+     * Human-readable warning message.
+     */
+    readonly message: string;
+};
+
+/**
+ * Lightweight resource status safe to pass into client navigation.
+ */
+export type ServerResourceWarningStatus = {
+    /**
+     * Whether any monitored resource is currently under pressure.
+     */
+    readonly isWarningShown: boolean;
+
+    /**
+     * Individual resource pressure issues.
+     */
+    readonly issues: ReadonlyArray<ServerResourceWarningIssue>;
+
+    /**
+     * Human-readable warning messages.
+     */
+    readonly warningMessages: ReadonlyArray<string>;
+};
+
+/**
+ * Default empty resource warning status.
+ */
+export const RESOURCE_MONITOR_OK_WARNING_STATUS: ServerResourceWarningStatus = {
+    isWarningShown: false,
+    issues: [],
+    warningMessages: [],
+};
+
+/**
+ * CPU usage snapshot.
+ */
+export type CpuResourceUsage = {
+    /**
+     * Number of logical CPU cores visible to Node.js.
+     */
+    readonly coreCount: number;
+
+    /**
+     * One-minute system load average, or `null` when the platform does not expose it.
+     */
+    readonly averageLoadOneMinute: number | null;
+
+    /**
+     * Five-minute system load average, or `null` when the platform does not expose it.
+     */
+    readonly averageLoadFiveMinutes: number | null;
+
+    /**
+     * Fifteen-minute system load average, or `null` when the platform does not expose it.
+     */
+    readonly averageLoadFifteenMinutes: number | null;
+
+    /**
+     * One-minute load divided by logical CPU cores.
+     */
+    readonly loadRatio: number | null;
+
+    /**
+     * Current Node.js process CPU ratio sampled over a short interval.
+     */
+    readonly processUsageRatio: number | null;
+};
+
+/**
+ * Memory usage snapshot.
+ */
+export type MemoryResourceUsage = {
+    readonly totalBytes: number;
+    readonly freeBytes: number;
+    readonly usedBytes: number;
+    readonly usedRatio: number;
+    readonly availableRatio: number;
+    readonly processRssBytes: number;
+    readonly processHeapUsedBytes: number;
+    readonly processHeapTotalBytes: number;
+    readonly processExternalBytes: number;
+    readonly processArrayBuffersBytes: number;
+};
+
+/**
+ * Disk usage snapshot for the filesystem that hosts the server process.
+ */
+export type DiskResourceUsage = {
+    readonly inspectedPath: string;
+    readonly totalBytes: number | null;
+    readonly freeBytes: number | null;
+    readonly availableBytes: number | null;
+    readonly usedBytes: number | null;
+    readonly usedRatio: number | null;
+    readonly availableRatio: number | null;
+    readonly errorMessage: string | null;
+};
+
+/**
+ * Network traffic snapshot for one interface.
+ */
+export type NetworkInterfaceResourceUsage = {
+    readonly name: string;
+    readonly receivedBytes: number;
+    readonly transmittedBytes: number;
+    readonly receivedBytesPerSecond: number | null;
+    readonly transmittedBytesPerSecond: number | null;
+};
+
+/**
+ * Network traffic summary.
+ */
+export type NetworkResourceUsage = {
+    /**
+     * Whether traffic counters are available on this host.
+     */
+    readonly isTrafficAvailable: boolean;
+
+    readonly interfaces: ReadonlyArray<NetworkInterfaceResourceUsage>;
+    readonly totalReceivedBytes: number | null;
+    readonly totalTransmittedBytes: number | null;
+    readonly totalReceivedBytesPerSecond: number | null;
+    readonly totalTransmittedBytesPerSecond: number | null;
+    readonly networkInterfaceCount: number;
+    readonly networkAddressCount: number;
+    readonly errorMessage: string | null;
+};
+
+/**
+ * Full resource monitor snapshot rendered by `/admin/resource-monitor`.
+ */
+export type ServerResourceMonitorSnapshot = {
+    readonly measuredAt: string;
+    readonly cpu: CpuResourceUsage;
+    readonly memory: MemoryResourceUsage;
+    readonly disk: DiskResourceUsage;
+    readonly network: NetworkResourceUsage;
+    readonly warningStatus: ServerResourceWarningStatus;
+};

package/apps/agents-server/src/utils/resourceMonitor/waitForResourceMonitorSample.ts

@@ -0,0 +1,11 @@
+/**
+ * Waits for a short sampling interval between resource counter reads.
+ *
+ * @param durationMs - Sampling duration in milliseconds.
+ * @returns Promise resolved after the duration elapses.
+ */
+export function waitForResourceMonitorSample(durationMs: number): Promise<void> {
+    return new Promise((resolve) => {
+        setTimeout(resolve, Math.max(0, durationMs));
+    });
+}

package/apps/agents-server/src/utils/shibbolethAuthentication/createShibbolethSamlClient.ts

@@ -0,0 +1,35 @@
+import { SAML, ValidateInResponseTo } from '@node-saml/node-saml';
+import {
+    SHIBBOLETH_ACCEPTED_CLOCK_SKEW_MS,
+    SHIBBOLETH_PERSISTENT_NAME_ID_FORMAT,
+} from './shibbolethAuthenticationConstants';
+import type { ShibbolethAuthenticationConfiguration } from './shibbolethAuthenticationTypes';
+
+/**
+ * Creates a Node-SAML client for the resolved Shibboleth configuration.
+ *
+ * @param configuration - Resolved Shibboleth configuration with parsed IdP metadata.
+ * @returns Configured Node-SAML client.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export function createShibbolethSamlClient(configuration: ShibbolethAuthenticationConfiguration): SAML {
+    if (!configuration.identityProviderMetadata) {
+        throw new Error('Shibboleth Identity Provider metadata is not loaded.');
+    }
+
+    return new SAML({
+        callbackUrl: configuration.serviceProviderUrls.assertionConsumerServiceUrl,
+        entryPoint: configuration.identityProviderMetadata.singleSignOnServiceUrl,
+        issuer: configuration.serviceProviderUrls.entityId,
+        audience: configuration.serviceProviderUrls.entityId,
+        idpCert: [...configuration.identityProviderMetadata.signingCertificates],
+        identifierFormat: SHIBBOLETH_PERSISTENT_NAME_ID_FORMAT,
+        wantAssertionsSigned: true,
+        wantAuthnResponseSigned: false,
+        acceptedClockSkewMs: SHIBBOLETH_ACCEPTED_CLOCK_SKEW_MS,
+        validateInResponseTo: ValidateInResponseTo.never,
+        disableRequestedAuthnContext: true,
+        signatureAlgorithm: 'sha256',
+    });
+}

package/apps/agents-server/src/utils/shibbolethAuthentication/createShibbolethServiceProviderMetadataXml.ts

@@ -0,0 +1,25 @@
+import { generateServiceProviderMetadata } from '@node-saml/node-saml';
+import { SHIBBOLETH_AUTHENTICATION_METADATA_KEYS } from '@/src/constants/shibbolethAuth';
+import { getMetadataMap } from '@/src/database/getMetadata';
+import { SHIBBOLETH_PERSISTENT_NAME_ID_FORMAT } from './shibbolethAuthenticationConstants';
+import { resolveShibbolethServiceProviderUrls } from './resolveShibbolethServiceProviderUrls';
+
+/**
+ * Creates Service Provider metadata XML for the current Agents Server deployment.
+ *
+ * @param requestUrl - URL of the current metadata route request.
+ * @returns Service Provider metadata XML suitable for the Shibboleth IdP admin.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export async function createShibbolethServiceProviderMetadataXml(requestUrl: string): Promise<string> {
+    const metadata = await getMetadataMap(SHIBBOLETH_AUTHENTICATION_METADATA_KEYS);
+    const serviceProviderUrls = resolveShibbolethServiceProviderUrls(requestUrl, metadata);
+
+    return generateServiceProviderMetadata({
+        issuer: serviceProviderUrls.entityId,
+        callbackUrl: serviceProviderUrls.assertionConsumerServiceUrl,
+        identifierFormat: SHIBBOLETH_PERSISTENT_NAME_ID_FORMAT,
+        wantAssertionsSigned: true,
+    });
+}

package/apps/agents-server/src/utils/shibbolethAuthentication/extractShibbolethProfileAttributes.ts

@@ -0,0 +1,173 @@
+import type { Profile } from '@node-saml/node-saml';
+import {
+    DEFAULT_SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES,
+    DEFAULT_SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES,
+    DEFAULT_SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES,
+    SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES_METADATA_KEY,
+    SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES_METADATA_KEY,
+    SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES_METADATA_KEY,
+} from '@/src/constants/shibbolethAuth';
+import type { Json } from '@/src/database/schema';
+import type { ShibbolethProfileAttributes } from './shibbolethAuthenticationTypes';
+
+/**
+ * Extracts required Shibboleth profile attributes from a validated SAML profile.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export function extractShibbolethProfileAttributes(
+    profile: Profile,
+    metadata: Readonly<Record<string, string | null>>,
+): ShibbolethProfileAttributes {
+    const rawAttributes = sanitizeShibbolethRawAttributes(profile);
+    const email = getFirstProfileAttribute(
+        profile,
+        parseAttributeNames(
+            metadata[SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES_METADATA_KEY],
+            DEFAULT_SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES,
+        ),
+    )?.toLowerCase();
+
+    if (!email) {
+        throw new Error('Shibboleth login did not provide an email attribute.');
+    }
+
+    const displayName =
+        getFirstProfileAttribute(
+            profile,
+            parseAttributeNames(
+                metadata[SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES_METADATA_KEY],
+                DEFAULT_SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES,
+            ),
+        ) || null;
+    const unstructuredName =
+        getFirstProfileAttribute(
+            profile,
+            parseAttributeNames(
+                metadata[SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES_METADATA_KEY],
+                DEFAULT_SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES,
+            ),
+        ) || null;
+    const eduPersonPrincipalName =
+        getFirstProfileAttribute(profile, ['eduPersonPrincipalName', 'urn:oid:1.3.6.1.4.1.5923.1.1.1.6']) || null;
+
+    return {
+        email,
+        displayName,
+        nameId: getStringOrNull(profile.nameID),
+        nameIdFormat: getStringOrNull(profile.nameIDFormat),
+        unstructuredName,
+        eduPersonPrincipalName,
+        rawAttributes,
+    };
+}
+
+/**
+ * Finds the first non-empty profile attribute from a list of accepted names.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+function getFirstProfileAttribute(profile: Profile, attributeNames: ReadonlyArray<string>): string | null {
+    for (const attributeName of attributeNames) {
+        const value = profile[attributeName];
+        const stringValue = getFirstStringValue(value);
+        if (stringValue) {
+            return stringValue;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Parses metadata-defined attribute names.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+function parseAttributeNames(value: string | null | undefined, fallback: string): string[] {
+    return (value || fallback)
+        .split(/[\s,]+/u)
+        .map((attributeName) => attributeName.trim())
+        .filter(Boolean);
+}
+
+/**
+ * Converts a profile value into one string.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+function getFirstStringValue(value: unknown): string | null {
+    if (typeof value === 'string') {
+        return value.trim() || null;
+    }
+
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const stringValue = getFirstStringValue(item);
+            if (stringValue) {
+                return stringValue;
+            }
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Converts an unknown value into a string or null.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+function getStringOrNull(value: unknown): string | null {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+/**
+ * Builds a JSON-safe SAML profile snapshot for audit records.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+function sanitizeShibbolethRawAttributes(profile: Profile): Json {
+    const sanitizedAttributes: Record<string, Json> = {};
+
+    for (const [key, value] of Object.entries(profile)) {
+        if (typeof value === 'function') {
+            continue;
+        }
+
+        const sanitizedValue = sanitizeJsonValue(value);
+        if (sanitizedValue !== undefined) {
+            sanitizedAttributes[key] = sanitizedValue;
+        }
+    }
+
+    return sanitizedAttributes;
+}
+
+/**
+ * Converts unknown profile values into JSON-safe values.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+function sanitizeJsonValue(value: unknown): Json | undefined {
+    if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeJsonValue(item)).filter((item): item is Json => item !== undefined);
+    }
+
+    if (typeof value === 'object') {
+        const result: Record<string, Json> = {};
+        for (const [key, nestedValue] of Object.entries(value)) {
+            const sanitizedValue = sanitizeJsonValue(nestedValue);
+            if (sanitizedValue !== undefined) {
+                result[key] = sanitizedValue;
+            }
+        }
+        return result;
+    }
+
+    return undefined;
+}

package/apps/agents-server/src/utils/shibbolethAuthentication/fetchIdentityProviderMetadataXml.ts

@@ -0,0 +1,21 @@
+import { SHIBBOLETH_IDENTITY_PROVIDER_METADATA_TIMEOUT_MS } from './shibbolethAuthenticationConstants';
+
+/**
+ * Loads remote IdP metadata XML.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export async function fetchIdentityProviderMetadataXml(identityProviderMetadataUrl: string): Promise<string> {
+    const response = await fetch(identityProviderMetadataUrl, {
+        cache: 'no-store',
+        signal: AbortSignal.timeout(SHIBBOLETH_IDENTITY_PROVIDER_METADATA_TIMEOUT_MS),
+    });
+
+    if (!response.ok) {
+        throw new Error(
+            `Failed to load Shibboleth Identity Provider metadata: ${response.status} ${response.statusText}.`,
+        );
+    }
+
+    return response.text();
+}