End a session from the shell

[kanushka]

What to build

A user can end their session from the shell.

The shell establishes a session at login and has no command that ends one. Until now the shell command reference listed a logout command anyway, and the login guide noted that it was proposed and not in the release; #94 removes the incorrect listing. This issue is the command itself.

Ending a session means more than forgetting a local credential, which is why this is not a small change and is deliberately not part of the module lifecycle work in #92. What the shell does at the issuer is now decided and recorded in ADR 0010: logout asks the issuer to revoke the refresh token per RFC 7009 when the deployment advertises a revocation_endpoint, removes the shell-owned session either way, and reports which of the two actually happened. Whether a session can be ended for one product without ending it for others stays open in #43, which does not block this command, because a session is keyed by identity today and one logout ends one session.

Acceptance criteria

• It is decided and recorded whether ending a session revokes at the issuer or only removes the shell-owned session, and what happens when revocation fails.
• A user can end the active session from the shell.
• After ending a session, a command that needs authentication is refused with the guidance that names how to log in again.
• Ending a session when none is active is not an error a user has to interpret.
• No token material reaches any output surface.
• The shell command reference documents the command.

Blocked by

• None. ADR 0010 records the issuer-side decision this issue asked for. Per-product login sessions: one identity's session cannot serve several products on Thunder #43 shapes a later slice and does not block this one. Decide what the broker claims when a deployment cannot bind a token to one product #37 is no longer part of this issue's framing: it asks what the broker should claim about audience binding, and logout verifies no audience and narrows no token.

[kanushka]

Design settled

The command's shape is decided. ADR 0010, Best-Effort Revocation on Session End, carries the reasoning and the rejected alternatives; this is the summary.

wso2 logout takes --context and --output. It asks the issuer to revoke the refresh token per RFC 7009 when the discovery document advertises a revocation_endpoint, removes the shell-owned session entry from the OS secure store, and exits zero under every outcome. Three outcomes are reported distinctly: the issuer confirmed; the issuer advertises no revocation endpoint so it was never asked; the issuer refused or could not be reached. Collapsing them into one "session ended" would be the failure #37 objects to one layer up, a report that reads stronger than the verification behind it. A non-zero exit would invite a retry loop that cannot succeed, since the local session is gone in all three cases.

Revocation happens inside the session lock. The refresh token must be read before it is deleted, and releasing the lock in between opens a window where a concurrent wso2 login writes a fresh session that logout then deletes, ending a session the user just created. The network call is bounded by a deadline strictly shorter than the 45-second lock deadline from ADR 0007.

Ending a session ends it for every context naming that identity, because a session is keyed by the identity's credentialRef. Logout names the affected contexts rather than refusing. The term is now recorded as Session in CONTEXT.md, which states that a session is a property of the identity and not of the context a command happens to select.

Identity kinds that never hold a session, client-credentials and development-credential, are refused with auth.logout_not_required, mirroring the existing auth.login_not_required gate in wso2 login. No stored session is not an error: it exits zero with a plain statement. There is no confirmation prompt and no special non-interactive path, because logging back in costs one browser round-trip and logout needs no human.

Two things a reader should know

The provider facts are unmeasured. Nothing in docs/research/ records whether Asgardeo, Identity Server 7.3.0 or ThunderID advertises revocation_endpoint, whether their revocation endpoints accept a public client (ours are authorization code with PKCE and no stored secret), or whether revoking a refresh token cascades to already-issued access tokens. Thunder is documented as supporting revocation from a reading of its protocol index, not from a discovery measurement. The only concrete prior art is apictl revoking at oauth2/revoke, and apictl is a confidential client using the password grant, so it is not evidence that we can. The design tolerates this by discovering each provider's branch at runtime, and the first live run against each deployment will be recorded in the research corpus with a date and a URL.

The browser SSO session survives. Revoking a refresh token does not end the single-sign-on session the identity provider holds in the browser, and on Asgardeo and Identity Server that session will complete a later sign-in without prompting. Logout says so in its own output rather than leaving it to be discovered. RP-initiated logout via end_session_endpoint is out of scope: it needs a browser round-trip, which turns a local command into an interactive flow.

Docs this corrects

docs/guides/login.md tells the user to delete the secure-store entry by hand, and the table in docs/examples/login-walkthroughs.md claims logout does "revocation only", which is wrong in both halves.

[kanushka]

This was generated by AI during triage.

Implemented and merged in #106. Every open acceptance criterion is met on main: the command lives in internal/app/logout.go with acceptance coverage in test/acceptance/logout_test.go and a live measurement in test/smoke/logout_smoke_test.go; a command needing authentication after logout is refused with "Run wso2 login to establish a session for this context." (internal/auth/session/session.go:63, internal/auth/source_session.go:98); logging out with no active session is reported rather than treated as an error; revocation reads the refresh token under the session lock and no token material reaches an output surface; and docs/reference/commands.md documents the command. #109 added the live logout smoke run for the already-closed #108. Closing as implemented.