diff --git a/docs/superpowers/plans/2026-09-18-rfc-8693-token-exchange-research-note.md b/docs/superpowers/plans/2026-09-18-rfc-8693-token-exchange-research-note.md new file mode 100644 index 0000000..62aed00 --- /dev/null +++ b/docs/superpowers/plans/2026-09-18-rfc-8693-token-exchange-research-note.md @@ -0,0 +1,27 @@ +# RFC 8693 Token Exchange Research Note Implementation Plan + +> **For agentic workers:** Execute this plan inline with validation checkpoints. + +**Goal:** Add and publish a sourced research note on RFC 8693 OAuth 2.0 Token Exchange for delegated agent authority. + +**Architecture:** Explain the STS exchange request/response, subject and actor tokens, targeting parameters, impersonation/delegation claims, and policy boundary. Map the protocol to CF identity and service-to-service authorization. + +**Tech Stack:** Markdown, YAML frontmatter, Devbox, Git, GitHub CLI. + +--- + +### Task 1: Write `research/rfc-8693-token-exchange.md` + +- [ ] Add frontmatter with title `RFC 8693: OAuth 2.0 Token Exchange for Delegated Agent Authority`, author `Ruben Koster (@rkoster)`, date `2026-09-18`, tags `[authorization, identity, inter-agent-comms, ecosystem-survey]`, `cf_areas: [uaa, capi, diego]`, `status: draft`, ratings, and RFC 8693/RFC Editor sources. +- [ ] Explain RFC 8693 as an IETF Proposed Standard defining an HTTP/JSON Security Token Service protocol. +- [ ] Cover token exchange parameters including grant type, subject token, actor token, resource, audience, scope, and requested token type. +- [ ] Distinguish impersonation, where the issued subject acts as the original subject, from delegation, where `sub` and `act` preserve the principal and current actor; cover `may_act` authorization. +- [ ] Explain that RFC 8693 provides protocol mechanics but authorization policy, trust in token issuers, key validation, and resource policy remain deployment responsibilities. +- [ ] Assess CF relevance for UAA, instance identity, service bindings, agent gateways, service-to-service calls, least privilege, and audit. +- [ ] Add open questions about subject/actor mapping, audience/resource policy, token lifetime, revocation, nested delegation, and audit semantics. + +### Task 2: Validate and publish + +- [ ] Run `devbox run validate`, `devbox run test`, and `git diff --check`. +- [ ] Stage only the note and approved spec/plan, commit `docs: add RFC 8693 token exchange research note`, push `research/rfc-8693-token-exchange`, and open a separate checklist-complete PR targeting `main`. +- [ ] Verify PR metadata and CI with `gh pr view`. diff --git a/docs/superpowers/specs/2026-09-18-rfc-8693-token-exchange-research-note-design.md b/docs/superpowers/specs/2026-09-18-rfc-8693-token-exchange-research-note-design.md new file mode 100644 index 0000000..302fa89 --- /dev/null +++ b/docs/superpowers/specs/2026-09-18-rfc-8693-token-exchange-research-note-design.md @@ -0,0 +1,28 @@ +# RFC 8693 Token Exchange Research Note Design + +## Goal + +Add a sourced research note on RFC 8693 OAuth 2.0 Token Exchange for delegated agent authority. + +## Scope + +The note will cover the Security Token Service model, token exchange request/response, subject +and actor tokens, resource/audience/scope targeting, impersonation versus delegation, `act` and +`may_act` claims, and security considerations. It will identify RFC 8693 as an IETF Proposed +Standard and distinguish protocol mechanics from authorization policy and identity issuance. + +The Cloud Foundry analysis will map token exchange to UAA, instance identity, service bindings, +agent gateways, least privilege, service-to-service calls, and audit. It will not claim existing +CF/RFC 8693 integration. + +## Structure and evidence + +Create `research/rfc-8693-token-exchange.md` with the required four sections and frontmatter. +Use RFC 8693 and related OAuth/OIDC references. Clearly distinguish impersonation from delegation +and explain that token exchange does not itself decide whether a requested delegation is allowed. + +## Validation + +Run Devbox validation and tests, inspect whitespace/staged files, commit the note and plan on +`research/rfc-8693-token-exchange`, push, and open a separate PR targeting `main` without +unrelated artifacts. diff --git a/research/rfc-8693-token-exchange.md b/research/rfc-8693-token-exchange.md new file mode 100644 index 0000000..ce5d27f --- /dev/null +++ b/research/rfc-8693-token-exchange.md @@ -0,0 +1,105 @@ +--- +title: "RFC 8693: OAuth 2.0 Token Exchange for Delegated Agent Authority" +author: Ruben Koster (@rkoster) +date: 2026-09-18 +tags: [authorization, identity, inter-agent-comms, ecosystem-survey] +cf_areas: [uaa, capi, diego] +status: draft +ratings: + platform-impact: + value: 88 + note: "Token exchange provides a standardized mechanism for agents and services to obtain narrowly targeted credentials without sharing broad user tokens." + maturity: + value: 86 + note: "RFC 8693 is an IETF Proposed Standard with established OAuth and Security Token Service terminology." + novelty: + value: 58 + note: "The protocol formalizes established STS impersonation and delegation patterns rather than defining an agent-specific identity model." + actionability: + value: 90 + note: "The subject/actor/audience model maps directly to CF UAA, workload identity, service bindings, and agent gateway authorization." +sources: + - https://www.rfc-editor.org/rfc/rfc8693 + - https://www.rfc-editor.org/info/rfc8693/ + - https://datatracker.ietf.org/doc/rfc8693/ + - https://www.rfc-editor.org/rfc/rfc6749 +--- + +## Summary + +RFC 8693 defines an HTTP and JSON protocol for OAuth 2.0 token exchange through a Security Token +Service. A client presents a subject token, optionally an actor token, and target parameters to +obtain a new token appropriate for a resource or audience. The protocol supports impersonation +and delegation, making it a foundational mechanism for agents that need scoped authority without +holding broad user or provider credentials. + +## Key findings + +- **RFC 8693 standardizes an STS interaction.** It defines how a client requests a security + token from an OAuth authorization server using the token-exchange grant type. The server + validates the presented token(s), applies policy, and issues a token for the requested use. +- **The request carries explicit context.** Exchange parameters include `subject_token`, its + type, optional `actor_token`, target `resource`, logical `audience`, requested `scope`, and + requested token type. These fields let a deployment bind the issued token to a target service + and constrained authority. +- **Impersonation and delegation differ.** In impersonation, the client acts as the subject and + the issued token can preserve the subject identity without identifying a distinct actor. In + delegation, the subject is the party on whose behalf action occurs and the actor token + identifies the party currently acting. +- **The `act` claim preserves actor context.** RFC 8693 examples show an issued token with + `sub` identifying the subject and `act.sub` identifying the delegated actor. This preserves + accountability while allowing the actor to use a token targeted at a downstream service. +- **`may_act` can constrain delegation.** A subject token can express an actor authorized to act + on its behalf. The authorization server still decides whether the requested exchange is + allowed, how scopes are reduced, and what claims appear in the issued token. +- **Targeting is a security boundary.** `resource` identifies a protected resource URI and + `audience` identifies a logical target service. The target service can reject a token issued for + another audience, reducing the value of a token leaked outside its intended path. +- **Token exchange is not authorization policy by itself.** RFC 8693 defines protocol fields and + flows, but deployments choose trusted issuers, token validation, allowed actors, scope + reduction, audience/resource policy, token lifetime, revocation, and key management. +- **The issued token is a new credential.** Exchange does not merely forward the subject token; + it produces a token with the authorization server's issuer, target, lifetime, scopes, and + identity/delegation context. Downstream services must validate the new token and enforce their + own resource policy. +- **The model supports multi-hop services.** A service can exchange or pass delegated authority + onward when policy permits, but each hop increases the need for bounded scopes, actor-chain + visibility, audience restrictions, and reliable audit. +- **RFC 8693 is an IETF Proposed Standard.** It is a protocol foundation, not a complete agent + identity system, consent UX, credential vault, or workload lifecycle mechanism. + +## CF relevance + +Cloud Foundry could use RFC 8693 to let an agent exchange a user or workload token for a +resource-specific token without receiving a broad credential. UAA could participate as the +authorization server or trusted issuer, while a CF instance identity certificate identifies +the running workload. A gateway could exchange the agent's subject/actor context for a token +targeted at a service, tool, route, or downstream application. + +Service bindings could carry exchange endpoints and constrained client credentials rather than +long-lived provider secrets. The resulting token could identify the user in `sub`, the agent or +gateway in `act`, and the target CF service in `aud` or `resource`. CAPI and Diego lifecycle +events could inform revocation when an application, process instance, binding, or delegation is +removed, while Loggregator could correlate exchange, downstream request, policy decision, and +outcome. + +The protocol does not remove the need for CF policy. A platform must decide which workloads may +act for which users, how scopes are narrowed, whether nested delegation is allowed, how short +tokens live, and how token exchange is audited. RFC 8693 is therefore a useful interoperability +boundary for an identity broker or gateway, not a substitute for UAA governance or application +authorization. + +## Open questions + +- What should `sub` and `act` represent for CF users, app instances, agents, gateways, and + delegated tools? +- Should UAA issue exchange tokens directly, or should a dedicated agent identity broker sit + between UAA and downstream services? +- How should `resource` and `audience` map to CF apps, routes, service instances, tools, and + external providers? +- Which scopes may be exchanged, and how must every delegation hop reduce or preserve authority? +- How should instance replacement, certificate rotation, grant revocation, and user logout + invalidate exchanged tokens? +- What token lifetime and replay protections are appropriate for long-running agent tasks? +- How should nested `act` chains and exchange events appear in Loggregator, audit records, and + downstream authorization decisions?