Configuration System

/**
 * Main configuration object for MSAL applications
 */
type Configuration = {
  /** Authentication configuration (required) */
  auth: NodeAuthOptions;
  /** Broker configuration for native authentication */
  broker?: BrokerOptions;
  /** Cache configuration options */
  cache?: CacheOptions;
  /** System-level configuration */
  system?: NodeSystemOptions;
  /** Telemetry configuration */
  telemetry?: NodeTelemetryOptions;
};

import { PublicClientApplication, LogLevel } from "@azure/msal-node";

const config: Configuration = {
  auth: {
    clientId: "your-client-id",
    authority: "https://login.microsoftonline.com/common"
  },
  cache: {
    cachePlugin: // your cache plugin
  },
  system: {
    loggerOptions: {
      logLevel: LogLevel.Info,
      loggerCallback: (level, message) => console.log(message)
    },
    networkClient: // custom network client
  },
  telemetry: {
    application: {
      appName: "MyApp",
      appVersion: "1.0.0"
    }
  }
};

const pca = new PublicClientApplication(config);

/**
 * Authentication configuration options
 */
type NodeAuthOptions = {
  /** Application (client) ID from app registration */
  clientId: string;
  /** Authority URL - defaults to https://login.microsoftonline.com/common */
  authority?: string;
  /** Client secret for confidential client applications */
  clientSecret?: string;
  /** Client assertion JWT or callback function for certificate-based auth */
  clientAssertion?: string | ClientAssertionCallback;
  /** Client certificate configuration for certificate-based auth */
  clientCertificate?: {
    /** 
     * @deprecated Use thumbprintSha256 property instead
     * SHA-1 thumbprint for backwards compatibility with older ADFS versions
     */
    thumbprint?: string;
    /** SHA-256 thumbprint of the certificate (recommended) */
    thumbprintSha256?: string;
    /** PEM encoded private key */
    privateKey: string;
    /** X.509 certificate chain (optional) */
    x5c?: string;
  };
  /** Known authorities for B2C and ADFS scenarios */
  knownAuthorities?: Array<string>;
  /** Cloud discovery metadata for custom clouds */
  cloudDiscoveryMetadata?: string;
  /** Authority metadata for custom authorities */
  authorityMetadata?: string;
  /** Client capabilities for conditional access */
  clientCapabilities?: Array<string>;
  /** Protocol mode (AAD or OIDC) */
  protocolMode?: ProtocolMode;
  /** Azure cloud configuration options */
  azureCloudOptions?: AzureCloudOptions;
  /** Skip authority metadata cache for testing */
  skipAuthorityMetadataCache?: boolean;
  /** 
   * @deprecated This flag is deprecated and will be removed in the next major version
   * All extra query params will be encoded by default
   */
  encodeExtraQueryParams?: boolean;
};

/**
 * Callback function type for client assertions
 */
type ClientAssertionCallback = () => string;

/**
 * Protocol modes supported by MSAL
 */
enum ProtocolMode {
  /** Azure Active Directory protocol */
  AAD = "AAD",
  /** OpenID Connect protocol */
  OIDC = "OIDC"
}

// Basic public client configuration
const publicClientAuth: NodeAuthOptions = {
  clientId: "12345678-1234-1234-1234-123456789012",
  authority: "https://login.microsoftonline.com/common"
};

// Confidential client with client secret
const confidentialClientAuth: NodeAuthOptions = {
  clientId: "12345678-1234-1234-1234-123456789012",
  clientSecret: "your-client-secret",
  authority: "https://login.microsoftonline.com/your-tenant-id"
};

// Certificate-based authentication
const certificateAuth: NodeAuthOptions = {
  clientId: "12345678-1234-1234-1234-123456789012",
  clientCertificate: {
    thumbprintSha256: "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99",
    privateKey: `-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...
-----END PRIVATE KEY-----`,
    x5c: "base64-encoded-certificate-chain"
  },
  authority: "https://login.microsoftonline.com/your-tenant-id"
};

// Dynamic client assertion
const dynamicAssertionAuth: NodeAuthOptions = {
  clientId: "12345678-1234-1234-1234-123456789012",
  clientAssertion: () => {
    // Generate JWT assertion dynamically
    return generateJWTAssertion();
  },
  authority: "https://login.microsoftonline.com/your-tenant-id"
};

// B2C configuration
const b2cAuth: NodeAuthOptions = {
  clientId: "12345678-1234-1234-1234-123456789012",
  authority: "https://yourtenant.b2clogin.com/yourtenant.onmicrosoft.com/B2C_1_signupsignin1",
  knownAuthorities: ["yourtenant.b2clogin.com"],
  protocolMode: ProtocolMode.OIDC
};

/**
 * Azure cloud instance enumeration
 */
enum AzureCloudInstance {
  /** No specific cloud (use authority as-is) */
  None = "",
  /** Azure Public Cloud */
  AzurePublic = "https://login.microsoftonline.com",
  /** Azure US Government Cloud */
  AzurePpope = "https://login.microsoftonline.us",
  /** Azure China Cloud */
  AzureChina = "https://login.chinacloudapi.cn",
  /** Azure Germany Cloud */
  AzureGermany = "https://login.microsoftonline.de"
}

/**
 * Azure cloud configuration options
 */
type AzureCloudOptions = {
  /** Azure cloud instance */
  azureCloudInstance: AzureCloudInstance;
  /** Tenant ID or domain */
  tenant: string;
};

// Azure US Government configuration
const govCloudAuth: NodeAuthOptions = {
  clientId: "your-client-id",
  azureCloudOptions: {
    azureCloudInstance: AzureCloudInstance.AzurePpope,
    tenant: "your-tenant-id"
  }
};

// Azure China configuration
const chinaCloudAuth: NodeAuthOptions = {
  clientId: "your-client-id",
  azureCloudOptions: {
    azureCloudInstance: AzureCloudInstance.AzureChina,
    tenant: "your-tenant-id"
  }
};

/**
 * System configuration options
 */
type NodeSystemOptions = {
  /** Logger configuration */
  loggerOptions?: LoggerOptions;
  /** Custom network client implementation */
  networkClient?: INetworkModule;
  /** Proxy URL for network requests */
  proxyUrl?: string;
  /** Custom HTTP agent options */
  customAgentOptions?: http.AgentOptions | https.AgentOptions;
  /** Disable internal request retries */
  disableInternalRetries?: boolean;
};

/**
 * Logger configuration options
 */
type LoggerOptions = {
  /** Callback function for log messages */
  loggerCallback?: (level: LogLevel, message: string, containsPii: boolean) => void;
  /** Enable PII (personally identifiable information) logging */
  piiLoggingEnabled?: boolean;
  /** Minimum log level to output */
  logLevel?: LogLevel;
  /** Correlation ID for log correlation */
  correlationId?: string;
};

/**
 * Log levels
 */
enum LogLevel {
  Error = 0,
  Warning = 1,
  Info = 2,
  Verbose = 3,
  Trace = 4
}

/**
 * Network module interface for custom HTTP clients
 */
interface INetworkModule {
  /** Send HTTP request */
  sendGetRequestAsync<T>(
    url: string,
    options?: NetworkRequestOptions,
    cancellationToken?: number
  ): Promise<NetworkResponse<T>>;
  
  /** Send HTTP POST request */
  sendPostRequestAsync<T>(
    url: string,
    options?: NetworkRequestOptions
  ): Promise<NetworkResponse<T>>;
}

/**
 * Network request options
 */
type NetworkRequestOptions = {
  /** Request headers */
  headers?: Record<string, string>;
  /** Request body */
  body?: string;
  /** Request timeout in milliseconds */
  timeout?: number;
  /** Proxy URL */
  proxyUrl?: string;
};

/**
 * Network response structure
 */
type NetworkResponse<T> = {
  /** Response headers */
  headers: Record<string, string>;
  /** Response body */
  body: T;
  /** HTTP status code */
  status: number;
};

import https from "https";

// Custom logger configuration
const systemWithLogger: NodeSystemOptions = {
  loggerOptions: {
    loggerCallback: (level, message, containsPii) => {
      if (!containsPii) {
        const timestamp = new Date().toISOString();
        const levelName = LogLevel[level];
        console.log(`[${timestamp}] ${levelName}: ${message}`);
      }
    },
    logLevel: LogLevel.Verbose,
    piiLoggingEnabled: false
  }
};

// Proxy configuration
const systemWithProxy: NodeSystemOptions = {
  proxyUrl: "http://proxy.company.com:8080",
  customAgentOptions: {
    timeout: 30000,
    keepAlive: true
  }
};

// Custom HTTPS agent with certificate validation
const systemWithCustomAgent: NodeSystemOptions = {
  customAgentOptions: {
    ca: [fs.readFileSync("./ca-cert.pem")],
    rejectUnauthorized: true,
    timeout: 10000
  } as https.AgentOptions
};

// Disable retries for testing
const systemWithoutRetries: NodeSystemOptions = {
  disableInternalRetries: true,
  loggerOptions: {
    logLevel: LogLevel.Trace,
    loggerCallback: (level, message) => console.log(message)
  }
};

/**
 * Cache configuration options
 */
type CacheOptions = {
  /** Cache plugin for custom storage backends */
  cachePlugin?: ICachePlugin;
  /** 
   * @deprecated claims-based-caching functionality will be removed in the next version
   */
  claimsBasedCachingEnabled?: boolean;
};

/**
 * Cache plugin interface
 */
interface ICachePlugin {
  /** Called before cache access - load cache data */
  beforeCacheAccess(tokenCacheContext: TokenCacheContext): Promise<void>;
  /** Called after cache access - persist cache data if changed */
  afterCacheAccess(tokenCacheContext: TokenCacheContext): Promise<void>;
}

// File-based cache plugin
class FileCachePlugin implements ICachePlugin {
  private cacheFilePath: string;

  constructor(cacheFilePath: string) {
    this.cacheFilePath = cacheFilePath;
  }

  async beforeCacheAccess(cacheContext: TokenCacheContext): Promise<void> {
    try {
      const cacheData = await fs.readFile(this.cacheFilePath, "utf8");
      await cacheContext.tokenCache.deserialize(cacheData);
    } catch (error) {
      // Cache file doesn't exist - start with empty cache
    }
  }

  async afterCacheAccess(cacheContext: TokenCacheContext): Promise<void> {
    if (cacheContext.hasChanged) {
      const serializedCache = await cacheContext.tokenCache.serialize();
      await fs.writeFile(this.cacheFilePath, serializedCache);
    }
  }
}

const cacheConfig: CacheOptions = {
  cachePlugin: new FileCachePlugin("./token-cache.json")
};

/**
 * Broker configuration options
 * Note: These options are only available for PublicClientApplications using Authorization Code Flow
 */
type BrokerOptions = {
  /** Native broker plugin implementation */
  nativeBrokerPlugin?: INativeBrokerPlugin;
};

/**
 * Native broker plugin interface
 */
interface INativeBrokerPlugin {
  /** Check if broker is available on current platform */
  isBrokerAvailable(): Promise<boolean>;
  /** Acquire token using native broker */
  acquireTokenSilent(request: SilentFlowRequest): Promise<AuthenticationResult>;
  /** Acquire token interactively using native broker */
  acquireTokenInteractive(request: InteractiveRequest): Promise<AuthenticationResult>;
  /** Get accounts from native broker */
  getAllAccounts(): Promise<AccountInfo[]>;
  /** Remove account from native broker */
  removeAccount(account: AccountInfo): Promise<void>;
}

// Broker configuration (requires msal-node-extensions package)
import { NativeBrokerPlugin } from "msal-node-extensions";

const brokerConfig: BrokerOptions = {
  nativeBrokerPlugin: new NativeBrokerPlugin()
};

const pca = new PublicClientApplication({
  auth: {
    clientId: "your-client-id"
  },
  broker: brokerConfig
});

/**
 * Telemetry configuration options
 */
type NodeTelemetryOptions = {
  /** Application telemetry information */
  application?: ApplicationTelemetry;
};

/**
 * Application telemetry information
 */
type ApplicationTelemetry = {
  /** Application name */
  appName: string;
  /** Application version */
  appVersion: string;
};

const telemetryConfig: NodeTelemetryOptions = {
  application: {
    appName: "MyNodeApp",
    appVersion: "2.1.0"
  }
};

const pca = new PublicClientApplication({
  auth: {
    clientId: "your-client-id"
  },
  telemetry: telemetryConfig
});

/**
 * Configuration for managed identity applications
 */
type ManagedIdentityConfiguration = {
  /** Client capabilities for conditional access */
  clientCapabilities?: Array<string>;
  /** Parameters for user-assigned managed identity */
  managedIdentityIdParams?: ManagedIdentityIdParams;
  /** System configuration options */
  system?: NodeSystemOptions;
};

/**
 * Parameters for user-assigned managed identity
 */
type ManagedIdentityIdParams = {
  /** Client ID of the user-assigned managed identity */
  userAssignedClientId?: string;
  /** Resource ID of the user-assigned managed identity */
  userAssignedResourceId?: string;
  /** Object ID of the user-assigned managed identity */
  userAssignedObjectId?: string;
};

import { ManagedIdentityApplication } from "@azure/msal-node";

// System-assigned managed identity
const systemAssignedConfig: ManagedIdentityConfiguration = {};

// User-assigned managed identity by client ID
const userAssignedConfig: ManagedIdentityConfiguration = {
  managedIdentityIdParams: {
    userAssignedClientId: "12345678-1234-1234-1234-123456789012"
  },
  clientCapabilities: ["CP1"], // Conditional access capability
  system: {
    loggerOptions: {
      logLevel: LogLevel.Info,
      loggerCallback: (level, message) => console.log(message)
    }
  }
};

const mia = new ManagedIdentityApplication(userAssignedConfig);

/**
 * Default configuration values applied automatically
 */
const DEFAULT_AUTH_OPTIONS: Required<NodeAuthOptions> = {
  clientId: "", // Must be provided
  authority: "https://login.microsoftonline.com/common",
  clientSecret: "",
  clientAssertion: "",
  clientCertificate: {
    thumbprint: "",
    thumbprintSha256: "",
    privateKey: "",
    x5c: ""
  },
  knownAuthorities: [],
  cloudDiscoveryMetadata: "",
  authorityMetadata: "",
  clientCapabilities: [],
  protocolMode: ProtocolMode.AAD,
  azureCloudOptions: {
    azureCloudInstance: AzureCloudInstance.None,
    tenant: ""
  },
  skipAuthorityMetadataCache: false,
  encodeExtraQueryParams: false
};

const DEFAULT_SYSTEM_OPTIONS: Required<NodeSystemOptions> = {
  loggerOptions: {
    loggerCallback: () => {}, // No-op by default
    piiLoggingEnabled: false,
    logLevel: LogLevel.Info
  },
  networkClient: new HttpClient(),
  proxyUrl: "",
  customAgentOptions: {},
  disableInternalRetries: false
};

/**
 * Configuration validation function (internal)
 */
function buildAppConfiguration(config: Configuration): NodeConfiguration;

/**
 * Validation rules applied during configuration
 */
type ConfigurationValidation = {
  /** Client ID is required and must be valid GUID */
  clientIdRequired: boolean;
  /** Certificate thumbprint validation (SHA-1 or SHA-256 required) */
  certificateThumbprintRequired: boolean;
  /** Known authorities format validation */
  knownAuthoritiesFormat: boolean;
  /** Protocol mode compatibility */
  protocolModeCompatibility: boolean;
};

// Configuration with validation
try {
  const pca = new PublicClientApplication({
    auth: {
      clientId: "invalid-client-id" // This will cause validation error
    }
  });
} catch (error) {
  console.error("Configuration validation failed:", error.message);
}

// Valid configuration
const validConfig: Configuration = {
  auth: {
    clientId: "12345678-1234-1234-1234-123456789012",
    authority: "https://login.microsoftonline.com/common",
    clientCapabilities: ["CP1", "CP2"]
  },
  system: {
    loggerOptions: {
      logLevel: LogLevel.Warning,
      loggerCallback: (level, message, containsPii) => {
        if (!containsPii && level <= LogLevel.Warning) {
          console.warn(message);
        }
      }
    }
  }
};

const pca = new PublicClientApplication(validConfig);

const developmentConfig: Configuration = {
  auth: {
    clientId: "dev-client-id",
    authority: "https://login.microsoftonline.com/common"
  },
  system: {
    loggerOptions: {
      logLevel: LogLevel.Verbose,
      loggerCallback: (level, message) => console.log(message),
      piiLoggingEnabled: false
    },
    disableInternalRetries: false
  }
};

const productionConfig: Configuration = {
  auth: {
    clientId: process.env.MSAL_CLIENT_ID!,
    clientSecret: process.env.MSAL_CLIENT_SECRET,
    authority: `https://login.microsoftonline.com/${process.env.TENANT_ID}`
  },
  system: {
    loggerOptions: {
      logLevel: LogLevel.Error,
      loggerCallback: (level, message, containsPii) => {
        if (!containsPii) {
          // Log to production logging system
          logger.log(level, message);
        }
      }
    },
    proxyUrl: process.env.HTTPS_PROXY,
    disableInternalRetries: false
  },
  cache: {
    cachePlugin: new ProductionCachePlugin()
  }
};

const testConfig: Configuration = {
  auth: {
    clientId: "test-client-id",
    authority: "https://login.microsoftonline.com/common",
    skipAuthorityMetadataCache: true
  },
  system: {
    disableInternalRetries: true,
    loggerOptions: {
      logLevel: LogLevel.Error,
      loggerCallback: () => {} // Silent in tests
    }
  }
};