SwiftPM 包注册表认证：SE-0378 的 login/logout 子命令与凭据存储机制详解

SwiftPM 包注册表认证SE-0378 的 login/logout 子命令与凭据存储机制详解【免费下载链接】swift-evolutionThis maintains proposals for changes and user-visible enhancements to the Swift Programming Language.项目地址: https://gitcode.com/gh_mirrors/sw/swift-evolution本文以 Swift Evolution 提案 SE-0378Package Registry AuthenticationSwift 5.8 已实现为主体系统讲解 Swift Package ManagerSwiftPM如何通过新增的swift package-registry login/logout子命令为包注册表服务提供基本认证Basic与令牌认证Token两种方式。读完本文你将掌握登录/注销命令的完整参数用法、registries.json配置文件中新增的authentication键的格式、macOS Keychain 与用户级 netrc 文件两种凭据存储的差异与选择逻辑以及注册表服务端必须实现的loginAPI 规范。背景为什么 SwiftPM 需要令牌认证从 SE-0292 继承的注册表体系Swift 包注册表Package Registry的概念由 SE-0292Package Registry ServiceSwift 5.7 实现引入。它定义了一套标准化的 REST API让 SwiftPM 不再依赖 Git 克隆而是通过 HTTP 直接获取包GET /{scope}/{name}列出发布版本、GET /{scope}/{name}/{version}/Package.swift获取清单、GET /{scope}/{name}/{version}.zip下载源码归档。在 SE-0292 的原始设计中注册表凭据通过swift package-registry set子命令的--login与--password选项提供凭据被写入项目目录下的.netrc文件并在registries.json的注册表条目中记录一个login键。SE-0378 要解决的三个问题SE-0378 明确指出这套旧方案存在明显局限认证方式单一Web 服务常见的认证方式包括基本认证Basic Authentication、访问令牌Access Token和 OAuth而 SwiftPM 当时只支持基本认证无法与大量采用令牌机制的注册表服务交互。凭据存储不安全旧设计把凭据写进项目级.netrc文件容易被误提交进版本控制库造成敏感信息泄露。命令语义不清晰set --login --password把配置注册表 URL和录入凭据两件事耦合在一起交互体验差。新方案的设计灵感来自docker login和npm login提供一个单一命令让用户校验并持久化注册表凭据同时把凭据存放到操作系统原生的安全凭据存储如 macOS Keychain中。命令变更新增login与logout子命令SE-0378 对swift package-registry命令的改动是用login和logout子命令替代原先 SE-0292 中set子命令配合--login/--password的做法用于添加/移除注册表凭据。login子命令登录到包注册表。SwiftPM 会调用注册表服务的loginAPI 校验凭据校验成功后凭据被持久化到操作系统凭据存储如果支持否则写入用户级 netrc 文件。用户级配置文件~/.swiftpm/configuration/registries.json也会同步更新。完整命令语法如下SYNOPSIS swift package-registry login url [options] OPTIONS: --username Username --password Password --token Access token --no-confirm Allow writing to netrc file without confirmation --netrc-file Specify the netrc file path --netrc Use netrc file even in cases where other credential stores are preferred各参数含义参数说明url注册表的基础 URL如https://example-registry.com如果loginAPI 的位置不是默认的/login如https://example-registry.com/api/v1/login则直接提供完整 URL。URL 必须是 HTTPS。--username用户名基本认证--password密码基本认证--token访问令牌令牌认证--no-confirm允许不经确认直接写入 netrc 文件用于非交互模式--netrc-file指定自定义 netrc 文件路径--netrc即使在其他凭据存储更受青睐的情况下也强制使用 netrc 文件支持两种认证类型各自对应的必填选项如下认证方式必填选项Basic基本认证--username、--passwordToken令牌认证--token认证类型推断与交互提示工具会分析用户提供的选项来判断认证类型如果缺少密码或令牌会进入交互模式进行提示。例如只提供--username时工具假定是基本认证并提示输入密码。非交互模式下则必须显式提供--password或--token或确保密钥已存在于凭据存储中。netrc 写入确认如果操作系统凭据存储不受支持工具在把凭据写入安全性较弱的 netrc 文件前会提示用户确认--no-confirm可跳过该确认。若要强制使用 netrc 文件而非操作系统凭据存储传入--netrc标志即可。logout子命令从注册表注销移除操作系统凭据存储如果支持和用户级配置文件registries.json中的凭据。为避免误删敏感数据netrc 文件需要用户手动更新。SYNOPSIS swift package-registry logout url完整操作示例以下示例完整覆盖了原提案给出的全部典型场景。示例一macOS 基本认证交互式 swift package-registry login https://example-registry.com \ --username jappleseed Enter password for jappleseed: Login successful. Credentials have been saved to the operating systems secure credential store.此时example-registry.com的条目被写入 macOS Keychainregistries.json被更新以表明该注册表需要基本认证{ authentication: { example-registry.com: { type: basic }, ... }, ... }示例二基本认证操作系统无凭据存储交互式 swift package-registry login https://example-registry.com \ --username jappleseed Enter password for jappleseed: Login successful. WARNING: Secure credential store is not supported on this platform. Your credentials will be written out to netrc file. Continue? (Yes/No): Yes Credentials have been saved to netrc file.netrc 文件中的条目为machine example-registry.com login jappleseed password alpineregistries.json同样记录type: basic。示例三基本认证强制使用 netrc交互式 swift package-registry login https://example-registry.com \ --username jappleseed --netrc Enter password for jappleseed: Login successful. WARNING: You choose to use netrc file instead of the operating systems secure credential store. Your credentials will be written out to netrc file. Continue? (Yes/No): Yes Credentials have been saved to netrc file.示例四基本认证无凭据存储非交互式通过--no-confirm跳过确认适合脚本与 CI 场景 swift package-registry login https://example-registry.com \ --username jappleseed \ --password alpine \ --no-confirm Login successful. Credentials have been saved to netrc file.示例五基本认证非默认loginURL非交互式当loginAPI 不在默认的/login路径时直接把完整 URL 作为参数传入 swift package-registry login https://example-registry.com/api/v1/login \ --username jappleseed \ --password alpine \ --no-confirm Login successful. Credentials have been saved to netrc file.此时registries.json会额外记录loginAPIPath{ authentication: { example-registry.com: { type: basic, loginAPIPath: /api/v1/login }, ... }, ... }示例六令牌认证 swift package-registry login https://example-registry.com \ --token jappleseedstokenexample-registry.com的条目被写入操作系统凭据存储若支持否则写入用户级 netrc 文件。令牌在 netrc 中的表示比较特殊——login固定为tokenpassword为访问令牌本身machine example-registry.com login token password jappleseedstokenregistries.json中记录的认证类型为token{ authentication: { example-registry.com: { type: token }, ... }, ... }注册表配置变更registries.json新增authentication键SE-0378 在用户级registries.json文件默认位于~/.swiftpm/configuration/registries.json中引入新的顶级authentication键。任何需要认证的包注册表都必须在该字典中有对应条目。完整格式如下含 JSONC 注释说明{ registries: { [default]: { url: https://example-registry.com } }, authentication: { example-registry.com: { type: AUTHENTICATION_TYPE, // One of: basic, token loginAPIPath: LOGIN_API_PATH // Optional. Overrides the default API path (i.e., /login). } }, version: 1 }配置要点type必须是以下之一basic用户名 密码或token访问令牌。loginAPIPath为可选项用于覆盖默认的 API 路径/login。实际的凭据密码、令牌不存放在此文件中而是存放在操作系统原生凭据存储若支持或用户级 netrc 文件中。初始版本仅支持 macOS Keychain未来可能增加更多存储后端。凭据存储机制详解SwiftPM 始终优先使用平台上最安全的凭据处理方式即操作系统凭据存储如 macOS Keychain只有在没有其他方案可用时才回退到 netrc 文件。基本认证macOS Keychain注册表凭据应存储为 Keychain 中的 Internet password 条目其 item name 为包含https://的注册表 URL如https://example-registry.com。netrc 文件当操作系统凭据存储不受支持时基本认证的 netrc 条目格式为machine example-registry.com login jappleseed password alpine默认情况下SwiftPM 在用户主目录中查找 netrc 文件可通过--netrc-file选项指定自定义路径。令牌认证令牌的配置方式与基本认证类似区别在于 netrc 的 login/username 固定写为tokenpassword 位置放访问令牌machine example-registry.com login token password jappleseedstokenSwiftPM 的其他行为变更SE-0378 还对 SwiftPM 的凭据处理行为做了三点收紧只使用用户级 netrc 文件不再支持项目级 netrc 文件。每次只在一个凭据存储中查找macOS 用 Keychain其他所有平台用用户级 netrc 文件不做跨存储回退。移除--disable-keychain和--disable-netrc选项简化了以往可以显式开关凭据存储的行为。注册表服务端必须实现的loginAPI一个需要认证的包注册表必须实现本节描述的新 API 端点。请求格式SwiftPM 通过login子命令校验用户凭据时会向该端点发送HTTPPOST请求。默认 API 路径为/login可通过向login子命令传入完整 API URL 覆盖见示例五。请求中携带的AuthorizationHTTP 头按认证方式构造基本认证Authorization: Basic base64 编码的 username:password令牌认证Authorization: Bearer token响应语义HTTP 状态码含义200登录成功SwiftPM 会将凭据持久化到本地凭据存储401凭据无效登录失败501注册表服务不支持该认证方法这一约定与 SE-0292 定义的注册表 REST 接口GET /{scope}/{name}等是同一套 HTTP 体系内的自然延伸作为佐证SE-0391Package Registry PublishSwift 5.8 同版本实现在描述swift package-registry publish子命令时也明确把先运行swift package-registry login认证注册表用户列为发布包的前置条件。安全考量SE-0378 在安全上的核心收益有两点迁移到操作系统原生凭据存储在受支持的平台上macOS Keychain凭据不再以明文形式散落在文件系统中安全性显著提升。消除项目级 netrc 文件旧设计中凭据可能被写入项目目录下的.netrc一旦随代码提交进 Git 仓库就会泄露SE-0378 彻底移除了这一路径。此外login命令强制要求注册表 URL 使用 HTTPS保证凭据在传输过程中加密令牌以Bearer方案传输与服务端常见的 OAuth 2.0 风格授权机制兼容。对现有包的影响该提案对现有包几乎没有影响唯一的行为变化是移除了项目级 netrc 文件的使用。已经通过 Git 拉取依赖、不使用注册表认证的包无需任何改动。需要留意的是如果你之前依赖 SE-0292 的swift package-registry set --login/--password写入项目级.netrc升级到 Swift 5.8 后应改用swift package-registry login并注意凭据现在只会写入用户级存储。与其他提案的关联SE-0292Package Registry Service定义了注册表 REST 接口与registries.json配置体系SE-0378 在其基础上新增认证能力并修正了set子命令携带凭据的旧设计。SE-0391Package Registry Publish发布包时要求先完成swift package-registry login说明认证机制是注册表发布/消费完整链路的基础设施。SE-0549HTTP 代理配置该提案在描述未来方向时明确认证代理的支持将复用 SPM 现有的安全凭据存储macOS 用 Keychain其他平台用.netrc——这正是 SE-0378 建立的凭据存储体系可见其已成为 SwiftPM 网络栈的统一凭据基础。综上SE-0378 以两个新子命令、一个authentication配置键、两级凭据存储和一个服务端loginAPI完整补齐了 SwiftPM 与私有/受保护包注册表之间的认证闭环是理解 Swift 包注册表生态发布、消费、私有依赖必不可少的一环。【免费下载链接】swift-evolutionThis maintains proposals for changes and user-visible enhancements to the Swift Programming Language.项目地址: https://gitcode.com/gh_mirrors/sw/swift-evolution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考