證機(jī)制詳解：auth.json 配置、GitHub / Azure DevOps 鑒權(quán)與憑證安全)
Specify CLI 認(rèn)證機(jī)制詳解auth.json 配置、GitHub / Azure DevOps 鑒權(quán)與憑證安全【免費(fèi)下載鏈接】spec-kit Toolkit to help you get started with Spec-Driven Development項(xiàng)目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit本文基于 spec-kit 倉庫的認(rèn)證參考文檔完整講解 Specify CLI 的 opt-in顯式啟用認(rèn)證機(jī)制如何編寫~/.specify/auth.json、hosts/provider/auth等字段的取值與校驗(yàn)規(guī)則、GitHub 與 Azure DevOps 各類認(rèn)證方案bearer、basic-pat、azure-cli、azure-ad的配置示例以及憑證匹配、401/403 回退與重定向憑證剝離的底層實(shí)現(xiàn)。讀完后你可以為公共 GitHub、GitHub Enterprise Server 或 Azure DevOps 私有目錄catalog/擴(kuò)展extension/預(yù)設(shè)preset下載正確配置憑據(jù)并理解其安全邊界。1. 設(shè)計(jì)原則不配置即不發(fā)送憑據(jù)Specify CLI 對(duì)目錄源 HTTP 請(qǐng)求、擴(kuò)展下載和版本發(fā)布檢查均采用**可選認(rèn)證opt-in authentication**模型只有當(dāng)你顯式創(chuàng)建~/.specify/auth.json時(shí)CLI 才會(huì)向?qū)?yīng)主機(jī)附加Authorization頭該文件不存在時(shí)所有 HTTP 請(qǐng)求均以未認(rèn)證方式發(fā)出配置文件中“哪些主機(jī) 哪個(gè) provider 哪種認(rèn)證方案”由你聲明provider 類定義“如何認(rèn)證”Bearer、Basic-PAT 等。這一模型在 src/specify_cli/authentication/init.py 的模塊 docstring 中被明確陳述其內(nèi)置 provider 注冊(cè)表AUTH_REGISTRY通過_register_builtins()注冊(cè)了github與azure-devops兩個(gè)內(nèi)置 provider。2. 配置文件結(jié)構(gòu)認(rèn)證配置全部集中在用戶主目錄下的單個(gè) JSON 文件中mkdir -p ~/.specify # 將下文 JSON 寫入 ~/.specify/auth.json chmod 600 ~/.specify/auth.json最小可用的 GitHub 配置{ providers: [ { hosts: [github.com, api.github.com, raw.githubusercontent.com, codeload.github.com], provider: github, auth: bearer, token_env: GH_TOKEN } ] }安全提示建議將文件權(quán)限收緊為僅屬主可讀寫chmod 600。這一點(diǎn)并非只是文檔建議——從源碼看config.py 在加載配置時(shí)會(huì)檢查文件權(quán)限位若在 POSIX 系統(tǒng)上該文件對(duì) group/others 可讀會(huì)發(fā)出UserWarning提醒執(zhí)行chmod 600但不會(huì)因此失敗。2.1 字段參考providers數(shù)組中每個(gè)條目的通用字段字段必填說明hosts是該條目適用的主機(jī)名數(shù)組。僅支持精確主機(jī)名或以*.開頭的子域通配如*.visualstudio.com。*.visualstudio.com匹配foo.visualstudio.com但不匹配visualstudio.com本身。*github.com、gith?b.com等其他 glob 模式不被支持會(huì)在加載時(shí)被拒絕。provider是內(nèi)置 provider 鍵github或azure-devops。auth是認(rèn)證方案見下節(jié)。token否內(nèi)聯(lián) token 值?？赡軙r(shí)優(yōu)先使用token_env。token_env否存放 token 的環(huán)境變量名。azure-ad方案額外要求三個(gè)字段字段必填說明tenant_id是Azure AD 租戶 ID。client_id是服務(wù)主體service principal客戶端 ID。client_secret_env是存放 client secret 的環(huán)境變量名。bearer與basic-pat方案必須至少設(shè)置token或token_env之一。2.2 源碼中的校驗(yàn)規(guī)則load_auth_config() 對(duì)配置的約束比文檔表格更具體了解它們可以避免配置不生效host 模式白名單_is_valid_host_pattern()只接受兩種形式——精確主機(jī)名和*.suffix。它顯式拒絕含?、[、]的模式以及*出現(xiàn)在其他位置的寫法。注釋中說明動(dòng)機(jī)*github.com會(huì)匹配github.com.evil.com這類危險(xiǎn)形式因此必須禁用。歸一化所有hosts值在存儲(chǔ)前會(huì)被strip().lower()token_env、tenant_id、client_id、client_secret_env等字符串引用字段經(jīng)_norm()去除首尾空白防止“驗(yàn)證通過但環(huán)境變量查不到”的靜默故障。provider/scheme 兼容性未知provider或該 provider 不支持的auth值會(huì)拋出ValueError錯(cuò)誤信息會(huì)列出已注冊(cè)的 provider 或該 provider 支持的方案列表。schema 違規(guī)的容錯(cuò)策略文件不存在返回空列表即全部未認(rèn)證請(qǐng)求JSON 結(jié)構(gòu)錯(cuò)誤則拋ValueError而更高層的 HTTP 輔助函數(shù)會(huì)捕獲它、告警后繼續(xù)以未認(rèn)證方式運(yùn)行見 http.py 的_load_config()配置按進(jìn)程緩存文件最多讀取一次。3. Provider 與認(rèn)證方案3.1 GitHubgithub方案請(qǐng)求頭適用場景bearerAuthorization: Bearer tokenPAT、細(xì)粒度 PATfine-grained PAT、OAuth token、GitHub App tokenGitHubAuth 類只聲明了key github與supported_auth_schemes (bearer,)其auth_headers()對(duì)非bearer方案直接拋ValueErrortoken 解析則繼承基類默認(rèn)邏輯優(yōu)先讀entry.token否則讀token_env指定的環(huán)境變量并對(duì)值做strip()。示例 — 通過環(huán)境變量注入 PAT{ hosts: [github.com, api.github.com, raw.githubusercontent.com, codeload.github.com], provider: github, auth: bearer, token_env: GH_TOKEN }3.2 GitHub Enterprise ServerGHES若目錄或擴(kuò)展托管在自管的 GHES 實(shí)例上只需添加一條github條目列出該實(shí)例的主機(jī)名。同一條目既用于認(rèn)證 catalog JSON 拉取也用于私有 release 資產(chǎn)下載——Specify 會(huì)識(shí)別這些主機(jī)為 GitHub Enterprise并將 release 下載解析到 GHES REST API/api/v3。{ providers: [ { hosts: [ghes.example.com, raw.ghes.example.com, codeload.ghes.example.com], provider: github, auth: bearer, token_env: GH_ENTERPRISE_TOKEN } ] }配置要點(diǎn)必須列出裸 web 主機(jī)如ghes.example.com因?yàn)?release 下載 URL 就掛在它下面若實(shí)例使用子域隔離還要把 catalog/擴(kuò)展 URL 實(shí)際用到的raw.、codeload.子域一并列出*.ghes.example.com通配只匹配子域、不匹配裸主機(jī)因此裸主機(jī)必須顯式列出。源碼側(cè)可以印證這一機(jī)制http.py 的github_provider_hosts()會(huì)收集auth.json中所有g(shù)ithubprovider 條目的hosts供 resolve_github_release_asset_api_url() 使用。該函數(shù)把瀏覽器式下載 URLhttps://host/owner/repo/releases/download/tag/asset解析為 REST API 資產(chǎn) URL主機(jī)是否按 GHES 處理正是由這份白名單決定——未列入的主機(jī)不會(huì)被當(dāng)作 GHES從而阻止惡意 catalog 誘導(dǎo)向任意主機(jī)發(fā)起 API 請(qǐng)求。擴(kuò)展、預(yù)設(shè)、workflow 的安裝路徑如 extensions/__init__.py、presets/__init__.py、commands/bundle/__init__.py都通過傳入github_provider_hosts()復(fù)用這一邏輯。3.3 Azure DevOpsazure-devopsAzureDevOpsAuth 支持四種方案方案請(qǐng)求頭適用場景basic-patAuthorization: Basic base64(:PAT)個(gè)人訪問令牌PATbearerAuthorization: Bearer token預(yù)先獲取的 OAuth / Azure AD tokenazure-cliAuthorization: Bearer token通過az account get-access-token獲取 tokenazure-adAuthorization: Bearer token通過 OAuth2 client credentials 流程獲取 token示例 — 環(huán)境變量注入 PAT{ hosts: [dev.azure.com], provider: azure-devops, auth: basic-pat, token_env: AZURE_DEVOPS_PAT }示例 — Azure CLI交互式登錄{ hosts: [dev.azure.com], provider: azure-devops, auth: azure-cli }要求此前已執(zhí)行az login。從源碼看_acquire_via_az_cli()會(huì)以 30 秒超時(shí)執(zhí)行az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --output json并解析accessToken字段它特意用shutil.which尊重 Windows 的PATHEXT解析出絕對(duì)路徑的az避免工作目錄中一個(gè)名為az.cmd的惡意文件被當(dāng)成憑證操作執(zhí)行——任何失敗都會(huì)返回None并回退到下一個(gè)策略而不是拋出異常。示例 — Azure AD 服務(wù)主體CI/自動(dòng)化{ hosts: [dev.azure.com], provider: azure-devops, auth: azure-ad, tenant_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, client_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, client_secret_env: AZURE_CLIENT_SECRET }_acquire_via_client_credentials()會(huì)向https://login.microsoftonline.com/tenant_id/oauth2/v2.0/token發(fā)起 POST請(qǐng)求client_credentials授權(quán)與499b84ac-1321-427f-aa17-267ca6975798/.default作用域。該請(qǐng)求有三層防護(hù)拒絕一切 307/308 重定向否則 POST 體中的client_secret會(huì)被原樣轉(zhuǎn)發(fā)到別處響應(yīng)經(jīng)read_response_limited按上限讀取超大響應(yīng)視為失敗網(wǎng)絡(luò)故障、JSON 解析失敗等一律返回None落入回退。4. 多條目配置可以同時(shí)配置多個(gè)條目以覆蓋不同主機(jī)或組織條目按數(shù)組順序匹配{ providers: [ { hosts: [github.com, api.github.com, raw.githubusercontent.com, codeload.github.com], provider: github, auth: bearer, token_env: GH_TOKEN }, { hosts: [dev.azure.com], provider: azure-devops, auth: basic-pat, token_env: AZURE_DEVOPS_PAT } ] }5. 工作機(jī)制與源碼級(jí)實(shí)現(xiàn)文檔描述的運(yùn)行時(shí)行為可概括為五步下面逐條對(duì)照 src/specify_cli/authentication/http.py 的實(shí)現(xiàn)主機(jī)匹配每個(gè)出站請(qǐng)求先用 find_entries_for_url() 解析 URL 的 hostname與auth.json中各條目的hosts模式比對(duì)*.前綴通配對(duì)hostname.endswith(pattern[1:])求值因此只匹配子域?；?authority如未閉合的 IPv6 方括號(hào)被視為無主機(jī)名返回空匹配而非拋異常。附加憑證命中后由對(duì)應(yīng) provider 的resolve_token()取 tokenauth_headers()構(gòu)造Authorization頭。build_request()中有一個(gè)防繞過細(xì)節(jié)extra_headers里的Authorization鍵會(huì)被剝除認(rèn)證頭最后合并外部無法覆蓋。401/403 回退open_url() 遍歷所有匹配條目某一輪收到 401/403 時(shí)關(guān)閉響應(yīng)、嘗試下一條目其他錯(cuò)誤404、500、網(wǎng)絡(luò)錯(cuò)誤立即拋出。未認(rèn)證兜底所有條目用盡或無匹配后以無認(rèn)證請(qǐng)求作為最后回退。重定向憑證剝離每次嘗試都安裝隔離的 opener 并掛上_StripAuthOnRedirect處理器。重定向時(shí)它會(huì)校驗(yàn)?zāi)繕?biāo)必須為帶主機(jī)名的 HTTPS僅允許環(huán)回地址之間使用 HTTP若新主機(jī)不在該條目的聲明主機(jī)內(nèi)、或發(fā)生 HTTPS→HTTP 降級(jí)則從請(qǐng)求和unredirected_hdrs中同時(shí)移除Authorization防止憑據(jù)泄漏到 CDN 或第三方服務(wù)目標(biāo) URL 畸形則拋URLError交由上層下載錯(cuò)誤處理。隔離 opener 的動(dòng)機(jī)是代碼注釋中說明的open_url()每次自建 opener使得進(jìn)程中若有全局urllib.request.install_opener也無法替換掉重定向守衛(wèi)。6. 與其他鑒權(quán)路徑的關(guān)系倉庫中另有一條獨(dú)立的輕量路徑build_github_request() 直接讀取GITHUB_TOKEN/GH_TOKEN環(huán)境變量但只針對(duì)內(nèi)置的四個(gè) GitHub 官方域名GITHUB_HOSTSgithub.com、api.github.com、raw.githubusercontent.com、codeload.github.com附加 Bearer 頭非 GitHub 主機(jī)一律不加避免向第三方主機(jī)泄漏憑據(jù)。從源碼結(jié)構(gòu)看配置驅(qū)動(dòng)的open_url()/build_request()是擴(kuò)展、預(yù)設(shè)、bundle、workflow 安裝時(shí)下載資產(chǎn)的主通道tests/test_authentication.py及tests/http_helpers.py對(duì)其行為有測試覆蓋而build_github_request()服務(wù)于對(duì) GitHub 官方域名的簡單請(qǐng)求場景。7. 快速上手模板一份預(yù)置 GitHub 配置的參考auth.json{ providers: [ { hosts: [ github.com, api.github.com, raw.githubusercontent.com, codeload.github.com ], provider: github, auth: bearer, token_env: GH_TOKEN } ] }啟用步驟mkdir -p ~/.specify # 將上方 JSON 復(fù)制到 ~/.specify/auth.json chmod 600 ~/.specify/auth.json # 使用前確保 GH_TOKEN 已導(dǎo)出小結(jié)spec-kit 的認(rèn)證體系圍繞單一事實(shí)源~/.specify/auth.json展開以主機(jī)白名單控制憑據(jù)作用范圍以 provider/scheme 雙層鍵約束認(rèn)證方式并在請(qǐng)求鏈路上實(shí)現(xiàn)了 401/403 逐條目回退、未認(rèn)證兜底、重定向剝離與跨域防泄漏等安全行為。對(duì)使用公共 GitHub 的用戶最小配置即是一條bearertoken_env條目對(duì) GHES 用戶額外列出裸主機(jī)即可同時(shí)打通 catalog 拉取與私有 release 下載對(duì) Azure DevOps 用戶則可根據(jù)交互或 CI 場景在basic-pat、azure-cli、azure-ad三種動(dòng)態(tài)/靜態(tài)方案中選擇。【免費(fèi)下載鏈接】spec-kit Toolkit to help you get started with Spec-Driven Development項(xiàng)目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Specify CLI 認(rèn)證機(jī)制詳解：auth.json 配置、GitHub / Azure DevOps 鑒權(quán)與憑證安全
Specify CLI 認(rèn)證機(jī)制詳解auth.json 配置、GitHub / Azure DevOps 鑒權(quán)與憑證安全【免費(fèi)下載鏈接】spec-kit Toolkit to help you get started with Spec-Driven Development項(xiàng)目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit本文基于 spec-kit 倉庫的認(rèn)證參考文檔完整講解 Specify CLI 的 opt-in顯式啟用認(rèn)證機(jī)制如何編寫~/.specify/auth.json、hosts/provider/auth等字段的取值與校驗(yàn)規(guī)則、GitHub 與 Azure DevOps 各類認(rèn)證方案bearer、basic-pat、azure-cli、azure-ad的配置示例以及憑證匹配、401/403 回退與重定向憑證剝離的底層實(shí)現(xiàn)。讀完后你可以為公共 GitHub、GitHub Enterprise Server 或 Azure DevOps 私有目錄catalog/擴(kuò)展extension/預(yù)設(shè)preset下載正確配置憑據(jù)并理解其安全邊界。1. 設(shè)計(jì)原則不配置即不發(fā)送憑據(jù)Specify CLI 對(duì)目錄源 HTTP 請(qǐng)求、擴(kuò)展下載和版本發(fā)布檢查均采用**可選認(rèn)證opt-in authentication**模型只有當(dāng)你顯式創(chuàng)建~/.specify/auth.json時(shí)CLI 才會(huì)向?qū)?yīng)主機(jī)附加Authorization頭該文件不存在時(shí)所有 HTTP 請(qǐng)求均以未認(rèn)證方式發(fā)出配置文件中“哪些主機(jī) 哪個(gè) provider 哪種認(rèn)證方案”由你聲明provider 類定義“如何認(rèn)證”Bearer、Basic-PAT 等。這一模型在 src/specify_cli/authentication/init.py 的模塊 docstring 中被明確陳述其內(nèi)置 provider 注冊(cè)表AUTH_REGISTRY通過_register_builtins()注冊(cè)了github與azure-devops兩個(gè)內(nèi)置 provider。2. 配置文件結(jié)構(gòu)認(rèn)證配置全部集中在用戶主目錄下的單個(gè) JSON 文件中mkdir -p ~/.specify # 將下文 JSON 寫入 ~/.specify/auth.json chmod 600 ~/.specify/auth.json最小可用的 GitHub 配置{ providers: [ { hosts: [github.com, api.github.com, raw.githubusercontent.com, codeload.github.com], provider: github, auth: bearer, token_env: GH_TOKEN } ] }安全提示建議將文件權(quán)限收緊為僅屬主可讀寫chmod 600。這一點(diǎn)并非只是文檔建議——從源碼看config.py 在加載配置時(shí)會(huì)檢查文件權(quán)限位若在 POSIX 系統(tǒng)上該文件對(duì) group/others 可讀會(huì)發(fā)出UserWarning提醒執(zhí)行chmod 600但不會(huì)因此失敗。2.1 字段參考providers數(shù)組中每個(gè)條目的通用字段字段必填說明hosts是該條目適用的主機(jī)名數(shù)組。僅支持精確主機(jī)名或以*.開頭的子域通配如*.visualstudio.com。*.visualstudio.com匹配foo.visualstudio.com但不匹配visualstudio.com本身。*github.com、gith?b.com等其他 glob 模式不被支持會(huì)在加載時(shí)被拒絕。provider是內(nèi)置 provider 鍵github或azure-devops。auth是認(rèn)證方案見下節(jié)。token否內(nèi)聯(lián) token 值?？赡軙r(shí)優(yōu)先使用token_env。token_env否存放 token 的環(huán)境變量名。azure-ad方案額外要求三個(gè)字段字段必填說明tenant_id是Azure AD 租戶 ID。client_id是服務(wù)主體service principal客戶端 ID。client_secret_env是存放 client secret 的環(huán)境變量名。bearer與basic-pat方案必須至少設(shè)置token或token_env之一。2.2 源碼中的校驗(yàn)規(guī)則load_auth_config() 對(duì)配置的約束比文檔表格更具體了解它們可以避免配置不生效host 模式白名單_is_valid_host_pattern()只接受兩種形式——精確主機(jī)名和*.suffix。它顯式拒絕含?、[、]的模式以及*出現(xiàn)在其他位置的寫法。注釋中說明動(dòng)機(jī)*github.com會(huì)匹配github.com.evil.com這類危險(xiǎn)形式因此必須禁用。歸一化所有hosts值在存儲(chǔ)前會(huì)被strip().lower()token_env、tenant_id、client_id、client_secret_env等字符串引用字段經(jīng)_norm()去除首尾空白防止“驗(yàn)證通過但環(huán)境變量查不到”的靜默故障。provider/scheme 兼容性未知provider或該 provider 不支持的auth值會(huì)拋出ValueError錯(cuò)誤信息會(huì)列出已注冊(cè)的 provider 或該 provider 支持的方案列表。schema 違規(guī)的容錯(cuò)策略文件不存在返回空列表即全部未認(rèn)證請(qǐng)求JSON 結(jié)構(gòu)錯(cuò)誤則拋ValueError而更高層的 HTTP 輔助函數(shù)會(huì)捕獲它、告警后繼續(xù)以未認(rèn)證方式運(yùn)行見 http.py 的_load_config()配置按進(jìn)程緩存文件最多讀取一次。3. Provider 與認(rèn)證方案3.1 GitHubgithub方案請(qǐng)求頭適用場景bearerAuthorization: Bearer tokenPAT、細(xì)粒度 PATfine-grained PAT、OAuth token、GitHub App tokenGitHubAuth 類只聲明了key github與supported_auth_schemes (bearer,)其auth_headers()對(duì)非bearer方案直接拋ValueErrortoken 解析則繼承基類默認(rèn)邏輯優(yōu)先讀entry.token否則讀token_env指定的環(huán)境變量并對(duì)值做strip()。示例 — 通過環(huán)境變量注入 PAT{ hosts: [github.com, api.github.com, raw.githubusercontent.com, codeload.github.com], provider: github, auth: bearer, token_env: GH_TOKEN }3.2 GitHub Enterprise ServerGHES若目錄或擴(kuò)展托管在自管的 GHES 實(shí)例上只需添加一條github條目列出該實(shí)例的主機(jī)名。同一條目既用于認(rèn)證 catalog JSON 拉取也用于私有 release 資產(chǎn)下載——Specify 會(huì)識(shí)別這些主機(jī)為 GitHub Enterprise并將 release 下載解析到 GHES REST API/api/v3。{ providers: [ { hosts: [ghes.example.com, raw.ghes.example.com, codeload.ghes.example.com], provider: github, auth: bearer, token_env: GH_ENTERPRISE_TOKEN } ] }配置要點(diǎn)必須列出裸 web 主機(jī)如ghes.example.com因?yàn)?release 下載 URL 就掛在它下面若實(shí)例使用子域隔離還要把 catalog/擴(kuò)展 URL 實(shí)際用到的raw.、codeload.子域一并列出*.ghes.example.com通配只匹配子域、不匹配裸主機(jī)因此裸主機(jī)必須顯式列出。源碼側(cè)可以印證這一機(jī)制http.py 的github_provider_hosts()會(huì)收集auth.json中所有g(shù)ithubprovider 條目的hosts供 resolve_github_release_asset_api_url() 使用。該函數(shù)把瀏覽器式下載 URLhttps://host/owner/repo/releases/download/tag/asset解析為 REST API 資產(chǎn) URL主機(jī)是否按 GHES 處理正是由這份白名單決定——未列入的主機(jī)不會(huì)被當(dāng)作 GHES從而阻止惡意 catalog 誘導(dǎo)向任意主機(jī)發(fā)起 API 請(qǐng)求。擴(kuò)展、預(yù)設(shè)、workflow 的安裝路徑如 extensions/__init__.py、presets/__init__.py、commands/bundle/__init__.py都通過傳入github_provider_hosts()復(fù)用這一邏輯。3.3 Azure DevOpsazure-devopsAzureDevOpsAuth 支持四種方案方案請(qǐng)求頭適用場景basic-patAuthorization: Basic base64(:PAT)個(gè)人訪問令牌PATbearerAuthorization: Bearer token預(yù)先獲取的 OAuth / Azure AD tokenazure-cliAuthorization: Bearer token通過az account get-access-token獲取 tokenazure-adAuthorization: Bearer token通過 OAuth2 client credentials 流程獲取 token示例 — 環(huán)境變量注入 PAT{ hosts: [dev.azure.com], provider: azure-devops, auth: basic-pat, token_env: AZURE_DEVOPS_PAT }示例 — Azure CLI交互式登錄{ hosts: [dev.azure.com], provider: azure-devops, auth: azure-cli }要求此前已執(zhí)行az login。從源碼看_acquire_via_az_cli()會(huì)以 30 秒超時(shí)執(zhí)行az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --output json并解析accessToken字段它特意用shutil.which尊重 Windows 的PATHEXT解析出絕對(duì)路徑的az避免工作目錄中一個(gè)名為az.cmd的惡意文件被當(dāng)成憑證操作執(zhí)行——任何失敗都會(huì)返回None并回退到下一個(gè)策略而不是拋出異常。示例 — Azure AD 服務(wù)主體CI/自動(dòng)化{ hosts: [dev.azure.com], provider: azure-devops, auth: azure-ad, tenant_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, client_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, client_secret_env: AZURE_CLIENT_SECRET }_acquire_via_client_credentials()會(huì)向https://login.microsoftonline.com/tenant_id/oauth2/v2.0/token發(fā)起 POST請(qǐng)求client_credentials授權(quán)與499b84ac-1321-427f-aa17-267ca6975798/.default作用域。該請(qǐng)求有三層防護(hù)拒絕一切 307/308 重定向否則 POST 體中的client_secret會(huì)被原樣轉(zhuǎn)發(fā)到別處響應(yīng)經(jīng)read_response_limited按上限讀取超大響應(yīng)視為失敗網(wǎng)絡(luò)故障、JSON 解析失敗等一律返回None落入回退。4. 多條目配置可以同時(shí)配置多個(gè)條目以覆蓋不同主機(jī)或組織條目按數(shù)組順序匹配{ providers: [ { hosts: [github.com, api.github.com, raw.githubusercontent.com, codeload.github.com], provider: github, auth: bearer, token_env: GH_TOKEN }, { hosts: [dev.azure.com], provider: azure-devops, auth: basic-pat, token_env: AZURE_DEVOPS_PAT } ] }5. 工作機(jī)制與源碼級(jí)實(shí)現(xiàn)文檔描述的運(yùn)行時(shí)行為可概括為五步下面逐條對(duì)照 src/specify_cli/authentication/http.py 的實(shí)現(xiàn)主機(jī)匹配每個(gè)出站請(qǐng)求先用 find_entries_for_url() 解析 URL 的 hostname與auth.json中各條目的hosts模式比對(duì)*.前綴通配對(duì)hostname.endswith(pattern[1:])求值因此只匹配子域?；?authority如未閉合的 IPv6 方括號(hào)被視為無主機(jī)名返回空匹配而非拋異常。附加憑證命中后由對(duì)應(yīng) provider 的resolve_token()取 tokenauth_headers()構(gòu)造Authorization頭。build_request()中有一個(gè)防繞過細(xì)節(jié)extra_headers里的Authorization鍵會(huì)被剝除認(rèn)證頭最后合并外部無法覆蓋。401/403 回退open_url() 遍歷所有匹配條目某一輪收到 401/403 時(shí)關(guān)閉響應(yīng)、嘗試下一條目其他錯(cuò)誤404、500、網(wǎng)絡(luò)錯(cuò)誤立即拋出。未認(rèn)證兜底所有條目用盡或無匹配后以無認(rèn)證請(qǐng)求作為最后回退。重定向憑證剝離每次嘗試都安裝隔離的 opener 并掛上_StripAuthOnRedirect處理器。重定向時(shí)它會(huì)校驗(yàn)?zāi)繕?biāo)必須為帶主機(jī)名的 HTTPS僅允許環(huán)回地址之間使用 HTTP若新主機(jī)不在該條目的聲明主機(jī)內(nèi)、或發(fā)生 HTTPS→HTTP 降級(jí)則從請(qǐng)求和unredirected_hdrs中同時(shí)移除Authorization防止憑據(jù)泄漏到 CDN 或第三方服務(wù)目標(biāo) URL 畸形則拋URLError交由上層下載錯(cuò)誤處理。隔離 opener 的動(dòng)機(jī)是代碼注釋中說明的open_url()每次自建 opener使得進(jìn)程中若有全局urllib.request.install_opener也無法替換掉重定向守衛(wèi)。6. 與其他鑒權(quán)路徑的關(guān)系倉庫中另有一條獨(dú)立的輕量路徑build_github_request() 直接讀取GITHUB_TOKEN/GH_TOKEN環(huán)境變量但只針對(duì)內(nèi)置的四個(gè) GitHub 官方域名GITHUB_HOSTSgithub.com、api.github.com、raw.githubusercontent.com、codeload.github.com附加 Bearer 頭非 GitHub 主機(jī)一律不加避免向第三方主機(jī)泄漏憑據(jù)。從源碼結(jié)構(gòu)看配置驅(qū)動(dòng)的open_url()/build_request()是擴(kuò)展、預(yù)設(shè)、bundle、workflow 安裝時(shí)下載資產(chǎn)的主通道tests/test_authentication.py及tests/http_helpers.py對(duì)其行為有測試覆蓋而build_github_request()服務(wù)于對(duì) GitHub 官方域名的簡單請(qǐng)求場景。7. 快速上手模板一份預(yù)置 GitHub 配置的參考auth.json{ providers: [ { hosts: [ github.com, api.github.com, raw.githubusercontent.com, codeload.github.com ], provider: github, auth: bearer, token_env: GH_TOKEN } ] }啟用步驟mkdir -p ~/.specify # 將上方 JSON 復(fù)制到 ~/.specify/auth.json chmod 600 ~/.specify/auth.json # 使用前確保 GH_TOKEN 已導(dǎo)出小結(jié)spec-kit 的認(rèn)證體系圍繞單一事實(shí)源~/.specify/auth.json展開以主機(jī)白名單控制憑據(jù)作用范圍以 provider/scheme 雙層鍵約束認(rèn)證方式并在請(qǐng)求鏈路上實(shí)現(xiàn)了 401/403 逐條目回退、未認(rèn)證兜底、重定向剝離與跨域防泄漏等安全行為。對(duì)使用公共 GitHub 的用戶最小配置即是一條bearertoken_env條目對(duì) GHES 用戶額外列出裸主機(jī)即可同時(shí)打通 catalog 拉取與私有 release 下載對(duì) Azure DevOps 用戶則可根據(jù)交互或 CI 場景在basic-pat、azure-cli、azure-ad三種動(dòng)態(tài)/靜態(tài)方案中選擇。【免費(fèi)下載鏈接】spec-kit Toolkit to help you get started with Spec-Driven Development項(xiàng)目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考