fix(auth): harden OAuth callback flow and add per-app redirect URI config (#64)

Author: robert-hoffmann

CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All user-visible bugs and enhancements should be recorded here.
+
+## Unreleased
+
+Last updated: 2026-04-19 23:48:20 CEST
+
+### Fixed
+
+- [2026-04-19 23:08:51 CEST] OAuth2 callback listeners now bind to the host and port derived from the effective redirect URI instead of always listening on `127.0.0.1:8080`. For `localhost`, `xurl` now listens on both `127.0.0.1` and `::1`, which fixes browser-dependent loopback resolution failures while still supporting non-default callback paths.
+- [2026-04-19 23:08:51 CEST] The OAuth2 listener now starts listening before the browser opens, which removes a race where the browser could reach the callback URL before the local server was ready.
+- [2026-04-19 23:08:51 CEST] OAuth2 token refresh no longer depends on `/2/users/me` succeeding. If username discovery fails, `xurl` keeps the refreshed token instead of failing the request.
+- [2026-04-19 23:08:51 CEST] Shortcut commands that need the current user ID now fall back to `--username` lookups when `/2/users/me` is unavailable.
+- [2026-04-19 23:08:51 CEST] `GetOAuth2Header` now consistently returns a `Bearer` header even when it has to trigger a fresh OAuth2 flow.
+
+### Enhanced
+
+- [2026-04-19 23:08:51 CEST] OAuth2 tokens can now be retained without a discovered username label when X’s `/2/users/me` lookup is unavailable. Status output makes that state visible as `(unknown user)` instead of silently dropping the token.
+- [2026-04-19 23:08:51 CEST] Repo documentation now describes the effective redirect URI as the source of callback host, port, and path, calls out explicit username authentication as the safer fallback when username discovery is unreliable, and documents the new stored `redirect_uri` behavior.
+- [2026-04-19 23:08:51 CEST] Apps can now store a per-app `redirect_uri` in `~/.xurl`, `REDIRECT_URI` from the environment still takes precedence, and `xurl auth apps redirect-uri get/set` plus `auth apps update --redirect-uri` make that configuration visible and editable from the CLI.
+- [2026-04-19 23:48:20 CEST] Documentation now records the confirmed X platform enrollment requirement behind `client-forbidden` / `client-not-enrolled` read failures: moving the app to the `Pay-per-use` package and the `Production` environment fixed live `/2/*` reads after OAuth had already succeeded.

README.md

@@ -51,19 +51,28 @@ Register your X API app credentials so they're stored in `~/.xurl` (no env vars
 xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
 ```
 
+If you want the app to keep its own callback configuration in `~/.xurl`, you can store the redirect URI there too:
+
+```bash
+xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --redirect-uri http://localhost:8080/callback
+```
+
 You can register multiple apps:
 ```bash
 xurl auth apps add prod-app --client-id PROD_ID --client-secret PROD_SECRET
 xurl auth apps add dev-app  --client-id DEV_ID  --client-secret DEV_SECRET
 ```
 
 > **Legacy / env-var flow:** You can also set `CLIENT_ID` and `CLIENT_SECRET` as environment variables. They'll be auto-saved into the active app on first use.
+>
+> `REDIRECT_URI` now resolves in this order: `REDIRECT_URI` environment variable, then the app's stored `redirect_uri` in `~/.xurl`, then the built-in default `http://localhost:8080/callback`.
 
 #### OAuth 2.0 User-Context
 **Note:** For OAuth 2.0 authentication, you must specify the redirect URI in the [X API developer portal](https://developer.x.com/en/portal/dashboard).
 
 1. Create an app at the [X API developer portal](https://developer.x.com/en/portal/dashboard).
-2. Go to authentication settings and set the redirect URI to `http://localhost:8080/callback`.
+2. Go to authentication settings and set the redirect URI to the same value that `xurl` will use through `REDIRECT_URI`.
+   The default is `http://localhost:8080/callback`, and `xurl` derives the callback host, port, and path from the effective redirect URI. The effective value is resolved from `REDIRECT_URI`, then the app's stored `redirect_uri`, then the built-in default. When you use `localhost`, `xurl` listens on both `127.0.0.1` and `::1` so browser loopback resolution does not break the callback.
 ![Setup](./assets/setup.png)
 ![Redirect URI](./assets/callback.png)
 3. Register the app (if you haven't already):
@@ -75,6 +84,24 @@ xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT
 xurl auth oauth2
 ```
 
+If X returns a `client-forbidden` / `client-not-enrolled` error even though auth completed successfully, check the app’s package and environment in the X developer console. On current X platform setup, the working fix was:
+
+1. Go to `Apps` -> `Manage apps`
+2. Open the app
+3. Use `Move to package`
+4. Choose `Pay-per-use`
+5. Move the app to the `Production` environment
+
+Without that enrollment step, `xurl whoami` and other `/2/*` reads can fail even when the OAuth callback and tokens are valid.
+
+If X does not return your username reliably through `/2/users/me`, authenticate with an explicit handle instead:
+
+```bash
+xurl auth oauth2 YOUR_USERNAME
+```
+
+That keeps the OAuth2 token associated with the expected username and also gives shortcut commands a fallback when `/2/users/me` is unavailable.
+
 #### App authentication (bearer token):
 ```bash
 xurl auth app --bearer-token BEARER_TOKEN
@@ -95,6 +122,19 @@ xurl auth apps list
 Update credentials on an existing app:
 ```bash
 xurl auth apps update my-app --client-id NEW_ID --client-secret NEW_SECRET
+xurl auth apps update my-app --redirect-uri http://localhost:8080/callback
+```
+
+`REDIRECT_URI` from the environment still overrides the stored app value at runtime, so `auth apps update --redirect-uri` is best for your default per-app callback while env vars remain the temporary override path.
+
+View the effective and stored redirect URI for an app:
+```bash
+xurl auth apps redirect-uri get my-app
+```
+
+Set the stored redirect URI for an app:
+```bash
+xurl auth apps redirect-uri set my-app http://localhost:8080/callback
 ```
 
 Remove an app:
@@ -124,20 +164,28 @@ View authentication status across all apps:
 xurl auth status
 ```
 
+This output shows the effective redirect URI for each app and, when `REDIRECT_URI` is set in the environment, also shows the stored app value separately so precedence is visible.
+
 Example output:
 ```
 ▸ my-app  [client_id: VUttdG9P…]
+      redirect_uri: http://localhost:8080/callback  [app config]
     ▸ oauth2: alice
       oauth2: bob
       oauth1: ✓
       bearer: ✓
 
   dev-app  [client_id: OTHER789…]
+      redirect_uri: http://localhost:8080/callback  [built-in default]
       oauth2: (none)
       oauth1: –
       bearer: –
 ```
 
+### X Platform Enrollment Troubleshooting
+
+If OAuth succeeds but reads like `xurl whoami` fail with an error body containing `client-forbidden` or `client-not-enrolled`, the current X platform fix is to move the app into the `Pay-per-use` package and use the `Production` environment in the developer console. This is an X platform enrollment issue, not a local callback-listener issue in `xurl`.
+
 `▸` on the left = default app. `▸` next to a user = default user.
 
 ### Clear Authentication
@@ -283,6 +331,7 @@ apps:
   my-app:
     client_id: abc123
     client_secret: secret456
+    redirect_uri: http://localhost:8080/callback
     default_user: alice
     oauth2_tokens:
       alice:

SKILL.md

@@ -40,13 +40,15 @@ For multiple pre-configured apps, switch between them:
 xurl auth default prod-app          # set default app
 xurl auth default prod-app alice    # set default app + user
 xurl --app dev-app /2/users/me      # one-off override
+xurl auth apps redirect-uri get prod-app
+xurl auth apps redirect-uri set prod-app http://localhost:8080/callback
 ```
 
 ### Other auth methods
 
 Examples with inline secret flags are intentionally omitted. If OAuth1 or app-only auth is needed, the user must run those commands manually outside agent/LLM context.
 
-Tokens are persisted to `~/.xurl` in YAML format. Each app has its own isolated tokens. Do not read this file through the agent/LLM. Once authenticated, every command below will auto‑attach the right `Authorization` header.
+Tokens are persisted to `~/.xurl` in YAML format. Each app has its own isolated tokens and may also store a `redirect_uri`. `REDIRECT_URI` in the environment still takes precedence over the stored app value. Do not read this file through the agent/LLM. Once authenticated, every command below will auto‑attach the right `Authorization` header.
 
 ---
 
@@ -87,7 +89,9 @@ Tokens are persisted to `~/.xurl` in YAML format. Each app has its own isolated
 | **App Management** | |
 | Register app | Manual, outside agent (do not pass secrets via agent) |
 | List apps | `xurl auth apps list` |
-| Update app creds | Manual, outside agent (do not pass secrets via agent) |
+| Update app config | Manual, outside agent (do not pass secrets via agent) |
+| View app redirect URI | `xurl auth apps redirect-uri get [NAME]` |
+| Set app redirect URI | `xurl auth apps redirect-uri set NAME URI` |
 | Remove app | `xurl auth apps remove NAME` |
 | Set default (interactive) | `xurl auth default` |
 | Set default (command) | `xurl auth default APP_NAME [USERNAME]` |
@@ -382,7 +386,8 @@ xurl --app staging /2/users/me         # one-off request against staging
 - Non‑zero exit code on any error.
 - API errors are printed as JSON to stdout (so you can still parse them).
 - Auth errors suggest re‑running `xurl auth oauth2` or checking your tokens.
-- If a command requires your user ID (like, repost, bookmark, follow, etc.), xurl will automatically fetch it via `/2/users/me`. If that fails, you'll see an auth error.
+- If a command requires your user ID (like, repost, bookmark, follow, etc.), xurl will automatically fetch it via `/2/users/me`. When that endpoint is unreliable, use `--username USERNAME` or authenticate with `xurl auth oauth2 USERNAME` so xurl can fall back to username lookup.
+- If X returns `client-forbidden` / `client-not-enrolled` after successful auth, check the app’s X developer-console package and environment. In current testing, moving the app to `Pay-per-use` and `Production` fixed `/2/*` read failures without changing local `xurl` auth data.
 
 ---
 
@@ -391,7 +396,10 @@ xurl --app staging /2/users/me         # one-off request against staging
 - **Rate limits:** The X API enforces rate limits per endpoint. If you get a 429 error, wait and retry. Write endpoints (post, reply, like, repost) have stricter limits than read endpoints.
 - **Scopes:** OAuth 2.0 tokens are requested with broad scopes. If you get a 403 on a specific action, your token may lack the required scope — re‑run `xurl auth oauth2` to get a fresh token.
 - **Token refresh:** OAuth 2.0 tokens auto‑refresh when expired. No manual intervention needed.
-- **Multiple apps:** Each app has its own isolated credentials and tokens. Configure credentials manually outside agent/LLM context, then switch with `xurl auth default` or `--app`.
+- **Multiple apps:** Each app has its own isolated credentials, tokens, and optional stored `redirect_uri`. Configure credentials manually outside agent/LLM context, then switch with `xurl auth default` or `--app`.
+- **Redirect URI precedence:** The effective redirect URI resolves from `REDIRECT_URI` in the environment first, then the app's stored `redirect_uri` in `~/.xurl`, then the built-in default.
+- **Redirect URI management:** Use `xurl auth apps redirect-uri get [NAME]`, `xurl auth apps redirect-uri set NAME URI`, or `xurl auth apps update NAME --redirect-uri URI` to inspect and manage the stored per-app callback value.
+- **X platform enrollment:** A successful OAuth callback does not guarantee `/2/*` reads will work. If you see `client-not-enrolled`, verify the app is in the correct X package/environment. Current confirmed fix: `Apps` -> `Manage apps` -> `Move to package` -> choose `Pay-per-use`, then move the app to `Production`.
 - **Multiple accounts:** You can authenticate multiple OAuth 2.0 accounts per app and switch between them with `--username` / `-u` or set a default with `xurl auth default APP USER`.
 - **Default user:** When no `-u` flag is given, xurl uses the default user for the active app (set via `xurl auth default`). If no default user is set, it uses the first available token.
 - **Token storage:** `~/.xurl` is YAML. Each app stores its own credentials and tokens. Never read or send this file to LLM context.