@promptbook/cli 0.113.0-8 → 0.114.0-0

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();
+}

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

@@ -0,0 +1,323 @@
+import type { Profile } from '@node-saml/node-saml';
+import { SHIBBOLETH_AUTHENTICATION_METADATA_KEYS } from '@/src/constants/shibbolethAuth';
+import { $getTableName } from '@/src/database/$getTableName';
+import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForServer';
+import { getMetadataMap } from '@/src/database/getMetadata';
+import type { AgentsServerDatabase } from '@/src/database/schema';
+import { extractShibbolethProfileAttributes } from './extractShibbolethProfileAttributes';
+import { getShibbolethUserIdentityTableName } from './getShibbolethUserIdentityTableName';
+import {
+    LOCAL_AND_SHIBBOLETH_AUTHENTICATION_PROVIDER,
+    LOCAL_AUTHENTICATION_PROVIDER,
+    SHIBBOLETH_AUTHENTICATION_PROVIDER,
+    SHIBBOLETH_PASSWORDLESS_USER_PASSWORD_HASH,
+    SHIBBOLETH_USER_SELECT_COLUMNS,
+} from './shibbolethAuthenticationConstants';
+import type { ShibbolethProfileAttributes, ShibbolethUserIdentityRow } from './shibbolethAuthenticationTypes';
+
+/**
+ * User table row fields needed while linking Shibboleth identities.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+type UserRowWithShibbolethColumns = Pick<
+    AgentsServerDatabase['public']['Tables']['User']['Row'],
+    'id' | 'username' | 'isAdmin'
+> & {
+    readonly email?: string | null;
+    readonly displayName?: string | null;
+    readonly authenticationProvider?: string | null;
+};
+
+/**
+ * User insert shape with Shibboleth profile columns added by migration.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+type UserInsertWithShibbolethColumns = AgentsServerDatabase['public']['Tables']['User']['Insert'] & {
+    readonly email?: string | null;
+    readonly displayName?: string | null;
+    readonly authenticationProvider?: string | null;
+};
+
+/**
+ * User update shape with Shibboleth profile columns added by migration.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+type UserUpdateWithShibbolethColumns = AgentsServerDatabase['public']['Tables']['User']['Update'] & {
+    readonly email?: string | null;
+    readonly displayName?: string | null;
+    readonly authenticationProvider?: string | null;
+};
+
+/**
+ * Result of linking a SAML profile to an Agents Server user.
+ *
+ * @private type of `shibbolethAuthentication`
+ */
+type LinkedShibbolethUser = {
+    readonly user: UserRowWithShibbolethColumns;
+    readonly profileAttributes: ShibbolethProfileAttributes;
+};
+
+/**
+ * Links a validated SAML profile to an Agents Server user, creating a passwordless user when needed.
+ *
+ * @param profile - Validated SAML profile from Node-SAML.
+ * @returns Linked database user and extracted Shibboleth attributes.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export async function findOrCreateShibbolethUser(profile: Profile): Promise<LinkedShibbolethUser> {
+    const metadata = await getMetadataMap(SHIBBOLETH_AUTHENTICATION_METADATA_KEYS);
+    const profileAttributes = extractShibbolethProfileAttributes(profile, metadata);
+    const now = new Date().toISOString();
+    const existingIdentity =
+        (await findShibbolethIdentityByNameId(profileAttributes.nameId)) ||
+        (await findShibbolethIdentityByEmail(profileAttributes.email));
+    let user = existingIdentity ? await findUserRowById(existingIdentity.userId) : null;
+
+    if (!user) {
+        user = await findUserRowByEmail(profileAttributes.email);
+    }
+
+    if (!user) {
+        user = await findUserRowByUsername(profileAttributes.email);
+    }
+
+    if (!user) {
+        user = await insertShibbolethUser(profileAttributes, now);
+    } else {
+        user = await updateLinkedShibbolethUser(user, profileAttributes, now);
+    }
+
+    await upsertShibbolethIdentity(user, profileAttributes, existingIdentity, now);
+
+    return {
+        user,
+        profileAttributes,
+    };
+}
+
+/**
+ * Finds one Shibboleth identity by persistent NameID.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+async function findShibbolethIdentityByNameId(nameId: string | null): Promise<ShibbolethUserIdentityRow | null> {
+    if (!nameId) {
+        return null;
+    }
+
+    const supabase = $provideSupabaseForServer();
+    const tableName = await getShibbolethUserIdentityTableName();
+    const { data, error } = await supabase
+        .from(tableName)
+        .select('*')
+        .eq('nameId' as never, nameId as never)
+        .maybeSingle();
+
+    if (error) {
+        throw new Error(`Failed to resolve Shibboleth identity by NameID: ${error.message}`);
+    }
+
+    return (data as ShibbolethUserIdentityRow | null) || null;
+}
+
+/**
+ * Finds one Shibboleth identity by email.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+async function findShibbolethIdentityByEmail(email: string): Promise<ShibbolethUserIdentityRow | null> {
+    const supabase = $provideSupabaseForServer();
+    const tableName = await getShibbolethUserIdentityTableName();
+    const { data, error } = await supabase
+        .from(tableName)
+        .select('*')
+        .eq('email' as never, email as never)
+        .maybeSingle();
+
+    if (error) {
+        throw new Error(`Failed to resolve Shibboleth identity by email: ${error.message}`);
+    }
+
+    return (data as ShibbolethUserIdentityRow | null) || null;
+}
+
+/**
+ * Finds one user row by database id.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+async function findUserRowById(userId: number): Promise<UserRowWithShibbolethColumns | null> {
+    const supabase = $provideSupabaseForServer();
+    const { data, error } = await supabase
+        .from(await $getTableName('User'))
+        .select(SHIBBOLETH_USER_SELECT_COLUMNS)
+        .eq('id', userId)
+        .maybeSingle();
+
+    if (error) {
+        throw new Error(`Failed to resolve Shibboleth user by id: ${error.message}`);
+    }
+
+    return (data as UserRowWithShibbolethColumns | null) || null;
+}
+
+/**
+ * Finds one user row by email.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+async function findUserRowByEmail(email: string): Promise<UserRowWithShibbolethColumns | null> {
+    const supabase = $provideSupabaseForServer();
+    const { data, error } = await supabase
+        .from(await $getTableName('User'))
+        .select(SHIBBOLETH_USER_SELECT_COLUMNS)
+        .eq('email' as never, email as never)
+        .maybeSingle();
+
+    if (error) {
+        throw new Error(`Failed to resolve Shibboleth user by email: ${error.message}`);
+    }
+
+    return (data as UserRowWithShibbolethColumns | null) || null;
+}
+
+/**
+ * Finds one user row by username.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+async function findUserRowByUsername(username: string): Promise<UserRowWithShibbolethColumns | null> {
+    const supabase = $provideSupabaseForServer();
+    const { data, error } = await supabase
+        .from(await $getTableName('User'))
+        .select(SHIBBOLETH_USER_SELECT_COLUMNS)
+        .eq('username', username)
+        .maybeSingle();
+
+    if (error) {
+        throw new Error(`Failed to resolve Shibboleth user by username: ${error.message}`);
+    }
+
+    return (data as UserRowWithShibbolethColumns | null) || null;
+}
+
+/**
+ * Inserts a new passwordless Shibboleth user.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+async function insertShibbolethUser(
+    profileAttributes: ShibbolethProfileAttributes,
+    now: string,
+): Promise<UserRowWithShibbolethColumns> {
+    const supabase = $provideSupabaseForServer();
+    const userInsert: UserInsertWithShibbolethColumns = {
+        username: profileAttributes.email,
+        passwordHash: SHIBBOLETH_PASSWORDLESS_USER_PASSWORD_HASH,
+        isAdmin: false,
+        email: profileAttributes.email,
+        displayName: profileAttributes.displayName,
+        authenticationProvider: SHIBBOLETH_AUTHENTICATION_PROVIDER,
+        createdAt: now,
+        updatedAt: now,
+    };
+    const { data, error } = await supabase
+        .from(await $getTableName('User'))
+        .insert(userInsert)
+        .select(SHIBBOLETH_USER_SELECT_COLUMNS)
+        .single();
+
+    if (error) {
+        throw new Error(`Failed to create Shibboleth user: ${error.message}`);
+    }
+
+    return data as unknown as UserRowWithShibbolethColumns;
+}
+
+/**
+ * Updates Shibboleth profile columns on an existing user row.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+async function updateLinkedShibbolethUser(
+    user: UserRowWithShibbolethColumns,
+    profileAttributes: ShibbolethProfileAttributes,
+    now: string,
+): Promise<UserRowWithShibbolethColumns> {
+    const supabase = $provideSupabaseForServer();
+    const nextAuthenticationProvider =
+        user.authenticationProvider === LOCAL_AUTHENTICATION_PROVIDER || !user.authenticationProvider
+            ? LOCAL_AND_SHIBBOLETH_AUTHENTICATION_PROVIDER
+            : user.authenticationProvider;
+    const userUpdate: UserUpdateWithShibbolethColumns = {
+        email: profileAttributes.email,
+        displayName: profileAttributes.displayName,
+        authenticationProvider: nextAuthenticationProvider,
+        updatedAt: now,
+    };
+    const { data, error } = await supabase
+        .from(await $getTableName('User'))
+        .update(userUpdate)
+        .eq('id', user.id)
+        .select(SHIBBOLETH_USER_SELECT_COLUMNS)
+        .single();
+
+    if (error) {
+        throw new Error(`Failed to update Shibboleth user: ${error.message}`);
+    }
+
+    return data as unknown as UserRowWithShibbolethColumns;
+}
+
+/**
+ * Creates or updates the Shibboleth identity link.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+async function upsertShibbolethIdentity(
+    user: UserRowWithShibbolethColumns,
+    profileAttributes: ShibbolethProfileAttributes,
+    existingIdentity: ShibbolethUserIdentityRow | null,
+    now: string,
+): Promise<void> {
+    const supabase = $provideSupabaseForServer();
+    const tableName = await getShibbolethUserIdentityTableName();
+    const identityPayload = {
+        userId: user.id,
+        email: profileAttributes.email,
+        displayName: profileAttributes.displayName,
+        nameId: profileAttributes.nameId,
+        nameIdFormat: profileAttributes.nameIdFormat,
+        unstructuredName: profileAttributes.unstructuredName,
+        eduPersonPrincipalName: profileAttributes.eduPersonPrincipalName,
+        rawAttributes: profileAttributes.rawAttributes,
+        lastLoggedInAt: now,
+        loginCount: Number(existingIdentity?.loginCount || 0) + 1,
+        updatedAt: now,
+    };
+
+    if (existingIdentity) {
+        const { error } = await supabase
+            .from(tableName)
+            .update(identityPayload as never)
+            .eq('id' as never, existingIdentity.id as never);
+        if (error) {
+            throw new Error(`Failed to update Shibboleth identity: ${error.message}`);
+        }
+        return;
+    }
+
+    const { error } = await supabase.from(tableName).insert({
+        ...identityPayload,
+        createdAt: now,
+    } as never);
+
+    if (error) {
+        throw new Error(`Failed to create Shibboleth identity: ${error.message}`);
+    }
+}

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

@@ -0,0 +1,13 @@
+import { $provideServer } from '@/src/tools/$provideServer';
+
+/**
+ * Resolves the prefixed Shibboleth authentication attempt table name without relying on generated schema typings.
+ *
+ * @returns Prefixed table name.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export async function getShibbolethAuthenticationAttemptTableName(): Promise<string> {
+    const { tablePrefix } = await $provideServer();
+    return `${tablePrefix}ShibbolethAuthenticationAttempt`;
+}

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

@@ -0,0 +1,19 @@
+import type { ShibbolethRequestDetails } from './shibbolethAuthenticationTypes';
+
+/**
+ * Extracts audit metadata from an incoming request.
+ *
+ * @param request - Incoming route-handler request.
+ * @returns Request details safe to store in the Shibboleth audit log.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export function getShibbolethRequestDetails(request: Request): ShibbolethRequestDetails {
+    const forwardedFor = request.headers.get('x-forwarded-for');
+    const ip = forwardedFor?.split(',')[0]?.trim() || request.headers.get('x-real-ip') || null;
+
+    return {
+        ip,
+        userAgent: request.headers.get('user-agent'),
+    };
+}

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

@@ -0,0 +1,13 @@
+import { $provideServer } from '@/src/tools/$provideServer';
+
+/**
+ * Resolves the prefixed Shibboleth identity table name without relying on generated schema typings.
+ *
+ * @returns Prefixed table name.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export async function getShibbolethUserIdentityTableName(): Promise<string> {
+    const { tablePrefix } = await $provideServer();
+    return `${tablePrefix}ShibbolethUserIdentity`;
+}