portless macOS 钥匙串深挖security 命令、Touch ID 弹窗与重复证书清理指南【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portlessportless 是一个把端口号换成稳定命名本地地址的本地开发 HTTPS 代理工具——运行portless myapp next dev就能访问https://myapp.localhost无需再记 3000、3001。而在 macOS 上让浏览器信任这套本地 HTTPS 的核心战场就是系统钥匙串Keychain。本文带你深挖 portless 是如何调用系统security命令、处理 Touch ID 授权弹窗、并自动清理钥匙串里重复的本地 CA 证书的。为什么 portless 要动 macOS 钥匙串portless 首次启动时会做三件事逻辑集中在 certs.ts用 OpenSSL 生成一个自签本地 CA有效期 10 年和服务器证书把 CA 加入系统信任存储之后浏览器访问*.localhost就没有任何连接不安全警告。macOS 的信任存储由钥匙串守护进程securityd管理命令行入口是security工具。portless 对它的使用可以归纳为三条命令命令作用是否弹窗security default-keychain找出当前用户的登录钥匙串路径❌security verify-cert -c ca.pem -L -p ssl验证 CA 是否已被信任❌security add-trusted-cert -r trustRoot -k 钥匙串 ca.pem把 CA 写入信任存储⚠️ 普通用户会弹 Touch ID/密码框一步到位如何定位登录钥匙串security add-trusted-cert需要明确指定目标钥匙串。portless 不硬编码路径而是先问系统要默认钥匙串见 loginKeychainPath()security default-keychain # 输出形如/Users/you/Library/Keychains/login.keychain-db如果命令失败比如securityd卡住代码会回退到惯例路径~/Library/Keychains/login.keychain-db保证健壮性。快速验证verify-cert 与 15 秒耐心每次代理启动前portless 都会检查本地 CA 是否还受信任isCATrustedMacOS。它执行的是security verify-cert -c ca.pem -L -p ssl-L沿完整信任链验证-p ssl限定 Web 信任用途。这条命令默认给了15 秒超时——注释里写明因为钥匙串守护进程在系统高负载或 macOS 更新后可能明显变慢超时常量定义。这个超时设计直接修复过security 命令偶发缓慢导致代理启动失败的问题见 CHANGELOG。还有一个细节当 portless 以sudoroot身份运行时它会用sudo -u $SUDO_USER security verify-cert ...切回真实用户视角去验证——因为 root 信任了证书不代表以普通用户身份运行的 Chrome 能看见对应代码。Touch ID 弹窗从哪来120 秒倒计时背后的设计真正写入信任的命令是trustCA# 普通用户写入登录钥匙串 security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db ca.pem这条命令会触发 macOS 的系统级授权对话框Touch ID 或密码确认。因此 portless 把这条命令的超时设为120 秒非 root 场景足够用户从容按指纹而 root 场景加-d写入/Library/Keychains/System.keychain不弹窗超时 60 秒。 权限不足的兜底如果portless trust因权限被拒handleTrust 会自动发起sudo提权重试——这也是文档中macOS/Linux 可能需要输入一次 sudo 密码的由来。信任标记缓存别让弹窗反复打扰反复执行security verify-cert本身不弹窗但频繁触发 OS 信任检查在securityd不健康时可能连带弹出系统授权框。portless 在~/.portless下写入一个ca.trusted标记文件内容是 CA 证书内容的SHA-256 指纹writeTrustMarker。下次启动时指纹一致就跳过系统检查从源头减少弹窗干扰。这也是 0.11.0 把状态目录从/tmp迁到~/.portless的动机之一——/tmp会被系统周期性清理标记一丢信任提示就反复出现见 CHANGELOG 记录。重复证书清理delete-certificate 循环与 is ambiguous 难题多次升级、重装、换用户名后钥匙串里可能残留多个同名的 portless Local CA 条目。此时执行security delete-certificate -c portless Local CA会报is ambiguous, matches more than one certificate——它拒绝在有歧义时删除。portless 的清理策略在 untrustCAMacOS 中思路非常实用先security remove-trusted-cert ca.pem摘掉信任标记对登录钥匙串和系统钥匙串各跑一个最多 20 次的循环每次删除一个匹配证书直到命令不再返回歧义错误最后用verify-cert复查确认 CA 已彻底不受信任才宣告成功。# 清理效果的最终判定命令与验证信任时完全对称 security verify-cert -c ca.pem -L -p ssl这个循环到删干净的写法正是针对 GitHub 上反馈的重复证书问题#251 修复记录——旧版本一次delete-certificate撞上歧义就放弃残留证书会在每次升级时继续累积。当 security 命令卡死实用排障清单如果 portless 提示macOS security 命令超时通常不是 portless 的问题而是securityd本身无响应。代码内置的排障提示错误处理给了标准解法重启钥匙串访问退出并重新打开钥匙串访问App终极手段执行sudo killall securityd让守护进程自愈然后重新运行portless trust完成信任写入。此外项目还专门做了假 security 二进制的故障注入测试certs.test.ts确保security命令彻底失败时用户拿到的是可操作的错误信息而不是裸异常。小结一张表看懂 macOS 信任链路环节portless 的做法源码位置找钥匙串security default-keychain 路径回退certs.ts#L512-L529验证信任verify-cert -L -p ssl15s 超时sudo 时切换用户视角certs.ts#L483-L510写入信任普通用户写登录钥匙串弹 Touch ID120sroot 写系统钥匙串certs.ts#L909-L933防重复弹窗ca.trusted指纹标记免重复系统检查certs.ts#L103-L111清理重复证书双钥匙串 × 20 次循环删除 最终复查certs.ts#L1011-L1040权限兜底权限被拒时自动 sudo 提权重试cli.ts#L1975-L1998对新手来说日常只需要记住一条命令信任异常时运行portless trust重新授权彻底不用时运行portless clean让 portless 自动走上面的完整清理流程。更多本地 HTTPS 的细节可参考官方文档 HTTPS 页面。【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
portless macOS 钥匙串深挖：security 命令、Touch ID 弹窗与重复证书清理指南
portless macOS 钥匙串深挖security 命令、Touch ID 弹窗与重复证书清理指南【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portlessportless 是一个把端口号换成稳定命名本地地址的本地开发 HTTPS 代理工具——运行portless myapp next dev就能访问https://myapp.localhost无需再记 3000、3001。而在 macOS 上让浏览器信任这套本地 HTTPS 的核心战场就是系统钥匙串Keychain。本文带你深挖 portless 是如何调用系统security命令、处理 Touch ID 授权弹窗、并自动清理钥匙串里重复的本地 CA 证书的。为什么 portless 要动 macOS 钥匙串portless 首次启动时会做三件事逻辑集中在 certs.ts用 OpenSSL 生成一个自签本地 CA有效期 10 年和服务器证书把 CA 加入系统信任存储之后浏览器访问*.localhost就没有任何连接不安全警告。macOS 的信任存储由钥匙串守护进程securityd管理命令行入口是security工具。portless 对它的使用可以归纳为三条命令命令作用是否弹窗security default-keychain找出当前用户的登录钥匙串路径❌security verify-cert -c ca.pem -L -p ssl验证 CA 是否已被信任❌security add-trusted-cert -r trustRoot -k 钥匙串 ca.pem把 CA 写入信任存储⚠️ 普通用户会弹 Touch ID/密码框一步到位如何定位登录钥匙串security add-trusted-cert需要明确指定目标钥匙串。portless 不硬编码路径而是先问系统要默认钥匙串见 loginKeychainPath()security default-keychain # 输出形如/Users/you/Library/Keychains/login.keychain-db如果命令失败比如securityd卡住代码会回退到惯例路径~/Library/Keychains/login.keychain-db保证健壮性。快速验证verify-cert 与 15 秒耐心每次代理启动前portless 都会检查本地 CA 是否还受信任isCATrustedMacOS。它执行的是security verify-cert -c ca.pem -L -p ssl-L沿完整信任链验证-p ssl限定 Web 信任用途。这条命令默认给了15 秒超时——注释里写明因为钥匙串守护进程在系统高负载或 macOS 更新后可能明显变慢超时常量定义。这个超时设计直接修复过security 命令偶发缓慢导致代理启动失败的问题见 CHANGELOG。还有一个细节当 portless 以sudoroot身份运行时它会用sudo -u $SUDO_USER security verify-cert ...切回真实用户视角去验证——因为 root 信任了证书不代表以普通用户身份运行的 Chrome 能看见对应代码。Touch ID 弹窗从哪来120 秒倒计时背后的设计真正写入信任的命令是trustCA# 普通用户写入登录钥匙串 security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db ca.pem这条命令会触发 macOS 的系统级授权对话框Touch ID 或密码确认。因此 portless 把这条命令的超时设为120 秒非 root 场景足够用户从容按指纹而 root 场景加-d写入/Library/Keychains/System.keychain不弹窗超时 60 秒。 权限不足的兜底如果portless trust因权限被拒handleTrust 会自动发起sudo提权重试——这也是文档中macOS/Linux 可能需要输入一次 sudo 密码的由来。信任标记缓存别让弹窗反复打扰反复执行security verify-cert本身不弹窗但频繁触发 OS 信任检查在securityd不健康时可能连带弹出系统授权框。portless 在~/.portless下写入一个ca.trusted标记文件内容是 CA 证书内容的SHA-256 指纹writeTrustMarker。下次启动时指纹一致就跳过系统检查从源头减少弹窗干扰。这也是 0.11.0 把状态目录从/tmp迁到~/.portless的动机之一——/tmp会被系统周期性清理标记一丢信任提示就反复出现见 CHANGELOG 记录。重复证书清理delete-certificate 循环与 is ambiguous 难题多次升级、重装、换用户名后钥匙串里可能残留多个同名的 portless Local CA 条目。此时执行security delete-certificate -c portless Local CA会报is ambiguous, matches more than one certificate——它拒绝在有歧义时删除。portless 的清理策略在 untrustCAMacOS 中思路非常实用先security remove-trusted-cert ca.pem摘掉信任标记对登录钥匙串和系统钥匙串各跑一个最多 20 次的循环每次删除一个匹配证书直到命令不再返回歧义错误最后用verify-cert复查确认 CA 已彻底不受信任才宣告成功。# 清理效果的最终判定命令与验证信任时完全对称 security verify-cert -c ca.pem -L -p ssl这个循环到删干净的写法正是针对 GitHub 上反馈的重复证书问题#251 修复记录——旧版本一次delete-certificate撞上歧义就放弃残留证书会在每次升级时继续累积。当 security 命令卡死实用排障清单如果 portless 提示macOS security 命令超时通常不是 portless 的问题而是securityd本身无响应。代码内置的排障提示错误处理给了标准解法重启钥匙串访问退出并重新打开钥匙串访问App终极手段执行sudo killall securityd让守护进程自愈然后重新运行portless trust完成信任写入。此外项目还专门做了假 security 二进制的故障注入测试certs.test.ts确保security命令彻底失败时用户拿到的是可操作的错误信息而不是裸异常。小结一张表看懂 macOS 信任链路环节portless 的做法源码位置找钥匙串security default-keychain 路径回退certs.ts#L512-L529验证信任verify-cert -L -p ssl15s 超时sudo 时切换用户视角certs.ts#L483-L510写入信任普通用户写登录钥匙串弹 Touch ID120sroot 写系统钥匙串certs.ts#L909-L933防重复弹窗ca.trusted指纹标记免重复系统检查certs.ts#L103-L111清理重复证书双钥匙串 × 20 次循环删除 最终复查certs.ts#L1011-L1040权限兜底权限被拒时自动 sudo 提权重试cli.ts#L1975-L1998对新手来说日常只需要记住一条命令信任异常时运行portless trust重新授权彻底不用时运行portless clean让 portless 自动走上面的完整清理流程。更多本地 HTTPS 的细节可参考官方文档 HTTPS 页面。【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
