pi-codex-marketplace 0.4.0 → 0.6.0

package/README.md

@@ -37,7 +37,7 @@ Nine subcommands, no arguments = 總覽：
 
 | 子命令 | 行為 |
 |--------|------|
-| `add <路徑\|網址>` | 註冊 marketplace（本機資料夾、GitHub 完整網址、`owner/repo` 簡寫皆收），自動偵測 codex／claude 格式並告知 `偵測：<format> marketplace · N plugins`。重複註冊同來源被拒絕並提示下一步。Git 來源以安全線取得（`core.hooksPath=/dev/null`、`GIT_LFS_SKIP_SMUDGE=1`、`GIT_TERMINAL_PROMPT=0`），catalog 解析失敗明示錯誤、不註冊。 |
+| `add <路徑\|網址>` | 註冊 marketplace（本機資料夾、GitHub 完整網址、`owner/repo` 簡寫皆收），自動偵測 codex／claude 格式並告知 `偵測：<format> marketplace · N plugins`。重複註冊同來源被拒絕並提示下一步。Git 來源以安全線取得（`core.hooksPath=/dev/null`、`GIT_LFS_SKIP_SMUDGE=1`、`GIT_TERMINAL_PROMPT=0`），catalog 解析失敗明示錯誤、不註冊。私有 HTTPS repo **開箱即用**：自動偵測本機憑證來源（`gh` 登入／macOS 鑰匙圈／`credential-store`）並逐次核准；也可用 `PI_CODEX_MARKETPLACE_CREDENTIAL_HELPERS` 顯式覆蓋核准清單（逐次生效、永不持久化），或改用 SSH 定位器；用法與範例見下方〈私有 Git repo：Credentialed Acquisition〉。 |
 | `list [名稱]` | 列出 plugins（編號／所屬 marketplace／狀態：可安裝・已裝啟用・已裝停用・unavailable＋原因），可帶 marketplace 名稱過濾。 |
 | `install <編號\|名稱>` | 裝到**當下最新**並自動啟用＋reload。成功話術如 `安裝 "name"（N skills：a, b, c）· 已重新載入生效`；同名衝突列出 `⚠ skill "b" 與既有同名，未投影（名稱衝突）`。**重複安裝＝重抓最新覆寫**（重裝＝更新，不報錯）。 |
 | `update` | 對全部已註冊 marketplace 重抓最新：有變化的 plugin 升到最新、無變化各自顯示「無變化」；整體以「已重新載入生效」收尾（有變時）。 |
@@ -53,6 +53,46 @@ Nine subcommands, no arguments = 總覽：
 - 安裝成功後由指令層主動要求 reload；reload 失敗不影響已記錄狀態，下次 session start 或 `/reload` 仍生效。
 - `--no-skills` 啟動 Pi 不影響 Bridge 投影。
 
+### 私有 Git repo：Credentialed Acquisition（核准式取得）
+
+對私有 HTTPS repo，`add`／`update` **開箱即用**：預設會自動偵測本機已存在的憑證來源並逐次核准（**固定白名單**，不讀本機 gitconfig 的任意 helper；偵測結果只限該次呼叫、永不持久化）：
+
+| 偵測來源 | 核准的 credential helper |
+|---|---|
+| `gh` CLI 已登入（`gh auth status` 成功） | `!gh auth git-credential` |
+| macOS 原生鑰匙圈 helper 存在 | `osxkeychain` |
+| git `credential-store` 存在 | `store`（明文憑證檔，請知悉風險） |
+
+已註冊或欲手動控制時，以逗號分隔設定環境變數——**顯式設定完全覆蓋自動偵測**（逐次生效、永不持久化，`add` 與 `update` 共用同一核准來源）：
+
+```
+PI_CODEX_MARKETPLACE_CREDENTIAL_HELPERS='store, !f() { echo "username=${GITHUB_USER}"; echo "password=${GITHUB_TOKEN}"; }; f'
+/codex-marketplace add https://github.com/acme/private-mkt
+```
+
+Credentialed Acquisition 語意（安全線）：
+
+- 預設（未設 env）＝自動偵測固定白名單（gh／osxkeychain／store），僅限該次呼叫：**不寫入** Bridge State、設定檔或任何持久化位置；偵測到的 helper 以命令列 `credential.helper=` 傳入，gitconfig 的其他 helper（含 URL-scoped）仍被排除。
+- 設定 env 後完全覆蓋：值為 git `credential.helper` 字串，逗號分隔、各項 trim、空項目忽略；未設定且偵測無結果＝無任何 helper（行為與 credential-free 完全相同，安全線其餘禁制不變）。
+- 憑證與核准清單**永不**進入指令輸出、Bridge State、Canonical Git Locator（定位器）、Validation Snapshot（快照）或 cache identity（快取身份）——取得流程的 identity 判定與憑證完全無關。
+- 自動偵測或已核准的 helper 仍被遠端拒絕（401）時，錯誤訊息提示檢查登入（`gh auth status`／keychain）或設環境變數核准其他 helper；本機偵測不到任何憑證來源時提示設環境變數或改用 SSH。
+- 設定的 helper 名稱無效時（例如直接寫 `gh`——它不是 git 原生的 credential helper 執行檔），錯誤訊息指出正確寫法：原生 helper 名稱（`osxkeychain`／`store`）或 shell form（`!gh auth git-credential`）。
+
+#### SSH 定位器：私有 repo 的替代路徑
+
+私有 repo 可以完全繞過此環境變數，直接用 SSH 定位器註冊（HTTPS 與 SSH 同屬允許的 credential-free 定位器）：
+
+```
+/codex-marketplace add git@github.com:acme/private-mkt       # scp-like 簡寫（canonical：ssh://git@github.com/acme/private-mkt）
+/codex-marketplace add ssh://git@github.com/acme/private-mkt
+```
+
+前提（與既有 Acquisition Trust Base 一致）：
+
+- host key 必須**預先存在** `~/.ssh/known_hosts`——安全線以 `StrictHostKeyChecking=yes` 只信任既有 host key，遇到未知或變更的主機金鑰直接拒絕，不會提示接受；
+- 憑證由 SSH agent 提供，整個取得過程不互動（`BatchMode=yes`）、無任何提示；
+- SSH 定位器本身仍維持 credential-free：不得內嵌密碼（`user:pass@` 拒絕）；憑證只能經由 SSH agent 或 Credentialed Acquisition 到達取得流程。
+
 ## Bridge State storage
 
 Bridge State 是唯一權威，存於**單一 Global Scope 文件** `{getAgentDir()}/codex-marketplace/state.json`（`~/.pi/agent/codex-marketplace/state.json`）：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-codex-marketplace",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Bridge Package for Codex and Claude Marketplace compatibility in Pi — 極簡 /codex-marketplace 純文字指令（add/list/install/update/disable/enable/remove/forget）、單一 Global Bridge State、當下最新安裝與即時投影",
   "type": "module",
   "keywords": [

package/src/bridge/command.ts

@@ -31,6 +31,11 @@ import { findEntryByManifestName, GIT_FAMILY_UNAVAILABLE_REASON, type Catalog, t
 import type { ValidationFinding } from '../registration/findings.js';
 import { normalizeGitLocator } from '../registration/git-locator.js';
 import { acquireGitSource, cleanupAcquisition, type GitExecutor } from '../registration/git-acquisition.js';
+import {
+  CREDENTIAL_HELPERS_ENV,
+  resolveApprovedHelpers,
+  type CredentialHelperDetector,
+} from '../registration/credential-helpers.js';
 import { gitSourceKey } from '../registration/source-key.js';
 import { buildGitSnapshot } from '../registration/snapshot.js';
 import { SourceCache } from '../cache/source-cache.js';
@@ -42,6 +47,8 @@ export interface CommandOptions {
   cwd?: string;
   /** Git executor seam for tests — mocks `git` invocations (ls-remote/clone/checkout). */
   gitExecutor?: GitExecutor;
+  /** 自動偵測 seam for tests — mocks gh/keychain/store detection (#117). */
+  credentialHelperDetector?: CredentialHelperDetector;
 }
 
 export interface CommandResult {
@@ -598,6 +605,15 @@ export async function runCommand(
 ): Promise<CommandResult> {
   const rawArgs = typeof argv === 'string' ? argv.trim().split(/\s+/).filter(Boolean) : [...argv];
 
+  // Credentialed Acquisition (#109，#117)：逐次核准的 credential helper allowlist。
+  // env 顯式設定 → 完全覆蓋；未設定／空白 → 自動偵測固定白名單（gh／keychain／store），
+  // 開箱即用（私有 repo 不再要求先設 env）。解析結果只經既有 AcquisitionTrustOptions
+  // 傳給 Git 取得；底層不讀環境變數，未核准（偵測也無結果）時 trust 為 undefined，
+  // 行為與 credential-free 完全一致。
+  const resolved = resolveApprovedHelpers(process.env[CREDENTIAL_HELPERS_ENV], opts.credentialHelperDetector);
+  const acquireTrust: { allowedCredentialHelpers: string[]; helperMode: 'detected' | 'approved' } | undefined =
+    resolved.helpers.length > 0 ? { allowedCredentialHelpers: resolved.helpers, helperMode: resolved.mode as 'detected' | 'approved' } : undefined;
+
   // Strip leading command token if passed
   if (rawArgs.length > 0 && (rawArgs[0] === '/codex-marketplace' || rawArgs[0] === 'codex-marketplace')) {
     rawArgs.shift();
@@ -671,6 +687,7 @@ export async function runCommand(
               acquireResult = await acquireGitSource({
                 locator,
                 executor: opts.gitExecutor,
+                trust: acquireTrust,
               });
             } catch (e) {
               const msg = e instanceof Error ? e.message : String(e);
@@ -1089,6 +1106,7 @@ export async function runCommand(
               acquireResult = await acquireGitSource({
                 locator: locRes.locator!,
                 executor: opts.gitExecutor,
+                trust: acquireTrust,
               });
             } catch (e) {
               const msg = e instanceof Error ? e.message : String(e);

package/src/registration/credential-helpers.ts

@@ -0,0 +1,102 @@
+/**
+ * Credentialed Acquisition approval (#109) — env-var allowlist parsing.
+ * See CONTEXT.md: Credentialed Acquisition; docs/adr/0006-credentialed-acquisition-approval.md.
+ *
+ * Per-invocation approval of git credential helpers via
+ * `PI_CODEX_MARKETPLACE_CREDENTIAL_HELPERS` (comma-separated `credential.helper`
+ * strings). Empty/unset means "not approved" — but since #117 the approval may also
+ * come from an auto-detected fixed allowlist, so empty/unset falls back to detection.
+ * This module only parses/detects; the resulting allowlist travels through
+ * AcquisitionTrustOptions and never touches Bridge State, snapshots, or cache identity.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const CREDENTIAL_HELPERS_ENV = 'PI_CODEX_MARKETPLACE_CREDENTIAL_HELPERS';
+
+/**
+ * 允許清單來源：#117 開箱即用後，credential helper 可能有兩種來源。
+ * - approved：使用者經 `PI_CODEX_MARKETPLACE_CREDENTIAL_HELPERS` 顯式核准（可完全覆蓋偵測）。
+ * - detected：預設自動偵測的固定白名單（gh CLI／macOS keychain／git credential-store）。
+ * - none：無任何 helper 可用（錯誤訊息給「未核准」指引變體）。
+ */
+export type CredentialHelperMode = 'none' | 'detected' | 'approved';
+
+/**
+ * 自動偵測介面——可注入（測試）或使用預設真機偵測。偵測目標是**固定白名單**，
+ * 不是讀本機 gitconfig：gitconfig 的任意 helper（含 URL-scoped）仍被命令列
+ * `credential.helper=` 清空排除，僅白名單上的 helper 參與（#117，與 ADR 0006
+ * 被拒的「隱式信任本機 git config」不同）。
+ */
+export interface CredentialHelperDetector {
+  /** gh CLI 已登入（`gh auth status` exit 0） */
+  ghLoggedIn(): boolean;
+  /** git 原生 credential helper 執行檔存在（`git --exec-path` 或 PATH） */
+  hasGitHelper(name: string): boolean;
+}
+
+const defaultDetector: CredentialHelperDetector = {
+  ghLoggedIn() {
+    try {
+      const res = spawnSync('gh', ['auth', 'status'], { stdio: 'ignore', timeout: 5000 });
+      return res.status === 0;
+    } catch {
+      return false;
+    }
+  },
+  hasGitHelper(name) {
+    try {
+      const execPath = spawnSync('git', ['--exec-path'], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 });
+      if (execPath.status === 0) {
+        const dir = String(execPath.stdout ?? '').trim();
+        if (dir && existsSync(join(dir, `git-${name}`))) return true;
+      }
+    } catch {
+      // fall through to PATH check
+    }
+    try {
+      const which = spawnSync('sh', ['-c', `command -v git-${name}`], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 });
+      return which.status === 0 && String(which.stdout ?? '').trim().length > 0;
+    } catch {
+      return false;
+    }
+  },
+};
+
+/**
+ * Parse the approval env var into a helper allowlist.
+ * Comma-separated, each entry trimmed, empty entries ignored.
+ * Empty/unset → no explicit approval ([]).
+ */
+export function parseCredentialHelpers(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+export interface ResolvedCredentialAllowlist {
+  helpers: string[];
+  mode: CredentialHelperMode;
+}
+
+/**
+ * 解析最終 allowlist（#117 開箱即用）：
+ * - env 有非空內容 → 顯式核准，完全覆蓋自動偵測（可預測性不變）。
+ * - env 未設定／空白 → 自動偵測固定白名單。
+ */
+export function resolveApprovedHelpers(
+  raw: string | undefined,
+  detector: CredentialHelperDetector = defaultDetector,
+): ResolvedCredentialAllowlist {
+  const parsed = parseCredentialHelpers(raw);
+  if (parsed.length > 0) return { helpers: parsed, mode: 'approved' };
+  const detected: string[] = [];
+  if (detector.ghLoggedIn()) detected.push('!gh auth git-credential');
+  if (detector.hasGitHelper('credential-osxkeychain')) detected.push('osxkeychain');
+  if (detector.hasGitHelper('credential-store')) detected.push('store');
+  return { helpers: detected, mode: detected.length > 0 ? 'detected' : 'none' };
+}

package/src/registration/findings.ts

@@ -52,6 +52,8 @@ export const RULE = {
   GIT_TRUST_HOST_KEY: 'GIT-31',
   GIT_TRUST_REDIRECT: 'GIT-32',
   GIT_TRUST_CREDENTIAL_HELPER: 'GIT-33',
+  GIT_TRUST_AUTH_REQUIRED: 'GIT-34',
+  GIT_TRUST_CREDENTIAL_HELPER_INVALID: 'GIT-35',
 } as const;
 
 export const CODE = {
@@ -75,6 +77,9 @@ export const CODE = {
   GIT_TRUST_HOST_KEY_CHANGED: 'GIT_TRUST_HOST_KEY_CHANGED',
   GIT_TRUST_REDIRECT: 'GIT_TRUST_REDIRECT',
   GIT_TRUST_CREDENTIAL_HELPER: 'GIT_TRUST_CREDENTIAL_HELPER',
+  GIT_TRUST_AUTH_REQUIRED: 'GIT_TRUST_AUTH_REQUIRED',
+  GIT_TRUST_CREDENTIAL_HELPER_INVALID: 'GIT_TRUST_CREDENTIAL_HELPER_INVALID',
+  GIT_REPO_NOT_FOUND: 'GIT_REPO_NOT_FOUND',
 } as const;
 
 const CLASS_RANK: Record<FindingClass, number> = { blocking: 0, warning: 1, notice: 2 };

package/src/registration/git-acquisition.ts

@@ -15,6 +15,7 @@ import { join } from 'node:path';
 
 import { CODE, RULE, blocking, type ValidationFinding } from './findings.js';
 import type { CanonicalGitLocator } from './git-locator.js';
+import { CREDENTIAL_HELPERS_ENV, type CredentialHelperMode } from './credential-helpers.js';
 
 export interface GitExecutor {
   (args: string[], opts?: { cwd?: string; env?: Record<string, string> }): Promise<{
@@ -46,6 +47,8 @@ export function defaultGitExecutor(): GitExecutor {
 export interface AcquisitionTrustOptions {
   knownHostsFile?: string;
   allowedCredentialHelpers?: string[];
+  /** 允許清單來源（#117）：approved＝env 顯式核准；detected＝自動偵測白名單；缺省視為 approved（相容既有 caller）。 */
+  helperMode?: CredentialHelperMode;
   gitPath?: string;
   sshCommand?: string;
   allowRedirects?: boolean;
@@ -126,50 +129,141 @@ function isFullHex(s: string): boolean {
   return /^[0-9a-f]{40}$/.test(s) || /^[0-9a-f]{64}$/.test(s);
 }
 
+/**
+ * 共用失敗分類（#110）：ls-remote 與 clone 兩條取得路徑採用同一分類與訊息。
+ * - auth：伺服器 401（authentication failed）→ GIT-34，訊息依 helper 模式分三變體（none／detected／approved）。
+ * - invalid-helper：核准的 helper 名稱無效（git 找不到對應執行檔，如 `gh`）→ GIT-35，
+ *   訊息指出正確寫法（原生 helper 名稱或 `!命令` shell form）。放在 auth 之前：stderr 常同時含兩者。
+ * - not-found：「repository not found」類字串 → 標明 repo 不存在（保留非 GitHub 情境；
+ *   GitHub smart-HTTP 對不存在 repo 實測回 401，落入 auth 分支）。
+ * - helper：credential source 拒絕（原字串匹配的 helper 拒絕情境）→ GIT-33 保留。
+ */
+type FailureKind =
+  | { kind: 'host-key'; isChanged: boolean }
+  | { kind: 'redirect' }
+  | { kind: 'not-found' }
+  | { kind: 'invalid-helper'; name: string }
+  | { kind: 'auth'; mode: CredentialHelperMode }
+  | { kind: 'helper'; mode: CredentialHelperMode };
+
+const INVALID_HELPER_RE = /git: 'credential-([^']+)' is not a git command/i;
+
+/**
+ * 從 allowlist 推導模式：未提供時視為 approved（既有 caller 語意）；
+ * 空 allowlist → none。
+ */
+function modeOf(trust: AcquisitionTrustOptions | undefined): CredentialHelperMode {
+  if (trust?.helperMode) return trust.helperMode;
+  return (trust?.allowedCredentialHelpers?.length ?? 0) > 0 ? 'approved' : 'none';
+}
+
+function classifyFailure(stderr: string, mode: CredentialHelperMode): FailureKind | null {
+  const lower = stderr.toLowerCase();
+  if (lower.includes('host key verification failed') || lower.includes('unknown host key') || lower.includes('offending')) {
+    return { kind: 'host-key', isChanged: lower.includes('changed') || lower.includes('offending') || lower.includes('key changed') };
+  }
+  if (lower.includes('redirect') || lower.includes('moved') || lower.includes('followredirects')) {
+    return { kind: 'redirect' };
+  }
+  if (lower.includes('repository not found') || lower.includes('repo not found') || lower.includes('does not appear to be a git repository') || lower.includes("' not found")) {
+    return { kind: 'not-found' };
+  }
+  const invalidMatch = stderr.match(INVALID_HELPER_RE);
+  if (invalidMatch && (lower.includes('credentials') || lower.includes('credential-'))) {
+    return { kind: 'invalid-helper', name: invalidMatch[1] };
+  }
+  if (lower.includes('authentication failed')) {
+    return { kind: 'auth', mode };
+  }
+  if (
+    lower.includes('could not read username') ||
+    lower.includes('could not read password') ||
+    lower.includes('terminal prompts disabled') ||
+    lower.includes('credential')
+  ) {
+    return { kind: 'helper', mode };
+  }
+  return null;
+}
+
+function failureFinding(kind: FailureKind, locator: CanonicalGitLocator, stderr: string): ValidationFinding {
+  switch (kind.kind) {
+    case 'host-key':
+      return trustFinding(
+        kind.isChanged ? CODE.GIT_TRUST_HOST_KEY_CHANGED : CODE.GIT_TRUST_HOST_KEY_UNKNOWN,
+        RULE.GIT_TRUST_HOST_KEY,
+        `Acquisition Trust Base violation: SSH host key ${kind.isChanged ? 'changed' : 'unknown'} for ${locator.host} — ${stderr.trim()} (only pre-established known-host keys are trusted)`,
+      );
+    case 'redirect':
+      return trustFinding(
+        CODE.GIT_TRUST_REDIRECT,
+        RULE.GIT_TRUST_REDIRECT,
+        `Acquisition Trust Base violation: redirect that would change canonical locator (followRedirects disabled) — ${stderr.trim()}`,
+      );
+    case 'not-found':
+      return trustFinding(
+        CODE.GIT_REPO_NOT_FOUND,
+        RULE.GIT_TRUST_AUTH_REQUIRED,
+        `Acquisition Trust Base violation: repository not found — '${locator.canonicalUrl}' does not exist (check the URL or owner/repo name) — ${stderr.trim()}`,
+      );
+    case 'invalid-helper': {
+      // GIT-35：核准的 helper 名稱無效（git 找不到 `git-credential-<name>` 執行檔）。
+      // 典型：使用者直覺設 `PI_CODEX_MARKETPLACE_CREDENTIAL_HELPERS=gh`，git 抱怨
+      // `credential-gh` is not a git command；正確寫法是 `!gh auth git-credential`。
+      return trustFinding(
+        CODE.GIT_TRUST_CREDENTIAL_HELPER_INVALID,
+        RULE.GIT_TRUST_CREDENTIAL_HELPER_INVALID,
+        `Acquisition Trust Base violation: '${kind.name}' is not a valid git credential helper — use a native helper name (osxkeychain / store) or a shell form like '!gh auth git-credential' — ${stderr.trim()}`,
+      );
+    }
+    case 'auth': {
+      // 伺服器 401：訊息依 helper 模式分三變體（#117）：
+      // - none：本機也偵測不到任何憑證來源 → 指引設 env 或改 SSH。
+      // - detected：自動偵測白名單被伺服器拒絕 → 指引檢查登入，或手動核准其他 helper。
+      // - approved：顯式核准仍 401 → 指引檢查登入。
+      const why =
+        kind.mode === 'none'
+          ? `repository requires authentication (private or nonexistent); no credential source was detected on this machine (gh CLI / macOS keychain / git credential-store) and this acquisition is credential-free — approve a credential helper via ${CREDENTIAL_HELPERS_ENV}, or switch to an SSH locator`
+          : kind.mode === 'detected'
+            ? `repository requires authentication; the credential sources auto-detected on this machine (gh / macOS keychain / credential-store) were rejected by the server — check your login with 'gh auth status' or your keychain, or set ${CREDENTIAL_HELPERS_ENV} to approve a different helper`
+            : `approved credential helper did not provide valid credentials — check your login with 'gh auth status' or your keychain`;
+      return trustFinding(
+        CODE.GIT_TRUST_AUTH_REQUIRED,
+        RULE.GIT_TRUST_AUTH_REQUIRED,
+        `Acquisition Trust Base violation: ${why} — ${stderr.trim()}`,
+      );
+    }
+    case 'helper': {
+      // GIT-33 保留：credential source 拒絕（could not read Username/Password 等原字串匹配）；
+      // 訊息依模式分變體：none 維持原「not approved」措辭。
+      const why =
+        kind.mode === 'none'
+          ? `credential helper/agent not approved — set ${CREDENTIAL_HELPERS_ENV} to approve one, or use SSH`
+          : `approved or auto-detected credential helper failed to supply credentials — check your login with 'gh auth status' or your keychain`;
+      return trustFinding(
+        CODE.GIT_TRUST_CREDENTIAL_HELPER,
+        RULE.GIT_TRUST_CREDENTIAL_HELPER,
+        `Acquisition Trust Base: ${why} — ${stderr.trim()}`,
+      );
+    }
+  }
+}
+
 async function resolveHead(
   locator: CanonicalGitLocator,
   executor: GitExecutor,
   env: Record<string, string>,
   configArgs: string[],
+  mode: CredentialHelperMode,
 ): Promise<{ ok: true; sha: string } | { ok: false; findings: ValidationFinding[]; stderr?: string }> {
   const lsArgs = [...configArgs, 'ls-remote', locator.canonicalUrl, 'HEAD'];
   const res = await executor(lsArgs, { env });
   if (res.exitCode !== 0) {
-    const stderr = (res.stderr || '').toLowerCase();
-    if (stderr.includes('host key verification failed') || stderr.includes('unknown host key') || stderr.includes('offending')) {
-      const isChanged = stderr.includes('changed') || stderr.includes('offending') || stderr.includes('key changed');
-      const code = isChanged ? CODE.GIT_TRUST_HOST_KEY_CHANGED : CODE.GIT_TRUST_HOST_KEY_UNKNOWN;
+    const kind = classifyFailure(res.stderr || '', mode);
+    if (kind) {
       return {
         ok: false,
-        findings: [
-          trustFinding(
-            code,
-            RULE.GIT_TRUST_HOST_KEY,
-            `Acquisition Trust Base violation: SSH host key ${isChanged ? 'changed' : 'unknown'} for ${locator.host} — ${res.stderr.trim()} (only pre-established known-host keys are trusted)`,
-          ),
-        ],
-        stderr: res.stderr,
-      };
-    }
-    if (stderr.includes('redirect') || stderr.includes('moved') || stderr.includes('followredirects')) {
-      return {
-        ok: false,
-        findings: [
-          trustFinding(CODE.GIT_TRUST_REDIRECT, RULE.GIT_TRUST_REDIRECT, `Acquisition Trust Base violation: redirect that would change canonical locator (followRedirects disabled) — ${res.stderr.trim()}`),
-        ],
-        stderr: res.stderr,
-      };
-    }
-    if (stderr.includes('could not read username') || stderr.includes('authentication failed') || stderr.includes('credential')) {
-      return {
-        ok: false,
-        findings: [
-          trustFinding(
-            CODE.GIT_ACQUISITION_FAILED,
-            RULE.GIT_TRUST_CREDENTIAL_HELPER,
-            `Acquisition Trust Base: credential helper/agent not approved — ${res.stderr.trim()}`,
-          ),
-        ],
+        findings: [failureFinding(kind, locator, res.stderr)],
         stderr: res.stderr,
       };
     }
@@ -211,7 +305,8 @@ export async function resolveGitRevision(
 ): Promise<{ ok: true; sha: string } | { ok: false; findings: ValidationFinding[]; stderr?: string }> {
   const env = hardenedEnv(opts.trust, locator);
   const configArgs = hardenedConfigArgs(opts.trust);
-  return resolveHead(locator, opts.executor ?? defaultGitExecutor(), env, configArgs);
+  const mode = modeOf(opts.trust);
+  return resolveHead(locator, opts.executor ?? defaultGitExecutor(), env, configArgs, mode);
 }
 
 /**
@@ -223,8 +318,9 @@ export async function acquireGitSource(opts: AcquireOptions): Promise<AcquireRes
   const trust = opts.trust;
   const env = hardenedEnv(trust, locator);
   const configArgs = hardenedConfigArgs(trust);
+  const mode = modeOf(trust);
 
-  const resolved = await resolveHead(locator, executor, env, configArgs);
+  const resolved = await resolveHead(locator, executor, env, configArgs, mode);
   if (!resolved.ok) {
     return { ok: false, findings: (resolved as { findings: ValidationFinding[] }).findings, stderr: (resolved as { stderr?: string }).stderr };
   }
@@ -243,39 +339,12 @@ export async function acquireGitSource(opts: AcquireOptions): Promise<AcquireRes
   const cloneRes = await executor(cloneArgs, { env });
   if (cloneRes.exitCode !== 0) {
     const stderr = cloneRes.stderr || '';
-    const lower = stderr.toLowerCase();
-    if (lower.includes('host key verification failed') || lower.includes('unknown host key') || lower.includes('offending')) {
-      const isChanged = lower.includes('changed') || lower.includes('offending');
-      const code = isChanged ? CODE.GIT_TRUST_HOST_KEY_CHANGED : CODE.GIT_TRUST_HOST_KEY_UNKNOWN;
-      if (createdTemp) try { rmSync(dest, { recursive: true, force: true }); } catch {}
-      return {
-        ok: false,
-        findings: [
-          trustFinding(
-            code,
-            RULE.GIT_TRUST_HOST_KEY,
-            `Acquisition Trust Base violation: SSH host key ${isChanged ? 'changed' : 'unknown'} — ${stderr.trim()}`,
-          ),
-        ],
-        stderr,
-      };
-    }
-    if (lower.includes('redirect') || lower.includes('moved permanently') || lower.includes('followredirects')) {
-      if (createdTemp) try { rmSync(dest, { recursive: true, force: true }); } catch {}
-      return {
-        ok: false,
-        findings: [
-          trustFinding(CODE.GIT_TRUST_REDIRECT, RULE.GIT_TRUST_REDIRECT, `Acquisition Trust Base violation: redirect changing canonical locator — ${stderr.trim()}`),
-        ],
-        stderr,
-      };
-    }
+    const kind = classifyFailure(stderr, mode);
+    const finding = kind
+      ? failureFinding(kind, locator, stderr)
+      : acquireFinding(`git clone failed: ${stderr.trim() || `exit ${cloneRes.exitCode}`}`);
     if (createdTemp) try { rmSync(dest, { recursive: true, force: true }); } catch {}
-    return {
-      ok: false,
-      findings: [acquireFinding(`git clone failed: ${stderr.trim() || `exit ${cloneRes.exitCode}`}`)],
-      stderr,
-    };
+    return { ok: false, findings: [finding], stderr };
   }
 
   if (trust?.allowRedirects !== true) {