docs: add Agentic Identity Broker research note

docs/superpowers/plans/2026-09-18-agentic-identity-broker-research-note.md

@@ -0,0 +1,27 @@
+# Agentic Identity Broker Research Note Implementation Plan
+
+> **For agentic workers:** Execute this plan inline with validation checkpoints.
+
+**Goal:** Add and publish a sourced research note on Agentic Identity Broker as delegated OAuth and credential mediation infrastructure.
+
+**Architecture:** Describe the broker's consent/grant model, trusted proxy boundary, dual-port Go service, encrypted token vault, and RFC 8693 gateway exchange. Map these capabilities to CF identity, bindings, service policy, agent/tool authorization, and audit.
+
+**Tech Stack:** Markdown, YAML frontmatter, Devbox, Git, GitHub CLI.
+
+---
+
+### Task 1: Write `research/agentic-identity-broker.md`
+
+- [ ] Add frontmatter with title `Agentic Identity Broker: Delegated OAuth and Credential Mediation`, author `Ruben Koster (@rkoster)`, date `2026-09-18`, tags `[authorization, identity, observability-governance, ecosystem-survey]`, `cf_areas: [uaa, capi, diego, loggregator]`, `status: draft`, ratings, and official website/concept/API sources.
+- [ ] Explain principal, agent, third-party service, permission set, grant, and user-session objects, including expiry and revocation.
+- [ ] Describe the trusted reverse-proxy authentication boundary and dual-port service topology for end-user versus admin surfaces.
+- [ ] Cover consent UI, encrypted token storage with envelope encryption, and the rule that agents do not receive long-lived provider credentials.
+- [ ] Explain RFC 8693 token exchange, resource-based provider selection, gateway client assertions, and audit identities.
+- [ ] Assess CF relevance for UAA, instance identity, service bindings, service brokers, agent/tool authorization, credential rotation, and Loggregator.
+- [ ] Add open questions about canonical agent identity, delegated authority, token exchange placement, revocation latency, service policy, and audit/privacy.
+
+### 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 Agentic Identity Broker research note`, push `research/agentic-identity-broker`, and open a checklist-complete PR targeting `main`.
+- [ ] Verify PR metadata and CI with `gh pr view`.

docs/superpowers/specs/2026-09-18-agentic-identity-broker-research-note-design.md

@@ -0,0 +1,30 @@
+# Agentic Identity Broker Research Note Design
+
+## Goal
+
+Add a sourced research note on Agentic Identity Broker as delegated OAuth and credential
+mediation infrastructure for AI agents.
+
+## Scope
+
+The note will cover the broker's principals, agents, services, permission sets, grants, user
+sessions, consent UI, dual-port architecture, trusted proxy boundary, encrypted token vault,
+RFC 8693 token exchange, optional Envoy ExtProc sidecar, and audit identities. It will explain
+why agents should not receive long-lived third-party provider credentials.
+
+The Cloud Foundry analysis will map the broker to UAA, instance identity, service bindings,
+agent/tool authorization, service brokers, credential rotation, and Loggregator/audit. It will
+not claim existing CF integration.
+
+## Structure and evidence
+
+Create `research/agentic-identity-broker.md` with the required four sections and frontmatter.
+Use the official website concepts, architecture, delegation, token exchange, encryption, and API
+documentation. Clearly distinguish authentication at the trusted edge from authorization and
+credential mediation inside the broker.
+
+## Validation
+
+Run Devbox validation and tests, inspect whitespace/staged files, commit the note and plan on
+`research/agentic-identity-broker`, push, and open a PR targeting `main` without unrelated
+artifacts.

research/agentic-identity-broker.md

@@ -0,0 +1,115 @@
+---
+title: "Agentic Identity Broker: Delegated OAuth and Credential Mediation"
+author: Ruben Koster (@rkoster)
+date: 2026-09-18
+tags: [authorization, identity, observability-governance, ecosystem-survey]
+cf_areas: [uaa, capi, diego, loggregator]
+status: draft
+ratings:
+  platform-impact:
+    value: 86
+    note: "Delegated, revocable agent access to third-party services is a central platform problem as agents act with user authority."
+  maturity:
+    value: 62
+    note: "The broker has a clear documented model and API architecture, but its adoption and production integration with CF remain to be evaluated."
+  novelty:
+    value: 78
+    note: "The combination of human-readable permission sets, encrypted token custody, and request-time RFC 8693 exchange addresses a specific agent credential gap."
+  actionability:
+    value: 84
+    note: "The principal/agent/grant model maps directly to UAA, CF workload identity, service bindings, and gateway policy decisions."
+sources:
+  - https://agenticidentitybroker.dev/
+  - https://agenticidentitybroker.dev/docs/concepts
+  - https://agenticidentitybroker.dev/docs/concepts/architecture
+  - https://agenticidentitybroker.dev/docs/concepts/delegation-and-consent
+  - https://agenticidentitybroker.dev/docs/concepts/token-exchange
+  - https://agenticidentitybroker.dev/docs/concepts/encryption
+  - https://agenticidentitybroker.dev/api/enduser
+---
+
+## Summary
+
+Agentic Identity Broker is identity infrastructure for agents that act on a user's behalf. It
+models per-user, per-agent, per-service delegation with scoped permission sets, expiry, and
+revocation, while keeping third-party access and refresh tokens in an encrypted broker vault.
+At request time, a trusted gateway exchanges an agent token for the appropriate provider token
+using RFC 8693. For Cloud Foundry, it provides a concrete pattern for separating workload
+identity, human consent, authorization, and third-party credential custody.
+
+## Key findings
+
+- **Delegation is explicit and scoped.** A principal grants an agent permission sets for named
+  third-party services. A user has at most one active grant for each agent, a grant may expire,
+  and a user can revoke selected permissions or the complete grant.
+- **The broker defines useful policy objects.** Agents have canonical IDs and declare required
+  services and permission sets. Services represent OAuth providers and protected resources.
+  Permission sets translate provider scopes into human-readable business permissions that users
+  can understand during consent.
+- **Authentication and authorization are separate.** The broker does not authenticate users.
+  A trusted reverse proxy authenticates each request and passes the principal identifier to the
+  broker. The broker then evaluates consent, grants, expiry, and service access.
+- **The deployment has separate trust surfaces.** A single Go broker exposes an end-user port
+  for APIs, consent UI, and OAuth endpoints, and an internal admin port for administrators and
+  automation. Operators can expose and secure these surfaces independently.
+- **Agents do not receive provider credentials.** The broker stores third-party access and
+  refresh tokens in encrypted user sessions. Agents hold broker-issued or upstream agent tokens,
+  not long-lived provider tokens that would be difficult to revoke or attribute.
+- **Token exchange happens at request time.** An agent gateway presents an agent token, target
+  resource, and a signed client assertion. The broker validates the gateway, derives user and
+  agent identity from the subject token, checks the active grant, selects the configured service,
+  refreshes the stored credential if needed, and returns the provider token.
+- **Exchange creates an audit boundary.** The exchange identifies the user, agent, gateway, and
+  protected resource. This enables attribution without requiring the agent itself to hold the
+  provider credential or expose it in tool/runtime logs.
+- **An optional Envoy ExtProc integrates at the edge.** The broker documents a standalone gRPC
+  External Processor sidecar that exchanges agent tokens for provider tokens on requests through
+  an Envoy-based agent gateway. It can cache results in memory and use OPA policy to restrict
+  proxied requests.
+- **Encryption is mandatory.** Third-party access tokens, refresh tokens, and service client
+  secrets are encrypted before storage, with ciphertext bound to the service. Production uses
+  envelope encryption with AWS KMS and cached branch keys; development has a raw-key backend.
+  The broker does not provide a plaintext fallback.
+- **Agent identity can be metadata-backed.** The broker can associate an agent with a Client ID
+  Metadata Document URL and validate the resulting metadata for the consent interface. This is
+  useful for governance, but the deployment still needs a trusted way to identify the calling
+  agent and gateway.
+
+## CF relevance
+
+Cloud Foundry could use this model to keep UAA or platform workload authentication separate from
+delegated access to GitHub, Google, Databricks, internal APIs, or other services. A CF-hosted
+agent would receive a scoped broker token through a binding or workload identity flow. A gateway
+would exchange that token only when the agent invokes an approved resource, while the provider
+credential remains in the broker's vault.
+
+The mapping has several possible boundaries. UAA could authenticate users and issue or validate
+agent-facing identities; CF instance identity certificates could identify the running workload;
+and a service broker could provision a delegation broker or service-specific permission sets.
+An Envoy or CF routing gateway could perform the request-time exchange, while CAPI/Diego
+lifecycle events could inform revocation when an app, instance, space, or binding disappears.
+
+The important platform property is least privilege with attribution. Service bindings should
+not distribute broad third-party refresh tokens to every agent instance. Instead, a binding or
+gateway policy should identify the agent and target resource, and the broker should enforce the
+active user grant. Loggregator or a protected audit store could correlate user, agent, gateway,
+resource, grant, exchange, and resulting operation without recording provider secrets.
+
+## Open questions
+
+- What is the canonical agent identity in CF: app, process instance, instance certificate,
+  service account, agent registration, or a composite identity?
+- Should UAA, a CF gateway, or the broker own token issuance and validation for agent-facing
+  credentials?
+- How should delegated authority interact with instance identity when an application scales,
+  restages, or moves between Diego cells?
+- Which component performs RFC 8693 exchange, and how should target resource, provider, and
+  service-binding policy be configured and audited?
+- How quickly must grant revocation, certificate revocation, app deletion, and binding removal
+  stop future exchanges?
+- How should permission sets map to CF orgs, spaces, apps, tools, service instances, and
+  external provider scopes?
+- Which exchange metadata belongs in Loggregator, and which sensitive consent or token data must
+  remain in a restricted audit store?
+- How should the broker's encrypted token vault, KMS dependency, key rotation, backup, and
+  recovery be operated by a CF foundation?