@amonstack/gitea-mcp 0.3.0 → 0.3.1

package/README.md

@@ -59,7 +59,7 @@ projects. Set them only to override the discovery.
 | Variable | Required | Description |
 |----------|:--------:|-------------|
 | `GITEA_BASE_URL` | No | Gitea instance URL (e.g. `https://gitea.example.com`). Auto-detected from the project's git remote when omitted. |
-| `GITEA_TOKEN` | No | Gitea API access token. Resolved from `.git/config`, the git credential store, then this variable (see [Token discovery](#token-discovery)). |
+| `GITEA_TOKEN` | No | Gitea API access token. One of several auth candidates; tried after a `.git/config [gitea]` token and before the git credential store (see [Token discovery](#token-discovery)). |
 | `GITEA_DEFAULT_OWNER` | No | Default repository owner — skip passing `owner` on every call |
 | `GITEA_DEFAULT_REPO` | No | Default repository name — skip passing `repo` on every call |
 
@@ -80,21 +80,48 @@ repository, or set `GITEA_BASE_URL` / `GITEA_TOKEN` explicitly.
 
 ### Token discovery
 
-The token is resolved in this order (first match wins):
+`gitea-mcp` collects authentication **candidates** from three sources, in this
+priority order:
 
-1. A `[gitea "<baseUrl>"]` section in `.git/config`:
+1. A `[gitea "<baseUrl>"]` section in `.git/config` (a bare `[gitea]` section is
+   a host-wide fallback):
    ```ini
    [gitea "https://gitea.example.com"]
        token = <your-token>
    ```
-   A bare `[gitea]` section with `token = ...` is a host-wide fallback.
-2. The git credential store (`~/.git-credentials`, or `$XDG_CONFIG_HOME/git/credentials`) —
-   a line whose host matches the instance, e.g. `https://oauth2:<token>@gitea.example.com`.
-3. The `GITEA_TOKEN` environment variable.
-
-If none resolves, the server still starts without a token (anonymous). Public repositories
-may be read; private repos and write operations return `401` — use the `gitea-configure`
-skill to guide setup, or set `GITEA_TOKEN`.
+   Always sent as `Authorization: token <token>`.
+2. The `GITEA_TOKEN` environment variable — also sent as `Authorization: token`.
+3. The git credential store (`~/.git-credentials`, or
+   `$XDG_CONFIG_HOME/git/credentials`) — every line whose host matches the
+   instance, e.g. `https://alice:s3cret@gitea.example.com`. When several lines
+   match, the one whose path best matches `owner/repo` is tried first.
+
+A credential-store entry's `password` field may hold a real PAT, an account
+password, or an OAuth token — git stores whatever was typed at the prompt, and
+the server cannot tell them apart statically. So each credential-store entry is
+tried under **two authentication schemes**:
+
+- `Authorization: Basic <base64(user:pass)>` — works for account passwords and
+  PATs alike (Gitea checks that the username matches the secret's owner).
+- `Authorization: token <secret>` — works only for real PATs.
+
+The order is chosen by a username heuristic: a convention username
+(`oauth2`, `x-oauth-basic`, or empty) tries `token` first; a real-looking
+username (e.g. `alice`) tries `basic` first.
+
+**Fault tolerance.** On `401`/`403` the server advances to the next
+scheme/candidate and retries the same request; once a combination succeeds it is
+locked for the rest of the session (no re-probing). Non-auth errors (`404`,
+`500`, network) propagate immediately and do **not** trigger a retry.
+
+**Diagnostics.** The `gitea_status` tool (see [Repository Helpers](#repository-helpers))
+returns a redacted view of the current state — which candidate is active, which
+are exhausted, the last status seen — without ever exposing the secret. Use it
+to troubleshoot a `401` instead of guessing.
+
+If no source resolves a credential, the server still starts anonymously. Public
+repositories may be read; private repos and write operations return `401` — use
+the `gitea-configure` skill to guide setup, or set `GITEA_TOKEN`.
 
 When `GITEA_DEFAULT_OWNER` and `GITEA_DEFAULT_REPO` are set, you can omit the
 `owner` and `repo` parameters in tool calls. The `resolve_repo` tool can also
@@ -234,6 +261,7 @@ gitea-mcp
 |------|-------------|
 | `list_my_repos` | List repositories accessible to the authenticated user |
 | `resolve_repo` | Detect `baseUrl`, `owner`, and `repo` from the project's git remotes (`upstream` preferred, then `origin`) |
+| `gitea_status` | Inspect credential-handling state — active candidate, exhausted candidates, last error (redacted; secrets never exposed) |
 
 ## AI Guidance & Skills
 
@@ -290,6 +318,7 @@ npm ci
 | `make test` | Run unit tests |
 | `make test-watch` | Run tests in watch mode |
 | `make test-integration` | Run integration tests (needs live Gitea instance) |
+| `make scan` | Scan for leaked secrets with gitleaks (part of `make verify`) |
 | `make dev` | Run directly with tsx |
 
 For the full architecture — module layout, dependency graph, core patterns, and

package/README.zh-CN.md

@@ -56,7 +56,7 @@ node dist/cli.js
 | 变量 | 必填 | 说明 |
 |------|:----:|------|
 | `GITEA_BASE_URL` | 否 | Gitea 实例地址（如 `https://gitea.example.com`）。未设置时从项目 git 远程地址自动推导。 |
-| `GITEA_TOKEN` | 否 | Gitea API 访问令牌。依次从 `.git/config`、git 凭据存储、本变量解析（见[令牌发现](#令牌发现)）。 |
+| `GITEA_TOKEN` | 否 | Gitea API 访问令牌。是多个认证候选之一；排在 `.git/config [gitea]` 令牌之后、git 凭据存储之前（见[令牌发现](#令牌发现)）。 |
 | `GITEA_DEFAULT_OWNER` | 否 | 默认仓库所有者，免去每次传入 `owner` 参数 |
 | `GITEA_DEFAULT_REPO` | 否 | 默认仓库名称，免去每次传入 `repo` 参数 |
 
@@ -76,20 +76,40 @@ node dist/cli.js
 
 ### 令牌发现
 
-令牌按以下顺序解析（先匹配者胜出）：
+`gitea-mcp` 从三个来源收集认证**候选**，按以下优先级排序：
 
-1. `.git/config` 中的 `[gitea "<baseUrl>"]` 段：
+1. `.git/config` 中的 `[gitea "<baseUrl>"]` 段（不带地址的 `[gitea]` 段作为全局兜底）：
    ```ini
    [gitea "https://gitea.example.com"]
        token = <your-token>
    ```
-   不带地址的 `[gitea]` 段中的 `token = ...` 作为全局兜底。
-2. git 凭据存储（`~/.git-credentials`，或 `$XDG_CONFIG_HOME/git/credentials`）——host 匹配实例
-   的那一行，如 `https://oauth2:<token>@gitea.example.com`。
-3. `GITEA_TOKEN` 环境变量。
+   始终以 `Authorization: token <token>` 发送。
+2. `GITEA_TOKEN` 环境变量 —— 同样以 `Authorization: token` 发送。
+3. git 凭据存储（`~/.git-credentials`，或 `$XDG_CONFIG_HOME/git/credentials`）—— host 匹配实例
+   的每一行，如 `https://alice:s3cret@gitea.example.com`。多行同时匹配时，path 与 `owner/repo`
+   最贴近的那一行优先尝试。
 
-若都未解析到，服务器仍会以匿名方式启动。公开仓库可读；私有仓库和写操作返回 `401`——此时使用
-`gitea-configure` 技能引导配置，或设置 `GITEA_TOKEN`。
+凭据存储条目的 `password` 字段可能是真正的 PAT、账户登录密码，或 OAuth token —— git 存的是
+用户在密码提示里输入的任何内容，服务端无法静态区分。因此每个凭据存储条目会以**两种认证方案**
+依次尝试：
+
+- `Authorization: Basic <base64(user:pass)>` —— 账户密码和 PAT 都能通过（Gitea 会校验用户名与
+  密钥属主一致）。
+- `Authorization: token <secret>` —— 仅对真正的 PAT 有效。
+
+尝试顺序由用户名启发式决定：约定用户名（`oauth2`、`x-oauth-basic`、空）先试 `token`；真实用户名
+（如 `alice`）先试 `basic`。
+
+**容错。** 遇到 `401`/`403`，服务端会切换到下一个方案/候选并重试同一请求；一旦某组凭据成功，
+它会被锁定到本会话结束（不再重复探测）。非认证类错误（`404`、`500`、网络错误）立即向上抛出，
+**不会**触发重试。
+
+**诊断。** `gitea_status` 工具（见[仓库辅助](#仓库辅助-repository-helpers)）返回当前状态的脱敏
+视图 —— 哪个候选处于 active、哪些已耗尽、最近一次的状态码 —— 永不暴露密钥本身。排查 `401` 时
+用它代替盲猜。
+
+若所有来源都未解析到凭据，服务器仍会以匿名方式启动。公开仓库可读；私有仓库和写操作返回
+`401` —— 此时使用 `gitea-configure` 技能引导配置，或设置 `GITEA_TOKEN`。
 
 设置 `GITEA_DEFAULT_OWNER` 和 `GITEA_DEFAULT_REPO` 后，调用工具时可以省略
 `owner` 和 `repo` 参数。也可以使用 `resolve_repo` 工具自动从本地 git 仓库
@@ -227,6 +247,7 @@ gitea-mcp
 |------|------|
 | `list_my_repos` | 列出当前用户可访问的仓库 |
 | `resolve_repo` | 从项目 git 远程地址检测 `baseUrl`、`owner`、`repo`（优先 `upstream`，回退 `origin`） |
+| `gitea_status` | 查看认证处理状态 —— active 候选、已耗尽候选、最近一次错误（脱敏；永不暴露密钥） |
 
 ## AI 引导与技能
 
@@ -279,6 +300,7 @@ npm ci
 | `make test` | 运行单元测试 |
 | `make test-watch` | 监听模式运行测试 |
 | `make test-integration` | 运行集成测试（需要可用的 Gitea 实例） |
+| `make scan` | 用 gitleaks 扫描泄露的密钥（属于 `make verify`） |
 | `make dev` | 通过 tsx 直接运行 |
 
 完整的架构说明（模块布局、依赖关系、核心模式，以及新增工具的指引）请参阅

package/dist/cli.js

@@ -13,10 +13,14 @@ if (argv[0] === "init") {
     });
 }
 else {
-    // Resolve baseUrl/owner/repo/token from env first, then the local git context
-    // (`.git/config` remotes + credential store). When neither env nor any git
-    // remote provides a baseUrl, the server is intentionally skipped: a single
-    // global install should stay dormant outside of git projects.
+    // Resolve baseUrl/owner/repo/credentials from env first, then the local git
+    // context (`.git/config` remotes + credential store). Discovery collects ALL
+    // credential candidates (config token, env token, credential-store entries)
+    // rather than picking one, so the client can fall back across them when one
+    // scheme is rejected (e.g. an account password that is not a PAT). When
+    // neither env nor any git remote provides a baseUrl, the server is
+    // intentionally skipped: a single global install should stay dormant outside
+    // of git projects.
     const discovered = await discoverConfig().catch((err) => {
         console.error("Fatal error:", err);
         process.exit(1);
@@ -25,7 +29,7 @@ else {
         console.error(`gitea-mcp: no git remote found in ${process.cwd()} and GITEA_BASE_URL is not set; skipping server start.`);
         process.exit(0);
     }
-    runServer(discovered.baseUrl, discovered.token, discovered.defaultOwner, discovered.defaultRepo).catch((err) => {
+    runServer(discovered.baseUrl, discovered.candidates, discovered.defaultOwner, discovered.defaultRepo).catch((err) => {
         console.error("Fatal error:", err);
         process.exit(1);
     });

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;IACvB,6EAA6E;IAC7E,sEAAsE;IACtE,sDAAsD;IACtD,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACvD,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACnD,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,CAAC;IACN,8EAA8E;IAC9E,2EAA2E;IAC3E,2EAA2E;IAC3E,8DAA8D;IAC9D,MAAM,UAAU,GAAG,MAAM,cAAc,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC/D,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CACX,qCAAqC,OAAO,CAAC,GAAG,EAAE,wDAAwD,CAC3G,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,SAAS,CACP,UAAU,CAAC,OAAO,EAClB,UAAU,CAAC,KAAK,EAChB,UAAU,CAAC,YAAY,EACvB,UAAU,CAAC,WAAW,CACvB,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACvB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;IACvB,6EAA6E;IAC7E,sEAAsE;IACtE,sDAAsD;IACtD,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACvD,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACnD,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,CAAC;IACN,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,4EAA4E;IAC5E,wEAAwE;IACxE,mEAAmE;IACnE,6EAA6E;IAC7E,mBAAmB;IACnB,MAAM,UAAU,GAAG,MAAM,cAAc,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC/D,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CACX,qCAAqC,OAAO,CAAC,GAAG,EAAE,wDAAwD,CAC3G,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,SAAS,CACP,UAAU,CAAC,OAAO,EAClB,UAAU,CAAC,UAAU,EACrB,UAAU,CAAC,YAAY,EACvB,UAAU,CAAC,WAAW,CACvB,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACvB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/credentials.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Credential candidate model and state machine for fault-tolerant Gitea auth.
+ *
+ * A discovered credential is treated as an opaque candidate: the `secret`
+ * field might be a Gitea Personal Access Token, an account login password,
+ * or an OAuth token — the type cannot be determined statically from any
+ * source (`~/.git-credentials` stores whatever the user typed into git's
+ * password prompt, and `[gitea] token` / `GITEA_TOKEN` are by convention but
+ * not guarantee a PAT). The runtime therefore tries each candidate under
+ * one or more HTTP auth schemes, advancing on 401/403 until something works
+ * or every candidate × scheme is exhausted.
+ *
+ * This module is pure (no I/O, no fetch) so the state machine is unit-tested
+ * directly. Mutation is contained to per-candidate state fields; callers
+ * never replace the candidates array.
+ *
+ * SECURITY: `secret` is never logged, never interpolated into error
+ * messages, and never surfaced by `summarizeCandidates`. Diagnostic output
+ * only ever carries `secretPresent: boolean` and a masked `username`.
+ */
+/** Where a candidate came from. Determines scheme ordering and priority. */
+export type CredentialSource = "gitea-config" | "env" | "credential-store";
+/**
+ * HTTP auth scheme. Both are sent via the `Authorization` header.
+ * - `token` → `Authorization: token <PAT>` (Gitea's PAT/OAuth-token scheme)
+ * - `basic` → `Authorization: Basic base64(<username>:<secret>)` (works for
+ *   both account passwords and PATs when the username matches the owner)
+ */
+export type AuthScheme = "token" | "basic";
+/**
+ * A single candidate credential with its runtime state. The state fields
+ * (`status`, `nextSchemeIndex`, `lastTriedScheme`, `lastError`,
+ * `activeScheme`) are mutated by the GiteaClient as requests succeed or fail.
+ */
+export interface CandidateCredential {
+    source: CredentialSource;
+    /** Username from a credential-store URL. Undefined for config/env sources. */
+    username?: string;
+    /** The secret value (PAT, password, or OAuth token). Never logged. */
+    secret: string;
+    /**
+     * Ordered list of auth schemes to try for this candidate. The first scheme
+     * that succeeds is locked in via `activeScheme` and reused for subsequent
+     * requests without re-iterating.
+     */
+    schemes: AuthScheme[];
+    /** Runtime state: pending (untried), active (verified working), exhausted. */
+    status: "pending" | "active" | "exhausted";
+    /** Index into `schemes` for the next untried scheme. */
+    nextSchemeIndex: number;
+    /** The scheme that last produced an HTTP error (for diagnostics). */
+    lastTriedScheme?: AuthScheme;
+    /**
+     * The scheme that succeeded and is in active use. Set when status becomes
+     * "active"; subsequent requests reuse it without re-iterating.
+     */
+    activeScheme?: AuthScheme;
+    /**
+     * Short error reason from the last failed attempt (e.g. "401"). Never
+     * contains the secret or the response body.
+     */
+    lastError?: string;
+}
+/** Result of credential discovery — feeds straight into GiteaClient. */
+export interface CredentialDiscoveryResult {
+    baseUrl: string;
+    defaultOwner?: string;
+    defaultRepo?: string;
+    /** Name of the remote the values were derived from. */
+    remote?: string;
+    /** Candidates in priority order (highest priority first). */
+    candidates: CandidateCredential[];
+}
+/** A picked next attempt — the candidate index plus the scheme to apply. */
+export interface Attempt {
+    candidateIndex: number;
+    scheme: AuthScheme;
+}
+/**
+ * Decide scheme ordering for a credential-store entry based on username
+ * heuristic. Config/env candidates always use `["token"]` (per project
+ * decision to preserve their "simple token" semantics).
+ *
+ * - Username `oauth2`, `x-oauth-basic`, or empty → `["token", "basic"]`:
+ *   these are git OAuth conventions; basic auth with such a username fails
+ *   for real passwords, so try `token` first.
+ * - Any other (real-looking) username → `["basic", "token"]`: basic auth
+ *   with the correct username works for both PATs and passwords, so it has
+ *   the widest coverage and goes first.
+ */
+export declare function orderSchemesForCredentialStore(username?: string): AuthScheme[];
+/**
+ * Build the `Authorization` header value for one attempt. Mutates nothing.
+ *
+ * For `basic`, the username falls back to `oauth2` when absent (a missing
+ * username only happens for malformed credential-store entries; Gitea
+ * rejects basic auth without a username, so the attempt will fail and the
+ * state machine will advance).
+ */
+export declare function buildAuthHeader(candidate: CandidateCredential, scheme: AuthScheme): string;
+/**
+ * Pick the next (candidate, scheme) to try. Skips exhausted candidates and
+ * candidates whose scheme list is fully tried. Does NOT mutate state — the
+ * caller records the attempt via `markAttemptFailed` / `markAttemptSucceeded`.
+ *
+ * Returns null when every candidate × scheme has been tried.
+ */
+export declare function pickNextAttempt(candidates: CandidateCredential[]): Attempt | null;
+/**
+ * Record that an attempt failed with `error` (a short reason like "401").
+ * Advances the candidate's scheme index; when no schemes remain, marks the
+ * candidate as exhausted.
+ */
+export declare function markAttemptFailed(candidates: CandidateCredential[], candidateIndex: number, error: string): void;
+/**
+ * Record that an attempt succeeded. Marks the candidate as active, locks in
+ * `activeScheme`, and marks all PRIOR candidates as exhausted (they were
+ * tried and failed before this one succeeded).
+ */
+export declare function markAttemptSucceeded(candidates: CandidateCredential[], candidateIndex: number, scheme: AuthScheme): void;
+/**
+ * Mask a username for diagnostic output: first character plus `***`. Returns
+ * null when the candidate has no username (config/env sources, or malformed
+ * credential-store entries).
+ */
+export declare function maskUsername(username?: string): string | null;
+/**
+ * Build a redacted summary of all candidates for the `gitea_status` tool.
+ * The `secret` value is never included — only `secretPresent: true`. The
+ * caller passes the active candidate index (or null) so the summary can flag
+ * which candidate is currently in use.
+ */
+export interface CandidateSummary {
+    source: CredentialSource;
+    schemes: AuthScheme[];
+    username: string | null;
+    secretPresent: boolean;
+    status: "pending" | "active" | "exhausted";
+    lastTriedScheme: AuthScheme | null;
+    activeScheme: AuthScheme | null;
+    lastError: string | null;
+}
+export declare function summarizeCandidates(candidates: CandidateCredential[]): CandidateSummary[];
+/** Find the index of the active candidate, or null when none is active. */
+export declare function findActiveCandidateIndex(candidates: CandidateCredential[]): number | null;

package/dist/credentials.js

@@ -0,0 +1,141 @@
+/**
+ * Credential candidate model and state machine for fault-tolerant Gitea auth.
+ *
+ * A discovered credential is treated as an opaque candidate: the `secret`
+ * field might be a Gitea Personal Access Token, an account login password,
+ * or an OAuth token — the type cannot be determined statically from any
+ * source (`~/.git-credentials` stores whatever the user typed into git's
+ * password prompt, and `[gitea] token` / `GITEA_TOKEN` are by convention but
+ * not guarantee a PAT). The runtime therefore tries each candidate under
+ * one or more HTTP auth schemes, advancing on 401/403 until something works
+ * or every candidate × scheme is exhausted.
+ *
+ * This module is pure (no I/O, no fetch) so the state machine is unit-tested
+ * directly. Mutation is contained to per-candidate state fields; callers
+ * never replace the candidates array.
+ *
+ * SECURITY: `secret` is never logged, never interpolated into error
+ * messages, and never surfaced by `summarizeCandidates`. Diagnostic output
+ * only ever carries `secretPresent: boolean` and a masked `username`.
+ */
+/**
+ * Decide scheme ordering for a credential-store entry based on username
+ * heuristic. Config/env candidates always use `["token"]` (per project
+ * decision to preserve their "simple token" semantics).
+ *
+ * - Username `oauth2`, `x-oauth-basic`, or empty → `["token", "basic"]`:
+ *   these are git OAuth conventions; basic auth with such a username fails
+ *   for real passwords, so try `token` first.
+ * - Any other (real-looking) username → `["basic", "token"]`: basic auth
+ *   with the correct username works for both PATs and passwords, so it has
+ *   the widest coverage and goes first.
+ */
+export function orderSchemesForCredentialStore(username) {
+    if (username === undefined)
+        return ["token", "basic"];
+    const u = username.toLowerCase();
+    if (u === "oauth2" || u === "x-oauth-basic") {
+        return ["token", "basic"];
+    }
+    return ["basic", "token"];
+}
+/**
+ * Build the `Authorization` header value for one attempt. Mutates nothing.
+ *
+ * For `basic`, the username falls back to `oauth2` when absent (a missing
+ * username only happens for malformed credential-store entries; Gitea
+ * rejects basic auth without a username, so the attempt will fail and the
+ * state machine will advance).
+ */
+export function buildAuthHeader(candidate, scheme) {
+    if (scheme === "basic") {
+        const user = candidate.username ?? "oauth2";
+        const encoded = Buffer.from(`${user}:${candidate.secret}`).toString("base64");
+        return `Basic ${encoded}`;
+    }
+    return `token ${candidate.secret}`;
+}
+/**
+ * Pick the next (candidate, scheme) to try. Skips exhausted candidates and
+ * candidates whose scheme list is fully tried. Does NOT mutate state — the
+ * caller records the attempt via `markAttemptFailed` / `markAttemptSucceeded`.
+ *
+ * Returns null when every candidate × scheme has been tried.
+ */
+export function pickNextAttempt(candidates) {
+    for (let i = 0; i < candidates.length; i++) {
+        const c = candidates[i];
+        if (c.status === "exhausted")
+            continue;
+        // Active candidates are already locked — the caller short-circuits
+        // before entering this iteration loop (GiteaClient.request checks
+        // findActiveCandidateIndex first). Here we skip them defensively.
+        if (c.status === "active")
+            continue;
+        if (c.nextSchemeIndex >= c.schemes.length)
+            continue;
+        return { candidateIndex: i, scheme: c.schemes[c.nextSchemeIndex] };
+    }
+    return null;
+}
+/**
+ * Record that an attempt failed with `error` (a short reason like "401").
+ * Advances the candidate's scheme index; when no schemes remain, marks the
+ * candidate as exhausted.
+ */
+export function markAttemptFailed(candidates, candidateIndex, error) {
+    const c = candidates[candidateIndex];
+    c.lastError = error;
+    c.lastTriedScheme = c.schemes[c.nextSchemeIndex];
+    c.nextSchemeIndex += 1;
+    if (c.nextSchemeIndex >= c.schemes.length || c.status === "active") {
+        c.status = "exhausted";
+        c.activeScheme = undefined;
+    }
+}
+/**
+ * Record that an attempt succeeded. Marks the candidate as active, locks in
+ * `activeScheme`, and marks all PRIOR candidates as exhausted (they were
+ * tried and failed before this one succeeded).
+ */
+export function markAttemptSucceeded(candidates, candidateIndex, scheme) {
+    for (let i = 0; i < candidateIndex; i++) {
+        if (candidates[i].status !== "active")
+            candidates[i].status = "exhausted";
+    }
+    const c = candidates[candidateIndex];
+    c.status = "active";
+    c.activeScheme = scheme;
+    c.lastError = undefined;
+}
+/**
+ * Mask a username for diagnostic output: first character plus `***`. Returns
+ * null when the candidate has no username (config/env sources, or malformed
+ * credential-store entries).
+ */
+export function maskUsername(username) {
+    if (!username)
+        return null;
+    return `${username.charAt(0)}***`;
+}
+export function summarizeCandidates(candidates) {
+    return candidates.map((c) => ({
+        source: c.source,
+        schemes: c.schemes,
+        username: maskUsername(c.username),
+        secretPresent: c.secret.length > 0,
+        status: c.status,
+        lastTriedScheme: c.lastTriedScheme ?? null,
+        activeScheme: c.activeScheme ?? null,
+        lastError: c.lastError ?? null,
+    }));
+}
+/** Find the index of the active candidate, or null when none is active. */
+export function findActiveCandidateIndex(candidates) {
+    for (let i = 0; i < candidates.length; i++) {
+        if (candidates[i].status === "active")
+            return i;
+    }
+    return null;
+}
+//# sourceMappingURL=credentials.js.map

package/dist/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"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"}

package/dist/git-config.d.ts

@@ -1,3 +1,4 @@
+import { type CredentialDiscoveryResult } from "./credentials.js";
 /** A single parsed git remote. `remote` is the remote name (`origin`, `upstream`, ...). */
 export interface ParsedRemote {
     remote: string;
@@ -18,15 +19,22 @@ export interface DiscoverOptions {
     /** Override credential-store paths (defaults to XDG then `~/.git-credentials`). */
     credentialsPaths?: string[];
 }
-export interface DiscoveredConfig {
-    baseUrl: string;
-    /** Undefined when no token source resolves — the server still starts and a Skill guides the user. */
-    token?: string;
-    defaultOwner?: string;
-    defaultRepo?: string;
-    /** Name of the remote the values were derived from (undefined when derived purely from env). */
-    remote?: string;
-    source: "env" | "git";
+/**
+ * A parsed `~/.git-credentials` line. Both `username` and `password` are
+ * URL-decoded. Either may be absent:
+ * - `https://user:pass@host` → both present
+ * - `https://:pass@host` → only password
+ * - `https://tok@host` → only username (git stores a token here when the
+ *   host accepts one as the "username"; the caller treats it as the secret)
+ *
+ * `path` is the URL pathname with leading/trailing slashes and any `.git`
+ * suffix stripped, used to narrow multiple host matches toward the target repo.
+ */
+export interface ParsedCredentialEntry {
+    username?: string;
+    password?: string;
+    host: string;
+    path: string;
 }
 /**
  * Parse a git remote URL into host/baseUrl/owner/repo. Accepts `ssh://`, the
@@ -48,11 +56,18 @@ export declare function selectRemote(remotes: ParsedRemote[]): ParsedRemote | nu
  */
 export declare function readTokenFromGitConfig(content: string, baseUrl: string): string | undefined;
 /**
- * Find a credential for `host` in a `git-credentials` file. Each line is a URL;
- * the password (preferred) or username is returned as the token. Malformed and
- * non-matching lines are skipped.
+ * Parse every credential-store line whose host matches. Each line is a URL of
+ * the form `protocol://[user[:pass]]@host[:port][/path]`; malformed and
+ * non-matching lines are skipped. Returns entries in file order; callers
+ * narrow and re-sort by repo path specificity.
+ *
+ * The `password` field — when present — holds whatever the user typed into
+ * git's password prompt: a real account password, a Personal Access Token,
+ * or an OAuth token. Git itself does not distinguish, and neither does this
+ * parser; the GiteaClient runtime tries each entry under multiple auth
+ * schemes to discover what works.
  */
-export declare function parseGitCredentials(content: string, host: string): string | undefined;
+export declare function parseGitCredentials(content: string, host: string): ParsedCredentialEntry[];
 /** Default credential-store paths: `$XDG_CONFIG_HOME/git/credentials` then `~/.git-credentials`. */
 export declare function defaultCredentialsPaths(): string[];
 /**
@@ -62,12 +77,21 @@ export declare function defaultCredentialsPaths(): string[];
  *   remote (`upstream` → `origin` → first). Returns null only when neither is
  *   available — callers should treat that as "do not start the server".
  *
- * token: `.git/config` `[gitea "<baseUrl>"] token` → bare `[gitea] token` →
- *   matching entry in a git credential store → `GITEA_TOKEN` (env). May be
- *   undefined when nothing resolves; the server still starts and a Skill
- *   guides the user to provide one.
+ * candidates (in priority order):
+ *   1. `[gitea "<baseUrl>"] token` / bare `[gitea] token` from `.git/config`
+ *      (explicit user configuration; `token` scheme only).
+ *   2. `GITEA_TOKEN` env var (explicit env; `token` scheme only — preserves
+ *      the simple-token semantics).
+ *   3. Every host-matching entry in a git credential store, narrowed by repo
+ *      path specificity (most specific first). Each entry may be a PAT,
+ *      password, or OAuth token; the client tries each under `basic` and/or
+ *      `token` schemes per the username heuristic.
  *
  * owner/repo: `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO` (env) win; otherwise
- *   taken from the selected remote.
+ * taken from the selected remote.
+ *
+ * The result may have an empty `candidates` array (anonymous mode); the server
+ * still starts and a Skill guides the user to provide one. Write tools will
+ * fail with 401/403 until a working credential is added.
  */
-export declare function discoverConfig(options?: DiscoverOptions): Promise<DiscoveredConfig | null>;
+export declare function discoverConfig(options?: DiscoverOptions): Promise<CredentialDiscoveryResult | null>;