feat(cli): add auth commands for OIDC login (#32920)

* feat(cli): add auth commands for OIDC login

Signed-off-by: benjdlambert <ben@blam.sh>

* address PR review feedback

- move CIMD check before callback server start
- add try/finally for callback server cleanup
- validate URLs with human-readable errors
- deduplicate config URL candidates
- preserve selected flag on re-authentication
- delete accessToken on logout
- log token refresh to stderr in show command
- fix command descriptions to reference CIMD not DCR
- type keytar as optionalDependency, rename storage paths
- add auth-backend changeset

Signed-off-by: benjdlambert <ben@blam.sh>

* migrate auth module from yargs to cleye pattern

Signed-off-by: benjdlambert <ben@blam.sh>

* address PR review feedback

- consolidate storage imports in auth.ts
- add withMetadataLock to setSelectedInstance
- skip file permission tests on Windows
- clarify changeset endpoint path

Signed-off-by: benjdlambert <ben@blam.sh>

* address review feedback from Rugvip and Copilot

- use stdout for user-facing messages instead of stderr
- remove clientSecret remnants from logout
- make refresh_token optional in token response schema
- add timeout to CIMD metadata fetch
- pass same state to callback server and authorize URL
- remove inaccurate test comment

Signed-off-by: benjdlambert <ben@blam.sh>

* validate state in callback server, add CIMD endpoint tests

- localServer now validates the OAuth state parameter in the request
  handler and returns 400 on mismatch
- Added tests for the CIMD metadata endpoint in OidcRouter covering
  both disabled and enabled cases

Signed-off-by: benjdlambert <ben@blam.sh>

* revert validateRequest to use Zod error details

Signed-off-by: benjdlambert <ben@blam.sh>

* fix callback server hanging by closing keep-alive connections

Signed-off-by: benjdlambert <ben@blam.sh>

* rename secret store service prefix to backstage-cli:auth-instance

Signed-off-by: benjdlambert <ben@blam.sh>

---------

Signed-off-by: benjdlambert <ben@blam.sh>

.changeset/auth-backend-cimd-endpoint.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-auth-backend': patch
+---
+
+Added optional client metadata document endpoint at `/.well-known/oauth-client/cli.json` relative to the auth backend base URL for CLI authentication. Enabled when `auth.experimentalClientIdMetadataDocuments.enabled` is set to `true`.

.changeset/cli-auth-commands.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': minor
+---
+
+Added new `auth` command group for authenticating the CLI with Backstage instances using OAuth 2.0 with a pre-registered client metadata document. Commands include `login`, `logout`, `list`, `show`, `print-token`, and `select` for managing multiple authenticated instances.