@promptbook/cli 0.113.0-7 → 0.113.0-9

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

@@ -0,0 +1,57 @@
+import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForServer';
+import type { Json } from '@/src/database/schema';
+import { getShibbolethAuthenticationAttemptTableName } from './getShibbolethAuthenticationAttemptTableName';
+import type { ShibbolethRequestDetails } from './shibbolethAuthenticationTypes';
+
+/**
+ * Options for recording a Shibboleth authentication attempt.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+type RecordShibbolethAuthenticationAttemptOptions = {
+    readonly stage: string;
+    readonly status: string;
+    readonly requestDetails?: ShibbolethRequestDetails;
+    readonly userId?: number | null;
+    readonly email?: string | null;
+    readonly displayName?: string | null;
+    readonly nameId?: string | null;
+    readonly relayState?: string | null;
+    readonly errorMessage?: string | null;
+    readonly rawAttributes?: Json | null;
+};
+
+/**
+ * Records one Shibboleth authentication attempt.
+ *
+ * @param options - Attempt details.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export async function recordShibbolethAuthenticationAttempt(
+    options: RecordShibbolethAuthenticationAttemptOptions,
+): Promise<void> {
+    try {
+        const supabase = $provideSupabaseForServer();
+        const tableName = await getShibbolethAuthenticationAttemptTableName();
+        const { error } = await supabase.from(tableName).insert({
+            stage: options.stage,
+            status: options.status,
+            userId: options.userId ?? null,
+            email: options.email ?? null,
+            displayName: options.displayName ?? null,
+            nameId: options.nameId ?? null,
+            relayState: options.relayState ?? null,
+            ip: options.requestDetails?.ip ?? null,
+            userAgent: options.requestDetails?.userAgent ?? null,
+            errorMessage: options.errorMessage ?? null,
+            rawAttributes: options.rawAttributes ?? null,
+        } as never);
+
+        if (error) {
+            console.error('Failed to record Shibboleth authentication attempt:', error);
+        }
+    } catch (error) {
+        console.error('Failed to record Shibboleth authentication attempt:', error);
+    }
+}

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

@@ -0,0 +1,78 @@
+import {
+    IS_SHIBBOLETH_AUTH_ACTIVE_METADATA_KEY,
+    SHIBBOLETH_AUTHENTICATION_METADATA_KEYS,
+    SHIBBOLETH_IDENTITY_PROVIDER_METADATA_URL_METADATA_KEY,
+    SHIBBOLETH_IDENTITY_PROVIDER_METADATA_XML_METADATA_KEY,
+    parseShibbolethBooleanMetadata,
+} from '@/src/constants/shibbolethAuth';
+import { getMetadataMap } from '@/src/database/getMetadata';
+import { fetchIdentityProviderMetadataXml } from './fetchIdentityProviderMetadataXml';
+import { parseIdentityProviderMetadataXml } from './parseIdentityProviderMetadataXml';
+import { resolveShibbolethServiceProviderUrls } from './resolveShibbolethServiceProviderUrls';
+import type {
+    ShibbolethAuthenticationConfiguration,
+    ShibbolethIdentityProviderMetadata,
+} from './shibbolethAuthenticationTypes';
+
+/**
+ * Options for resolving Shibboleth authentication configuration.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+type ResolveShibbolethAuthenticationConfigurationOptions = {
+    readonly requestUrl: string;
+    readonly isIdentityProviderMetadataValidationEnabled?: boolean;
+};
+
+/**
+ * Resolves Shibboleth configuration from metadata for a route-handler request.
+ *
+ * @param options - Request URL and validation options.
+ * @returns Shibboleth configuration status and parsed IdP metadata when validation is enabled.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export async function resolveShibbolethAuthenticationConfiguration(
+    options: ResolveShibbolethAuthenticationConfigurationOptions,
+): Promise<ShibbolethAuthenticationConfiguration> {
+    const metadata = await getMetadataMap(SHIBBOLETH_AUTHENTICATION_METADATA_KEYS);
+    const isActive = parseShibbolethBooleanMetadata(metadata[IS_SHIBBOLETH_AUTH_ACTIVE_METADATA_KEY]);
+    const identityProviderMetadataUrl =
+        (metadata[SHIBBOLETH_IDENTITY_PROVIDER_METADATA_URL_METADATA_KEY] || '').trim() || null;
+    const identityProviderMetadataXml =
+        (metadata[SHIBBOLETH_IDENTITY_PROVIDER_METADATA_XML_METADATA_KEY] || '').trim() || null;
+    const serviceProviderUrls = resolveShibbolethServiceProviderUrls(options.requestUrl, metadata);
+    const errors: string[] = [];
+    let identityProviderMetadata: ShibbolethIdentityProviderMetadata | null = null;
+
+    if (!identityProviderMetadataUrl && !identityProviderMetadataXml) {
+        errors.push(
+            `Set ${SHIBBOLETH_IDENTITY_PROVIDER_METADATA_URL_METADATA_KEY} or ${SHIBBOLETH_IDENTITY_PROVIDER_METADATA_XML_METADATA_KEY}.`,
+        );
+    }
+
+    if (
+        options.isIdentityProviderMetadataValidationEnabled === true &&
+        (identityProviderMetadataUrl || identityProviderMetadataXml)
+    ) {
+        try {
+            const metadataXml =
+                identityProviderMetadataXml || (await fetchIdentityProviderMetadataXml(identityProviderMetadataUrl!));
+            identityProviderMetadata = parseIdentityProviderMetadataXml(metadataXml);
+        } catch (error) {
+            errors.push(
+                error instanceof Error ? error.message : 'Failed to load Shibboleth Identity Provider metadata.',
+            );
+        }
+    }
+
+    return {
+        isActive,
+        isConfigured: errors.length === 0,
+        errors,
+        identityProviderMetadataUrl,
+        isIdentityProviderMetadataXmlConfigured: Boolean(identityProviderMetadataXml),
+        serviceProviderUrls,
+        identityProviderMetadata,
+    };
+}

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

@@ -0,0 +1,101 @@
+/**
+ * HTTP protocols accepted from proxy forwarding headers.
+ */
+const SHIBBOLETH_FORWARDED_PROTOCOLS = new Set(['http', 'https']);
+
+/**
+ * Local hostnames that should keep their request protocol in development.
+ */
+const SHIBBOLETH_LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1']);
+
+/**
+ * Resolves the externally visible URL for one Shibboleth route request.
+ *
+ * @param request - Route-handler request received by the Agents Server.
+ * @returns Public request URL reconstructed from trusted reverse-proxy headers when present.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export function resolveShibbolethPublicRequestUrl(request: Request): string {
+    const publicRequestUrl = new URL(request.url);
+    const forwardedHost = getFirstHeaderValue(request.headers.get('x-forwarded-host'));
+    const requestHost = getFirstHeaderValue(request.headers.get('host'));
+    const host = forwardedHost || requestHost;
+
+    if (host) {
+        publicRequestUrl.host = host;
+        if (!hasExplicitPort(host)) {
+            publicRequestUrl.port = '';
+        }
+    }
+
+    publicRequestUrl.protocol = resolvePublicProtocol({
+        forwardedProtocol: getFirstHeaderValue(request.headers.get('x-forwarded-proto')),
+        fallbackProtocol: publicRequestUrl.protocol,
+        host: host || publicRequestUrl.host,
+    });
+
+    return publicRequestUrl.toString();
+}
+
+/**
+ * Returns the first value from a comma-separated forwarding header.
+ *
+ * @param value - Raw header value.
+ * @returns First trimmed value, or `null` when empty.
+ */
+function getFirstHeaderValue(value: string | null): string | null {
+    return value?.split(',')[0]?.trim() || null;
+}
+
+/**
+ * Checks whether one host header explicitly carries a port.
+ *
+ * @param host - Request or forwarded host.
+ * @returns `true` when the host includes a non-implicit port segment.
+ */
+function hasExplicitPort(host: string): boolean {
+    const trimmedHost = host.trim();
+
+    return /^\[[^\]]+\]:\d+$/u.test(trimmedHost) || /^[^:]+:\d+$/u.test(trimmedHost);
+}
+
+/**
+ * Resolves the public protocol for a Shibboleth request URL.
+ *
+ * @param options - Forwarded protocol, fallback protocol, and public host.
+ * @returns Protocol string ending with `:`.
+ */
+function resolvePublicProtocol(options: {
+    readonly forwardedProtocol: string | null;
+    readonly fallbackProtocol: string;
+    readonly host: string;
+}): string {
+    const normalizedForwardedProtocol = options.forwardedProtocol?.toLowerCase();
+
+    if (normalizedForwardedProtocol && SHIBBOLETH_FORWARDED_PROTOCOLS.has(normalizedForwardedProtocol)) {
+        return `${normalizedForwardedProtocol}:`;
+    }
+
+    if (!isLocalDevelopmentHost(options.host)) {
+        return 'https:';
+    }
+
+    return options.fallbackProtocol;
+}
+
+/**
+ * Checks whether the host should be treated as local development.
+ *
+ * @param host - Request or forwarded host.
+ * @returns `true` for localhost and loopback hosts.
+ */
+function isLocalDevelopmentHost(host: string): boolean {
+    const hostname = host
+        .trim()
+        .toLowerCase()
+        .replace(/^\[(.+)\](?::\d+)?$/u, '$1')
+        .replace(/:\d+$/u, '');
+
+    return SHIBBOLETH_LOCAL_HOSTNAMES.has(hostname);
+}

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

@@ -0,0 +1,63 @@
+import { SHIBBOLETH_SERVICE_PROVIDER_ENTITY_ID_METADATA_KEY } from '@/src/constants/shibbolethAuth';
+import type { ShibbolethServiceProviderUrls } from './shibbolethAuthenticationTypes';
+
+/**
+ * Local hostnames that should not override a configured public site URL.
+ */
+const LOCAL_DEVELOPMENT_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1']);
+
+/**
+ * Resolves SP URLs from request URL, environment, and metadata.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export function resolveShibbolethServiceProviderUrls(
+    requestUrl: string,
+    metadata: Readonly<Record<string, string | null>>,
+): ShibbolethServiceProviderUrls {
+    const requestOrigin = new URL(requestUrl).origin;
+    const configuredSiteUrl = (process.env.NEXT_PUBLIC_SITE_URL || '').trim();
+    const configuredOrigin = configuredSiteUrl ? new URL(configuredSiteUrl).origin : null;
+    const origin = resolveShibbolethPublicOrigin(requestOrigin, configuredOrigin);
+    const assertionConsumerServiceUrl = new URL('/api/auth/shibboleth/acs', origin).toString();
+    const metadataUrl = new URL('/api/auth/shibboleth/metadata', origin).toString();
+    const configuredEntityId = (metadata[SHIBBOLETH_SERVICE_PROVIDER_ENTITY_ID_METADATA_KEY] || '').trim();
+
+    return {
+        origin,
+        entityId: configuredEntityId || metadataUrl,
+        assertionConsumerServiceUrl,
+        metadataUrl,
+    };
+}
+
+/**
+ * Chooses the public origin used in Shibboleth metadata, ACS validation, and redirects.
+ *
+ * @param requestOrigin - Origin reconstructed from the current request and proxy headers.
+ * @param configuredOrigin - Optional origin from `NEXT_PUBLIC_SITE_URL`.
+ * @returns Origin that should be visible to the Identity Provider and browser.
+ */
+function resolveShibbolethPublicOrigin(requestOrigin: string, configuredOrigin: string | null): string {
+    if (!isLocalDevelopmentOrigin(requestOrigin)) {
+        return requestOrigin;
+    }
+
+    if (configuredOrigin && !isLocalDevelopmentOrigin(configuredOrigin)) {
+        return configuredOrigin;
+    }
+
+    return configuredOrigin || requestOrigin;
+}
+
+/**
+ * Checks whether one origin points to a local development host.
+ *
+ * @param origin - Origin to inspect.
+ * @returns `true` when the origin is localhost or loopback.
+ */
+function isLocalDevelopmentOrigin(origin: string): boolean {
+    const hostname = new URL(origin).hostname.toLowerCase();
+
+    return LOCAL_DEVELOPMENT_HOSTNAMES.has(hostname);
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Returns a safe relative URL to redirect to after Shibboleth finishes.
+ *
+ * @param relayState - Raw RelayState value from the request or SAML response.
+ * @returns Safe relative URL.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export function sanitizeShibbolethRelayState(relayState: string | null | undefined): string {
+    const trimmedRelayState = (relayState || '').trim();
+
+    if (!trimmedRelayState || !trimmedRelayState.startsWith('/') || trimmedRelayState.startsWith('//')) {
+        return '/';
+    }
+
+    return trimmedRelayState;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Persistent NameID format recommended for Shibboleth integrations.
+ *
+ * @private constant of `shibbolethAuthentication`
+ */
+export const SHIBBOLETH_PERSISTENT_NAME_ID_FORMAT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent';
+
+/**
+ * SAML HTTP Redirect binding URL.
+ *
+ * @private constant of `shibbolethAuthentication`
+ */
+export const SAML_HTTP_REDIRECT_BINDING = 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect';
+
+/**
+ * Timeout for loading remote Identity Provider metadata.
+ *
+ * @private constant of `shibbolethAuthentication`
+ */
+export const SHIBBOLETH_IDENTITY_PROVIDER_METADATA_TIMEOUT_MS = 10_000;
+
+/**
+ * Clock skew accepted when validating SAML assertion timestamps.
+ *
+ * @private constant of `shibbolethAuthentication`
+ */
+export const SHIBBOLETH_ACCEPTED_CLOCK_SKEW_MS = 120_000;
+
+/**
+ * Placeholder password hash for database users that can only sign in via Shibboleth.
+ *
+ * @private constant of `shibbolethAuthentication`
+ */
+export const SHIBBOLETH_PASSWORDLESS_USER_PASSWORD_HASH = 'shibboleth-passwordless-user';
+
+/**
+ * Marker stored on database users that authenticate with username/password only.
+ *
+ * @private constant of `shibbolethAuthentication`
+ */
+export const LOCAL_AUTHENTICATION_PROVIDER = 'LOCAL';
+
+/**
+ * Marker stored on database users that authenticate with Shibboleth only.
+ *
+ * @private constant of `shibbolethAuthentication`
+ */
+export const SHIBBOLETH_AUTHENTICATION_PROVIDER = 'SHIBBOLETH';
+
+/**
+ * Marker stored on database users that authenticate with username/password and Shibboleth.
+ *
+ * @private constant of `shibbolethAuthentication`
+ */
+export const LOCAL_AND_SHIBBOLETH_AUTHENTICATION_PROVIDER = 'LOCAL_AND_SHIBBOLETH';
+
+/**
+ * Supabase projection for user fields needed while linking Shibboleth identities.
+ *
+ * @private constant of `shibbolethAuthentication`
+ */
+export const SHIBBOLETH_USER_SELECT_COLUMNS: string = 'id, username, isAdmin, email, displayName, authenticationProvider';

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

@@ -0,0 +1,105 @@
+import type { Json } from '@/src/database/schema';
+
+/**
+ * Prefixed Shibboleth identity row.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+export type ShibbolethUserIdentityRow = {
+    readonly id: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly userId: number;
+    readonly email: string;
+    readonly displayName: string | null;
+    readonly nameId: string | null;
+    readonly nameIdFormat: string | null;
+    readonly unstructuredName: string | null;
+    readonly eduPersonPrincipalName: string | null;
+    readonly rawAttributes: Json | null;
+    readonly lastLoggedInAt: string | null;
+    readonly loginCount: number;
+};
+
+/**
+ * Prefixed Shibboleth authentication attempt row.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+export type ShibbolethAuthenticationAttemptRow = {
+    readonly id: number;
+    readonly createdAt: string;
+    readonly stage: string;
+    readonly status: string;
+    readonly userId: number | null;
+    readonly email: string | null;
+    readonly displayName: string | null;
+    readonly nameId: string | null;
+    readonly relayState: string | null;
+    readonly ip: string | null;
+    readonly userAgent: string | null;
+    readonly errorMessage: string | null;
+    readonly rawAttributes: Json | null;
+};
+
+/**
+ * Request metadata recorded with Shibboleth authentication attempts.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+export type ShibbolethRequestDetails = {
+    readonly ip: string | null;
+    readonly userAgent: string | null;
+};
+
+/**
+ * Parsed Shibboleth user attributes extracted from SAML profile data.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+export type ShibbolethProfileAttributes = {
+    readonly email: string;
+    readonly displayName: string | null;
+    readonly nameId: string | null;
+    readonly nameIdFormat: string | null;
+    readonly unstructuredName: string | null;
+    readonly eduPersonPrincipalName: string | null;
+    readonly rawAttributes: Json;
+};
+
+/**
+ * Service Provider URLs derived for the current request.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+export type ShibbolethServiceProviderUrls = {
+    readonly origin: string;
+    readonly entityId: string;
+    readonly assertionConsumerServiceUrl: string;
+    readonly metadataUrl: string;
+};
+
+/**
+ * Parsed Identity Provider metadata needed by Node-SAML.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+export type ShibbolethIdentityProviderMetadata = {
+    readonly singleSignOnServiceUrl: string;
+    readonly signingCertificates: ReadonlyArray<string>;
+};
+
+/**
+ * Resolved Shibboleth authentication configuration status.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+export type ShibbolethAuthenticationConfiguration = {
+    readonly isActive: boolean;
+    readonly isConfigured: boolean;
+    readonly errors: ReadonlyArray<string>;
+    readonly identityProviderMetadataUrl: string | null;
+    readonly isIdentityProviderMetadataXmlConfigured: boolean;
+    readonly serviceProviderUrls: ShibbolethServiceProviderUrls;
+    readonly identityProviderMetadata: ShibbolethIdentityProviderMetadata | null;
+};