pi-codex-marketplace 0.4.0 → 0.5.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 預設 credential-free（有權限也可能 401）——先以 `PI_CODEX_MARKETPLACE_CREDENTIAL_HELPERS` 核准 credential helper 再 add（逐次生效、永不持久化），或改用 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,37 @@ Nine subcommands, no arguments = 總覽：
 - 安裝成功後由指令層主動要求 reload；reload 失敗不影響已記錄狀態，下次 session start 或 `/reload` 仍生效。
 - `--no-skills` 啟動 Pi 不影響 Bridge 投影。
 
+### 私有 Git repo：Credentialed Acquisition（核准式取得）
+
+預設 `add`／`update` 對 Git 來源完全 credential-free：不執行任何 credential helper，因此「有權限卻失敗」時，私有 HTTPS repo 會以 401 失敗（並提示核准或改用 SSH）。若要核准 credential helper，以逗號分隔設定環境變數（**逐次生效、永不持久化**，`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 語意（安全線）：
+
+- 核准僅限該次呼叫（per-invocation）：環境變數逐指令讀取，**不寫入** Bridge State、設定檔或任何持久化位置；重開 session 後需重新設定。
+- 值為 git `credential.helper` 字串，逗號分隔、各項 trim、空項目忽略；未設定或空白＝未核准（行為與 credential-free 完全相同，安全線其餘禁制不變）。
+- 憑證與核准清單**永不**進入指令輸出、Bridge State、Canonical Git Locator（定位器）、Validation Snapshot（快照）或 cache identity（快取身份）——取得流程的 identity 判定與憑證完全無關。
+- 已核准 helper 仍被遠端拒絕（401）時，錯誤訊息提示檢查憑證；未核准時提示核准或改用 SSH。
+
+#### 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.5.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,7 @@ 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, parseCredentialHelpers } 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';
@@ -598,6 +599,13 @@ export async function runCommand(
 ): Promise<CommandResult> {
   const rawArgs = typeof argv === 'string' ? argv.trim().split(/\s+/).filter(Boolean) : [...argv];
 
+  // Credentialed Acquisition (#109)：逐次核准的 credential helper allowlist。
+  // 解析結果只經既有 AcquisitionTrustOptions 傳給 Git 取得；底層不讀環境變數，
+  // 未核准（空字串／未設定）時 trust 為 undefined，行為與 credential-free 完全一致。
+  const approvedHelpers = parseCredentialHelpers(process.env[CREDENTIAL_HELPERS_ENV]);
+  const acquireTrust: { allowedCredentialHelpers: string[] } | undefined =
+    approvedHelpers.length > 0 ? { allowedCredentialHelpers: approvedHelpers } : undefined;
+
   // Strip leading command token if passed
   if (rawArgs.length > 0 && (rawArgs[0] === '/codex-marketplace' || rawArgs[0] === 'codex-marketplace')) {
     rawArgs.shift();
@@ -671,6 +679,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 +1098,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,25 @@
+/**
+ * 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" — behavior identical to today.
+ * This module only parses; the resulting allowlist travels through
+ * AcquisitionTrustOptions and never touches Bridge State, snapshots, or cache identity.
+ */
+
+export const CREDENTIAL_HELPERS_ENV = 'PI_CODEX_MARKETPLACE_CREDENTIAL_HELPERS';
+
+/**
+ * Parse the approval env var into a helper allowlist.
+ * Comma-separated, each entry trimmed, empty entries ignored.
+ * Empty/unset → no approval ([]).
+ */
+export function parseCredentialHelpers(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}

package/src/registration/findings.ts

@@ -52,6 +52,7 @@ 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',
 } as const;
 
 export const CODE = {
@@ -75,6 +76,8 @@ 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_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 } from './credential-helpers.js';
 
 export interface GitExecutor {
   (args: string[], opts?: { cwd?: string; env?: Record<string, string> }): Promise<{
@@ -126,50 +127,106 @@ 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：credential source 拒絕（原字串匹配的 helper 拒絕情境）→ GIT-33 保留；
+ * - not-found：「repository not found」類字串 → 標明 repo 不存在（保留非 GitHub 情境；
+ *   GitHub smart-HTTP 對不存在 repo 實測回 401，落入 auth 分支）。
+ */
+type FailureKind =
+  | { kind: 'host-key'; isChanged: boolean }
+  | { kind: 'redirect' }
+  | { kind: 'not-found' }
+  | { kind: 'auth'; approved: boolean }
+  | { kind: 'helper'; approved: boolean };
+
+function classifyFailure(stderr: string, approvedHelpers: boolean): 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' };
+  }
+  if (lower.includes('authentication failed')) {
+    return { kind: 'auth', approved: approvedHelpers };
+  }
+  if (
+    lower.includes('could not read username') ||
+    lower.includes('could not read password') ||
+    lower.includes('terminal prompts disabled') ||
+    lower.includes('credential')
+  ) {
+    return { kind: 'helper', approved: approvedHelpers };
+  }
+  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 'auth': {
+      // 伺服器 401：訊息依核准狀態分兩變體（未核准 → 指出 credential-free 且需認證，指引核准或 SSH；已核准仍 401 → 指引檢查登入）。
+      const why = kind.approved
+        ? `approved credential helper did not provide valid credentials — check your login with 'gh auth status' or your keychain`
+        : `repository requires authentication (private or nonexistent) and this acquisition is credential-free — approve a credential helper via ${CREDENTIAL_HELPERS_ENV}, or switch to an SSH locator`;
+      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 等原字串匹配）；
+      // 訊息依核准狀態分兩變體，未核准時維持原「not approved」措辭。
+      const why = kind.approved
+        ? `approved credential helper failed to supply credentials — check your login with 'gh auth status' or your keychain`
+        : `credential helper/agent not approved — set ${CREDENTIAL_HELPERS_ENV} to approve one, or use SSH`;
+      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[],
+  approvedHelpers: boolean,
 ): 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;
-      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')) {
+    const kind = classifyFailure(res.stderr || '', approvedHelpers);
+    if (kind) {
       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 +268,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 approvedHelpers = (opts.trust?.allowedCredentialHelpers?.length ?? 0) > 0;
+  return resolveHead(locator, opts.executor ?? defaultGitExecutor(), env, configArgs, approvedHelpers);
 }
 
 /**
@@ -224,7 +282,7 @@ export async function acquireGitSource(opts: AcquireOptions): Promise<AcquireRes
   const env = hardenedEnv(trust, locator);
   const configArgs = hardenedConfigArgs(trust);
 
-  const resolved = await resolveHead(locator, executor, env, configArgs);
+  const resolved = await resolveHead(locator, executor, env, configArgs, (trust?.allowedCredentialHelpers?.length ?? 0) > 0);
   if (!resolved.ok) {
     return { ok: false, findings: (resolved as { findings: ValidationFinding[] }).findings, stderr: (resolved as { stderr?: string }).stderr };
   }
@@ -243,39 +301,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, (trust?.allowedCredentialHelpers?.length ?? 0) > 0);
+    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) {