docs: define auth broker p0 contract

2026-05-21 12:14:25 +00:00
parent 1dda130111
commit a2c469ee8c
2 changed files with 370 additions and 0 deletions
@@ -0,0 +1,215 @@
+# Auth Broker P0 Contract
+
+本文收口 GitHub issue/PR 权限注入的 P0 方案。P0 目标不是建设完整 IAM，也不是把 secret 分发给 runner；目标是先在 D601 dev 验证一个 Rust 单二进制 broker proxy，让 Code Queue runner 即使没有 `GH_TOKEN` / `GITHUB_TOKEN`，也能通过受控代理完成 GitHub issue/PR 访问和 PR preflight dry-run。
+
+## Existing Paths
+
+当前阻塞来自多个路径都把 GitHub 能力等同于 runner 环境变量：
+
+- `scripts/src/gh.ts`：UniDesk `gh` CLI 已经是 repo-native GitHub REST wrapper，优先读取 `GH_TOKEN`，其次读取 `GITHUB_TOKEN`，再 fallback 到系统 `gh auth token`。它不会打印 token 值，并已把 `missing-token`、`permission-denied`、`scope-insufficient`、`network-proxy-failed`、`unsupported-command` 等失败结构化。
+- `scripts/code-queue-pr-preflight-example.ts`：本地示例先检查 env token，再跑 `gh auth status`、`gh pr create --dry-run` 和 `gh pr comment --dry-run`。没有 env token 时该 workflow 直接失败。
+- `src/components/microservices/code-queue/src/runtime-preflight.ts`：D601 scheduler preflight 检查 `GH_TOKEN` / `GITHUB_TOKEN` 是否存在，用 curl/gh/git 探测 GitHub API、issue、PR、SSH 和可选 push dry-run。
+- `scripts/src/code-queue.ts`：`codex pr-preflight` 把 runtime preflight 压缩为 runner 合同；`tokenCoverageStatus` 目前要求 env token，缺失时输出 `failureKind=auth-missing`、`degradedReason=GH_TOKEN/GITHUB_TOKEN missing` 和 `runnerDisposition=infra-blocked`。
+- `src/components/microservices/code-queue/src/index.ts`：`CODE_QUEUE_REMOTE_CODEX_ENV_KEYS` 默认包含 `GH_TOKEN`、`GITHUB_TOKEN`、`GH_HOST`、`GITHUB_API_URL` 和 `GH_REPO`，用于把 scheduler env 继续传给 provider dev container。这是凭证分发路径，不适合作为 P0 的唯一解。
+- `src/components/microservices/code-queue/docker-compose.d601.yml`：D601 Code Queue 从 `.state/code-queue-d601.env` 读取运行时环境，并配置 provider-gateway egress proxy。该文件不能承载本任务中的真实 secret 值。
+- `src/components/microservices/code-queue/Dockerfile`：runner 镜像已经包含 `git`、`gh`、`curl`、`jq`、`rg`、`cargo`、`rustc` 和 `rustfmt`，足够执行轻量 broker client、preflight 和 contract test；本 P0 不需要为了调研临时安装新系统包。
+
+Artifact registry / deploy 路径的问题不同：D601 registry 是 host loopback 的 artifact cache，标准 CD 先验证 commit-pinned manifest，再 pull/import/retag/rollout。P0 auth broker 不代理 Docker registry credential、不替代 provider-gateway Host SSH、不执行 deploy apply，也不解决 production registry 发布授权。
+
+## P0 Scope
+
+P0 只解决 GitHub REST 权限不应出现在普通 runner env 中的问题：
+
+- 新增一个计划中的 Rust 单二进制服务，工作名 `auth-broker`。
+- 先只在 D601 dev 验证，入口只能是 k3s ClusterIP、backend-core/microservice 私有代理或 D601 loopback，不开放公网端口。
+- broker 持有服务端 GitHub 凭证引用并调用 GitHub REST；runner 不接收、不读取、不打印 `GH_TOKEN` / `GITHUB_TOKEN`。
+- API 只接受结构化 operation，不接受 shell、argv、任意 URL 或原始 `gh api`。
+- P0 不实现真实 secret 存储、轮换、用户身份绑定、细粒度授权、production rollout 或 registry/deploy 凭证代理。
+
+P0 可以让 Code Queue 并行推进，但必须把实现拆成互不冲突的 lane：Rust API skeleton、CLI client adapter、runtime-preflight contract、D601 dev manifest/dry-run、文档和 contract test。真实凭证配置、D601 dev Secret 创建、production 启用和 live write allowlist 需要人工确认。
+
+## API
+
+### `GET /health`
+
+只返回服务状态和 redacted capability，不返回 secret 值。
+
+```json
+{
+  "ok": true,
+  "service": "auth-broker",
+  "phase": "p0",
+  "github": {
+    "configured": true,
+    "credentialRef": "github:unidesk-dev",
+    "valuesPrinted": false
+  },
+  "capabilities": ["github.issue.read", "github.pr.read", "github.pr.preflight.dry-run"]
+}
+```
+
+### `POST /v1/github/gh`
+
+通用 GitHub issue/PR proxy。请求必须是结构化 JSON：
+
+```json
+{
+  "requestId": "uuid",
+  "caller": {
+    "plane": "code-queue",
+    "taskId": "codex_...",
+    "queueId": "default"
+  },
+  "repo": "pikasTech/unidesk",
+  "operation": "github.issue.read",
+  "dryRun": false,
+  "params": {
+    "number": 59,
+    "jsonFields": ["body", "title", "state"]
+  }
+}
+```
+
+P0 required operation allowlist:
+
+| Operation | Upstream | Remote write | P0 status |
+| --- | --- | --- | --- |
+| `github.auth.status` | GitHub REST rate limit + repo probe | no | enabled |
+| `github.issue.list` | `GET /repos/{owner}/{repo}/issues` | no | enabled |
+| `github.issue.read` | `GET /repos/{owner}/{repo}/issues/{number}` | no | enabled |
+| `github.pr.list` | `GET /repos/{owner}/{repo}/pulls` | no | enabled |
+| `github.pr.read` | `GET /repos/{owner}/{repo}/pulls/{number}` | no | enabled |
+| `github.pr.create` | planned request only when `dryRun=true` | no | enabled as dry-run |
+| `github.pr.comment.create` | planned request only when `dryRun=true` | no | enabled as dry-run |
+
+P0 explicitly blocks `gh pr merge`, issue/PR delete, arbitrary `gh api`, arbitrary HTTP proxying, raw git push, Docker registry login and deploy commands. Live GitHub writes can be added later only after a user-confirmed allowlist and identity/audit review; without that confirmation P0 mutation operations must return `dry-run-required`.
+
+### `POST /v1/github/pr-preflight`
+
+Runner-facing PR preflight proxy. It must preserve the existing `codex pr-preflight` semantics while replacing env-token coverage with broker coverage:
+
+```json
+{
+  "requestId": "uuid",
+  "repo": "pikasTech/unidesk",
+  "base": "master",
+  "head": "feature/example",
+  "issueNumber": 59,
+  "includePrCreateDryRun": true,
+  "includePushDryRun": false
+}
+```
+
+Successful response shape:
+
+```json
+{
+  "ok": true,
+  "runnerDisposition": "ready",
+  "failureKind": null,
+  "degradedReason": null,
+  "tokenCoverage": {
+    "ok": true,
+    "source": "auth-broker",
+    "scope": "broker-held-github-credential",
+    "runnerEnvTokenRequired": false,
+    "valuesPrinted": false
+  },
+  "prCapabilityContract": {
+    "targetBranch": "master",
+    "systemGhBinaryRequiredForWrites": false,
+    "preflightCreatesPr": false,
+    "preflightMergesPr": false,
+    "brokerProxy": {
+      "ok": true,
+      "operations": ["github.auth.status", "github.pr.create"],
+      "writesRemote": false
+    }
+  }
+}
+```
+
+Broker PR preflight can prove GitHub REST auth, repo visibility, issue/PR read, and PR create body/parameter shape. It cannot prove runner-local git push capability unless the runner still performs `git push --dry-run` with its own git credentials. Therefore `includePushDryRun=true` remains a runner-local check and may still fail as `git-remote-gap`.
+
+## Permission Boundary
+
+P0 permission is intentionally coarse because identity verification is not in scope:
+
+- Allowed repo list defaults to `pikasTech/unidesk`; unknown repos return `repo-not-allowed`.
+- Allowed operations are finite strings. The broker never executes caller-provided shell, argv or URLs.
+- Request body size is bounded. Markdown bodies are accepted only for planned dry-run output in P0.
+- Response redaction is mandatory. No response, log or audit field may contain token values, Authorization headers, cookie values or upstream credential material.
+- Broker-held credential is identified only by `credentialRef`, `credentialKind` and boolean readiness.
+- Network exposure is dev-only and private. Public frontend access must go through existing authenticated UniDesk proxy if exposed at all.
+- P0 does not grant production deploy, registry push/pull, provider token, database, k3s or host SSH permissions.
+
+## Audit Fields
+
+Every broker request must emit one JSONL audit record with these fields:
+
+| Field | Meaning |
+| --- | --- |
+| `requestId` | Caller-provided or broker-generated id |
+| `observedAt` | ISO timestamp |
+| `caller.plane` | `code-queue`, `ci`, `commander`, `manual-cli` or `unknown` |
+| `caller.taskId` / `caller.queueId` | Code Queue correlation, nullable |
+| `operation` | One allowlisted operation string |
+| `repo` | Owner/repo after allowlist validation |
+| `resource` | Issue/PR number or branch names, no body text |
+| `dryRun` | Whether upstream mutation is impossible |
+| `credentialRef` | Stable redacted credential reference |
+| `credentialValuePrinted` | Always false |
+| `upstream.method` / `upstream.path` | GitHub REST method/path without query secrets |
+| `status` | HTTP status returned to caller |
+| `ok` | Boolean success |
+| `failureKind` / `degradedReason` | Structured failure semantics |
+| `runnerDisposition` | `ready`, `infra-blocked` or `business-failed` |
+| `retryable` | Boolean retry hint |
+| `durationMs` | End-to-end broker latency |
+| `redaction.valuesPrinted` | Always false |
+
+Audit records may include body length and SHA-256 for planned PR/issue bodies, but must not store full Markdown bodies by default.
+
+## Failure Semantics
+
+P0 must use stable failure kinds so Code Queue can decide whether to retry, split blocker work or ask for manual action.
+
+| Failure kind | HTTP | Runner disposition | Retryable | Meaning |
+| --- | --- | --- | --- | --- |
+| `auth-not-configured` | 503 | `infra-blocked` | false | Broker has no configured GitHub credential reference |
+| `broker-unavailable` | 503 | `infra-blocked` | true | Broker service/proxy is unreachable |
+| `unauthorized-caller` | 403 | `infra-blocked` | false | Caller is outside the private dev/proxy boundary |
+| `repo-not-allowed` | 403 | `business-failed` | false | Repo is not in the broker allowlist |
+| `operation-not-allowed` | 403 | `business-failed` | false | Operation is not in the finite allowlist |
+| `dry-run-required` | 409 | `business-failed` | false | Mutation was requested but P0 only allows dry-run |
+| `validation-failed` | 400 | `business-failed` | false | Missing or invalid structured parameters |
+| `github-egress-failed` | 502 | `infra-blocked` | true | GitHub or proxy network path failed |
+| `github-rate-limited` | 429 | `infra-blocked` | true | GitHub returned rate limiting |
+| `github-permission-denied` | 403 | `infra-blocked` | false | Credential lacks repo or action access |
+| `scope-insufficient` | 403 | `infra-blocked` | false | Accepted scopes do not satisfy the operation |
+| `repo-not-found` | 404 | `business-failed` | false | Allowed repo/resource does not exist or is hidden |
+| `upstream-invalid-response` | 502 | `infra-blocked` | true | GitHub response could not be parsed safely |
+
+All failures must include `message`, `requestId`, `failureKind`, `degradedReason`, `runnerDisposition`, `retryable`, and a `next` array with bounded diagnostic commands or manual actions. None may include secret values.
+
+## D601 Dev Acceptance
+
+The minimum D601 dev verification is:
+
+1. Code Queue scheduler has no `GH_TOKEN` / `GITHUB_TOKEN` requirement for PR preflight success when broker is configured.
+2. `codex pr-preflight --remote` reports `tokenCoverage.source=auth-broker`, `runnerEnvTokenRequired=false` and `valuesPrinted=false`.
+3. Broker-backed issue/PR read returns structured GitHub data for `pikasTech/unidesk` through the stable proxy.
+4. Broker-backed PR create dry-run returns a planned operation with `writesRemote=false`.
+5. `includePushDryRun=true` is clearly reported as runner-local and can fail independently as `git-remote-gap`.
+6. Logs and audit records contain request ids, operation names and failure semantics, but no token values.
+7. No deploy, restart, production mutation, registry credential proxy or long-lived extra control plane is introduced by the verification itself.
+
+## Manual Confirmation Points
+
+These items are outside P0 automation and require user or operator confirmation:
+
+- Where the broker-held GitHub credential reference is mounted in D601 dev.
+- Whether P0 permits any live GitHub write. Default is read-only plus dry-run.
+- Whether Code Queue CLI should default to broker mode when env token is absent or require an explicit `--auth-broker` flag first.
+- Production exposure, production credentials, rotation, identity binding and per-user authorization.
+- Any deploy, restart, registry credential, provider token, database or k3s permission integration.
@@ -0,0 +1,155 @@
+import { readFileSync } from "node:fs";
+
+type RunnerDisposition = "ready" | "infra-blocked" | "business-failed";
+
+interface FailureContract {
+  failureKind: string;
+  httpStatus: number;
+  runnerDisposition: RunnerDisposition;
+  retryable: boolean;
+}
+
+const docPath = "docs/reference/auth-broker.md";
+const doc = readFileSync(docPath, "utf8");
+
+function assertCondition(condition: unknown, message: string, detail: unknown = {}): void {
+  if (!condition) throw new Error(`${message}: ${JSON.stringify(detail)}`);
+}
+
+function assertDocContains(text: string): void {
+  assertCondition(doc.includes(text), `missing auth broker doc text: ${text}`);
+}
+
+const requiredOperations = [
+  "github.auth.status",
+  "github.issue.list",
+  "github.issue.read",
+  "github.pr.list",
+  "github.pr.read",
+  "github.pr.create",
+  "github.pr.comment.create",
+];
+
+const forbiddenBoundaries = [
+  "gh pr merge",
+  "arbitrary `gh api`",
+  "Docker registry login",
+  "deploy commands",
+];
+
+const requiredAuditFields = [
+  "requestId",
+  "observedAt",
+  "caller.plane",
+  "operation",
+  "repo",
+  "credentialRef",
+  "credentialValuePrinted",
+  "runnerDisposition",
+  "retryable",
+];
+
+const failureContracts: FailureContract[] = [
+  { failureKind: "auth-not-configured", httpStatus: 503, runnerDisposition: "infra-blocked", retryable: false },
+  { failureKind: "broker-unavailable", httpStatus: 503, runnerDisposition: "infra-blocked", retryable: true },
+  { failureKind: "unauthorized-caller", httpStatus: 403, runnerDisposition: "infra-blocked", retryable: false },
+  { failureKind: "repo-not-allowed", httpStatus: 403, runnerDisposition: "business-failed", retryable: false },
+  { failureKind: "operation-not-allowed", httpStatus: 403, runnerDisposition: "business-failed", retryable: false },
+  { failureKind: "dry-run-required", httpStatus: 409, runnerDisposition: "business-failed", retryable: false },
+  { failureKind: "validation-failed", httpStatus: 400, runnerDisposition: "business-failed", retryable: false },
+  { failureKind: "github-egress-failed", httpStatus: 502, runnerDisposition: "infra-blocked", retryable: true },
+  { failureKind: "github-rate-limited", httpStatus: 429, runnerDisposition: "infra-blocked", retryable: true },
+  { failureKind: "github-permission-denied", httpStatus: 403, runnerDisposition: "infra-blocked", retryable: false },
+  { failureKind: "scope-insufficient", httpStatus: 403, runnerDisposition: "infra-blocked", retryable: false },
+  { failureKind: "repo-not-found", httpStatus: 404, runnerDisposition: "business-failed", retryable: false },
+  { failureKind: "upstream-invalid-response", httpStatus: 502, runnerDisposition: "infra-blocked", retryable: true },
+];
+
+const samplePreflightResponse = {
+  ok: true,
+  runnerDisposition: "ready" as const,
+  failureKind: null,
+  degradedReason: null,
+  tokenCoverage: {
+    ok: true,
+    source: "auth-broker",
+    scope: "broker-held-github-credential",
+    runnerEnvTokenRequired: false,
+    valuesPrinted: false,
+  },
+  prCapabilityContract: {
+    targetBranch: "master",
+    systemGhBinaryRequiredForWrites: false,
+    preflightCreatesPr: false,
+    preflightMergesPr: false,
+    brokerProxy: {
+      ok: true,
+      operations: ["github.auth.status", "github.pr.create"],
+      writesRemote: false,
+    },
+  },
+};
+
+function walk(value: unknown, path: string[] = []): void {
+  if (typeof value === "string") {
+    assertCondition(!/gh[pousr]_[A-Za-z0-9_]{20,}/u.test(value), "sample must not contain GitHub token-like values", { path, value });
+    assertCondition(!/github_pat_[A-Za-z0-9_]+/u.test(value), "sample must not contain GitHub PAT-like values", { path, value });
+    assertCondition(!/^Bearer\s+/iu.test(value), "sample must not contain Authorization header values", { path, value });
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => walk(item, [...path, String(index)]));
+    return;
+  }
+  if (typeof value === "object" && value !== null) {
+    for (const [key, entry] of Object.entries(value)) {
+      assertCondition(!["token", "secret", "authorization", "cookie"].includes(key.toLowerCase()), "sample must not expose secret-bearing keys", { path, key });
+      walk(entry, [...path, key]);
+    }
+  }
+}
+
+function main(): void {
+  for (const heading of ["## Existing Paths", "## API", "## Permission Boundary", "## Audit Fields", "## Failure Semantics", "## D601 Dev Acceptance"]) {
+    assertDocContains(heading);
+  }
+  for (const path of [
+    "scripts/src/gh.ts",
+    "scripts/code-queue-pr-preflight-example.ts",
+    "src/components/microservices/code-queue/src/runtime-preflight.ts",
+    "scripts/src/code-queue.ts",
+    "src/components/microservices/code-queue/src/index.ts",
+    "src/components/microservices/code-queue/docker-compose.d601.yml",
+    "src/components/microservices/code-queue/Dockerfile",
+  ]) {
+    assertDocContains(path);
+  }
+  for (const operation of requiredOperations) assertDocContains(operation);
+  for (const boundary of forbiddenBoundaries) assertDocContains(boundary);
+  for (const field of requiredAuditFields) assertDocContains(field);
+  for (const failure of failureContracts) {
+    assertDocContains(failure.failureKind);
+    assertCondition(Number.isInteger(failure.httpStatus) && failure.httpStatus >= 400, "failure HTTP status must be an error status", failure);
+  }
+  assertCondition(new Set(failureContracts.map((item) => item.failureKind)).size === failureContracts.length, "failure kinds must be unique", failureContracts);
+  assertCondition(samplePreflightResponse.tokenCoverage.source === "auth-broker", "preflight should use broker token coverage", samplePreflightResponse.tokenCoverage);
+  assertCondition(samplePreflightResponse.tokenCoverage.runnerEnvTokenRequired === false, "runner env token must not be required", samplePreflightResponse.tokenCoverage);
+  assertCondition(samplePreflightResponse.prCapabilityContract.brokerProxy.writesRemote === false, "P0 preflight must not write remotely", samplePreflightResponse.prCapabilityContract);
+  assertCondition(samplePreflightResponse.prCapabilityContract.preflightMergesPr === false, "P0 preflight must not merge PRs", samplePreflightResponse.prCapabilityContract);
+  walk(samplePreflightResponse);
+
+  process.stdout.write(`${JSON.stringify({
+    ok: true,
+    docPath,
+    operations: requiredOperations,
+    failureKinds: failureContracts.map((item) => item.failureKind),
+    p0Safety: {
+      runnerEnvTokenRequired: false,
+      preflightWritesRemote: false,
+      secretValuesPrinted: false,
+      liveWritesDefault: "dry-run-required",
+    },
+  }, null, 2)}\n`);
+}
+
+main();