diff --git a/docs/superpowers/plans/2026-09-18-rfc-8628-device-authorization-research-note.md b/docs/superpowers/plans/2026-09-18-rfc-8628-device-authorization-research-note.md new file mode 100644 index 0000000..b800800 --- /dev/null +++ b/docs/superpowers/plans/2026-09-18-rfc-8628-device-authorization-research-note.md @@ -0,0 +1,27 @@ +# RFC 8628 Device Authorization Research Note Implementation Plan + +> **For agentic workers:** Execute this plan inline with validation checkpoints. + +**Goal:** Add and publish a sourced research note on RFC 8628 OAuth 2.0 Device Authorization Grant for headless agents and remote workloads. + +**Architecture:** Explain the device authorization endpoint, user/device codes, secondary-device consent, polling and token issuance, then map the flow to CF UAA, remote daemons, bindings, and audit while separating initial consent from downstream delegation. + +**Tech Stack:** Markdown, YAML frontmatter, Devbox, Git, GitHub CLI. + +--- + +### Task 1: Write `research/rfc-8628-device-authorization.md` + +- [ ] Add frontmatter with title `RFC 8628: Device Authorization for Headless Agents and Remote Workloads`, author `Ruben Koster (@rkoster)`, date `2026-09-18`, tags `[identity, authorization, orchestration, ecosystem-survey]`, `cf_areas: [uaa, capi, diego]`, `status: draft`, ratings, and RFC 8628/RFC Editor sources. +- [ ] Explain the constrained/headless client problem and the secondary-device authorization flow. +- [ ] Cover device authorization request, device code, user code, verification URI, expiry, polling interval, token request, and errors such as `authorization_pending`, `slow_down`, `access_denied`, and `expired_token`. +- [ ] Cover discovery and client authentication/public-client behavior. +- [ ] Explain brute-force, phishing, device trust, polling overload, user consent, and token storage security considerations. +- [ ] Assess CF relevance for UAA, headless CLIs, remote agent daemons, service bindings, user consent, token persistence, revocation, and audit. +- [ ] Distinguish device authorization from RFC 8693 token exchange and agent delegation; add open questions about device identity, polling, binding, and revocation. + +### 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 8628 device authorization research note`, push `research/rfc-8628-device-authorization`, and open a checklist-complete PR targeting `main`. +- [ ] Verify PR metadata and CI with `gh pr view`. diff --git a/docs/superpowers/specs/2026-09-18-rfc-8628-device-authorization-research-note-design.md b/docs/superpowers/specs/2026-09-18-rfc-8628-device-authorization-research-note-design.md new file mode 100644 index 0000000..0636ee6 --- /dev/null +++ b/docs/superpowers/specs/2026-09-18-rfc-8628-device-authorization-research-note-design.md @@ -0,0 +1,30 @@ +# RFC 8628 Device Authorization Research Note Design + +## Goal + +Add a sourced research note on RFC 8628 OAuth 2.0 Device Authorization Grant for headless +agents, CLIs, remote daemons, and constrained devices. + +## Scope + +The note will cover the device authorization request/response, device and user codes, +verification URI, user approval on a secondary device, polling, token issuance, discovery, and +security considerations including brute force, phishing, device trust, and polling control. +It will identify RFC 8628 as an IETF Proposed Standard. + +The Cloud Foundry analysis will map device authorization to UAA, remote agent daemons, service +bindings, human consent, headless workloads, token storage, polling, revocation, and audit. It +will not claim existing CF/RFC 8628 integration. + +## Structure and evidence + +Create `research/rfc-8628-device-authorization.md` with the required four sections and +frontmatter. Use RFC 8628, RFC Editor metadata, and OAuth references. Clearly distinguish device +authorization from agent delegation and token exchange: device flow obtains initial user consent; +it does not itself define downstream resource delegation policy. + +## Validation + +Run Devbox validation and tests, inspect whitespace/staged files, commit the note and plan on +`research/rfc-8628-device-authorization`, push, and open a PR targeting `main` without unrelated +artifacts. diff --git a/research/rfc-8628-device-authorization.md b/research/rfc-8628-device-authorization.md new file mode 100644 index 0000000..5ab8586 --- /dev/null +++ b/research/rfc-8628-device-authorization.md @@ -0,0 +1,107 @@ +--- +title: "RFC 8628: Device Authorization for Headless Agents and Remote Workloads" +author: Ruben Koster (@rkoster) +date: 2026-09-18 +tags: [identity, authorization, orchestration, ecosystem-survey] +cf_areas: [uaa, capi, diego] +status: draft +ratings: + platform-impact: + value: 80 + note: "Device authorization is a practical bridge for connecting headless agents, CLIs, and remote daemons to human identity without embedding a browser." + maturity: + value: 88 + note: "RFC 8628 is an IETF Proposed Standard with a defined flow, error behavior, and security considerations." + novelty: + value: 52 + note: "The protocol formalizes a constrained-device OAuth pattern rather than introducing an agent-specific delegation model." + actionability: + value: 86 + note: "The flow maps directly to CF UAA, remote agent daemons, service bindings, user consent, and token lifecycle operations." +sources: + - https://www.rfc-editor.org/rfc/rfc8628 + - https://www.rfc-editor.org/info/rfc8628/ + - https://datatracker.ietf.org/doc/rfc8628/ + - https://www.rfc-editor.org/rfc/rfc6749 +--- + +## Summary + +RFC 8628 defines the OAuth 2.0 Device Authorization Grant for clients that cannot use a +browser-based authorization flow locally or are difficult to operate interactively. The client +requests a device code and user code, asks the user to authorize on a separate device, and polls +the authorization server until a token is available. This makes it relevant to headless agent +CLIs, remote daemons, coding sandboxes, and CF-hosted workloads, while leaving downstream +delegation and resource policy to other OAuth mechanisms. + +## Key findings + +- **The flow separates the client from the user agent.** A device client makes outbound HTTPS + requests and displays a verification URI and code. The user completes authentication and + consent on a phone or computer, so the client does not need to receive inbound browser traffic. +- **The authorization server returns short-lived flow state.** The device authorization response + includes a `device_code`, a human-entered `user_code`, a verification URI, an optional complete + verification URI, an expiration, and a recommended polling interval. +- **The client polls the token endpoint.** Before consent, the token endpoint returns + `authorization_pending`. The client must respect the interval; `slow_down` increases the + interval for subsequent requests. After approval, the client receives an OAuth access token + or another configured token response. Denial and expiry have explicit errors. +- **The user code is usability-sensitive.** Because users type the code, it has lower entropy + than a bearer token. RFC 8628 requires rate limiting and finite lifetime to make guessing + infeasible, and recommends user-facing information that helps prevent authorizing an attacker + controlled device. +- **Device and user codes have different security roles.** The device code is used by the client + during polling and must be protected as sensitive flow state. The user code is entered by the + human and needs rate limiting, sufficient entropy, expiration, and phishing defenses. +- **Public clients are supported.** Clients that cannot keep credentials secret identify + themselves with `client_id`, while confidential clients authenticate according to OAuth rules. + The grant is therefore suitable for command-line tools, remote daemons, and devices with no + secure client-secret storage. +- **Polling needs capacity controls.** The protocol explicitly addresses token-endpoint load by + requiring an interval and warning clients not to begin device authorization automatically on + every startup or expired session. Implementations need rate limits and retry behavior. +- **Device trust is part of the threat model.** The authorization server cannot assume that a + device or agent client is trustworthy merely because a user approved a code. Token storage, + malware, remote phishing, authorization-server choice, and device integrity remain deployment + concerns. +- **Device authorization is not token exchange.** RFC 8628 obtains user authorization through a + secondary device. RFC 8693 exchanges an existing subject/actor token for a targeted token. + A headless agent may use RFC 8628 for initial login and RFC 8693 or another mechanism for + downstream delegation. +- **RFC 8628 is an IETF Proposed Standard.** It standardizes the flow and security behavior but + does not define an agent registry, workload identity, consent taxonomy, or resource-specific + least-privilege policy. + +## CF relevance + +Cloud Foundry could use RFC 8628 for headless CLIs, remote agent daemons, coding sandboxes, and +automation that cannot open a browser on the execution host. A CLI or daemon could request a +device code from UAA, display the verification URI/code to the user, poll for completion, and +store the resulting token using the daemon's credential and filesystem policy. + +The flow also fits remote agents running under Diego or an adjacent sandbox substrate. CAPI +could manage the application or daemon, while a service binding supplies the UAA endpoints and +client identifier. The resulting access token would need bounded scopes and secure persistence; +device authorization alone does not establish that an agent may access every tool or resource +available to the user. + +CF operators would need to expose clear device/user consent information, rate-limit polling, +support revocation and logout, and audit the link between device code, user, client/agent, +application instance, and resulting token. For long-running agents, RFC 8628 is primarily an +initial or renewal login mechanism; token exchange, refresh, workload identity, or a delegation +broker may be needed to obtain resource-specific and renewable authority. + +## Open questions + +- Should CF UAA expose RFC 8628 for remote agent daemons and headless platform clients? +- How should a device authorization request identify the CF application, agent, sandbox, or + daemon without confusing the runtime identity with the consenting user? +- Where should tokens be stored for Diego processes, remote daemons, and disposable sandboxes, + and how should replacement or migration affect them? +- How should device flow scopes combine with RFC 8693 exchange, agent delegation, and service + binding policy? +- What polling, expiry, retry, and revocation behavior should CF enforce across many agents? +- How should user consent, device details, client identity, token issuance, and downstream agent + actions be correlated in Loggregator and protected audit records? +- Which phishing, device-trust, and user-code protections should be added beyond the RFC when + the client is an autonomous or semi-autonomous agent?