capacitor-ios-security-hardening

Capacitor iOS 安全加固

审计 Capacitor 应用及其原生插件中与安全相关的 Xcode 构建设置，然后分阶段启用用户批准的设置。此技能只会更改构建设置和权利文件，不会触及 Web 代码、ATS、签名或机密信息。

何时使用

触发条件：

• 用户想审计或加固 Capacitor 应用的 iOS 构建配置
• 用户询问 Enhanced Security、ENABLE_ENHANCED_SECURITY、强化进程权利、指针认证、arm64e 或内存标记
• 启用 Enhanced Security 后，链接步骤失败，且错误中提及 arm64e
• 插件作者想为插件的 Swift/ObjC/C 代码启用更严格的警告或静态分析
• 用户想在 CI 中运行“Build and Analyze”/xcodebuild analyze

请勿用于：

• ATS、TLS 固定、签名、机密信息、WebView 配置、Capseс 扫描：capacitor-security
• App Store 隐私清单和审核清单：capacitor-apple-review-preflight
• 从 AppDelegate 迁移到 SceneDelegate：capacitor-uiscene-migration
• Android R8、网络安全配置：capacitor-security

会影响方案的事实

• 构建设置不会跨越项目边界。 App 目标上的设置不会应用于 Pods（ios/App/Pods/Pods.xcodeproj）、SPM 包（插件、CapApp-SPM），也不会应用于 npx cap sync 生成的 Cordova 插件包。加固插件代码应在插件仓库中完成（podspec / Package.swift），而不是在应用中。
• 标准 Capacitor 应用的 App 目标是纯 Swift（AppDelegate.swift、SceneDelegate.swift）。只有当应用目标包含 .m、.mm、.c 或 .cpp 文件时，Clang 警告和分析器检查项才有意义。提出这些选项前，请先检测语言。
• Capacitor 8 模板已在项目级别设置了三个 Stage A 警告（GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR、GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE、GCC_WARN_64_TO_32_BIT_CONVERSION = YES）。请报告它们已完成加固，不要重复添加。
• WKWebView 内容不受影响。 JavaScript 和 JIT 在 WebKit 自己的进程中运行。Enhanced Security 权利适用于应用进程及其链接的原生代码（Capacitor 运行时、插件、SDK）。
• 指针认证会在设备构建中添加 arm64e 切片。 链接到应用中的每个二进制文件也必须包含 arm64e，否则链接会失败。这是 Capacitor 应用面临的主要兼容性风险。请参阅 references/enhanced-security.md。
• 不要编辑生成的文件。 ios/App/Pods/**、Pods-App.*.xcconfig、ios/App/CapApp-SPM/Package.swift、ios/capacitor-cordova-ios-plugins/** 和 ios/debug.xcconfig（SPM 模板，仅限 Debug，由 CLI 管理）会被 CocoaPods 或 npx cap sync 重写。请在 App 项目中设置选项（通过 Xcode Build Settings 写入 project.pbxproj），或写入团队已经维护的 xcconfig。
• 结果由用户负责。 Enhanced Security 会使潜在的内存错误演变为崩溃。更改任何内容前，请报告发现的问题并征得批准。发布前请在真实硬件上测试。

参考资料

仅在相关主题涉及当前任务时，才加载对应参考资料。

文件	加载时机
references/settings-catalog.md	编制审计表时：每项受跟踪的设置、其加固值、语言范围和风险
references/reading-build-settings.md	运行 xcodebuild -showBuildSettings、使用审计脚本，以及区分“显式禁用”和“默认关闭”时
references/enhanced-security.md	启用 Enhanced Security 功能、配置权利、在 CocoaPods/SPM/二进制 SDK 中使用指针认证，以及内存标记时
references/plugin-authors.md	加固插件代码：podspec pod_target_xcconfig、Package.swift 警告设置、分析插件仓库，以及发布 arm64e xcframework 时
references/decision-log.md	创建或更新团队决策文档时

脚本：scripts/audit-build-settings.mjs 会筛选 xcodebuild -showBuildSettings -json 的输出，仅保留受跟踪的设置，并将每项标记为已加固、默认值或显式设置（需提供 pbxproj）。

工作流

1. 简要说明并检查源代码管理

用两三句话告知用户：你将先进行审计、制定计划，并且在用户批准前不会做任何更改。如果项目没有 git，建议先提交更改。如果用户拒绝，则停止。

2. 探查（只读）

1. 确认 iOS 项目：检查 ios/App/App.xcodeproj 是否存在。注意使用 SPM（ios/App/CapApp-SPM/）还是 CocoaPods（ios/App/Podfile、App.xcworkspace）。
2. 从 package.json（@capacitor/ios）读取 Capacitor 版本。Capacitor 8 面向 iOS 15 部署，Capacitor 9 面向 iOS 16 部署，且需要 Xcode 27。
3. 检测 App 目标文件夹中的语言：运行 find ios/App/App -name '*.m' -o -name '*.mm' -o -name '*.c' -o -name '*.cpp'。还要运行 grep -E 'sourcecode\.cpp\.' ios/App/App.xcodeproj/project.pbxproj，以检查类型被覆盖为 C++/ObjC++ 的文件。
4. 列出包含二进制文件的原生依赖：node_modules/**/ios/** 下的 xcframeworks、插件 Package.swift 文件中的 binaryTarget，以及 podspec 中的 vendored_frameworks。
5. 查找现有的决策文档（ios/xcode-security-settings.md 或类似文件），并阅读先前的决策。
6. 阅读 Debug 和 Release 的求值后设置（参见 references/reading-build-settings.md）：

xcodebuild -showBuildSettings -json -project ios/App/App.xcodeproj -target App -configuration Release > /tmp/app-release.json
node <skill>/scripts/audit-build-settings.mjs /tmp/app-release.json --pbxproj ios/App/App.xcodeproj/project.pbxproj

7. 阅读求值后的 CODE_SIGN_ENTITLEMENTS 路径所指向的权利文件。默认模板没有权利文件，这是正常情况。

3. 制定计划并征求意见

在聊天中（或用户指定的文件中）写出计划。按阶段分组，只展示适用的项目：

阶段	项目	默认值
A. 编译器警告	五项安全警告；仅当目标中存在 C/ObjC/C++ 时适用	开启
B. 静态分析器	安全检查器和 clang-tidy 检查；分析器仅在 Analyze 时运行，因此不会带来构建风险	开启
C. Enhanced Security	项目级功能、App 目标上的权利，以及结合依赖计划启用的指针认证	开启，依赖检查后启用
D. 内存标记	checked-allocations + soft-mode	关闭，提供选项
E. 额外诊断	产生较多警告的选项	关闭，提供选项
F. 禁用的设置	逐项询问没有文档说明理由的显式 = NO 设置	开启

请用户批准、修改或取消。需要让用户判断的事项：

• 二进制 SDK 没有 arm64e 切片：在 App 目标上关闭指针认证（保留 Enhanced Security 的其余部分），还是等待供应商处理。
• CocoaPods：添加 post_install 钩子以在 pod 目标上启用指针认证，还是在 App 目标上关闭该功能。
• 内存标记：仅在制定了使用支持该功能的硬件进行测试的计划时启用。

4. 分阶段应用

• 在 App.xcodeproj 的项目级别应用设置，让所有目标继承这些设置；但按目标设置的项目除外（权利文件、指针认证退出选项）。
• 推荐做法：请用户在 Xcode 中设置（项目 > Build Settings > All）。然后使用 grep 检查 project.pbxproj。如果由你编辑 project.pbxproj，只能编辑项目自身 Debug 和 Release XCBuildConfiguration 条目的 buildSettings 字典（即 PBXProject buildConfigurationList 中列出的条目），保留 KEY = VALUE; 语法，并重新运行 -showBuildSettings 进行确认。
• 在 App 目标的Signing & Capabilities > + Capability > Enhanced Security 中添加 Enhanced Security。这会创建或更新 App.entitlements，并配置 CODE_SIGN_ENTITLEMENTS。详情：references/enhanced-security.md。
• 每个阶段完成后，都要先构建（步骤 5），再开始下一阶段。如果某个阶段导致构建失败，请撤销该阶段的更改，在决策日志中记录原因，然后继续。

5. 验证

# Sync, then build for a device (arm64e only exists for device SDKs)
npx cap sync ios
xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Release \
  -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO build
# CocoaPods projects: use -workspace ios/App/App.xcworkspace instead of -project

# Static analyzer
xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Debug \
  -destination 'generic/platform=iOS Simulator' analyze

# Confirm the slices of the built app binary
lipo -archs ~/Library/Developer/Xcode/DerivedData/App-*/Build/Products/Release-iphoneos/App.app/App

• 重新运行审计脚本。每项已批准的设置都应显示为已加固。
• 模拟器构建应能继续正常工作：模拟器 SDK 不包含 arm64e，构建系统会将其移除。不要添加仅适用于模拟器的退出选项。
• 在真实设备上运行应用。检查启动、插件调用以及 JS pause / resume 事件。若内存标记处于软模式，请从 Xcode Organizer 或设备日志（ios-android-logs）收集模拟崩溃报告。

6. 报告并记录

报告：启用了哪些设置、哪些设置原本已加固、跳过了哪些设置及原因、哪些依赖项会阻碍 arm64e，以及发布前在硬件上测试的待办事项。然后更新决策文档（references/decision-log.md）。

错误处理

症状	原因	修复方法
启用 Enhanced Security 后，链接失败并显示提及 arm64e 的消息	某个 pod、SPM 软件包或 xcframework 构建时未包含 arm64e	使用 lipo -archs 查找。源码 pod：使用 post_install 钩子。SPM 源码软件包：设置工作区选项 iOSPackagesShouldBuildARM64e。不包含该架构切片的二进制文件：在 App 目标上设置 ENABLE_POINTER_AUTHENTICATION = NO，并联系供应商。参见 references/enhanced-security.md
[CP] Embed Pods Frameworks 中出现 Sandbox: rsync(...) deny(1) file-write-create	CocoaPods 脚本阶段启用了 ENABLE_USER_SCRIPT_SANDBOXING = YES	使用 CocoaPods 时，在 App 目标上保持为 NO，记录原因，并在迁移到 SPM（cocoapods-to-spm）后重新评估
阶段 A 之后出现大量新警告	之前关闭了警告	优先修复实际 Bug。如果警告来自生成代码或供应商代码，保持警告开启并暂缓处理该代码；绝不要为整个项目切换 -Werror
设置已更改，但 -showBuildSettings 显示旧值	设置级别不正确，或目标级别的值覆盖了项目级设置	检查 Xcode 中的目标列；如果目标级别的覆盖没有合理原因，就移除它
仅在较新的设备上启动时应用崩溃，且内存标记已启用	过早关闭了软模式，或原生库存在内存 Bug	重新启用软模式，收集报告，并修复或更新该库（通常是随附的 C 代码，例如 zip 或 SQLite）
运行 npx cap sync 或 pod install 后编辑内容消失	编辑了生成文件	将设置移至 App 项目，或移至插件自身的 podspec / Package.swift

相关技能

• capacitor-security：ATS、签名、机密、WebView 和存储安全
• cocoapods-to-spm：SPM 可消除大多数与 pod 相关的加固障碍
• capacitor-plugin-spm-support：插件的 Package.swift 布局
• ios-android-logs：从设备捕获崩溃和内存标记报告