pikasTech-agentrun/docs/reference/spec-v01-secret-distribution.md

v0.1 Secret 与 provider credential 分发规格

本文定义 AgentRun v0.1 的 Secret 和 Code Agent provider credential 分发边界。真实 Code Agent backend 需要上游模型凭据；Codex stdio profile 测试凭据以 ~/.codex/auth.json、~/.codex/config.toml 和必要的 profile-local model catalog 形态为输入源，通过 Kubernetes Secret 投影进入 runner/backend Pod。这些值不得进入 Git source、GitOps branch、artifact catalog、event、trace、日志或 CLI 输出。

在装配 SPEC 中，本文承担 SecretRef、projection、rotation 和 redaction 规则；运行时 credential 必须先归入 ProfileRef、ResourceBundleRef.credentialRef 或 executionPolicy.secretScope.toolCredentials[]，再由 runner Job 装配。权威装配模型见 spec-v01-runtime-assembly.md。

设计目标

• API Key、Codex auth/config 等 provider credential 只通过 Kubernetes SecretRef 分发到需要它的 manager、runner 或 backend adapter。
• deploy/deploy.json 只记录 SecretRef 名称、key 名称、mount/env intent 和 secret scope，不记录 Secret 值。
• v0.1-gitops 的 rendered manifests 只能引用 Secret 名称和 key，不包含 Secret data。
• agentrun-mgr 保存 run 的 executionPolicy.secretScope，但保存的是 credential source reference，不是 credential value。
• runner 和 backend adapter 只能消费 manager 已授权的 secret scope，不能枚举 namespace 内所有 Secret。

Secret 分类

Secret 类别	用途	默认消费者	v0.1 规则
Postgres DSN	manager 连接 durable store	agentrun-mgr	只通过 agentrun-v01-mgr-db/DATABASE_URL 注入。
Codex stdio profile 凭据文件	真实 Code Agent backend 调上游模型	runner 或 backend adapter	codex、deepseek 与 minimax-m3 使用 auth.json/config.toml 文件形态；dsflash-go 额外要求 model-catalog.json。这些文件只通过 profile-scoped Kubernetes SecretRef 文件投影注入，不写入 run payload。
Git SSH deploy key	Tekton checkout source/GitOps promotion，Argo 读取 GitOps branch	Tekton、Argo CD	只存在于 agentrun-ci 或 argocd Secret；不进入 runtime Pod。
Registry credential	push/pull private registry	Tekton、runtime imagePullSecret	只作为 ServiceAccount/imagePullSecret 引用。
Tool credential	GitHub PR、issue、UniDesk SSH passthrough、artifact registry 等 agent shell/tool 授权	runner/backend adapter	必须通过 executionPolicy.secretScope.toolCredentials[] 的 SecretRef 装配进入运行时；不是 Queue integration，也不能用 transientEnv 承载长期 credential。
Future tenant credential	tenant 专属工具或外部服务	runner/backend adapter	必须先扩展装配 SPEC 的 SecretRef 和 secret scope，再允许 run 引用。

固定命名建议

对象	v0.1 建议
Manager DB Secret	agentrun-v01-mgr-db key DATABASE_URL
Codex Provider Secret	agentrun-v01-provider-codex keys auth.json、config.toml
DeepSeek Provider Secret	agentrun-v01-provider-deepseek keys auth.json、config.toml
MiniMax-M3 Provider Secret	agentrun-v01-provider-minimax-m3 keys auth.json、config.toml
dsflash-go Provider Secret	agentrun-v01-provider-dsflash-go keys auth.json、config.toml、model-catalog.json
Provider projection target	只读 /var/run/agentrun/secrets/<profile>-<index>/auth.json、config.toml 和 profile 需要的额外文件，再复制到当前 run/profile 的 writable CODEX_HOME
Provider config	非敏感 base URL/model 可以来自 config.toml 或 ConfigMap；credential value 不得放入 ConfigMap。
Tekton Git SSH Secret	agentrun-ci/agentrun-git-ssh
Argo Git SSH Secret	argocd/agentrun-git-ssh
GitHub Tool Secret	agentrun-v01-tool-github-pr key GH_TOKEN
UniDesk SSH Tool Secret	agentrun-v01-tool-unidesk-ssh key UNIDESK_SSH_CLIENT_TOKEN
Runtime ServiceAccount	agentrun-v01-mgr、agentrun-v01-runner

命名可以在实现时因集群约束调整，但必须满足 lane 独立、用途单一、最小 RBAC 和不跨 v0.1/v0.2 复用的原则。

Codex 测试凭据注入

v0.1 综合联调使用的 Codex stdio profile 测试凭据源固定为 operator 环境中的文件形态：

~/.codex/auth.json
~/.codex/config.toml

这两个文件只能作为 Kubernetes Secret 创建或轮换的输入源。codex profile 默认使用 operator 当前 Codex 配置；deepseek profile 使用 operator 准备的 DeepSeek-compatible Codex 配置，可以来自另一个 --codex-home 或显式 --auth-file/--config-file；minimax-m3 profile 使用从 HWLAB Code Queue 现有 MiniMax API key 派生的 Codex 配置，模型固定为 MiniMax-M3，wire API 使用当前 Codex app-server 支持的 responses；dsflash-go 使用 deepseek-v4-flash、1M/900k context 和 model-catalog.json。禁止把宿主机 ~/.codex 以 hostPath 挂入 runner/backend Pod，禁止复制进镜像，禁止提交到 source branch、GitOps branch、artifact catalog、issue、PR、event、trace、日志或 CLI 输出。

默认 Secret projection 规则：

项目	v0.1 规格
Kubernetes Secret	agentrun-v01/agentrun-v01-provider-codex、agentrun-v01/agentrun-v01-provider-deepseek、agentrun-v01/agentrun-v01-provider-minimax-m3 或 agentrun-v01/agentrun-v01-provider-dsflash-go
Secret key	auth.json，来自 ~/.codex/auth.json
Secret key	config.toml，来自 ~/.codex/config.toml
Secret key	model-catalog.json，仅 dsflash-go 必需，必须与 config.toml 的 model_catalog_json 指向同一 runtime 路径。
Projection path	只读 Secret projection 挂到 /var/run/agentrun/secrets/<profile>-<index>/auth.json、config.toml 和 profile 需要的额外文件；该路径只作为 credential source。
Runtime config path	runner 启动时把当前 backendProfile 授权的 Secret projection 复制到 writable CODEX_HOME，Kubernetes Job 默认使用该 Job 独占的 /home/agentrun/.codex-<profile>/auth.json、config.toml 和 profile 需要的额外文件；复用进程必须使用 run/profile 独占目录。
Projection mode	只读，建议 0400 或等价最小权限
Runtime env	HOME=/home/agentrun，CODEX_HOME=/home/agentrun/.codex-<profile>，AGENTRUN_CODEX_SECRET_HOME=<projection path>；不得 fallback 到节点宿主机 home。

Secret 创建和轮换必须通过 Kubernetes 密钥管理完成。deploy/deploy.json 只写 SecretRef 名称、key 和 mount intent；v0.1-gitops rendered manifests 只引用 Secret，不包含 Secret data。

Provider API Key 的 Web 配置由 spec-v01-provider-profile-management.md 定义：HWLAB Cloud API 鉴权后委托 AgentRun manager 更新受控 profile Secret/config。该路径仍只写 Kubernetes Secret data，不把 API Key 写入 Git、GitOps、Postgres、event、trace、日志或 CLI 输出。

Run secretScope 合同

Run 的 executionPolicy.secretScope 只能包含引用，不包含值。provider credential 使用 providerCredentials[]；GitHub PR、UniDesk SSH passthrough 等 agent shell/tool 授权使用装配 SPEC 定义的 toolCredentials[]，不得混入 transientEnv。示例形态：

{
  "providerCredentials": [
    {
      "profile": "codex",
      "secretRef": {
        "namespace": "agentrun-v01",
        "name": "agentrun-v01-provider-codex",
        "keys": ["auth.json", "config.toml"],
        "mountPath": "~/.codex"
      }
    },
    {
      "profile": "deepseek",
      "secretRef": {
        "namespace": "agentrun-v01",
        "name": "agentrun-v01-provider-deepseek",
        "keys": ["auth.json", "config.toml"],
        "mountPath": "~/.codex"
      }
    },
    {
      "profile": "minimax-m3",
      "secretRef": {
        "namespace": "agentrun-v01",
        "name": "agentrun-v01-provider-minimax-m3",
        "keys": ["auth.json", "config.toml"],
        "mountPath": "~/.codex"
      }
    },
    {
      "profile": "dsflash-go",
      "secretRef": {
        "namespace": "agentrun-v01",
        "name": "agentrun-v01-provider-dsflash-go",
        "keys": ["auth.json", "config.toml", "model-catalog.json"],
        "mountPath": "~/.codex"
      }
    }
  ],
  "allowCredentialEcho": false
}

规则：

• allowCredentialEcho 必须固定为 false。
• secretRef.namespace 默认只能是 run 所在 lane namespace 或明确批准的 platform namespace。
• manager 可以保存 secretRef，但不得读取 Secret 值后存库。
• runner/backend adapter 获得 Secret 的方式必须来自 Kubernetes env/file projection 或受限 Secret API 读取；Codex 默认从只读 Secret projection 复制 auth.json、config.toml 和 profile 需要的额外文件到 writable CODEX_HOME 后启动 app-server，不得通过 run payload、event、CLI 参数或日志传递。
• runner/backend adapter 只能选择与 run backendProfile 同名的 provider credential；backendProfile=deepseek、backendProfile=minimax-m3 或 backendProfile=dsflash-go 缺少 matching SecretRef 时必须 secret-unavailable，不得 fallback 到 codex 或另一个 profile。
• manager 会按内建 profile 的 requiredSecretKeys 规范化 secretRef.keys；消费侧旧 payload 即使只提交 auth.json/config.toml，dsflash-go runner Job 也必须投影 model-catalog.json。若实际 Kubernetes Secret 缺少该 key，run 必须在装配或 readiness 阶段失败为结构化 secret-unavailable。
• Secret projection 不能直接作为 CODEX_HOME。Codex app-server 会读取并可能维护默认配置、PATH 或运行态文件；把只读 Secret volume 直接挂到 CODEX_HOME 会造成启动期写入失败。v0.1 的固定边界是：Secret volume 只读、/home/agentrun 由 emptyDir 提供可写 runtime home、复制动作只发生在 runner/backend 容器内且不打印文件内容。
• SecretRef 不存在或 RBAC 不允许时，run 必须失败为结构化 failureKind=secret-unavailable 或等价错误，不得降级成无凭证重试风暴。
• toolCredentials 的 SecretRef/projection/redaction 规则以 spec-v01-runtime-assembly.md 为准；本文只约束 Secret value 不落库、不输出、不进入 Git source 或 GitOps Secret data。

runner-job transientEnv

transientEnv 用于承接调度方生成的短期、单次 runner Job 运行上下文，例如 HWLAB Code Agent 的 owner-scoped HWPOD/runtime API key、runtime URL 和非敏感 UniDesk frontend 地址。它也可以承接 manager 因 tool=unidesk-ssh 自动补齐的受控默认 endpoint env。它不是 provider credential、tool credential，也不是 run durable fact。

规则：

• transientEnv 只能出现在 POST /api/v1/runs/:runId/runner-jobs 请求中；不得写入 CreateRunInput、command payload、event payload 或 result envelope 的 value 明文。
• manager 不对 transientEnv 条目数量设固定上限，只校验数组形态、env name 合法且唯一、value 非空和单值长度；runner job payload hash 只纳入 env name 与 value hash。
• 当 run 请求 executionPolicy.secretScope.toolCredentials[].tool=unidesk-ssh 且调用方未提供 UNIDESK_MAIN_SERVER_IP、UNIDESK_MAIN_SERVER_HOST 或 UNIDESK_FRONTEND_URL 时，manager 可以从受控默认配置自动补齐一个非敏感 endpoint env。该自动补齐必须遵守同一 redaction 规则，只显示 name/count/hash 和 valuesPrinted=false。
• response、runner job status、event 和 dry-run manifest 只能展示 env name、count、SecretRef metadata 和 valuesPrinted=false；dry-run manifest 中的 transient env value 必须显示为 REDACTED。
• 正式 Kubernetes runner Job 不得把 transientEnv value 作为 pod spec plain env value。manager 必须先创建本次 Job 专属的短期 Kubernetes Secret，再在 runner container env 中使用 valueFrom.secretKeyRef 引用对应 key。Secret name、namespace、keys、ownerReference attached 状态和 valuesPrinted=false 可以出现在 response/event/trace 中，Secret data 和 env value 不得出现。
• 本次 Job 专属 transient env Secret 必须带有 run/command/attempt/runner/job metadata，创建 Job 失败时清理已创建 Secret；Job 创建成功后尽量给 Secret 加上 ownerReference，让 Kubernetes 随 Job GC。ownerReference patch 失败必须以 warning 暴露，不能回退为 plain env value。
• transientEnv token 必须由调度方控制 TTL、权限和业务授权范围；AgentRun 只负责本次 runner Job 的短期投影和 redaction，不把它升级为长期 credential。
• AgentRun 不解释 HWLAB HWPOD 权限，也不把业务鉴权做成通用 policy；AgentRun 只负责不持久化、不回显、不扩散这类短期 env value。
• GitHub token、UniDesk SSH client token、SSH private key、provider API key、registry token 等 provider/tool 可复用 credential 不得通过 transientEnv 注入；必须先进入装配 SPEC 的 SecretRef 路径。HWLAB dispatcher 生成并限定 owner/HWPOD/runtime scope 的 HWLAB_API_KEY 属于业务运行上下文，可以作为单次 runner Job env 透传，但不得变成 AgentRun durable fact 或通用授权。

分发路径

v0.1 默认路径：

deploy/deploy.json
  -> declares SecretRef names and mount/env intent only
Tekton promotion
  -> renders SecretRef references into v0.1-gitops manifests
Argo CD
  -> syncs workload references to agentrun-v01
Kubernetes Secret
  -> created from profile-specific auth.json, config.toml and required extra files by operator or approved secret-management flow
runner/backend Pod
  -> receives Codex auth/config/model catalog via read-only file projection
  -> copies authorized files into writable CODEX_HOME before starting Codex app-server

Secret 创建和轮换不由 source branch 自动生成；source branch 只声明需要哪个 SecretRef。后续如果接入 External Secrets、Vault、SealedSecrets 或 SOPS，必须新增或更新本 spec，明确 controller、source of truth、rotation 和 redaction 规则。

Codex Secret dry-run 工具

v0.1 提供只读 CLI 工具，用 operator 本地 ~/.codex/auth.json、~/.codex/config.toml 和 profile 需要的额外文件构造 Kubernetes Secret 创建计划：

./scripts/agentrun secrets codex render --dry-run [--profile codex|deepseek|minimax-m3|dsflash-go]

可选参数：

• --codex-home <dir>：覆盖默认 ~/.codex 输入目录。
• --profile <name>：默认 codex；deepseek、minimax-m3 和 dsflash-go 使用同一文件形态但默认 Secret name 分别为对应 agentrun-v01-provider-<profile>。
• --auth-file <path> / --config-file <path>：分别覆盖输入文件路径。
• --model-catalog-file <path>：覆盖 dsflash-go 的 model-catalog.json 输入文件路径。
• --namespace <name>：默认 agentrun-v01。
• --secret-name <name>：默认随 profile 变化，codex 为 agentrun-v01-provider-codex，deepseek 为 agentrun-v01-provider-deepseek，minimax-m3 为 agentrun-v01-provider-minimax-m3。

输出必须是 JSON，并且只包含 namespace、secretName、keys、每个输入文件的 bytes、sha256/contentHash、整体 hash、redaction 状态、apply 命令形状和 Secret manifest 摘要。输出不得包含 Secret value、auth.json 明文、config.toml 明文、model-catalog.json 明文、base64 data 字段或可直接恢复 credential 的内容。工具只支持 --dry-run；不得执行 kubectl apply。

失败必须结构化返回 failureKind：缺文件、不可读文件或空 credential 归类为 secret-unavailable；非法 JSON/TOML 归类为 schema-invalid。

日志与事件 Redaction

• event、trace、日志、CLI 输出、health 和 diagnostics 不得打印 Secret 值。
• Authorization、api_key、token、password、URL credential、DSN password、Codex auth.json 和 config.toml 文件内容必须 redacted。
• 可以打印 SecretRef 名称、key 名称、credential source、是否存在、是否被挂载、是否通过 readiness 检查。
• provider auth 失败只能报告 failure kind、HTTP status 分类和 request id；不得打印请求 header 或 body 中的凭据。

测试规格

T1 SecretRef render

阅读本文和 spec-v01-cicd.md，然后检查 deploy/deploy.json 只包含 SecretRef 名称/key 和 mount/env intent；rendered GitOps manifest 也只包含 SecretRef，不包含 Secret data。

T2 Runner credential projection

阅读本文，然后分别启动 backendProfile=codex、backendProfile=deepseek、backendProfile=minimax-m3 与 backendProfile=dsflash-go 的最小 backend runner dry-run，确认 Pod file projection 挂在 /var/run/agentrun/secrets/... 且只读，/home/agentrun 是 writable runtime home，runner/backend 只把当前 profile 授权文件复制到 CODEX_HOME 后再启动 Codex；dsflash-go 必须同时投影并复制 model-catalog.json；event、日志和 CLI 输出只显示 redacted credential source，不显示文件内容。

T3 Missing secret failure

阅读本文，然后用一个不存在的 provider SecretRef 创建 run，确认 run 失败为结构化 secret-unavailable，不会打印 Secret 值，也不会无限重试。

T4 transientEnv SecretRef 投影

阅读本文，然后通过正式 runner-jobs 或 Queue dispatch 路径创建带 transientEnv 的真实 runner Job。检查 runner job response、event、dry-run manifest 和 Kubernetes Pod spec：response/event 只能输出 env names、Secret name/namespace/keys、ownerReference 状态和 valuesPrinted=false；Pod spec 中对应 env 必须是 valueFrom.secretKeyRef，不能包含 value；Secret data 只能通过 Kubernetes Secret 保存，验证时只允许读取 key 列表和 metadata，不得输出 value。

规格的实现情况

规格项	状态	说明
Secret 分发规格	已定义	本文为 v0.1 provider credential 分发权威。
Kubernetes SecretRef 注入	已实现/已通过主闭环	runner Job dry-run 和正式 Job 创建路径已按 run executionPolicy.secretScope.providerCredentials 生成 Secret volume projection、writable runtime home 和 AGENTRUN_CODEX_SECRET_HOME；真实 Secret 与 Codex turn 已通过主闭环。
Codex Secret dry-run 工具	已实现	./scripts/agentrun secrets codex render --dry-run 只输出 Secret 创建计划、hash 和 redacted manifest 摘要，不执行 apply。
Codex auth/config file projection	已实现主路径	backend readiness 检查 auth.json/config.toml 可读性，缺失时返回 secret-unavailable；真实 runner Job 将只读 projection 复制到 writable CODEX_HOME。
DeepSeek profile SecretRef	已实现/已通过主闭环	已新增 agentrun-v01-provider-deepseek render、GitOps/RBAC 引用、Job projection、profile 选择和负向 missing-secret 自测试；真实 Secret 创建与 Kubernetes Job projection 已通过主闭环，轮换仍由 Kubernetes 密钥管理流程完成。
MiniMax-M3 profile SecretRef	已实现/待真实主闭环	已新增 agentrun-v01-provider-minimax-m3 render、GitOps/RBAC 引用、Job projection、profile 选择和负向 missing-secret 自测试；真实 Secret 创建使用 HWLAB Code Queue 现有 MiniMax API key，轮换仍由 Kubernetes 密钥管理流程完成。
dsflash-go profile SecretRef	已实现/待真实主闭环	已新增 agentrun-v01-provider-dsflash-go 的 model-catalog.json required key、Secret render、Job projection、writable CODEX_HOME 复制和负向 readiness；真实 profile turn 仍需按 provider 管理 canary 和 HWLAB 原入口复测。
Tool credential SecretRef	已实现最小 env projection	executionPolicy.secretScope.toolCredentials[] 已支持 tool=github、tool=unidesk-ssh 与 projection.kind=env，runner Job 通过 Kubernetes secretKeyRef 注入 env；CLI、event、runner job response 和 dry-run 只显示 SecretRef/projection 元数据，不输出值。
redaction 最小规则	已实现主路径	Secret dry-run 工具、event、Job dry-run 输出、self-test 和真实主闭环均不打印 Secret value；复杂审计按 spec-v01-validation.md 人工抽查。
外部 secret manager	未采用	如需 Vault/ExternalSecrets/SOPS，后续单独更新规格。