Deployment discovery: learn a deployment's products from one URL

Status: deferred on 2026-09-14. This work depends on the product teams. It
builds on context v4 (#190, merged).

Goal

The user points at the login product and the shell learns everything else:

wso2 context create local --url http://localhost:8501
wso2 login

or just wso2 login --url http://localhost:8501. On-premises users skip
writing an input file and running product add. Context-v4 refuses a bare
--url because a URL alone doesn't identify a descriptor. Discovery is what
makes a bare --url legal. Cloud login (#186) can use the same
mechanism with a WSO2-hosted document, so both paths share one design.

Design constraint

Discovery produces a context-v4 input file and sends it through
apply's normal steps: validate, plan, --dry-run, install, resolve and
freeze defaults, write. It is not a second way to write contexts.json, so:

• nothing from the context-v4 work gets thrown away, and defaults are
  frozen locally exactly as they are for a hand-written input file
• wso2 context show and export still print a file a person can read
• a deployment without discovery refuses a bare --url and names the
  explicit --login-product or --issuer form, as context-v4 does

Sketch

GET <login-product-url>/.well-known/wso2-deployment
{
  "login": { "product": "identity", "clientId": "wso2-cli", "provider": "thunder" },
  "products": {
    "identity": { "url": "http://localhost:8501" },
    "api":      { "url": "http://localhost:9251", "gateway": { "url": "http://localhost:9091" } }
  }
}

The body is one context in input form, without name. The user supplies the
name. The path, the name, and the versioning are all open. See the questions
below.

Why this needs other teams

The shell can't discover a product the deployment doesn't announce. One of
these has to be true:

Option	Who does the work	Notes
A. Login product serves it	Thunder / IS team	Thunder already knows the API platform as a resource server or app. The doc is generated from config Thunder already holds. One team, one endpoint.
B. Each product serves its own	Every product team	The user still needs every URL, which defeats the purpose. Rejected.
C. A context file at any HTTPS URL	Nobody	This is just wso2 context apply -f https://…. It needs no product-team work and could ship inside the context-v4 work as a cheap step before A.

Recommendation: ship C with context-v4 and propose A to the Thunder/IS team.
Cloud (#186) uses A's format, hosted by WSO2.

Security, the part to get right

ADR 0012 says writing a context grants nothing, but a context does decide
where the shell sends tokens. If a discovery document is spoofed or
wrong, it can point api at a host the attacker controls, and the shell
then presents tokens there. ADR 0005 (audience-side verification) limits
what a stolen token can do, but it doesn't stop the shell sending one.
Minimum bar:

• Before writing anything, show every discovered URL (this is apply's
  plan) and require confirmation. With --no-input, refuse unless
  --accept-discovered is given.
• A discovered document must not carry credentialRef or defaultContext.
  This follows the input-file rule in context-v4.
• By default, refuse products on a different host from the login product
  unless the user confirms. Localhost port differences count as the same
  host.
• Never trust discovery over HTTP, except for loopback.
• Discovery runs only at create or apply time, never at login or command
  time. Re-running it is an explicit command (wso2 context refresh?), so a
  file never changes without the user seeing it.

Open questions

1. Where the path lives and what it's called (/.well-known/wso2-deployment?),
   and whether to register it or keep it vendor-private.
2. How the document is versioned, and what the shell does with an unknown
   product namespace in it: ignore it, or offer to install it?
3. Whether discovered products get auto-installed the same way product add
   does, and whether that needs its own confirmation.
4. Should a cloud organization change (wso2 org use) re-run discovery,
   since products may differ per organization?
5. Who in the Thunder/IS team owns option A, and when.

First steps

1. Draft a one-page format proposal for the Thunder/IS team, built from the
   sketch above and the security section.
2. Ship option C with context-v4 so on-premises teams get most of the
   benefit now.
3. Get cloud (#186) to agree on the same document format.

Research findings (2026-09-10)

Moved here from the removed docs/research/2026-09-10-zero-config-product-discovery.md; the full text, with sources, is in git history.

• No product in scope publishes a document naming the other products a deployment offers. Each resource server names only its own trusted issuer.
• OpenChoreo and Agent Manager serve RFC 9728 Protected Resource Metadata; OpenChoreo's also names its CLI client ID. ThunderID serves it only for opt-in MCP resource servers. API Platform (platform-api, gateway controller, gateway) serves none and sends no WWW-Authenticate: resource_metadata on 401 (measured).
• Single sign-on across ThunderID and API Platform works today (measured) but is admin configuration ([platform_api.auth] mode = "idp" + jwks_url/issuer), not client-side discovery.
• No "WSO2 Identity Server 8" exists as of the research date; "WSO2 Cloud" has no dated official definition, and console.cloud.wso2.com/.well-known/openid-configuration returns HTML.

What a one-URL discovery flow would need from each product that it does not have today

ThunderID

• RFC 9728 Protected Resource Metadata on its general REST/OAuth surface,
  not only when a downstream MCP server opts in — today a CLI pointed at a
  bare ThunderID URL has nothing to fetch that would confirm "this is your
  issuer, here is your client ID."
• A WWW-Authenticate: resource_metadata=... header on 401s from the main
  API, mirroring what it already does for MCP-hosted resource servers.
• A "my apps"/"my resource servers" self-service endpoint, or an
  authorized-app claim, so a signed-in non-admin user (not just an
  administrator) can learn what they are allowed to reach — every
  enumeration route today falls back to requiring the root/admin
  permission.
• A registration tier between "wide open" (DCR.Insecure) and "requires
  full admin/root permission" — RFC 7591's initial-access-token concept, so
  a CLI could self-register as a public client without an administrator's
  own credential.

WSO2 Identity Server 8

• To exist. As of this research date there is nothing to evaluate: the
  premise names a product with no GA release, no announced codebase, and no
  primary-source mention anywhere in WSO2's own documentation or press
  material. If a next-generation Identity Server is planned, the gap list
  is an open question rather than a finding — it inherits whichever of
  ThunderID's gaps (above) it does or does not carry forward.

WSO2 API Platform

• RFC 9728 Protected Resource Metadata on platform-api, the gateway
  controller, and the gateway's data plane (measured absent on all three),
  so a client could learn the trusted issuer and JWKS URL from the product
  itself instead of being handed jwks_url/issuer by an administrator.
• A WWW-Authenticate: resource_metadata=... header on 401s from any of
  the three surfaces (measured absent on all three).
• Some way for a CLI to learn a product's expected audience without an
  administrator naming it — today the audience is whatever the IdP-side API
  resource/OAuth application was registered with, invisible to the client
  until it is told.

WSO2 Agent Manager

• RFC 8414 Authorization Server Metadata (or OIDC discovery) served by
  agent-manager-service itself, not only by the external Thunder instance
  its RFC 9728 document points at — today the second discovery hop leaves
  the product entirely, so "one product, one discovery chain" is still two
  servers.
• A documented way to point the platform's own console/CLI login at an
  identity provider other than the bundled Thunder — the per-org gateway
  identity provider feature already proves this pattern works for securing
  deployed agents; the platform's own login has no equivalent.
• A "my agents" enumeration scoped to the caller, not just an RBAC scope
  check against the whole org — today anyone with amp:agent:read in an
  org sees every agent in it, which answers "what can this role see," not
  "what can this signed-in person see."

OpenChoreo

• The one product that already does the client-side half of this document's
  question; what it lacks is the other direction and a couple of adjacent
  primitives:
  • No document, anywhere, names the other products/resource servers a
    deployment offers — OpenChoreo's own RFC 9728 metadata describes only
    itself.
  • No organization concept in its claim-mapping model (the one
    organization field found in source is marked unused), which matters
    if a one-issuer flow needs to resolve which WSO2 organization or tenant
    a signed-in user belongs to across products.
  • No RFC 8693 token exchange or RFC 7591 DCR — OpenChoreo's OAuth clients
    (like cli) are statically pre-registered in config, so a CLI cannot
    self-register the way it can against ThunderID with an admin token.
  • WWW-Authenticate: resource_metadata=... is wired for its MCP surface
    only, not its plain REST 401s.

WSO2 Cloud

• A dated, official definition of what "WSO2 Cloud" actually is, and
  whether it is one login surface across Identity, API Platform, Agent
  Manager, and OpenChoreo, or a marketing umbrella over products that still
  authenticate separately.
• A publicly reachable discovery document at whatever domain fronts its
  login — the one candidate checked, console.cloud.wso2.com, answers
  /.well-known/openid-configuration with its single-page app's HTML
  shell, not JSON.
• An explicit statement of which identity provider backs it (ThunderID,
  Asgardeo, or something else), so the rest of this document's findings
  about that provider would actually transfer to the cloud offering.
• A documented wso2 cloud login-equivalent, or an equivalent statement
  that the plain wso2 login case for WSO2 Cloud is meant to reuse one of
  the existing per-product CLIs' flows.

Start with the context-v4 create/apply flow and the cloud login work in #186, then review the discovery sketch and security requirements. The first deliverable is a one-page format proposal; completion requires an agreed discovery format, a scoped option C plan, and alignment with the product teams.