From 11f6bea598d780023a60e3dc40383a1ce08df5d3 Mon Sep 17 00:00:00 2001 From: Santiago Medina Rolong Date: Fri, 20 Feb 2026 15:54:59 -0800 Subject: [PATCH] add secret safety --- skills/xurl/SKILL.md | 131 +++++++++++++++++++++---------------------- 1 file changed, 65 insertions(+), 66 deletions(-) diff --git a/skills/xurl/SKILL.md b/skills/xurl/SKILL.md index 7980e974829..cf76bf158ad 100644 --- a/skills/xurl/SKILL.md +++ b/skills/xurl/SKILL.md @@ -66,23 +66,33 @@ go install github.com/xdevplatform/xurl@latest ## Prerequisites +This skill requires the `xurl` CLI utility: . + Before using any command you must be authenticated. Run `xurl auth status` to check. +### Secret Safety (Mandatory) + +- Never read, print, parse, summarize, upload, or send `~/.xurl` (or copies of it) to the LLM context. +- Never ask the user to paste credentials/tokens into chat. +- The user must fill `~/.xurl` with required secrets manually on their own machine. +- Do not recommend or execute auth commands with inline secrets in agent/LLM sessions. +- Warn that using CLI secret options in agent sessions can leak credentials (prompt/context, logs, shell history). +- Never use `--verbose` / `-v` in agent/LLM sessions; it can expose sensitive headers/tokens in output. +- Sensitive flags that must never be used in agent commands: `--bearer-token`, `--consumer-key`, `--consumer-secret`, `--access-token`, `--token-secret`, `--client-id`, `--client-secret`. +- To verify whether at least one app with credentials is already registered, run: `xurl auth status`. + ### Register an app (recommended) -```bash -# Register your X API app credentials (stored in ~/.xurl) -xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET +App credential registration must be done manually by the user outside the agent/LLM session. +After credentials are registered, authenticate with: -# Then authenticate +```bash xurl auth oauth2 ``` -You can register multiple apps and switch between them: +For multiple pre-configured apps, switch between them: ```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 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 @@ -90,63 +100,55 @@ xurl --app dev-app /2/users/me # one-off override ### Other auth methods -```bash -# OAuth 1.0a -xurl auth oauth1 \ - --consumer-key KEY --consumer-secret SECRET \ - --access-token TOKEN --token-secret SECRET +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. -# App‑only bearer token -xurl auth app --bearer-token TOKEN -``` - -Tokens are persisted to `~/.xurl` in YAML format. Each app has its own isolated tokens. 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. Do not read this file through the agent/LLM. Once authenticated, every command below will auto‑attach the right `Authorization` header. --- ## Quick Reference -| Action | Command | -| ------------------------- | ------------------------------------------------------------ | -| Post | `xurl post "Hello world!"` | -| Reply | `xurl reply POST_ID "Nice post!"` | -| Quote | `xurl quote POST_ID "My take"` | -| Delete a post | `xurl delete POST_ID` | -| Read a post | `xurl read POST_ID` | -| Search posts | `xurl search "QUERY" -n 10` | -| Who am I | `xurl whoami` | -| Look up a user | `xurl user @handle` | -| Home timeline | `xurl timeline -n 20` | -| Mentions | `xurl mentions -n 10` | -| Like | `xurl like POST_ID` | -| Unlike | `xurl unlike POST_ID` | -| Repost | `xurl repost POST_ID` | -| Undo repost | `xurl unrepost POST_ID` | -| Bookmark | `xurl bookmark POST_ID` | -| Remove bookmark | `xurl unbookmark POST_ID` | -| List bookmarks | `xurl bookmarks -n 10` | -| List likes | `xurl likes -n 10` | -| Follow | `xurl follow @handle` | -| Unfollow | `xurl unfollow @handle` | -| List following | `xurl following -n 20` | -| List followers | `xurl followers -n 20` | -| Block | `xurl block @handle` | -| Unblock | `xurl unblock @handle` | -| Mute | `xurl mute @handle` | -| Unmute | `xurl unmute @handle` | -| Send DM | `xurl dm @handle "message"` | -| List DMs | `xurl dms -n 10` | -| Upload media | `xurl media upload path/to/file.mp4` | -| Media status | `xurl media status MEDIA_ID` | -| **App Management** | | -| Register app | `xurl auth apps add NAME --client-id ID --client-secret SEC` | -| List apps | `xurl auth apps list` | -| Update app creds | `xurl auth apps update NAME --client-id ID` | -| Remove app | `xurl auth apps remove NAME` | -| Set default (interactive) | `xurl auth default` | -| Set default (command) | `xurl auth default APP_NAME [USERNAME]` | -| Use app per-request | `xurl --app NAME /2/users/me` | -| Auth status | `xurl auth status` | +| Action | Command | +| ------------------------- | ----------------------------------------------------- | +| Post | `xurl post "Hello world!"` | +| Reply | `xurl reply POST_ID "Nice post!"` | +| Quote | `xurl quote POST_ID "My take"` | +| Delete a post | `xurl delete POST_ID` | +| Read a post | `xurl read POST_ID` | +| Search posts | `xurl search "QUERY" -n 10` | +| Who am I | `xurl whoami` | +| Look up a user | `xurl user @handle` | +| Home timeline | `xurl timeline -n 20` | +| Mentions | `xurl mentions -n 10` | +| Like | `xurl like POST_ID` | +| Unlike | `xurl unlike POST_ID` | +| Repost | `xurl repost POST_ID` | +| Undo repost | `xurl unrepost POST_ID` | +| Bookmark | `xurl bookmark POST_ID` | +| Remove bookmark | `xurl unbookmark POST_ID` | +| List bookmarks | `xurl bookmarks -n 10` | +| List likes | `xurl likes -n 10` | +| Follow | `xurl follow @handle` | +| Unfollow | `xurl unfollow @handle` | +| List following | `xurl following -n 20` | +| List followers | `xurl followers -n 20` | +| Block | `xurl block @handle` | +| Unblock | `xurl unblock @handle` | +| Mute | `xurl mute @handle` | +| Unmute | `xurl unmute @handle` | +| Send DM | `xurl dm @handle "message"` | +| List DMs | `xurl dms -n 10` | +| Upload media | `xurl media upload path/to/file.mp4` | +| Media status | `xurl media status MEDIA_ID` | +| **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) | +| Remove app | `xurl auth apps remove NAME` | +| Set default (interactive) | `xurl auth default` | +| Set default (command) | `xurl auth default APP_NAME [USERNAME]` | +| Use app per-request | `xurl --app NAME /2/users/me` | +| Auth status | `xurl auth status` | > **Post IDs vs URLs:** Anywhere `POST_ID` appears above you can also paste a full post URL (e.g. `https://x.com/user/status/1234567890`) — xurl extracts the ID automatically. @@ -304,7 +306,7 @@ These flags work on every command: | `--app` | | Use a specific registered app for this request (overrides default) | | `--auth` | | Force auth type: `oauth1`, `oauth2`, or `app` | | `--username` | `-u` | Which OAuth2 account to use (if you have multiple) | -| `--verbose` | `-v` | Print full request/response headers | +| `--verbose` | `-v` | Forbidden in agent/LLM sessions (can leak auth headers/tokens) | | `--trace` | `-t` | Add `X-B3-Flags: 1` trace header | --- @@ -424,11 +426,8 @@ xurl timeline -n 20 ### Set up multiple apps ```bash -# Register two apps -xurl auth apps add prod --client-id PROD_ID --client-secret PROD_SECRET -xurl auth apps add staging --client-id STG_ID --client-secret STG_SECRET - -# Authenticate users on each +# App credentials must already be configured manually outside agent/LLM context. +# Authenticate users on each pre-configured app xurl auth default prod xurl auth oauth2 # authenticates on prod app @@ -456,7 +455,7 @@ 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:** Register multiple apps with `xurl auth apps add`. Each app has its own isolated credentials and tokens. Switch with `xurl auth default` or `--app`. +- **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 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. +- **Token storage:** `~/.xurl` is YAML. Each app stores its own credentials and tokens. Never read or send this file to LLM context.