feat(security): 仅加载显式授权的外部 DLL

Runtime/Bootstrap/ShrinkModBootstrap.cs

@@ -9,7 +9,7 @@ namespace ShrinkModFramework
         [SerializeField] private ShrinkModFrameworkSettings settingsOverride;
 
         [Header("Bootstrap")]
-        [SerializeField] private bool autoLoadOnAwake = true;
+        [SerializeField] private bool autoLoadOnAwake;
 
         private static bool _bootstrapped;
 

Runtime/Bootstrap/ShrinkModFrameworkSettings.cs

@@ -5,6 +5,10 @@ namespace ShrinkModFramework
     [CreateAssetMenu(fileName = "ShrinkModFrameworkSettings", menuName = "ShrinkSDK/模组/模组设置")]
     public class ShrinkModFrameworkSettings : ScriptableObject
     {
+        public const string PreferredResourcesPath =
+            "GameAssets/Runtime/Data/ShrinkSDK/ShrinkModFrameworkSettings";
+        public const string LegacyResourcesPath = "ShrinkModFrameworkSettings";
+
         private static ShrinkModFrameworkSettings _instance;
 
         public static ShrinkModFrameworkSettings Instance
@@ -13,7 +17,9 @@ namespace ShrinkModFramework
             {
                 if (_instance) return _instance;
 
-                _instance = Resources.Load<ShrinkModFrameworkSettings>("ShrinkModFrameworkSettings");
+                _instance = Resources.Load<ShrinkModFrameworkSettings>(PreferredResourcesPath);
+                if (!_instance)
+                    _instance = Resources.Load<ShrinkModFrameworkSettings>(LegacyResourcesPath);
 
 #if UNITY_EDITOR
                 if (!_instance)
@@ -39,8 +45,13 @@ namespace ShrinkModFramework
             internal set => _instance = value;
         }
 
+        internal static void ResetCachedInstance()
+        {
+            _instance = null;
+        }
+
         [Header("Bootstrap")]
-        public bool autoLoadOnStartup = true;
+        public bool autoLoadOnStartup;
         [Tooltip("使用 ShrinkContextHost 协调模组组件；关闭时回退到旧的只增不减 ShrinkModLoader。")]
         public bool useContextHost = true;
 
@@ -51,10 +62,10 @@ namespace ShrinkModFramework
         public string[] assemblyNamePrefixes = new string[0];
 
         [Header("External Mods")]
-        public bool enableExternalDllMods = true;
+        public bool enableExternalDllMods;
         public bool autoCreateExternalModsDirectory = true;
         public string externalModsFolderName = "Mods";
-        public bool watchExternalModsDirectory = true;
+        public bool watchExternalModsDirectory;
         public float externalModsReloadDelaySeconds = 0.5f;
         [Min(1)]
         [Tooltip("Mono 下外部程序集 revision 会常驻；历史数量达到该软阈值后提示 Domain Reload/重启。")]

Runtime/Bootstrap/ShrinkModRuntimeBootstrap.cs

@@ -4,6 +4,15 @@ namespace ShrinkModFramework
 {
     public static class ShrinkModRuntimeBootstrap
     {
+        /// <summary>
+        /// 显式创建或更新模组运行时驱动。安全启动链可先调用此入口，再调用
+        /// ShrinkModLoader.LoadAuthorized 提交已校验的 DLL 白名单。
+        /// </summary>
+        public static void InitializeDriver(ShrinkModFrameworkSettings settings = null)
+        {
+            ShrinkModRuntimeDriver.EnsureCreated(settings ?? ShrinkModFrameworkSettings.Instance);
+        }
+
         [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
         private static void ResetStaticStateForPlayMode()
         {
@@ -15,11 +24,11 @@ namespace ShrinkModFramework
         private static void AutoLoad()
         {
             var settings = ShrinkModFrameworkSettings.Instance;
-            ShrinkModRuntimeDriver.EnsureCreated(settings);
-
             if (settings && !settings.autoLoadOnStartup)
                 return;
 
+            InitializeDriver(settings);
+
             try
             {
                 ShrinkModLoader.LoadAll(settings);

Runtime/Context/ShrinkModComponentDiscovery.cs

@@ -12,10 +12,13 @@ namespace ShrinkModFramework
     /// </summary>
     internal static class ShrinkModComponentDiscovery
     {
-        public static IReadOnlyList<ShrinkModComponentSource> Discover(ShrinkModFrameworkSettings settings,
-            bool verboseLogging)
+        public static IReadOnlyList<ShrinkModComponentSource> Discover(
+            ShrinkModFrameworkSettings settings,
+            bool verboseLogging,
+            IEnumerable<string> authorizedDllPaths)
         {
-            ShrinkExternalModAssemblyLoader.ScanExternalAssemblyRevisions(settings, verboseLogging);
+            ShrinkExternalModAssemblyLoader.ScanExternalAssemblyRevisions(
+                settings, verboseLogging, authorizedDllPaths);
             var results = new List<ShrinkModComponentSource>();
             var prefixes = settings?.assemblyNamePrefixes;
 

Runtime/Context/ShrinkModCordisRuntime.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using Cysharp.Threading.Tasks;
 
 namespace ShrinkModFramework
@@ -19,7 +20,8 @@ namespace ShrinkModFramework
             new Dictionary<string, ShrinkModHandle>();
 
         public static async UniTask<IReadOnlyDictionary<string, ShrinkModHandle>> ApplyDiscoveredAsync(
-            ShrinkModFrameworkSettings settings = null)
+            ShrinkModFrameworkSettings settings = null,
+            IEnumerable<string> authorizedDllPaths = null)
         {
             settings ??= ShrinkModFrameworkSettings.Instance;
             var verboseLogging = settings == null || settings.verboseLogging;
@@ -34,7 +36,9 @@ namespace ShrinkModFramework
             ShrinkModNetworkManager.Configure(settings == null || settings.enableNetworkSync, verboseLogging);
             try
             {
-                var sources = ShrinkModComponentDiscovery.Discover(settings, verboseLogging);
+                var authorizedPaths = authorizedDllPaths?.ToArray() ?? Array.Empty<string>();
+                var sources = ShrinkModComponentDiscovery.Discover(
+                    settings, verboseLogging, authorizedPaths);
                 await _host.ApplyAsync(sources);
             }
             catch

Runtime/Loading/ShrinkExternalModAssemblyLoader.cs

@@ -34,17 +34,22 @@ namespace ShrinkModFramework
         private static bool _resolveRegistered;
         private static int _lastWarnedResidentCount;
 
-        public static IReadOnlyList<Assembly> LoadExternalAssemblies(ShrinkModFrameworkSettings settings, bool verboseLogging)
+        public static IReadOnlyList<Assembly> LoadExternalAssemblies(
+            ShrinkModFrameworkSettings settings,
+            bool verboseLogging,
+            IEnumerable<string> authorizedDllPaths = null)
         {
-            return ScanExternalAssemblyRevisions(settings, verboseLogging)
+            return ScanExternalAssemblyRevisions(settings, verboseLogging, authorizedDllPaths)
                 .Select(revision => revision.Assembly)
                 .ToArray();
         }
 
         internal static IReadOnlyList<ExternalAssemblyRevision> ScanExternalAssemblyRevisions(
-            ShrinkModFrameworkSettings settings, bool verboseLogging)
+            ShrinkModFrameworkSettings settings,
+            bool verboseLogging,
+            IEnumerable<string> authorizedDllPaths = null)
         {
-            if (settings != null && !settings.enableExternalDllMods)
+            if (settings == null || !settings.enableExternalDllMods)
             {
                 CurrentAssemblyRevisions.Clear();
                 KnownAssemblyFiles.Clear();
@@ -52,27 +57,23 @@ namespace ShrinkModFramework
             }
 
 #if ENABLE_IL2CPP && !UNITY_EDITOR
-            Debug.LogWarning("[ShrinkModFramework] IL2CPP 运行时不支持外部 DLL 热加载，已跳过外部模组扫描。");
+            Debug.LogWarning("[ShrinkModFramework] IL2CPP 运行时不支持外部 DLL 加载，已跳过授权模组。");
             return Array.Empty<ExternalAssemblyRevision>();
 #else
-            var modsDirectory = GetExternalModsDirectory(settings);
-            if (settings == null || settings.autoCreateExternalModsDirectory)
-                Directory.CreateDirectory(modsDirectory);
-
             RegisterAssemblyResolve();
 
-            var dllPaths = Directory.GetFiles(modsDirectory, "*.dll", SearchOption.AllDirectories)
-                .Select(Path.GetFullPath)
-                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase)
-                .ToArray();
-            var presentPaths = new HashSet<string>(dllPaths, StringComparer.OrdinalIgnoreCase);
+            var dllPaths = NormalizeAuthorizedPaths(authorizedDllPaths);
+            var presentPaths = new HashSet<string>(
+                dllPaths.Where(File.Exists),
+                StringComparer.OrdinalIgnoreCase);
 
-            foreach (var dllPath in dllPaths
+            KnownAssemblyFiles.Clear();
+            foreach (var dllPath in presentPaths)
+                KnownAssemblyFiles[Path.GetFileNameWithoutExtension(dllPath)] = dllPath;
+
+            foreach (var dllPath in presentPaths
                          .OrderBy(path => path, StringComparer.OrdinalIgnoreCase))
             {
-                var assemblyName = Path.GetFileNameWithoutExtension(dllPath);
-                KnownAssemblyFiles[assemblyName] = dllPath;
-
                 try
                 {
                     var bytes = File.ReadAllBytes(dllPath);
@@ -131,6 +132,41 @@ namespace ShrinkModFramework
 #endif
         }
 
+        private static string[] NormalizeAuthorizedPaths(IEnumerable<string> authorizedDllPaths)
+        {
+            if (authorizedDllPaths == null)
+                return Array.Empty<string>();
+
+            var normalized = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            foreach (var rawPath in authorizedDllPaths)
+            {
+                if (string.IsNullOrWhiteSpace(rawPath))
+                    continue;
+
+                string fullPath;
+                try
+                {
+                    fullPath = Path.GetFullPath(rawPath.Trim());
+                }
+                catch (Exception exception)
+                {
+                    throw new ArgumentException($"授权 DLL 路径无效：{rawPath}",
+                        nameof(authorizedDllPaths), exception);
+                }
+
+                if (!string.Equals(Path.GetExtension(fullPath), ".dll",
+                        StringComparison.OrdinalIgnoreCase))
+                {
+                    throw new ArgumentException($"授权路径不是 DLL：{fullPath}",
+                        nameof(authorizedDllPaths));
+                }
+
+                normalized.Add(fullPath);
+            }
+
+            return normalized.OrderBy(path => path, StringComparer.OrdinalIgnoreCase).ToArray();
+        }
+
         internal static bool IsExternalAssembly(Assembly assembly) =>
             assembly != null && ExternalAssemblyHistory.ContainsKey(assembly);
 
@@ -268,13 +304,38 @@ namespace ShrinkModFramework
             if (!KnownAssemblyFiles.TryGetValue(requestedName, out var path) || !File.Exists(path))
                 return null;
 
-            try
+            lock (ResolveLock)
             {
-                return Assembly.Load(File.ReadAllBytes(path));
-            }
-            catch
-            {
-                return null;
+                try
+                {
+                    var bytes = File.ReadAllBytes(path);
+                    var revision = ComputeSha256(bytes);
+                    if (CurrentAssemblyRevisions.TryGetValue(path, out var current) &&
+                        string.Equals(current.Revision, revision, StringComparison.Ordinal))
+                    {
+                        return current.Assembly;
+                    }
+
+                    var pdbPath = Path.ChangeExtension(path, ".pdb");
+                    var pdbBytes = File.Exists(pdbPath) ? File.ReadAllBytes(pdbPath) : null;
+                    var assembly = pdbBytes != null
+                        ? Assembly.Load(bytes, pdbBytes)
+                        : Assembly.Load(bytes);
+                    var loadedRevision = new ExternalAssemblyRevision
+                    {
+                        Path = path,
+                        Revision = revision,
+                        Assembly = assembly,
+                        LoadedBytes = bytes.LongLength + (pdbBytes?.LongLength ?? 0L)
+                    };
+                    CurrentAssemblyRevisions[path] = loadedRevision;
+                    ExternalAssemblyHistory[assembly] = loadedRevision;
+                    return assembly;
+                }
+                catch
+                {
+                    return null;
+                }
             }
         }
     }

Runtime/Loading/ShrinkModLoader.cs

@@ -18,6 +18,7 @@ namespace ShrinkModFramework
         private static readonly Dictionary<string, ShrinkModHandle> LoadedMods = new(StringComparer.Ordinal);
         private static readonly List<ShrinkModHandle> LoadSequence = new();
         private static readonly ShrinkModRegistryManager RegistryManager = new();
+        private static string[] _authorizedDllPaths = Array.Empty<string>();
 
         public static bool IsLoaded { get; private set; }
         public static IReadOnlyDictionary<string, ShrinkModHandle> Mods =>
@@ -27,8 +28,35 @@ namespace ShrinkModFramework
         public static event Action<IReadOnlyDictionary<string, ShrinkModHandle>> OnAllModsReady;
 
         public static IReadOnlyDictionary<string, ShrinkModHandle> LoadAll(ShrinkModFrameworkSettings settings = null)
+            => LoadInternal(settings, Array.Empty<string>());
+
+        /// <summary>
+        /// 加载工程内模组，并且只加载调用方显式授权的外部 DLL 路径。
+        /// 路径集合是完整白名单，不会递归扫描模组目录；后续 revision 刷新也只复用该白名单。
+        /// </summary>
+        public static IReadOnlyDictionary<string, ShrinkModHandle> LoadAuthorized(
+            ShrinkModFrameworkSettings settings,
+            IEnumerable<string> authorizedDllPaths)
+        {
+            if (authorizedDllPaths == null)
+                throw new ArgumentNullException(nameof(authorizedDllPaths));
+
+            return LoadInternal(settings, authorizedDllPaths);
+        }
+
+        private static IReadOnlyDictionary<string, ShrinkModHandle> LoadInternal(
+            ShrinkModFrameworkSettings settings,
+            IEnumerable<string> authorizedDllPaths)
         {
             settings ??= ShrinkModFrameworkSettings.Instance;
+            _authorizedDllPaths = authorizedDllPaths
+                .Where(path => !string.IsNullOrWhiteSpace(path))
+                .Select(path => path.Trim())
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .ToArray();
+
+            if (settings == null || settings.useContextHost)
+                return ApplyContextComposition(settings, _authorizedDllPaths);
 
             if (IsLoaded)
             {
@@ -36,15 +64,13 @@ namespace ShrinkModFramework
                 return Mods;
             }
 
-            if (settings == null || settings.useContextHost)
-                return ApplyContextComposition(settings);
-
             var verboseLogging = settings == null || settings.verboseLogging;
 
             try
             {
                 ShrinkModNetworkManager.Configure(settings == null || settings.enableNetworkSync, verboseLogging);
-                ShrinkExternalModAssemblyLoader.LoadExternalAssemblies(settings, verboseLogging);
+                ShrinkExternalModAssemblyLoader.LoadExternalAssemblies(
+                    settings, verboseLogging, _authorizedDllPaths);
 
                 var discovered = DiscoverMods(settings);
                 var ordered = ResolveLoadOrder(discovered, allowExistingLoadedDependencies: true);
@@ -73,12 +99,13 @@ namespace ShrinkModFramework
         {
             settings ??= ShrinkModFrameworkSettings.Instance;
             if (settings == null || settings.useContextHost)
-                return ApplyContextComposition(settings);
+                return ApplyContextComposition(settings, _authorizedDllPaths);
             if (!IsLoaded)
-                return LoadAll(settings);
+                return LoadInternal(settings, _authorizedDllPaths);
 
             var verboseLogging = settings == null || settings.verboseLogging;
-            ShrinkExternalModAssemblyLoader.LoadExternalAssemblies(settings, verboseLogging);
+            ShrinkExternalModAssemblyLoader.LoadExternalAssemblies(
+                settings, verboseLogging, _authorizedDllPaths);
 
             var discovered = DiscoverMods(settings)
                 .Where(mod => !LoadedMods.ContainsKey(mod.Info.ModId))
@@ -145,6 +172,7 @@ namespace ShrinkModFramework
             ShrinkModNetworkManager.ResetForDomainReload();
             ShrinkExternalModAssemblyLoader.ResetForTesting();
             ShrinkHarmonyPatchService.ResetForTesting();
+            _authorizedDllPaths = Array.Empty<string>();
         }
 
         internal static void ResetForDomainReload()
@@ -160,17 +188,22 @@ namespace ShrinkModFramework
             ShrinkModNetworkManager.ResetForDomainReload();
             ShrinkExternalModAssemblyLoader.ResetForDomainReload();
             ShrinkHarmonyPatchService.ResetForTesting();
+            _authorizedDllPaths = Array.Empty<string>();
         }
 
         private static IReadOnlyDictionary<string, ShrinkModHandle> ApplyContextComposition(
-            ShrinkModFrameworkSettings settings)
+            ShrinkModFrameworkSettings settings,
+            IEnumerable<string> authorizedDllPaths)
         {
             var previousGenerations = Mods.ToDictionary(
                 pair => pair.Key,
                 pair => pair.Value.Generation,
                 StringComparer.Ordinal);
 
-            var result = ShrinkModCordisRuntime.ApplyDiscoveredAsync(settings).GetAwaiter().GetResult();
+            var result = ShrinkModCordisRuntime
+                .ApplyDiscoveredAsync(settings, authorizedDllPaths)
+                .GetAwaiter()
+                .GetResult();
             IsLoaded = true;
             foreach (var pair in result.OrderBy(pair => pair.Key, StringComparer.Ordinal))
             {
@@ -206,6 +239,11 @@ namespace ShrinkModFramework
 
             foreach (var assembly in AppDomain.CurrentDomain.GetAssemblies())
             {
+                if (ShrinkExternalModAssemblyLoader.IsExternalAssembly(assembly) &&
+                    !ShrinkExternalModAssemblyLoader.TryGetCurrentRevision(assembly, out _))
+                {
+                    continue;
+                }
                 if (!ShouldScanAssembly(assembly, prefixes))
                     continue;