Design user-sponsored agent sessions for Apollo

[nobodyiam]

Background

Refs #5573 and #5624.

The first incremental step for agent-facing Apollo workflows is an official OpenAPI-based CLI. The more complex authorization model should be designed separately after the CLI surface and security expectations are clearer.

This issue tracks the later design direction for user-sponsored agent sessions.

Problem

Existing OpenAPI automation is based on Consumer tokens. That works for scripts and platforms, but it is not a complete agent authorization model:

• Consumer tokens may be too broad for AI-assisted workflows.
• An agent can be affected by prompt injection or untrusted context.
• Apollo configuration values may contain sensitive data.
• Some operations should be proposed or approved rather than executed directly.
• Audit should distinguish the sponsoring user, the agent/session context, and the actual operation.

Direction

Explore a user-sponsored agent session model:

• A user explicitly creates or approves a bounded agent session.
• The session is scoped to selected apps, envs, clusters, namespaces, and action classes.
• Effective permission is the intersection of the sponsoring user's permission and the session scope.
• High-risk operations require approval or are disabled by policy.
• Sensitive reads are redacted, separately approved, or disabled depending on policy.
• Audit records include user, session, agent/tool metadata, operation, target, and approval state.

Possible scope dimensions

• App scope: one or more app IDs.
• Environment scope: selected envs only.
• Namespace scope: selected namespaces or namespace patterns.
• Action scope: read, diff/propose, config write, release, rollback, permission/admin.
• Time scope: short-lived session expiration.
• Approval scope: operations that require explicit user confirmation.

Open questions

• Should the first server-side model introduce an Agent principal, or only an AgentSession sponsored by a user?
• How should Apollo classify sensitive config values for agent access?
• Which operations can be executed directly, proposed only, approval-required, or disabled by default?
• How should the CLI switch between Consumer token mode and future agent session mode?
• Should MCP or other agent protocol adapters call Portal directly, or go through the same governed CLI/OpenAPI semantics?

Out of scope for the first CLI release

• Implementing the server-side session model.
• Replacing existing Consumer token OpenAPI flows.
• Providing MCP before the trust and audit model is clear.

Acceptance criteria for this design issue

• A concrete trust-boundary proposal is documented.
• Scope and permission intersection rules are defined.
• Sensitive-read and mutation approval defaults are defined.
• Audit metadata requirements are defined.
• Follow-up implementation issues can be split for apollo-openapi, apollo-portal, CLI integration, and protocol adapters.

[github-actions]

🤖 Issue Triage

Thanks for opening this design discussion. The issue is well-structured with clear acceptance criteria and references to related work (#5573, #5624).

This tracks the user-sponsored agent session authorization model as a follow-up to the initial CLI implementation. The scope dimensions, open questions, and out-of-scope items provide a solid foundation for design exploration.

Maintainers can proceed with design discussions and split implementation issues once the trust-boundary proposal is documented.

AI generated by Apollo Issue Triage

[nobodyiam]

Current status and possible next direction

Current status: Apollo now has useful agent-facing tooling and user-scoped authorization foundations, but it does not yet implement a user-sponsored AgentSession or task-based authorization semantics.

Current progress

Since this issue was opened, several relevant building blocks have been completed:

• The initial Apollo CLI was implemented in apolloconfig/apollo-cli#1. It provides profile and credential management, structured JSON output and errors, secret redaction, mutation safeguards, configuration and release commands, and a generic apollo api command.
• #5632 introduced User Access Tokens for users, agents, and personal automation calling /openapi/v1/*.
• A User Access Token can be restricted by operation, AppId, environment, cluster, namespace, expiration time, revocation state, and rate limit. The API also exposes current-token and capability-discovery endpoints.
• Effective authorization is derived from both the user's current RBAC permissions and the token's UserTokenScope, and is validated on every request. UserTokenPermissionValidator provides a useful foundation for more contextual authorization.
• The CLI supports both user-token and consumer-token authentication.

However, the original agent-session model remains incomplete:

• A User Access Token is still a general bearer credential rather than a short-lived, task-oriented session credential.
• An allowed operation is normally executed directly.
• There is no server-side proposal and approval lifecycle.
• config:read does not distinguish between metadata access, redacted-value access, and approved raw-value access.
• Audit semantics do not yet cover the full chain from sponsor to session, proposal, approval, and execution.
• CLI confirmation such as --yes is a local safety mechanism, not an independent authorization approval. This distinction is also relevant to #5626.

Therefore, #5627 should remain open even though much of its underlying infrastructure now exists.

Possible direction for further discussion

One possible direction is to introduce a task-based access control layer above the existing RBAC and token-scope mechanisms.

RBAC answers:

What may this user generally do?

A task or agent session would answer:

What may this delegated agent do, for this specific task, during this limited period, and under which approval policy?

The effective permission could be modeled as:

effective permission
  = sponsor's current RBAC permission
  ∩ session/task scope
  ∩ action policy
  ∩ approval state

This would not replace the existing authorization models:

• Consumer tokens would continue to represent application or service identities.
• User Access Tokens would continue to provide scoped user delegation.
• Agent sessions or tasks would add short-lived context, workflow state, and approval semantics.

Possible domain concepts include:

• AgentSession: a short-lived delegated authorization context sponsored by a user.
• AgentTask: the purpose, resource boundary, and lifetime of a specific delegated task.
• AgentOperation: a proposed or executed operation with immutable arguments and audit identity.

Actions could have explicit policies such as:

• DIRECT
• REDACTED
• DRAFT_ONLY
• APPROVAL_REQUIRED
• DISABLED

For approval-required operations, the approval should be bound to the canonical request, target resources, and relevant resource revisions. Changing any of them should invalidate the approval.

The CLI and future MCP integrations should use the same governed Portal OpenAPI path. They should not introduce a separate high-privilege bypass.

Questions to resolve before implementation

1. Is a session plus a sequence of operations sufficient, or do we need a first-class AgentTask?
2. Should an agent session use a separate short-lived credential, or should User Access Tokens evolve to represent sessions?
3. Should all configuration values be treated as sensitive by default, or should approval and redaction support per-key policies?
4. Should mutations always begin as drafts, or may approval authorize the creation of the draft itself?
5. What should the default policy be for each action category?
6. Which lifecycle events and relationships must be recorded for audit and incident investigation?
7. Is the full model justified initially, or should the first version focus on short-lived, read-only, redacted sessions?

---

当前状态和可能的下一步方向

当前状态是：Apollo 已经具备面向 Agent 的工具入口和用户范围授权基础，但还没有实现 user-sponsored AgentSession 或基于任务的授权语义。

当前进展

自该 Issue 创建以来，已经完成了几项相关的基础工作：

• apolloconfig/apollo-cli#1 实现了初版 Apollo CLI，包括 profile 和凭证管理、结构化 JSON 输出和错误、敏感信息脱敏、变更操作保护、配置与发布命令，以及通用的 apollo api 命令。
• #5632 引入了 User Access Token，供用户、Agent 和个人自动化程序访问 /openapi/v1/*。
• User Access Token 可以按 operation、AppId、环境、集群、namespace、过期时间、吊销状态和速率限制进行约束，并提供当前 Token 信息和能力发现接口。
• 实际权限由用户当前的 RBAC 权限和 Token 的 UserTokenScope 共同决定，并在每次请求时重新校验。UserTokenPermissionValidator 为进一步实现上下文相关的授权提供了基础。
• CLI 同时支持 user-token 和 consumer-token 两种认证方式。

不过，最初设想的 Agent Session 模型仍未完成：

• User Access Token 仍然是通用的 bearer credential，而不是面向特定任务的短期会话凭证。
• 对于授权范围内的操作，系统通常会直接执行。
• 目前没有服务端的提案和审批生命周期。
• config:read 尚未区分元数据访问、脱敏值访问和经过批准的原始值访问。
• 审计语义尚未覆盖 sponsor、session、proposal、approval 和 execution 之间的完整关系。
• CLI 中的 --yes 等确认机制属于本地安全保护，不是独立的授权审批。这一区别也与 #5626 有关。

因此，即使底层基础已经有了较大进展，#5627 目前仍应保持 open。

进一步演进的可能方向

一个可能的方向是在现有 RBAC 和 Token Scope 机制之上增加一层基于任务的访问控制。

RBAC 回答的是：

这个用户通常可以做什么？

Task 或 Agent Session 回答的则是：

这个被委托的 Agent，在有限时间内，为了这个特定任务，可以做什么，并且需要遵守什么审批策略？

实际权限可以表示为：

实际权限
  = sponsor 当前拥有的 RBAC 权限
  ∩ session/task scope
  ∩ action policy
  ∩ approval state

它不会取代现有的授权模型：

• Consumer Token 继续表示应用或服务身份。
• User Access Token 继续提供具有范围限制的用户委托。
• Agent Session 或 Task 在此基础上增加短期上下文、工作流状态和审批语义。

可能涉及的领域概念包括：

• AgentSession：由用户发起并授权的短期委托上下文。
• AgentTask：特定委托任务的目的、资源边界和生命周期。
• AgentOperation：具有不可变参数和审计身份的待执行或已执行操作。

不同操作可以配置明确的策略，例如：

• DIRECT
• REDACTED
• DRAFT_ONLY
• APPROVAL_REQUIRED
• DISABLED

对于需要审批的操作，审批结果应当与规范化请求、目标资源以及相关资源版本绑定。任何内容发生变化后，原审批都应失效。

CLI 和未来的 MCP 集成都应使用同一套受治理的 Portal OpenAPI，不应引入单独的高权限旁路。

实现前需要讨论清楚的问题

1. Session 加一系列 Operation 是否已经足够，还是需要一等的 AgentTask？
2. Agent Session 应该使用独立的短期凭证，还是扩展 User Access Token 来表达 Session？
3. 是否应该默认把所有配置值都视为敏感信息，还是需要支持按 Key 配置脱敏和审批策略？
4. 变更操作是否必须先生成 Draft，还是审批可以授权创建 Draft 这一动作本身？
5. 各类操作的默认策略应该是什么？
6. 为满足审计和事件调查要求，需要记录哪些生命周期事件及其关联关系？
7. 初期是否需要实现完整模型，还是先从短期、只读、默认脱敏的 Session 开始？