@promptbook/cli 0.112.0-101 → 0.112.0-103

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

@@ -1,841 +1,949 @@
-import { randomBytes } from 'crypto';
-import {
-    SAML,
-    ValidateInResponseTo,
-    generateServiceProviderMetadata,
-    type CacheItem,
-    type CacheProvider,
-    type Profile,
-} from '@node-saml/node-saml';
-import { XMLParser } from 'fast-xml-parser';
-import { spaceTrim } from 'spacetrim';
-import { AUTHENTICATION_METHODS_METADATA_KEY, isAuthenticationMethodEnabled } from '../constants/authenticationMethods';
-import {
-    DEFAULT_SHIBBOLETH_PROVIDER_LABEL,
-    DEFAULT_SHIBBOLETH_USERNAME_ATTRIBUTE,
-    SHIBBOLETH_AUTHENTICATION_METADATA_KEYS,
-    SHIBBOLETH_AUTO_CREATE_USERS_METADATA_KEY,
-    SHIBBOLETH_CALLBACK_PATH,
-    SHIBBOLETH_CALLBACK_URL_METADATA_KEY,
-    SHIBBOLETH_ENTITY_ID_METADATA_KEY,
-    SHIBBOLETH_IDP_CERTIFICATE_METADATA_KEY,
-    SHIBBOLETH_IDP_ENTRYPOINT_METADATA_KEY,
-    SHIBBOLETH_IDP_ISSUER_METADATA_KEY,
-    SHIBBOLETH_IDP_METADATA_URL_METADATA_KEY,
-    SHIBBOLETH_PROVIDER_LABEL_METADATA_KEY,
-    SHIBBOLETH_SP_METADATA_PATH,
-    SHIBBOLETH_USERNAME_ATTRIBUTE_METADATA_KEY,
-} from '../constants/shibbolethAuthentication';
+import { SAML, ValidateInResponseTo, generateServiceProviderMetadata, type Profile } from '@node-saml/node-saml';
+import { DOMParser } from '@xmldom/xmldom';
 import { $getTableName } from '../database/$getTableName';
 import { $provideSupabaseForServer } from '../database/$provideSupabaseForServer';
+import type { AgentsServerDatabase, Json } from '../database/schema';
 import { getMetadataMap } from '../database/getMetadata';
-import type { AgentsServerDatabase } from '../database/schema';
-import { hashPassword } from './auth';
+import { $provideServer } from '../tools/$provideServer';
+import {
+    DEFAULT_SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES,
+    DEFAULT_SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES,
+    DEFAULT_SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES,
+    IS_SHIBBOLETH_AUTH_ACTIVE_METADATA_KEY,
+    SHIBBOLETH_AUTHENTICATION_METADATA_KEYS,
+    SHIBBOLETH_DISPLAY_NAME_ATTRIBUTE_NAMES_METADATA_KEY,
+    SHIBBOLETH_EMAIL_ATTRIBUTE_NAMES_METADATA_KEY,
+    SHIBBOLETH_IDENTITY_PROVIDER_METADATA_URL_METADATA_KEY,
+    SHIBBOLETH_IDENTITY_PROVIDER_METADATA_XML_METADATA_KEY,
+    SHIBBOLETH_SERVICE_PROVIDER_ENTITY_ID_METADATA_KEY,
+    SHIBBOLETH_UNSTRUCTURED_NAME_ATTRIBUTE_NAMES_METADATA_KEY,
+    parseShibbolethBooleanMetadata,
+} from '../constants/shibbolethAuth';
 
 /**
- * Maximum time SAML request identifiers are retained for InResponseTo validation.
+ * Persistent NameID format recommended for Shibboleth integrations.
  */
-const SHIBBOLETH_REQUEST_ID_EXPIRATION_PERIOD_MS = 8 * 60 * 60 * 1000;
+const SHIBBOLETH_PERSISTENT_NAME_ID_FORMAT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent';
 
 /**
- * Clock skew accepted while validating Shibboleth assertion validity timestamps.
+ * SAML HTTP Redirect binding URL.
  */
-const SHIBBOLETH_ACCEPTED_CLOCK_SKEW_MS = 60 * 1000;
+const SAML_HTTP_REDIRECT_BINDING = 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect';
 
 /**
- * SAML NameID format requested from Shibboleth.
+ * Timeout for loading remote Identity Provider metadata.
  */
-const SHIBBOLETH_IDENTIFIER_FORMAT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent';
+const SHIBBOLETH_IDENTITY_PROVIDER_METADATA_TIMEOUT_MS = 10_000;
 
 /**
- * Metadata fetch timeout used when loading Shibboleth IdP metadata.
+ * Clock skew accepted when validating SAML assertion timestamps.
  */
-const SHIBBOLETH_METADATA_FETCH_TIMEOUT_MS = 10 * 1000;
+const SHIBBOLETH_ACCEPTED_CLOCK_SKEW_MS = 120_000;
 
 /**
- * XML parser used for Shibboleth IdP metadata.
+ * Placeholder password hash for database users that can only sign in via Shibboleth.
  */
-const SHIBBOLETH_METADATA_XML_PARSER = new XMLParser({
-    attributeNamePrefix: '@_',
-    ignoreAttributes: false,
-    removeNSPrefix: true,
-    trimValues: true,
-});
+const SHIBBOLETH_PASSWORDLESS_USER_PASSWORD_HASH = 'shibboleth-passwordless-user';
 
 /**
- * Process-local cache used by node-saml for InResponseTo validation.
+ * Marker stored on database users that authenticate with username/password only.
  */
-const SHIBBOLETH_REQUEST_ID_CACHE = new Map<string, CacheItem>();
+const LOCAL_AUTHENTICATION_PROVIDER = 'LOCAL';
 
 /**
- * Cache provider shared across SAML instances so the login route and ACS route
- * can validate the same AuthnRequest IDs.
+ * Marker stored on database users that authenticate with Shibboleth only.
  */
-const SHIBBOLETH_REQUEST_ID_CACHE_PROVIDER: CacheProvider = {
-    async saveAsync(key, value) {
-        pruneExpiredShibbolethRequestIds();
-        const cacheItem = { value, createdAt: Date.now() };
-        SHIBBOLETH_REQUEST_ID_CACHE.set(key, cacheItem);
-        return cacheItem;
-    },
-    async getAsync(key) {
-        pruneExpiredShibbolethRequestIds();
-        return SHIBBOLETH_REQUEST_ID_CACHE.get(key)?.value ?? null;
-    },
-    async removeAsync(key) {
-        if (!key) {
-            return null;
-        }
+const SHIBBOLETH_AUTHENTICATION_PROVIDER = 'SHIBBOLETH';
 
-        const value = SHIBBOLETH_REQUEST_ID_CACHE.get(key)?.value ?? null;
-        SHIBBOLETH_REQUEST_ID_CACHE.delete(key);
-        return value;
-    },
+/**
+ * Marker stored on database users that authenticate with username/password and Shibboleth.
+ */
+const LOCAL_AND_SHIBBOLETH_AUTHENTICATION_PROVIDER = 'LOCAL_AND_SHIBBOLETH';
+
+/**
+ * User table row with Shibboleth profile columns added by migration.
+ */
+type UserRowWithShibbolethColumns = AgentsServerDatabase['public']['Tables']['User']['Row'] & {
+    readonly email?: string | null;
+    readonly displayName?: string | null;
+    readonly authenticationProvider?: string | null;
 };
 
 /**
- * Parsed Shibboleth IdP metadata fields used by SAML configuration.
+ * User insert shape with Shibboleth profile columns added by migration.
+ */
+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.
+ */
+type UserUpdateWithShibbolethColumns = AgentsServerDatabase['public']['Tables']['User']['Update'] & {
+    readonly email?: string | null;
+    readonly displayName?: string | null;
+    readonly authenticationProvider?: string | null;
+};
+
+/**
+ * Prefixed Shibboleth identity row.
+ *
+ * @private internal Shibboleth authentication record
+ */
+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 internal Shibboleth authentication record
+ */
+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.
  *
- * @public exported from `apps/agents-server`
+ * @private internal Shibboleth authentication record
  */
-export type ShibbolethIdentityProviderMetadata = {
-    /**
-     * Identity Provider entity ID.
-     */
-    readonly entityId: string | null;
-    /**
-     * Preferred HTTP-Redirect SSO endpoint.
-     */
-    readonly entryPoint: string | null;
-    /**
-     * Signing certificates exposed by the Identity Provider metadata.
-     */
-    readonly certificates: ReadonlyArray<string>;
+export type ShibbolethRequestDetails = {
+    readonly ip: string | null;
+    readonly userAgent: string | null;
 };
 
 /**
- * Enabled and fully configured Shibboleth authentication settings.
+ * Parsed Shibboleth user attributes extracted from SAML profile data.
  *
- * @public exported from `apps/agents-server`
- */
-export type EnabledShibbolethConfiguration = {
-    /**
-     * Whether Shibboleth is enabled by metadata.
-     */
-    readonly isEnabled: true;
-    /**
-     * Whether the enabled method has all required IdP settings.
-     */
-    readonly isConfigured: true;
-    /**
-     * User-facing provider label.
-     */
-    readonly providerLabel: string;
-    /**
-     * SAML Service Provider entity ID.
-     */
-    readonly issuer: string;
-    /**
-     * SAML Assertion Consumer Service URL.
-     */
-    readonly callbackUrl: string;
-    /**
-     * Shibboleth IdP SSO URL.
-     */
-    readonly entryPoint: string;
-    /**
-     * Shibboleth IdP signing certificates.
-     */
-    readonly idpCertificates: ReadonlyArray<string>;
-    /**
-     * Expected Shibboleth IdP entity ID, when known.
-     */
-    readonly idpIssuer: string | null;
-    /**
-     * SAML profile attribute used as Agents Server username.
-     */
-    readonly usernameAttribute: string;
-    /**
-     * Whether unknown Shibboleth users are created automatically.
-     */
-    readonly isAutoCreateUsers: boolean;
+ * @private internal Shibboleth authentication record
+ */
+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;
 };
 
 /**
- * Disabled or incomplete Shibboleth authentication settings.
+ * Service Provider URLs derived for the current request.
  *
- * @public exported from `apps/agents-server`
- */
-export type InactiveShibbolethConfiguration = {
-    /**
-     * Whether Shibboleth is enabled by metadata.
-     */
-    readonly isEnabled: boolean;
-    /**
-     * Whether the enabled method has all required IdP settings.
-     */
-    readonly isConfigured: false;
-    /**
-     * User-facing provider label.
-     */
-    readonly providerLabel: string;
-    /**
-     * SAML Service Provider entity ID, if resolvable.
-     */
-    readonly issuer: string | null;
-    /**
-     * SAML Assertion Consumer Service URL, if resolvable.
-     */
-    readonly callbackUrl: string | null;
-    /**
-     * Missing metadata keys or derived settings.
-     */
-    readonly missingConfiguration: ReadonlyArray<string>;
+ * @private internal Shibboleth authentication configuration
+ */
+export type ShibbolethServiceProviderUrls = {
+    readonly origin: string;
+    readonly entityId: string;
+    readonly assertionConsumerServiceUrl: string;
+    readonly metadataUrl: string;
 };
 
 /**
- * Resolved Shibboleth authentication settings.
+ * Parsed Identity Provider metadata needed by Node-SAML.
  *
- * @public exported from `apps/agents-server`
+ * @private internal Shibboleth authentication configuration
  */
-export type ShibbolethConfiguration = EnabledShibbolethConfiguration | InactiveShibbolethConfiguration;
+export type ShibbolethIdentityProviderMetadata = {
+    readonly singleSignOnServiceUrl: string;
+    readonly signingCertificates: ReadonlyArray<string>;
+};
 
 /**
- * Result of resolving a Shibboleth profile into a local Agents Server user.
+ * Resolved Shibboleth authentication configuration status.
  *
- * @public exported from `apps/agents-server`
- */
-export type ShibbolethUserResolution = {
-    /**
-     * Local Agents Server username.
-     */
-    readonly username: string;
-    /**
-     * Whether the local user has admin privileges.
-     */
-    readonly isAdmin: boolean;
-    /**
-     * Whether a new local user row was created for this Shibboleth login.
-     */
-    readonly isNewUser: boolean;
+ * @private internal Shibboleth authentication configuration
+ */
+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;
+};
+
+/**
+ * Options for resolving Shibboleth authentication configuration.
+ */
+type ResolveShibbolethAuthenticationConfigurationOptions = {
+    readonly requestUrl: string;
+    readonly isIdentityProviderMetadataValidationEnabled?: boolean;
+};
+
+/**
+ * Options for recording a Shibboleth authentication attempt.
+ */
+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;
 };
 
 /**
- * Error thrown when Shibboleth metadata is enabled but incomplete.
+ * Result of linking a SAML profile to an Agents Server user.
+ */
+type LinkedShibbolethUser = {
+    readonly user: UserRowWithShibbolethColumns;
+    readonly profileAttributes: ShibbolethProfileAttributes;
+};
+
+/**
+ * Minimal XML node shape used to avoid mixing browser DOM and xmldom typings.
+ */
+type XmlNodeWithElements = {
+    readonly getElementsByTagName: (tagName: string) => ArrayLike<XmlElementWithAttributes>;
+};
+
+/**
+ * Minimal XML element shape used by the Shibboleth metadata parser.
+ */
+type XmlElementWithAttributes = XmlNodeWithElements & {
+    readonly localName?: string | null;
+    readonly nodeName: string;
+    readonly textContent?: string | null;
+    readonly getAttribute: (attributeName: string) => string | null;
+};
+
+/**
+ * Returns a safe relative URL to redirect to after Shibboleth finishes.
  *
- * @public exported from `apps/agents-server`
- */
-export class ShibbolethConfigurationError extends Error {
-    /**
-     * Missing metadata keys or derived settings.
-     */
-    public readonly missingConfiguration: ReadonlyArray<string>;
-
-    /**
-     * Creates a Shibboleth configuration error.
-     *
-     * @param missingConfiguration - Missing metadata keys or derived settings.
-     */
-    public constructor(missingConfiguration: ReadonlyArray<string>) {
-        super(
-            spaceTrim(`
-                Shibboleth authentication is enabled, but its configuration is incomplete.
-
-                Missing configuration: \`${missingConfiguration.join('`, `')}\`
-            `),
-        );
-        this.name = 'ShibbolethConfigurationError';
-        this.missingConfiguration = missingConfiguration;
+ * @param relayState - Raw RelayState value from the request or SAML response.
+ * @returns Safe relative URL.
+ *
+ * @private internal Shibboleth authentication helper
+ */
+export function sanitizeShibbolethRelayState(relayState: string | null | undefined): string {
+    const trimmedRelayState = (relayState || '').trim();
+
+    if (!trimmedRelayState || !trimmedRelayState.startsWith('/') || trimmedRelayState.startsWith('//')) {
+        return '/';
     }
+
+    return trimmedRelayState;
 }
 
 /**
- * Loads Shibboleth configuration from Agents Server metadata.
+ * Extracts audit metadata from an incoming request.
  *
- * @param request - Incoming request used to derive default public URLs.
- * @returns Resolved Shibboleth configuration.
+ * @param request - Incoming route-handler request.
+ * @returns Request details safe to store in the Shibboleth audit log.
  *
- * @public exported from `apps/agents-server`
- */
-export async function loadShibbolethConfiguration(request?: Request): Promise<ShibbolethConfiguration> {
-    const metadata = await getMetadataMap([
-        AUTHENTICATION_METHODS_METADATA_KEY,
-        ...SHIBBOLETH_AUTHENTICATION_METADATA_KEYS,
-    ]);
-    const providerLabel = metadata[SHIBBOLETH_PROVIDER_LABEL_METADATA_KEY]?.trim() || DEFAULT_SHIBBOLETH_PROVIDER_LABEL;
-    const publicBaseUrl = resolveShibbolethPublicBaseUrl(request);
-    const issuer =
-        metadata[SHIBBOLETH_ENTITY_ID_METADATA_KEY]?.trim() ||
-        (publicBaseUrl ? `${publicBaseUrl}${SHIBBOLETH_SP_METADATA_PATH}` : null);
-    const callbackUrl =
-        metadata[SHIBBOLETH_CALLBACK_URL_METADATA_KEY]?.trim() ||
-        (publicBaseUrl ? `${publicBaseUrl}${SHIBBOLETH_CALLBACK_PATH}` : null);
-    const isEnabled = isAuthenticationMethodEnabled(metadata[AUTHENTICATION_METHODS_METADATA_KEY], 'SHIBBOLETH');
-
-    if (!isEnabled) {
-        return {
-            isEnabled: false,
-            isConfigured: false,
-            providerLabel,
-            issuer,
-            callbackUrl,
-            missingConfiguration: [],
-        };
-    }
+ * @private internal Shibboleth authentication helper
+ */
+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;
 
-    const identityProviderMetadata = await loadShibbolethIdentityProviderMetadata(
-        metadata[SHIBBOLETH_IDP_METADATA_URL_METADATA_KEY],
-    );
-    const entryPoint =
-        metadata[SHIBBOLETH_IDP_ENTRYPOINT_METADATA_KEY]?.trim() || identityProviderMetadata.entryPoint || null;
-    const idpCertificates = parseShibbolethCertificates(metadata[SHIBBOLETH_IDP_CERTIFICATE_METADATA_KEY]);
-    const resolvedIdpCertificates =
-        idpCertificates.length > 0 ? idpCertificates : identityProviderMetadata.certificates;
-    const idpIssuer = metadata[SHIBBOLETH_IDP_ISSUER_METADATA_KEY]?.trim() || identityProviderMetadata.entityId || null;
-    const usernameAttribute =
-        metadata[SHIBBOLETH_USERNAME_ATTRIBUTE_METADATA_KEY]?.trim() || DEFAULT_SHIBBOLETH_USERNAME_ATTRIBUTE;
-    const isAutoCreateUsers = (metadata[SHIBBOLETH_AUTO_CREATE_USERS_METADATA_KEY] ?? 'true') !== 'false';
-    const missingConfiguration = [
-        issuer ? null : SHIBBOLETH_ENTITY_ID_METADATA_KEY,
-        callbackUrl ? null : SHIBBOLETH_CALLBACK_URL_METADATA_KEY,
-        entryPoint ? null : SHIBBOLETH_IDP_ENTRYPOINT_METADATA_KEY,
-        resolvedIdpCertificates.length > 0 ? null : SHIBBOLETH_IDP_CERTIFICATE_METADATA_KEY,
-    ].filter((value): value is string => value !== null);
+    return {
+        ip,
+        userAgent: request.headers.get('user-agent'),
+    };
+}
+
+/**
+ * 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 internal Shibboleth authentication helper
+ */
+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 (
-        missingConfiguration.length > 0 ||
-        !issuer ||
-        !callbackUrl ||
-        !entryPoint ||
-        resolvedIdpCertificates.length === 0
+        options.isIdentityProviderMetadataValidationEnabled === true &&
+        (identityProviderMetadataUrl || identityProviderMetadataXml)
     ) {
-        return {
-            isEnabled: true,
-            isConfigured: false,
-            providerLabel,
-            issuer,
-            callbackUrl,
-            missingConfiguration,
-        };
+        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 {
-        isEnabled: true,
-        isConfigured: true,
-        providerLabel,
-        issuer,
-        callbackUrl,
-        entryPoint,
-        idpCertificates: resolvedIdpCertificates,
-        idpIssuer,
-        usernameAttribute,
-        isAutoCreateUsers,
+        isActive,
+        isConfigured: errors.length === 0,
+        errors,
+        identityProviderMetadataUrl,
+        isIdentityProviderMetadataXmlConfigured: Boolean(identityProviderMetadataXml),
+        serviceProviderUrls,
+        identityProviderMetadata,
     };
 }
 
 /**
- * Builds a node-saml client from resolved Shibboleth configuration.
+ * Creates a Node-SAML client for the resolved Shibboleth configuration.
  *
- * @param configuration - Enabled Shibboleth configuration.
- * @returns Configured SAML client.
+ * @param configuration - Resolved Shibboleth configuration with parsed IdP metadata.
+ * @returns Configured Node-SAML client.
  *
- * @public exported from `apps/agents-server`
+ * @private internal Shibboleth authentication helper
  */
-export function createShibbolethSamlClient(configuration: EnabledShibbolethConfiguration): SAML {
+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,
-        callbackUrl: configuration.callbackUrl,
-        digestAlgorithm: 'sha256',
+        validateInResponseTo: ValidateInResponseTo.never,
         disableRequestedAuthnContext: true,
-        entryPoint: configuration.entryPoint,
-        identifierFormat: SHIBBOLETH_IDENTIFIER_FORMAT,
-        idpCert: [...configuration.idpCertificates],
-        idpIssuer: configuration.idpIssuer ?? undefined,
-        issuer: configuration.issuer,
-        requestIdExpirationPeriodMs: SHIBBOLETH_REQUEST_ID_EXPIRATION_PERIOD_MS,
         signatureAlgorithm: 'sha256',
-        validateInResponseTo: ValidateInResponseTo.always,
-        wantAssertionsSigned: true,
-        wantAuthnResponseSigned: false,
-        cacheProvider: SHIBBOLETH_REQUEST_ID_CACHE_PROVIDER,
     });
 }
 
 /**
- * Creates SAML Service Provider metadata XML for the configured server.
+ * Creates Service Provider metadata XML for the current Agents Server deployment.
  *
- * @param configuration - Shibboleth configuration with issuer and callback URL.
- * @returns SAML SP metadata XML.
+ * @param requestUrl - URL of the current metadata route request.
+ * @returns Service Provider metadata XML suitable for the Shibboleth IdP admin.
  *
- * @public exported from `apps/agents-server`
+ * @private internal Shibboleth authentication helper
  */
-export function createShibbolethServiceProviderMetadata(
-    configuration: Pick<EnabledShibbolethConfiguration, 'issuer' | 'callbackUrl'>,
-): string {
+export async function createShibbolethServiceProviderMetadataXml(requestUrl: string): Promise<string> {
+    const metadata = await getMetadataMap(SHIBBOLETH_AUTHENTICATION_METADATA_KEYS);
+    const serviceProviderUrls = resolveShibbolethServiceProviderUrls(requestUrl, metadata);
+
     return generateServiceProviderMetadata({
-        callbackUrl: configuration.callbackUrl,
-        identifierFormat: SHIBBOLETH_IDENTIFIER_FORMAT,
-        issuer: configuration.issuer,
+        issuer: serviceProviderUrls.entityId,
+        callbackUrl: serviceProviderUrls.assertionConsumerServiceUrl,
+        identifierFormat: SHIBBOLETH_PERSISTENT_NAME_ID_FORMAT,
         wantAssertionsSigned: true,
     });
 }
 
 /**
- * Resolves a valid local redirect path from SAML RelayState.
+ * Records one Shibboleth authentication attempt.
  *
- * @param relayState - Raw RelayState value.
- * @returns Safe local redirect path.
+ * @param options - Attempt details.
  *
- * @public exported from `apps/agents-server`
+ * @private internal Shibboleth authentication audit helper
  */
-export function resolveSafeShibbolethRelayState(relayState: string | null | undefined): string {
-    const trimmedRelayState = relayState?.trim() || '';
-
-    if (!trimmedRelayState || !trimmedRelayState.startsWith('/') || trimmedRelayState.startsWith('//')) {
-        return '/';
-    }
-
+export async function recordShibbolethAuthenticationAttempt(
+    options: RecordShibbolethAuthenticationAttemptOptions,
+): Promise<void> {
     try {
-        const parsedUrl = new URL(trimmedRelayState, 'https://promptbook.local');
-        return `${parsedUrl.pathname}${parsedUrl.search}${parsedUrl.hash}`;
-    } catch {
-        return '/';
+        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);
     }
 }
 
 /**
- * Resolves the local Agents Server user represented by a validated Shibboleth profile.
+ * Links a validated SAML profile to an Agents Server user, creating a passwordless user when needed.
  *
- * @param profile - Validated SAML profile.
- * @param configuration - Enabled Shibboleth configuration.
- * @returns Local user resolution.
+ * @param profile - Validated SAML profile from Node-SAML.
+ * @returns Linked database user and extracted Shibboleth attributes.
  *
- * @public exported from `apps/agents-server`
+ * @private internal Shibboleth authentication user helper
  */
-export async function resolveShibbolethUser(
-    profile: Profile,
-    configuration: Pick<EnabledShibbolethConfiguration, 'usernameAttribute' | 'isAutoCreateUsers'>,
-): Promise<ShibbolethUserResolution> {
-    const username = resolveShibbolethUsername(profile, configuration.usernameAttribute);
-
-    if (!username) {
-        throw new Error(
-            spaceTrim(`
-                Shibboleth profile does not contain a usable username.
-
-                Checked configured attribute \`${configuration.usernameAttribute}\` and common fallback attributes.
-            `),
-        );
-    }
+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;
 
-    const supabase = $provideSupabaseForServer();
-    const userTable = await $getTableName('User');
-    const { data: existingUser, error: existingUserError } = await supabase
-        .from(userTable)
-        .select('username, isAdmin')
-        .eq('username', username)
-        .maybeSingle<Pick<AgentsServerDatabase['public']['Tables']['User']['Row'], 'username' | 'isAdmin'>>();
-
-    if (existingUserError) {
-        throw new Error(`Failed to load Shibboleth user \`${username}\`: ${existingUserError.message}`);
+    if (!user) {
+        user = await findUserRowByEmail(profileAttributes.email);
     }
 
-    if (existingUser) {
-        return {
-            username: existingUser.username,
-            isAdmin: existingUser.isAdmin,
-            isNewUser: false,
-        };
+    if (!user) {
+        user = await findUserRowByUsername(profileAttributes.email);
     }
 
-    if (!configuration.isAutoCreateUsers) {
-        throw new Error(`Shibboleth user \`${username}\` does not exist and automatic user creation is disabled.`);
+    if (!user) {
+        user = await insertShibbolethUser(profileAttributes, now);
+    } else {
+        user = await updateLinkedShibbolethUser(user, profileAttributes, now);
     }
 
-    const passwordHash = await hashPassword(randomBytes(32).toString('hex'));
-    const { data: createdUser, error: createdUserError } = await supabase
-        .from(userTable)
-        .insert({
-            username,
-            passwordHash,
-            isAdmin: false,
-            createdAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString(),
-        })
-        .select('username, isAdmin')
-        .single<Pick<AgentsServerDatabase['public']['Tables']['User']['Row'], 'username' | 'isAdmin'>>();
-
-    if (createdUserError) {
-        throw new Error(`Failed to create Shibboleth user \`${username}\`: ${createdUserError.message}`);
-    }
+    await upsertShibbolethIdentity(user, profileAttributes, existingIdentity, now);
 
     return {
-        username: createdUser.username,
-        isAdmin: createdUser.isAdmin,
-        isNewUser: true,
+        user,
+        profileAttributes,
     };
 }
 
 /**
- * Logs one Shibboleth authentication event with consistent metadata.
+ * Resolves the prefixed Shibboleth identity table name without relying on generated schema typings.
  *
- * @param event - Event identifier.
- * @param details - Safe structured details.
+ * @returns Prefixed table name.
  *
- * @public exported from `apps/agents-server`
+ * @private internal Shibboleth authentication table helper
  */
-export function logShibbolethAuthenticationEvent(event: string, details: Record<string, unknown> = {}): void {
-    console.info('[agents-server:shibboleth]', {
-        event,
-        ...details,
-    });
+export async function getShibbolethUserIdentityTableName(): Promise<string> {
+    const { tablePrefix } = await $provideServer();
+    return `${tablePrefix}ShibbolethUserIdentity`;
 }
 
 /**
- * Extracts safe profile diagnostics for Shibboleth logging.
+ * Resolves the prefixed Shibboleth authentication attempt table name without relying on generated schema typings.
  *
- * @param profile - Validated SAML profile.
- * @param usernameAttribute - Configured username attribute.
- * @returns Safe diagnostic payload.
+ * @returns Prefixed table name.
  *
- * @public exported from `apps/agents-server`
+ * @private internal Shibboleth authentication table helper
  */
-export function createShibbolethProfileLogDetails(
+export async function getShibbolethAuthenticationAttemptTableName(): Promise<string> {
+    const { tablePrefix } = await $provideServer();
+    return `${tablePrefix}ShibbolethAuthenticationAttempt`;
+}
+
+/**
+ * Extracts required Shibboleth profile attributes from a validated SAML profile.
+ */
+function extractShibbolethProfileAttributes(
     profile: Profile,
-    usernameAttribute: string,
-): Record<string, unknown> {
+    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 {
-        issuer: profile.issuer,
-        nameIDFormat: profile.nameIDFormat,
-        configuredUsernameAttribute: usernameAttribute,
-        availableAttributes: Object.keys(profile)
-            .filter((key) => !['getAssertion', 'getAssertionXml', 'getSamlResponseXml'].includes(key))
-            .sort(),
+        email,
+        displayName,
+        nameId: getStringOrNull(profile.nameID),
+        nameIdFormat: getStringOrNull(profile.nameIDFormat),
+        unstructuredName,
+        eduPersonPrincipalName,
+        rawAttributes,
     };
 }
 
 /**
- * Parses Shibboleth IdP metadata XML.
- *
- * @param xml - Raw IdP metadata XML.
- * @returns Parsed metadata fields.
- *
- * @public exported from `apps/agents-server`
+ * Resolves SP URLs from request URL, environment, and metadata.
  */
-export function parseShibbolethIdentityProviderMetadata(xml: string): ShibbolethIdentityProviderMetadata {
-    const parsedXml = SHIBBOLETH_METADATA_XML_PARSER.parse(xml) as unknown;
+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 origin = configuredSiteUrl ? new URL(configuredSiteUrl).origin : requestOrigin;
+    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 {
-        entityId: findFirstAttribute(parsedXml, 'entityID'),
-        entryPoint: findPreferredSingleSignOnServiceLocation(parsedXml),
-        certificates: findAllValuesByKey(parsedXml, 'X509Certificate').map(formatShibbolethCertificate),
+        origin,
+        entityId: configuredEntityId || metadataUrl,
+        assertionConsumerServiceUrl,
+        metadataUrl,
     };
 }
 
 /**
- * Resolves the public base URL used for Shibboleth defaults.
- *
- * @param request - Incoming request.
- * @returns Public base URL without a trailing slash.
- *
- * @public exported from `apps/agents-server`
+ * Loads remote IdP metadata XML.
  */
-export function resolveShibbolethPublicBaseUrl(request?: Request): string | null {
-    const configuredSiteUrl = normalizeShibbolethUrl(process.env.NEXT_PUBLIC_SITE_URL);
-    if (configuredSiteUrl) {
-        return configuredSiteUrl;
+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}.`,
+        );
     }
 
-    if (!request) {
-        return null;
+    return response.text();
+}
+
+/**
+ * Parses IdP metadata XML into the fields needed for SAML login.
+ */
+function parseIdentityProviderMetadataXml(metadataXml: string): ShibbolethIdentityProviderMetadata {
+    const document = new DOMParser().parseFromString(metadataXml, 'application/xml') as unknown as XmlNodeWithElements;
+    const singleSignOnServices = getElementsByLocalName(document, 'SingleSignOnService');
+    const redirectSingleSignOnService =
+        singleSignOnServices.find((element) => element.getAttribute('Binding') === SAML_HTTP_REDIRECT_BINDING) ||
+        singleSignOnServices[0];
+    const singleSignOnServiceUrl = redirectSingleSignOnService?.getAttribute('Location') || '';
+    const signingCertificates = getSigningCertificates(document);
+
+    if (!singleSignOnServiceUrl) {
+        throw new Error('Shibboleth Identity Provider metadata is missing SingleSignOnService Location.');
     }
 
-    const host = request.headers.get('x-forwarded-host') || request.headers.get('host');
-    if (!host) {
-        return null;
+    if (signingCertificates.length === 0) {
+        throw new Error('Shibboleth Identity Provider metadata is missing a signing certificate.');
     }
 
-    const protocol = (request.headers.get('x-forwarded-proto') || 'https').split(',')[0]?.trim() || 'https';
-    return normalizeShibbolethUrl(`${protocol}://${host}`);
+    return {
+        singleSignOnServiceUrl,
+        signingCertificates,
+    };
 }
 
 /**
- * Loads and parses remote Shibboleth IdP metadata.
- *
- * @param metadataUrl - Raw metadata URL.
- * @returns Parsed metadata or an empty fallback.
- */
-async function loadShibbolethIdentityProviderMetadata(
-    metadataUrl: string | null | undefined,
-): Promise<ShibbolethIdentityProviderMetadata> {
-    const normalizedMetadataUrl = normalizeShibbolethUrl(metadataUrl);
-    if (!normalizedMetadataUrl) {
-        return {
-            entityId: null,
-            entryPoint: null,
-            certificates: [],
-        };
-    }
+ * Finds all XML elements with the given local name.
+ */
+function getElementsByLocalName(root: XmlNodeWithElements, localName: string): Array<XmlElementWithAttributes> {
+    return Array.from(root.getElementsByTagName('*')).filter(
+        (element) =>
+            element.localName === localName ||
+            element.nodeName === localName ||
+            element.nodeName.endsWith(`:${localName}`),
+    );
+}
 
-    try {
-        const response = await fetch(normalizedMetadataUrl, {
-            signal: AbortSignal.timeout(SHIBBOLETH_METADATA_FETCH_TIMEOUT_MS),
-        });
-
-        if (!response.ok) {
-            logShibbolethAuthenticationEvent('idp_metadata_fetch_failed', {
-                metadataUrl: normalizedMetadataUrl,
-                status: response.status,
-            });
-            return {
-                entityId: null,
-                entryPoint: null,
-                certificates: [],
-            };
-        }
+/**
+ * Extracts signing certificates from IdP metadata XML.
+ */
+function getSigningCertificates(document: XmlNodeWithElements): string[] {
+    const signingKeyDescriptors = getElementsByLocalName(document, 'KeyDescriptor').filter((element) => {
+        const use = element.getAttribute('use');
+        return !use || use === 'signing';
+    });
+    const certificateElements = signingKeyDescriptors.flatMap((element) =>
+        getElementsByLocalName(element, 'X509Certificate'),
+    );
+    const fallbackCertificateElements =
+        certificateElements.length > 0 ? certificateElements : getElementsByLocalName(document, 'X509Certificate');
+
+    return Array.from(
+        new Set(
+            fallbackCertificateElements
+                .map((element) => formatPemCertificate(element.textContent || ''))
+                .filter(Boolean),
+        ),
+    );
+}
 
-        return parseShibbolethIdentityProviderMetadata(await response.text());
-    } catch (error) {
-        logShibbolethAuthenticationEvent('idp_metadata_fetch_error', {
-            metadataUrl: normalizedMetadataUrl,
-            error: error instanceof Error ? error.message : String(error),
-        });
-        return {
-            entityId: null,
-            entryPoint: null,
-            certificates: [],
-        };
+/**
+ * Formats an XML X.509 certificate value as PEM.
+ */
+function formatPemCertificate(certificate: string): string {
+    const base64Certificate = certificate
+        .replace(/-----BEGIN CERTIFICATE-----/gu, '')
+        .replace(/-----END CERTIFICATE-----/gu, '')
+        .replace(/\s+/gu, '');
+
+    if (!base64Certificate) {
+        return '';
     }
+
+    const wrappedCertificate = base64Certificate.match(/.{1,64}/gu)?.join('\n') || base64Certificate;
+    return `-----BEGIN CERTIFICATE-----\n${wrappedCertificate}\n-----END CERTIFICATE-----`;
 }
 
 /**
- * Parses one metadata field containing one or more certificates.
- *
- * @param value - Raw certificate metadata.
- * @returns Normalized certificates.
+ * Finds the first non-empty profile attribute from a list of accepted names.
  */
-function parseShibbolethCertificates(value: string | null | undefined): ReadonlyArray<string> {
-    const trimmedValue = value?.trim() || '';
-    if (!trimmedValue) {
-        return [];
+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;
+        }
     }
 
-    const pemMatches = trimmedValue.match(/-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/gu);
-    if (pemMatches && pemMatches.length > 0) {
-        return pemMatches.map(formatShibbolethCertificate);
-    }
+    return null;
+}
 
-    return trimmedValue
-        .split(/\n\s*\n/u)
-        .map(formatShibbolethCertificate)
+/**
+ * Parses metadata-defined attribute names.
+ */
+function parseAttributeNames(value: string | null | undefined, fallback: string): string[] {
+    return (value || fallback)
+        .split(/[\s,]+/u)
+        .map((attributeName) => attributeName.trim())
         .filter(Boolean);
 }
 
 /**
- * Normalizes a certificate to PEM form.
- *
- * @param certificate - Raw certificate value.
- * @returns PEM certificate.
+ * Converts a profile value into one string.
  */
-function formatShibbolethCertificate(certificate: string): string {
-    const trimmedCertificate = certificate.trim().replace(/\\n/gu, '\n');
-    if (trimmedCertificate.includes('-----BEGIN CERTIFICATE-----')) {
-        return trimmedCertificate;
+function getFirstStringValue(value: unknown): string | null {
+    if (typeof value === 'string') {
+        return value.trim() || null;
     }
 
-    const compactCertificate = trimmedCertificate.replace(/[\s\r\n]+/gu, '');
-    const lines = compactCertificate.match(/.{1,64}/gu) || [];
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const stringValue = getFirstStringValue(item);
+            if (stringValue) {
+                return stringValue;
+            }
+        }
+    }
 
-    return ['-----BEGIN CERTIFICATE-----', ...lines, '-----END CERTIFICATE-----'].join('\n');
+    return null;
 }
 
 /**
- * Resolves the local username from a validated SAML profile.
- *
- * @param profile - Validated SAML profile.
- * @param usernameAttribute - Configured username attribute.
- * @returns Local username or `null`.
- */
-function resolveShibbolethUsername(profile: Profile, usernameAttribute: string): string | null {
-    const rawUsername =
-        pickProfileAttribute(profile, usernameAttribute) ||
-        pickProfileAttribute(profile, 'mail') ||
-        pickProfileAttribute(profile, 'email') ||
-        pickProfileAttribute(profile, 'urn:oid:0.9.2342.19200300.100.1.3') ||
-        pickProfileAttribute(profile, 'eduPersonPrincipalName') ||
-        pickProfileAttribute(profile, 'unstructuredName') ||
-        profile.nameID;
-
-    const normalizedUsername = rawUsername.trim();
-    if (!normalizedUsername) {
-        return null;
+ * Converts an unknown value into a string or null.
+ */
+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.
+ */
+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 normalizedUsername.includes('@') ? normalizedUsername.toLowerCase() : normalizedUsername;
+    return sanitizedAttributes;
 }
 
 /**
- * Reads the first string-like value of one SAML profile attribute.
- *
- * @param profile - Validated SAML profile.
- * @param attributeName - Attribute name.
- * @returns Attribute value or empty string.
+ * Converts unknown profile values into JSON-safe values.
  */
-function pickProfileAttribute(profile: Profile, attributeName: string): string {
-    const value = profile[attributeName];
-
-    if (typeof value === 'string') {
+function sanitizeJsonValue(value: unknown): Json | undefined {
+    if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
         return value;
     }
 
     if (Array.isArray(value)) {
-        const firstString = value.find((item): item is string => typeof item === 'string');
-        return firstString || '';
+        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 '';
+    return undefined;
 }
 
 /**
- * Finds the first XML attribute value with the given local name.
- *
- * @param value - Parsed XML subtree.
- * @param attributeName - Local attribute name.
- * @returns Attribute value or `null`.
+ * Finds one Shibboleth identity by persistent NameID.
  */
-function findFirstAttribute(value: unknown, attributeName: string): string | null {
-    if (!value || typeof value !== 'object') {
+async function findShibbolethIdentityByNameId(nameId: string | null): Promise<ShibbolethUserIdentityRow | null> {
+    if (!nameId) {
         return null;
     }
 
-    const record = value as Record<string, unknown>;
-    const directValue = record[`@_${attributeName}`];
-    if (typeof directValue === 'string' && directValue.trim()) {
-        return directValue.trim();
+    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}`);
     }
 
-    for (const childValue of Object.values(record)) {
-        const nestedValue = Array.isArray(childValue)
-            ? childValue.map((item) => findFirstAttribute(item, attributeName)).find(Boolean)
-            : findFirstAttribute(childValue, attributeName);
+    return (data as ShibbolethUserIdentityRow | null) || null;
+}
 
-        if (nestedValue) {
-            return nestedValue;
-        }
+/**
+ * Finds one Shibboleth identity by email.
+ */
+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 null;
+    return (data as ShibbolethUserIdentityRow | null) || null;
 }
 
 /**
- * Finds all parsed XML text values for a key name.
- *
- * @param value - Parsed XML subtree.
- * @param key - Local XML key name.
- * @returns Matching text values.
+ * Finds one user row by database id.
  */
-function findAllValuesByKey(value: unknown, key: string): string[] {
-    if (!value || typeof value !== 'object') {
-        return [];
+async function findUserRowById(userId: number): Promise<UserRowWithShibbolethColumns | null> {
+    const supabase = $provideSupabaseForServer();
+    const { data, error } = await supabase
+        .from(await $getTableName('User'))
+        .select('*')
+        .eq('id', userId)
+        .maybeSingle();
+
+    if (error) {
+        throw new Error(`Failed to resolve Shibboleth user by id: ${error.message}`);
     }
 
-    const record = value as Record<string, unknown>;
-    const directValue = record[key];
-    const directValues =
-        typeof directValue === 'string'
-            ? [directValue]
-            : Array.isArray(directValue)
-            ? directValue.filter((item): item is string => typeof item === 'string')
-            : [];
-
-    return [
-        ...directValues,
-        ...Object.entries(record)
-            .filter(([childKey]) => childKey !== key)
-            .flatMap(([, childValue]) =>
-                Array.isArray(childValue)
-                    ? childValue.flatMap((item) => findAllValuesByKey(item, key))
-                    : findAllValuesByKey(childValue, key),
-            ),
-    ];
+    return (data as UserRowWithShibbolethColumns | null) || null;
 }
 
 /**
- * Finds the preferred SAML SingleSignOnService location.
- *
- * @param value - Parsed XML subtree.
- * @returns Preferred SSO location.
+ * Finds one user row by email.
  */
-function findPreferredSingleSignOnServiceLocation(value: unknown): string | null {
-    const services = findAllObjectsByKey(value, 'SingleSignOnService');
-    const preferredService =
-        services.find((service) => String(service['@_Binding'] || '').includes('HTTP-Redirect')) || services[0];
-    const location = preferredService?.['@_Location'];
+async function findUserRowByEmail(email: string): Promise<UserRowWithShibbolethColumns | null> {
+    const supabase = $provideSupabaseForServer();
+    const { data, error } = await supabase
+        .from(await $getTableName('User'))
+        .select('*')
+        .eq('email' as never, email as never)
+        .maybeSingle();
+
+    if (error) {
+        throw new Error(`Failed to resolve Shibboleth user by email: ${error.message}`);
+    }
 
-    return typeof location === 'string' && location.trim() ? location.trim() : null;
+    return (data as UserRowWithShibbolethColumns | null) || null;
 }
 
 /**
- * Finds all parsed XML objects for a key name.
- *
- * @param value - Parsed XML subtree.
- * @param key - Local XML key name.
- * @returns Matching objects.
+ * Finds one user row by username.
  */
-function findAllObjectsByKey(value: unknown, key: string): Array<Record<string, unknown>> {
-    if (!value || typeof value !== 'object') {
-        return [];
+async function findUserRowByUsername(username: string): Promise<UserRowWithShibbolethColumns | null> {
+    const supabase = $provideSupabaseForServer();
+    const { data, error } = await supabase
+        .from(await $getTableName('User'))
+        .select('*')
+        .eq('username', username)
+        .maybeSingle();
+
+    if (error) {
+        throw new Error(`Failed to resolve Shibboleth user by username: ${error.message}`);
     }
 
-    const record = value as Record<string, unknown>;
-    const directValue = record[key];
-    const directObjects = Array.isArray(directValue)
-        ? directValue.filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === 'object')
-        : directValue && typeof directValue === 'object'
-        ? [directValue as Record<string, unknown>]
-        : [];
-
-    return [
-        ...directObjects,
-        ...Object.entries(record)
-            .filter(([childKey]) => childKey !== key)
-            .flatMap(([, childValue]) =>
-                Array.isArray(childValue)
-                    ? childValue.flatMap((item) => findAllObjectsByKey(item, key))
-                    : findAllObjectsByKey(childValue, key),
-            ),
-    ];
+    return (data as UserRowWithShibbolethColumns | null) || null;
 }
 
 /**
- * Normalizes a URL-like metadata value.
- *
- * @param value - Raw URL value.
- * @returns URL without trailing slash, or `null`.
+ * Inserts a new passwordless Shibboleth user.
  */
-function normalizeShibbolethUrl(value: string | null | undefined): string | null {
-    const trimmedValue = value?.trim() || '';
-    if (!trimmedValue) {
-        return null;
+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('*')
+        .single();
+
+    if (error) {
+        throw new Error(`Failed to create Shibboleth user: ${error.message}`);
     }
 
-    try {
-        const url = new URL(trimmedValue);
-        return url.toString().replace(/\/$/u, '');
-    } catch {
-        return null;
+    return data as UserRowWithShibbolethColumns;
+}
+
+/**
+ * Updates Shibboleth profile columns on an existing user row.
+ */
+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('*')
+        .single();
+
+    if (error) {
+        throw new Error(`Failed to update Shibboleth user: ${error.message}`);
     }
+
+    return data as UserRowWithShibbolethColumns;
 }
 
 /**
- * Removes expired SAML request IDs from the process-local cache.
+ * Creates or updates the Shibboleth identity link.
  */
-function pruneExpiredShibbolethRequestIds(): void {
-    const now = Date.now();
+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,
+    };
 
-    for (const [key, item] of SHIBBOLETH_REQUEST_ID_CACHE.entries()) {
-        if (now - item.createdAt > SHIBBOLETH_REQUEST_ID_EXPIRATION_PERIOD_MS) {
-            SHIBBOLETH_REQUEST_ID_CACHE.delete(key);
+    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}`);
     }
 }