From 1363ebaf7669a574b1e44f6c60bb99e4a762d335 Mon Sep 17 00:00:00 2001 From: Deivid Soto Date: Fri, 13 Feb 2026 20:37:32 +0100 Subject: [PATCH 1/6] docs: align API docs with OpenAPI spec and improve ClawHub discoverability --- CHANGELOG.md | 14 +++++--- README.md | 21 ++++++------ SKILL.md | 66 +++++++++++++++++++++++++----------- references/api-reference.md | 67 +++++++++++++++++++++++++++++++++++-- 4 files changed, 132 insertions(+), 36 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d9ff5b7..151d870 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,12 +6,16 @@ All notable changes to this project will be documented in this file. ### Features -- Search movies and TV shows across 12+ torrent sources -- Filter by quality (480p-2160p), genre, year, rating, language, season/episode -- API key authentication with tiered rate limits -- Quality scoring (0-100) based on resolution, codec, seeders, source trust +- Search movies and TV shows across 30+ torrent sources +- Filter by quality (480p–2160p), genre, year, rating, language, season/episode +- HDR and Dolby Vision filtering (hdr10, dolby_vision, hdr10plus, hlg) +- Audio codec filtering (AAC, FLAC, Opus, Atmos) +- API key authentication with tiered rate limits (anonymous, free, pro) +- Quality scoring (0–100) based on resolution, codec, seeders, source trust - Multi-language support (11 languages with accent-insensitive search) +- TMDB metadata enrichment: posters, backdrops, genres, cast, director credits - Detect installed torrent clients (Transmission, aria2) - Add magnet links directly to torrent clients - Download .torrent files or copy magnet links -- OS-specific installation guides for torrent clients +- OS-specific installation guides for torrent clients (Linux, macOS, Windows/WSL) +- MCP server alternative for Claude Desktop, Cursor, and Windsurf diff --git a/README.md b/README.md index ec8845a..dd2c8e1 100644 --- a/README.md +++ b/README.md @@ -4,23 +4,24 @@ **License:** MIT **Homepage:** https://torrentclaw.com -Agent Skill for searching and downloading torrents via [TorrentClaw](https://torrentclaw.com). +Search and download movies and TV shows from 30+ torrent sources directly from your AI agent. TorrentClaw aggregates torrents from YTS, EZTV, Knaben, Prowlarr, Bitmagnet, Torrentio, DonTorrent, Torrents.csv and more — enriched with TMDB metadata, quality scoring, and multi-language support. -Compatible with Claude Code, OpenClaw, Codex CLI, Cline, Roo Code, and any tool supporting the [Agent Skills](https://agentskills.io) specification. +Compatible with **Claude Code**, **OpenClaw**, **Codex CLI**, **Cline**, **Roo Code**, and any tool supporting the [Agent Skills](https://agentskills.io) specification. **Alternative:** For Claude Desktop, Cursor, or Windsurf, use the [MCP Server](https://torrentclaw.com/mcp) instead (`npx @torrentclaw/mcp`). ## Features -- Search movies and TV shows across 12+ torrent sources (YTS, EZTV, Knaben, Prowlarr, Bitmagnet, Torrentio, DonTorrent, Torrents.csv, and more) -- Filter by quality (480p-2160p), genre, year, rating, language, season/episode (S01E05, 1x05) -- API key authentication for higher rate limits (120 req/min free, 1K req/min pro) -- Quality scoring (0-100) based on resolution, codec, seeders, source trust +- Search movies and TV shows across 30+ torrent sources (YTS, EZTV, Knaben, Prowlarr, Bitmagnet, Torrentio, DonTorrent, Torrents.csv, and more) +- Filter by quality (480p–2160p), genre, year, rating, language, audio codec, HDR format, season/episode +- HDR and Dolby Vision filtering (hdr10, dolby_vision) and audio codec filtering (AAC, FLAC, Opus, Atmos) +- Quality scoring (0–100) based on resolution, codec, seeders, source trust - Multi-language support (11 languages with accent-insensitive search) -- Detect installed torrent clients (Transmission, aria2) -- Add magnet links directly to your torrent client +- TMDB metadata enrichment: posters, backdrops, genres, cast, director credits +- Detect installed torrent clients (Transmission, aria2) and add magnets directly - Download .torrent files or copy magnet links -- OS-specific installation guides for torrent clients +- OS-specific installation guides for torrent clients (Linux, macOS, Windows/WSL) +- API key authentication for higher rate limits (anonymous 30/min, free 120/min, pro 1K/min) ## Install @@ -64,7 +65,7 @@ Or just ask naturally: The skill will: 1. Detect your torrent client (Transmission, aria2) -2. Search TorrentClaw across 12+ sources +2. Search TorrentClaw across 30+ sources 3. Present results ranked by quality score (0-100) 4. Add best torrent to your client or provide magnet link 5. Show install guide if no client detected diff --git a/SKILL.md b/SKILL.md index e105cdf..e382483 100644 --- a/SKILL.md +++ b/SKILL.md @@ -2,7 +2,7 @@ name: torrentclaw description: Search and download torrents via TorrentClaw. Use when the user asks to find, search, or download movies, TV shows, or torrents. Detects local torrent clients (Transmission, aria2) and adds magnets directly, or offers magnet link copy and .torrent file download. Supports filtering by type (movie/show), genre, year, quality (480p-2160p), rating, language, and season/episode (S01E05, 1x05). Features API key authentication with tiered rate limits, AI-verified matching, and quality scoring (0-100). Returns titles with posters, ratings, and torrents with magnet links and quality scores. license: MIT -metadata: {"version": "0.1.13", "repository": "https://github.com/torrentclaw/torrentclaw-skill", "homepage": "https://torrentclaw.com", "openclaw": {"emoji": "🎬", "os": ["darwin", "linux", "win32"]}} +metadata: {"version": "0.1.13", "repository": "https://github.com/torrentclaw/torrentclaw-skill", "homepage": "https://torrentclaw.com", "openclaw": {"emoji": "🎬", "os": ["darwin", "linux", "win32"], "requires": {"bins": ["curl", "bash", "jq"], "env": ["TORRENTCLAW_API_KEY"]}, "primaryEnv": "TORRENTCLAW_API_KEY"}, "tags": ["torrent", "movies", "tv-shows", "download", "media", "entertainment", "magnet", "transmission", "aria2", "search", "4k", "hdr"]} --- # TorrentClaw @@ -44,6 +44,8 @@ curl -s -H "x-search-source: skill" "https://torrentclaw.com/api/v1/search?q=QUE - `year_min=2020&year_max=2025` - `min_rating=7` - `lang=es` (ISO 639 language code) +- `audio=atmos` (also: aac, flac, opus) +- `hdr=dolby_vision` (also: hdr10, hdr10plus, hlg) - `season=1` — Filter by TV show season - `episode=5` — Filter by episode number - `locale=es` — Get titles in Spanish (also: fr, de, pt, it, ja, ko, zh, ru, ar) @@ -101,13 +103,13 @@ Recommend **Transmission** for Linux/macOS (lightweight daemon, simple CLI) and Main search endpoint. Required: `q` (query string). -**Filters:** `type` (movie/show), `genre`, `year_min`, `year_max`, `min_rating` (0-10), `quality` (480p/720p/1080p/2160p), `lang` (ISO 639), `availability` (all/available/unavailable). +**Filters:** `type` (movie/show), `genre`, `year_min`, `year_max`, `min_rating` (0-10), `quality` (480p/720p/1080p/2160p), `lang` (ISO 639), `audio` (aac/flac/opus/atmos), `hdr` (hdr10/dolby_vision/hdr10plus/hlg). **Sorting:** `sort` = relevance | seeders | year | rating | added **Pagination:** `page` (1-1000), `limit` (1-50, default 20) -**Response:** `{ total, page, pageSize, results: [{ id, imdbId, tmdbId, contentType, title, year, overview, posterUrl, genres, ratingImdb, ratingTmdb, hasTorrents, maxSeeders, torrents: [{ infoHash, magnetUrl, torrentUrl, quality, codec, sourceType, sizeBytes, seeders, leechers, source, qualityScore, scrapedAt, languages, audioCodec, hdrType }] }] }` +**Response:** `{ total, page, pageSize, results: [{ id, imdbId, tmdbId, contentType, title, year, overview, posterUrl, backdropUrl, genres, ratingImdb, ratingTmdb, contentUrl, hasTorrents, maxSeeders, torrents: [{ infoHash, magnetUrl, torrentUrl, quality, codec, sourceType, sizeBytes, seeders, leechers, source, qualityScore, scrapedAt, uploadedAt, languages, audioCodec, hdrType, releaseGroup, isProper, isRepack, isRemastered, season, episode }] }] }` **New fields:** - `hasTorrents` (boolean) — Whether content has any associated torrents @@ -120,11 +122,11 @@ Fast typeahead. Param: `q` (min 2 chars). Returns max 8 suggestions. ### Popular — `GET /api/v1/popular` -Trending content by seeders. Params: `limit` (1-24), `page`. +Trending content by seeders. Params: `limit` (1-24, default 12), `page`. ### Recent — `GET /api/v1/recent` -Recently added content. Params: `limit` (1-24), `page`. +Recently added content. Params: `limit` (1-24, default 12), `page`. ### Torrent File — `GET /api/v1/torrent/{infoHash}` @@ -134,25 +136,34 @@ Download .torrent file by 40-char hex info hash. Returns binary `application/x-b Content/torrent counts and recent ingestion history. No params. -### Content Details — `GET /api/v1/content/:id` +### Credits — `GET /api/v1/content/{id}/credits` -Full metadata for a specific movie or show. Returns complete content object with all torrents, cast, crew, and metadata. +Director and top 10 cast members with character names. -### Track — `GET /api/v1/track` +**Params:** `id` (path, required — content ID from search) -Analytics tracking endpoint. Params: `contentId` (required), `type` (view/click/download). +**Response:** `{ contentId, director: "name", cast: [{ name, character, profileUrl }] }` + +**Usage:** Show cast info when the user asks "who's in this movie?" or wants details about a search result. + +### Track — `POST /api/v1/track` + +Record user interactions for popularity ranking. Call this after the user selects a torrent. + +**Request body (JSON):** +```json +{"infoHash": "40-char hex", "action": "magnet|torrent_download|copy"} +``` + +**Response:** `{"ok": true}` ### Search Analytics — `GET /api/v1/search-analytics` -Popular searches and trending queries. **Requires API key with pro tier.** +Search volume, top queries, and zero-result queries by period. **Requires API key with pro tier.** -### Cache Stats — `GET /api/v1/cache-stats` +**Params:** `days` (1-90, default 7), `limit` (1-100, default 20) -Search cache metrics and performance stats. No params. - -### Enrichment Stats — `GET /api/v1/enrichment-stats` - -TMDB enrichment progress and coverage statistics. No params. +**Response:** `{ period, summary, topQueries, zeroResultQueries, dailyVolume }` ## Season & Episode Search @@ -248,12 +259,29 @@ curl -H "Authorization: Bearer tc_live_xxxxx" \ **Find popular sci-fi movies:** ```bash -curl "https://torrentclaw.com/api/v1/search?genre=science-fiction&type=movie&sort=seeders" +curl "https://torrentclaw.com/api/v1/search?genre=Science%20Fiction&type=movie&sort=seeders" ``` -**Track content view for analytics:** +**Find Dolby Vision / HDR content:** ```bash -curl "https://torrentclaw.com/api/v1/track?contentId=123&type=view" +curl "https://torrentclaw.com/api/v1/search?q=dune&hdr=dolby_vision&quality=2160p" +``` + +**Find Atmos audio torrents:** +```bash +curl "https://torrentclaw.com/api/v1/search?q=oppenheimer&audio=atmos" +``` + +**Get cast info for a movie:** +```bash +curl "https://torrentclaw.com/api/v1/content/42/credits" +``` + +**Track torrent selection (call after user picks a torrent):** +```bash +curl -X POST -H "Content-Type: application/json" \ + -d '{"infoHash":"aaf1e71c...","action":"magnet"}' \ + "https://torrentclaw.com/api/v1/track" ``` ## Troubleshooting diff --git a/references/api-reference.md b/references/api-reference.md index 47dfcee..e369475 100644 --- a/references/api-reference.md +++ b/references/api-reference.md @@ -43,6 +43,9 @@ "audioCodec": "AAC", "hdrType": null, "releaseGroup": "YTS", + "isProper": false, + "isRepack": false, + "isRemastered": false, "season": null, "episode": null } @@ -81,24 +84,79 @@ X-Api-Key-Id: tc_live_abc1 - **Pro**: 1,000 req/min, 10,000 req/day (with API key) - **Internal**: Unlimited (with API key) -## New Query Parameters +## Search Query Parameters **Season & Episode Filtering:** - `season=1` — Filter by TV show season number - `episode=5` — Filter by episode number - Note: Also supports parsing from query text (e.g., `q=breaking+bad+S01E05`) +**Audio & Video Quality:** +- `audio=atmos` — Filter by audio codec (aac, flac, opus, atmos) +- `hdr=dolby_vision` — Filter by HDR format (hdr10, dolby_vision, hdr10plus, hlg) +- `quality=2160p` — Filter by resolution (480p, 720p, 1080p, 2160p) + **Localization:** - `locale=es` — Get titles in Spanish (also: fr, de, pt, it, ja, ko, zh, ru, ar) -## New Response Fields +## Response Fields **Content fields:** - `hasTorrents` (boolean) — Whether content has associated torrents - `maxSeeders` (number) — Highest seeder count across all torrents for this content +- `backdropUrl` (string) — TMDB backdrop image URL +- `contentUrl` (string) — Relative URL for content detail page **Torrent fields:** - `scrapedAt` (string, ISO 8601) — Timestamp of last tracker scrape for real-time seeder/leecher counts +- `uploadedAt` (string, ISO 8601) — When the torrent was first uploaded +- `releaseGroup` (string) — Release group name (e.g., "YTS", "RARBG") +- `isProper` (boolean) — Whether this is a PROPER release (fix for previous release issues) +- `isRepack` (boolean) — Whether this is a REPACK (re-packaged due to issues) +- `isRemastered` (boolean) — Whether this is a remastered release + +## Credits Response Schema + +```json +{ + "contentId": 1, + "director": "Christopher Nolan", + "cast": [ + { + "name": "Leonardo DiCaprio", + "character": "Cobb", + "profileUrl": "https://image.tmdb.org/t/p/w185/..." + } + ] +} +``` + +Returns `contentId`, director name, and up to 10 cast members. Param: `id` (path, required) + +## Track Request Schema + +```json +{ + "infoHash": "aaf1e71c0a0e3b1c0f1a2b3c4d5e6f7a8b9c0d1e", + "action": "magnet" +} +``` + +Method: **POST**. Actions: `magnet`, `torrent_download`, `copy`. Response: `{"ok": true}` + +## Search Analytics Response Schema + +```json +{ + "period": { "days": 7, "since": "2026-02-06T00:00:00Z" }, + "summary": { "totalSearches": 15420, "uniqueQueries": 8730, "avgResults": 12.3, "zeroResultSearches": 120, "webSearches": 10000, "apiSearches": 5420 }, + "topQueries": [{ "query": "dune", "count": 342, "avgResults": 15.2 }], + "zeroResultQueries": [{ "query": "obscure title", "count": 5 }], + "dailyVolume": [{ "date": "2026-02-13", "total": 2200, "web": 1500, "api": 700 }] +} +``` + +Params: `days` (1-90, default 7), `limit` (1-100, default 20). **Requires pro tier API key.** ## Error Responses @@ -115,8 +173,13 @@ X-Api-Key-Id: tc_live_abc1 |----------|-------| | /api/v1/search | 30/min | | /api/v1/autocomplete | 60/min | +| /api/v1/popular | 30/min | +| /api/v1/recent | 30/min | +| /api/v1/content/{id}/credits | 30/min | | /api/v1/stats | 10/min | | /api/v1/torrent | 20/min | +| /api/v1/track | 60/min | +| /api/v1/search-analytics | 10/min | ## Torrent Download Integration From 913f22fb24482078368f09b6bb8bd6f94744e5bc Mon Sep 17 00:00:00 2001 From: Deivid Soto Date: Fri, 13 Feb 2026 20:38:02 +0100 Subject: [PATCH 2/6] fix(detect-client): detect transmission-gtk and qt variants --- scripts/detect-client.sh | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/scripts/detect-client.sh b/scripts/detect-client.sh index 4bbf664..0bf2af6 100755 --- a/scripts/detect-client.sh +++ b/scripts/detect-client.sh @@ -27,13 +27,29 @@ esac # --- Client Detection --- # Transmission -transmission_path=$(command -v transmission-remote 2>/dev/null || true) +transmission_remote_path=$(command -v transmission-remote 2>/dev/null || true) +transmission_gtk_path=$(command -v transmission-gtk 2>/dev/null || true) +transmission_qt_path=$(command -v transmission-qt 2>/dev/null || true) +transmission_daemon_path=$(command -v transmission-daemon 2>/dev/null || true) +transmission_path="${transmission_remote_path:-${transmission_gtk_path:-${transmission_qt_path:-${transmission_daemon_path:-}}}}" transmission_installed="false" transmission_daemon="false" +transmission_remote_available="false" +transmission_variant="none" if [ -n "$transmission_path" ]; then transmission_installed="true" - if transmission-remote -l >/dev/null 2>&1; then - transmission_daemon="true" + if [ -n "$transmission_remote_path" ]; then + transmission_remote_available="true" + transmission_variant="cli" + if transmission-remote -l >/dev/null 2>&1; then + transmission_daemon="true" + fi + elif [ -n "$transmission_gtk_path" ]; then + transmission_variant="gtk" + elif [ -n "$transmission_qt_path" ]; then + transmission_variant="qt" + elif [ -n "$transmission_daemon_path" ]; then + transmission_variant="daemon" fi fi @@ -65,6 +81,8 @@ cat < Date: Sat, 14 Feb 2026 10:02:54 +0100 Subject: [PATCH 3/6] docs(SKILL.md): clarify API key is optional and use env var consistently --- SKILL.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/SKILL.md b/SKILL.md index e382483..2fe7258 100644 --- a/SKILL.md +++ b/SKILL.md @@ -31,12 +31,19 @@ The script outputs JSON with detected clients and OS info. Remember the result f ### Step 2: Search for content -Query the TorrentClaw API. Always include the `x-search-source: skill` header for analytics: +Query the TorrentClaw API. Always include the `x-search-source: skill` header for analytics. The API key is **optional** — anonymous usage allows 30 req/min, which is enough for casual searches. Only include the `Authorization` header if `$TORRENTCLAW_API_KEY` is set: ```bash curl -s -H "x-search-source: skill" "https://torrentclaw.com/api/v1/search?q=QUERY&sort=seeders&limit=5" ``` +If the user has configured an API key for higher rate limits: + +```bash +curl -s -H "x-search-source: skill" -H "Authorization: Bearer $TORRENTCLAW_API_KEY" \ + "https://torrentclaw.com/api/v1/search?q=QUERY&sort=seeders&limit=5" +``` + **Useful filters** (append as query params): - `type=movie` or `type=show` - `quality=1080p` (also: 720p, 2160p, 480p) @@ -191,7 +198,7 @@ The API automatically detects episode patterns in queries and filters results ac ## API Authentication -TorrentClaw supports optional API key authentication for higher rate limits. +The API works without authentication (30 req/min anonymous tier). An API key is **only needed** if you require higher rate limits for heavy or automated usage. **Rate Limit Tiers:** @@ -204,13 +211,11 @@ TorrentClaw supports optional API key authentication for higher rate limits. **Using an API key:** -```bash -# Via header (recommended) -curl -H "Authorization: Bearer tc_live_xxxxx" \ - "https://torrentclaw.com/api/v1/search?q=dune" +Always use the `$TORRENTCLAW_API_KEY` environment variable via the `Authorization` header. Avoid passing the key as a query parameter — query strings may be logged in server access logs and HTTP referrer headers. -# Via query parameter -curl "https://torrentclaw.com/api/v1/search?q=dune&api_key=tc_live_xxxxx" +```bash +curl -H "Authorization: Bearer $TORRENTCLAW_API_KEY" \ + "https://torrentclaw.com/api/v1/search?q=dune" ``` **Rate limit headers in response:** @@ -253,7 +258,7 @@ curl "https://torrentclaw.com/api/v1/search?q=entrevias+S01E05&locale=es" **Search with API key for higher rate limits:** ```bash -curl -H "Authorization: Bearer tc_live_xxxxx" \ +curl -H "Authorization: Bearer $TORRENTCLAW_API_KEY" \ "https://torrentclaw.com/api/v1/search?q=dune&quality=2160p" ``` From d3d6c702ed9b1e68e11cbcdcb64b42e97c404a90 Mon Sep 17 00:00:00 2001 From: Deivid Soto Date: Sun, 15 Feb 2026 10:46:34 +0100 Subject: [PATCH 4/6] fix(security): eliminate shell injection and add input validation Replace unsafe string interpolation in aria2 RPC JSON construction with jq --arg for proper escaping. Add magnet URL format validation to reject arbitrary input. Refactor detect-client.sh JSON output to use jq. Add CI security check to prevent regression. Resolves VirusTotal "Suspicious" classification caused by the shell injection vulnerability in add-torrent.sh. --- .github/workflows/ci.yml | 18 +++++++++++++++ CHANGELOG.md | 10 ++++++++ README.md | 2 +- SKILL.md | 2 +- scripts/add-torrent.sh | 16 ++++++++++--- scripts/detect-client.sh | 50 ++++++++++++++++++++++++---------------- 6 files changed, 73 insertions(+), 25 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0c4e9e1..7822970 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -51,3 +51,21 @@ jobs: - name: Run ShellCheck run: shellcheck scripts/*.sh + + security-check: + name: Security patterns check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Check for unsafe string interpolation in curl payloads + run: | + # Flag inline JSON in double quotes (allows shell interpolation). + # Safe patterns: curl -d '{}' (single quotes) or curl -d "$var" (pre-built payload). + if grep -rPn 'curl.*-d\s*"[{]' scripts/*.sh; then + echo "" + echo "ERROR: Found curl -d with inline JSON in double quotes." + echo "Use jq --arg to build JSON safely and pass via variable." + exit 1 + fi + echo "No unsafe curl patterns found." diff --git a/CHANGELOG.md b/CHANGELOG.md index 151d870..b9ec3ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,16 @@ All notable changes to this project will be documented in this file. +## [0.1.16] - 2026-02-14 + +### Security + +- Fix shell injection vulnerability in aria2 RPC JSON construction (add-torrent.sh) +- Add magnet URL format validation before passing to torrent clients +- Replace shell string interpolation with `jq --arg` for safe JSON construction +- Refactor detect-client.sh JSON output to use `jq` instead of heredoc interpolation +- Add CI security pattern check to prevent unsafe curl payload regression + ## [0.1.13] - 2026-02-13 ### Features diff --git a/README.md b/README.md index dd2c8e1..ffef74e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # torrentclaw-skill -**Version:** 0.1.13 +**Version:** 0.1.16 **License:** MIT **Homepage:** https://torrentclaw.com diff --git a/SKILL.md b/SKILL.md index 2fe7258..afd6ce5 100644 --- a/SKILL.md +++ b/SKILL.md @@ -2,7 +2,7 @@ name: torrentclaw description: Search and download torrents via TorrentClaw. Use when the user asks to find, search, or download movies, TV shows, or torrents. Detects local torrent clients (Transmission, aria2) and adds magnets directly, or offers magnet link copy and .torrent file download. Supports filtering by type (movie/show), genre, year, quality (480p-2160p), rating, language, and season/episode (S01E05, 1x05). Features API key authentication with tiered rate limits, AI-verified matching, and quality scoring (0-100). Returns titles with posters, ratings, and torrents with magnet links and quality scores. license: MIT -metadata: {"version": "0.1.13", "repository": "https://github.com/torrentclaw/torrentclaw-skill", "homepage": "https://torrentclaw.com", "openclaw": {"emoji": "🎬", "os": ["darwin", "linux", "win32"], "requires": {"bins": ["curl", "bash", "jq"], "env": ["TORRENTCLAW_API_KEY"]}, "primaryEnv": "TORRENTCLAW_API_KEY"}, "tags": ["torrent", "movies", "tv-shows", "download", "media", "entertainment", "magnet", "transmission", "aria2", "search", "4k", "hdr"]} +metadata: {"version": "0.1.16", "repository": "https://github.com/torrentclaw/torrentclaw-skill", "homepage": "https://torrentclaw.com", "openclaw": {"emoji": "🎬", "os": ["darwin", "linux", "win32"], "requires": {"bins": ["curl", "bash", "jq"], "env": ["TORRENTCLAW_API_KEY"]}, "primaryEnv": "TORRENTCLAW_API_KEY"}, "tags": ["torrent", "movies", "tv-shows", "download", "media", "entertainment", "magnet", "transmission", "aria2", "search", "4k", "hdr"]} --- # TorrentClaw diff --git a/scripts/add-torrent.sh b/scripts/add-torrent.sh index 3d45764..84dad87 100755 --- a/scripts/add-torrent.sh +++ b/scripts/add-torrent.sh @@ -44,6 +44,13 @@ if [ -z "$magnet_url" ]; then exit 1 fi +# --- Validate magnet URL format --- +if [[ ! "$magnet_url" =~ ^magnet:\?xt=urn:btih:[a-fA-F0-9]{40} ]] && \ + [[ ! "$magnet_url" =~ ^magnet:\?xt=urn:btih:[a-zA-Z2-7]{32} ]]; then + echo "Error: Invalid magnet URL format. Expected: magnet:?xt=urn:btih:" >&2 + exit 1 +fi + # --- Auto-detect client if not specified --- if [ -z "$client" ]; then if command -v transmission-remote >/dev/null 2>&1; then @@ -76,11 +83,14 @@ case "$client" in # Check if aria2 RPC is running if curl -sf http://localhost:6800/jsonrpc -d '{"jsonrpc":"2.0","id":"test","method":"aria2.getVersion"}' >/dev/null 2>&1; then echo "Adding to aria2 via RPC..." - dir_param="" if [ -n "$download_dir" ]; then - dir_param=",{\"dir\":\"$download_dir\"}" + payload=$(jq -n --arg url "$magnet_url" --arg dir "$download_dir" \ + '{"jsonrpc":"2.0","id":"add","method":"aria2.addUri","params":[[$url],{"dir":$dir}]}') + else + payload=$(jq -n --arg url "$magnet_url" \ + '{"jsonrpc":"2.0","id":"add","method":"aria2.addUri","params":[[$url]]}') fi - result=$(curl -sf http://localhost:6800/jsonrpc -d "{\"jsonrpc\":\"2.0\",\"id\":\"add\",\"method\":\"aria2.addUri\",\"params\":[[\"$magnet_url\"]$dir_param]}") + result=$(curl -sf http://localhost:6800/jsonrpc -d "$payload") if echo "$result" | grep -q '"result"'; then echo "Torrent added to aria2 successfully." else diff --git a/scripts/detect-client.sh b/scripts/detect-client.sh index 0bf2af6..1780b7a 100755 --- a/scripts/detect-client.sh +++ b/scripts/detect-client.sh @@ -73,24 +73,34 @@ elif [ "$aria2_installed" = "true" ]; then fi # --- JSON Output --- -cat < Date: Mon, 16 Feb 2026 11:44:34 +0100 Subject: [PATCH 5/6] fix(security): use --data-urlencode in SKILL.md curl commands --- CHANGELOG.md | 9 +++++++++ SKILL.md | 51 ++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 45 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b9ec3ee..71a8ed0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ All notable changes to this project will be documented in this file. +## [0.1.17] - 2026-02-16 + +### Security + +- Fix shell injection vulnerability in SKILL.md curl search commands +- Replace direct URL interpolation with `curl -G --data-urlencode` for all user-supplied query parameters +- Add explicit instruction to never interpolate user input directly into URL strings +- Update all curl examples (search, episode, common patterns, auth) to use safe parameter encoding + ## [0.1.16] - 2026-02-14 ### Security diff --git a/SKILL.md b/SKILL.md index afd6ce5..2710958 100644 --- a/SKILL.md +++ b/SKILL.md @@ -2,7 +2,7 @@ name: torrentclaw description: Search and download torrents via TorrentClaw. Use when the user asks to find, search, or download movies, TV shows, or torrents. Detects local torrent clients (Transmission, aria2) and adds magnets directly, or offers magnet link copy and .torrent file download. Supports filtering by type (movie/show), genre, year, quality (480p-2160p), rating, language, and season/episode (S01E05, 1x05). Features API key authentication with tiered rate limits, AI-verified matching, and quality scoring (0-100). Returns titles with posters, ratings, and torrents with magnet links and quality scores. license: MIT -metadata: {"version": "0.1.16", "repository": "https://github.com/torrentclaw/torrentclaw-skill", "homepage": "https://torrentclaw.com", "openclaw": {"emoji": "🎬", "os": ["darwin", "linux", "win32"], "requires": {"bins": ["curl", "bash", "jq"], "env": ["TORRENTCLAW_API_KEY"]}, "primaryEnv": "TORRENTCLAW_API_KEY"}, "tags": ["torrent", "movies", "tv-shows", "download", "media", "entertainment", "magnet", "transmission", "aria2", "search", "4k", "hdr"]} +metadata: {"version": "0.1.17", "repository": "https://github.com/torrentclaw/torrentclaw-skill", "homepage": "https://torrentclaw.com", "openclaw": {"emoji": "🎬", "os": ["darwin", "linux", "win32"], "requires": {"bins": ["curl", "bash", "jq"], "env": ["TORRENTCLAW_API_KEY"]}, "primaryEnv": "TORRENTCLAW_API_KEY"}, "tags": ["torrent", "movies", "tv-shows", "download", "media", "entertainment", "magnet", "transmission", "aria2", "search", "4k", "hdr"]} --- # TorrentClaw @@ -31,17 +31,24 @@ The script outputs JSON with detected clients and OS info. Remember the result f ### Step 2: Search for content -Query the TorrentClaw API. Always include the `x-search-source: skill` header for analytics. The API key is **optional** — anonymous usage allows 30 req/min, which is enough for casual searches. Only include the `Authorization` header if `$TORRENTCLAW_API_KEY` is set: +Query the TorrentClaw API. Always include the `x-search-source: skill` header for analytics. The API key is **optional** — anonymous usage allows 30 req/min, which is enough for casual searches. Only include the `Authorization` header if `$TORRENTCLAW_API_KEY` is set. + +**Important:** Always use `--data-urlencode` for user-supplied values to prevent shell injection. Never interpolate user input directly into the URL string. ```bash -curl -s -H "x-search-source: skill" "https://torrentclaw.com/api/v1/search?q=QUERY&sort=seeders&limit=5" +curl -s -G -H "x-search-source: skill" \ + --data-urlencode "q=QUERY" \ + -d "sort=seeders" -d "limit=5" \ + "https://torrentclaw.com/api/v1/search" ``` If the user has configured an API key for higher rate limits: ```bash -curl -s -H "x-search-source: skill" -H "Authorization: Bearer $TORRENTCLAW_API_KEY" \ - "https://torrentclaw.com/api/v1/search?q=QUERY&sort=seeders&limit=5" +curl -s -G -H "x-search-source: skill" -H "Authorization: Bearer $TORRENTCLAW_API_KEY" \ + --data-urlencode "q=QUERY" \ + -d "sort=seeders" -d "limit=5" \ + "https://torrentclaw.com/api/v1/search" ``` **Useful filters** (append as query params): @@ -186,12 +193,15 @@ TorrentClaw supports smart episode filtering with multiple formats: 1. **In query text** (automatic parsing): ```bash -curl "https://torrentclaw.com/api/v1/search?q=breaking+bad+S05E14" +curl -s -G --data-urlencode "q=breaking bad S05E14" \ + "https://torrentclaw.com/api/v1/search" ``` 2. **With explicit parameters**: ```bash -curl "https://torrentclaw.com/api/v1/search?q=breaking+bad&season=5&episode=14" +curl -s -G --data-urlencode "q=breaking bad" \ + -d "season=5" -d "episode=14" \ + "https://torrentclaw.com/api/v1/search" ``` The API automatically detects episode patterns in queries and filters results accordingly. @@ -214,8 +224,9 @@ The API works without authentication (30 req/min anonymous tier). An API key is Always use the `$TORRENTCLAW_API_KEY` environment variable via the `Authorization` header. Avoid passing the key as a query parameter — query strings may be logged in server access logs and HTTP referrer headers. ```bash -curl -H "Authorization: Bearer $TORRENTCLAW_API_KEY" \ - "https://torrentclaw.com/api/v1/search?q=dune" +curl -s -G -H "Authorization: Bearer $TORRENTCLAW_API_KEY" \ + --data-urlencode "q=dune" \ + "https://torrentclaw.com/api/v1/search" ``` **Rate limit headers in response:** @@ -253,28 +264,38 @@ Use `lang=es` filter. **Search for a specific TV episode:** ```bash -curl "https://torrentclaw.com/api/v1/search?q=entrevias+S01E05&locale=es" +curl -s -G --data-urlencode "q=entrevias S01E05" \ + -d "locale=es" \ + "https://torrentclaw.com/api/v1/search" ``` **Search with API key for higher rate limits:** ```bash -curl -H "Authorization: Bearer $TORRENTCLAW_API_KEY" \ - "https://torrentclaw.com/api/v1/search?q=dune&quality=2160p" +curl -s -G -H "Authorization: Bearer $TORRENTCLAW_API_KEY" \ + --data-urlencode "q=dune" \ + -d "quality=2160p" \ + "https://torrentclaw.com/api/v1/search" ``` **Find popular sci-fi movies:** ```bash -curl "https://torrentclaw.com/api/v1/search?genre=Science%20Fiction&type=movie&sort=seeders" +curl -s -G --data-urlencode "genre=Science Fiction" \ + -d "type=movie" -d "sort=seeders" \ + "https://torrentclaw.com/api/v1/search" ``` **Find Dolby Vision / HDR content:** ```bash -curl "https://torrentclaw.com/api/v1/search?q=dune&hdr=dolby_vision&quality=2160p" +curl -s -G --data-urlencode "q=dune" \ + -d "hdr=dolby_vision" -d "quality=2160p" \ + "https://torrentclaw.com/api/v1/search" ``` **Find Atmos audio torrents:** ```bash -curl "https://torrentclaw.com/api/v1/search?q=oppenheimer&audio=atmos" +curl -s -G --data-urlencode "q=oppenheimer" \ + -d "audio=atmos" \ + "https://torrentclaw.com/api/v1/search" ``` **Get cast info for a movie:** From d0a935a8bc6f7fa9f84a554da1e35791ed32f1eb Mon Sep 17 00:00:00 2001 From: Deivid Soto Date: Wed, 27 May 2026 15:45:46 +0200 Subject: [PATCH 6/6] ci: port workflows from .github/ to .forgejo/ (Forgejo Actions) GitHub torrentclaw org is shadow-banned; CI is hosted at git.torrentclaw.com now. Move workflows into the runner's natively-watched .forgejo/workflows/ tree and adapt steps to run in the available 'docker'-labeled Forgejo runner without GitHub-only tooling (gh CLI, third-party marketplace actions). - Use container: image to ship the toolchain (no actions/setup-* needed). - Drop GitHub-only marketplace actions in favour of upstream installers invoked over curl/apt. - Where a workflow created a GitHub Release (release.yml), substitute the step with a curl call against the Forgejo Releases API (POST /repos///releases). --- {.github => .forgejo}/workflows/ci.yml | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) rename {.github => .forgejo}/workflows/ci.yml (76%) diff --git a/.github/workflows/ci.yml b/.forgejo/workflows/ci.yml similarity index 76% rename from .github/workflows/ci.yml rename to .forgejo/workflows/ci.yml index 7822970..dde3e99 100644 --- a/.github/workflows/ci.yml +++ b/.forgejo/workflows/ci.yml @@ -12,9 +12,14 @@ permissions: jobs: lint-commits: name: Lint commits - runs-on: ubuntu-latest + runs-on: docker + container: + image: docker.io/library/ubuntu:24.04 if: github.event_name == 'pull_request' steps: + - name: Install git + grep + run: apt-get update && apt-get install -y --no-install-recommends git ca-certificates + - uses: actions/checkout@v4 with: fetch-depth: 0 @@ -45,8 +50,13 @@ jobs: lint-scripts: name: Lint shell scripts - runs-on: ubuntu-latest + runs-on: docker + container: + image: docker.io/library/ubuntu:24.04 steps: + - name: Install shellcheck + run: apt-get update && apt-get install -y --no-install-recommends shellcheck git ca-certificates + - uses: actions/checkout@v4 - name: Run ShellCheck @@ -54,8 +64,13 @@ jobs: security-check: name: Security patterns check - runs-on: ubuntu-latest + runs-on: docker + container: + image: docker.io/library/ubuntu:24.04 steps: + - name: Install grep + git + run: apt-get update && apt-get install -y --no-install-recommends git grep ca-certificates + - uses: actions/checkout@v4 - name: Check for unsafe string interpolation in curl payloads