feat(query): add exact multi-title filter (PRO-1969)

[SohamRatnaparkhi]

Linear

PRO-1969

What

Adds a repeatable --title option to hydradb query. Each value is preserved as one exact document title and forwarded to the backend, which resolves matching source IDs before running the normal query pipeline.

• exact, case-insensitive title matching is performed by the backend
• repeat --title to supply multiple titles
• punctuation such as commas stays inside the title
• blank values are rejected and case-insensitive duplicates are removed
• ordinary title-free calls continue through the generated SDK
• title-filtered calls use the existing authenticated API v2 transport until the SDK is regenerated with the new OpenAPI field

Dependency

Depends on hydra-db/hydradb-application#1355. Deploy the backend and complete its MongoDB index/backfill rollout first.

Checks

• .venv/bin/python -m pytest (335 passed)
• Ruff checks and formatting checks on all changed Python files

[greptile-apps]

Greptile Summary

Adds repeatable exact-title filtering to hydradb query and updates the package release references to 0.2.1.

• Normalizes title inputs through trimming, blank rejection, and case-insensitive deduplication.
• Uses the authenticated API-v2 transport for title-filtered requests while retaining the generated SDK path for ordinary queries.
• Adds CLI and wrapper coverage for title forwarding and validation.
• Updates documentation, changelog entries, package metadata, and displayed version examples.
• Greptile automatically discovered a related ticket that helped explain the purpose of this PR: expose optional exact, case-insensitive multi-title filtering consistently through the CLI.

Confidence Score: 5/5

The PR appears safe to merge, with no outstanding blocking or non-blocking findings.

The previously reported client-side limit and missing validation coverage are fixed in the current code. The stale release examples were manually resolved without explanation, and the current README now consistently matches version 0.2.1. No new actionable failures were introduced by the changes since the previous review.

Important Files Changed

Filename	Overview
src/hydradb_cli/commands/_impl.py	Normalizes and validates repeatable title values before forwarding them to the query wrapper.
src/hydradb_cli/commands/canonical.py	Exposes the repeatable --title CLI option and passes its values into query execution.
src/hydradb_cli/hydra/client.py	Routes title-filtered queries through the authenticated raw API-v2 transport while preserving the SDK path for ordinary queries.
tests/test_cli_commands.py	Covers title forwarding, whitespace normalization, case-insensitive deduplication, and blank rejection.
tests/test_wrapper.py	Verifies the title-filtered request body, scope fields, endpoint, and API-version header.
README.md	Documents repeatable title filtering and updates release examples consistently to version 0.2.1.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[hydradb query] --> B[Trim, validate, and deduplicate titles]
  B --> C{Titles present?}
  C -- No --> D[Generated SDK query]
  C -- Yes --> E[Authenticated API v2 POST /query]
  E --> F[Backend resolves exact titles to source IDs]
  D --> G[Normal query pipeline]
  F --> G

Loading

_{Reviews (6): Last reviewed commit: "docs(readme): point the install examples..." | Re-trigger Greptile}

[openhack-agent]

🔍 Security Scan Results

⚠️ 4 potential vulnerabilities detected

View full results on OpenHack

• 🟢 Low: 4

---

Findings

🟢 Server-controlled strings rendered as Rich markup allow terminal output spoofing in query results and error messages

Severity: LOW

Server-controlled strings are interpolated into Rich markup-parsed output without escaping, enabling terminal output spoofing. Confirmed injection sites: (1) _feedback_hint (commands/_impl.py:87) embeds the server-supplied request_id verbatim into a markup string that _format_query_result renders via Text.from_markup at line 122; (2) print_error (output.py:97) interpolates server error body text into a markup-parsed f-string on stderr; (3) commands/_impl.py:213 embeds server request_id into a markup string passed to console.print; (4) commands/_impl.py:108 embeds chunk source_title into a markup-parsed Panel title — the highest-impact variant, since a co-tenant who ingests a document titled e.g. "[red]SYSTEM: quota exceeded[/red]" can spoof other users' query output without controlling the server. This violates the codebase's own documented convention in make_table (output.py:151-155), which explicitly escapes cells because "a title like '[draft] Q3 plan' would otherwise be read as a style tag and vanish". Impact ceiling is verified: Rich markup cannot emit arbitrary ANSI escapes or execute commands — damage is limited to recoloring, concealing text, and injecting clickable OSC-8 phishing hyperlinks (e.g. a fake "ERROR: rotate your key" line linking to an attacker URL).

Location: src/hydradb_cli/commands/_impl.py:122

View details on OpenHack →

---

🟢 API key echoed in full to stdout by config set when the key is 12 characters or shorter

Severity: LOW

hydradb config set api_key <value> echoes the FULL API key to stdout when the key is 12 characters or shorter. The inline masking at config_cmd.py:112-114 only masks when len(value) > 12; for shorter keys display_value remains the raw key and is printed verbatim in the success message at line 120 ("Set api_key = in ~/.hydradb/config.json"). This diverges from the shared mask_api_key() helper (utils/common.py:12-16), which returns "***" for exactly the same input — mask_api_key is already imported in config_cmd.py (line 16) and used correctly by config show (lines 45, 53); only set_value bypasses it with a buggy inline reimplementation. The full bearer key lands in terminal scrollback, CI job logs, and piped/tee'd output, defeating the feature's stated guarantee that no path prints the full key. Realistic scenario: a user or agent script following the docs' advice to pass --api-key explicitly runs hydradb config set api_key sk-abc123 in a CI job; the key is captured in the job log visible to anyone with read access to the pipeline.

Location: src/hydradb_cli/commands/config_cmd.py:112

View details on OpenHack →

---

🟢 Credential file written world-readable before chmod(0o600): TOCTOU window and persistent insecure mode on crash

Severity: LOW

_write_config_file() in src/hydradb_cli/config.py writes the API key with CONFIG_FILE.write_text() — which creates the file with mode 0666 & ~umask, i.e. world-readable (0644) under the default umask 022 — and only THEN calls chmod(0o600). Any local process polling the path can read the plaintext bearer key during the window between file creation and the chmod. The window recurs on every first-time config creation (login, first config set); if a previous run crashed between write and chmod (or the file was restored from backup with permissive modes), the insecure mode persists indefinitely because _read_config_file() performs no permission check and nothing else in the codebase re-checks it. Additionally, _ensure_config_dir() creates ~/.hydradb with default mkdir perms (0755), leaving the credential directory world-listable. The protected value is real: save_config(api_key=...) is invoked with the live bearer token from hydradb login (commands/auth.py:85) and hydradb config set api_key (commands/config_cmd.py:110). This is not design intent — the code comment ('Restrict permissions on config file (contains API key)') and auth.py's docstring ('stored ... with restricted permissions') show the developer intended 0600 from the start.

Location: src/hydradb_cli/config.py:91

View details on OpenHack →

---

🟢 Installer performs no integrity verification of release wheels and the publish pipeline allows post-tag asset replacement

Severity: LOW

The curl|bash installer performs zero integrity verification of the wheel it downloads and executes, and the release pipeline makes assets mutable, so the documented version-pinning mechanism provides no tamper-evidence. (1) install.sh builds the wheel URL (line 122), HEAD-checks only its existence (asset_exists, lines 108-117 — no hash comparison), then hands the URL directly to pipx install --force "$WHEEL_URL" (lines 147/149) or pip install --user ... "$WHEEL_URL" (lines 161/163). There is no SHA256SUMS asset, no --require-hashes, no cosign/sigstore attestation, and no GPG signature anywhere in the repo, and the README's 'Verify the installation' section only runs hydradb --version. (2) .github/workflows/publish.yml line 51 uploads artifacts with gh release upload "$TAG" dist/* --clobber, explicitly allowing a wheel to be replaced after a tag is published. Attack scenario: an attacker with maintainer-token or Actions write access re-uploads a backdoored hydradb_cli-0.2.1-py3-none-any.whl onto the already-published v0.2.1 tag; every user running the README-documented command — including the pinned form HYDRADB_CLI_VERSION=0.2.1 curl -fsSL https://cli.hydradb.com/install | bash — installs the malicious wheel, yielding arbitrary code execution with user privileges. The publish workflow itself runs unpinned pip install build twine inside a job holding a contents:write GITHUB_TOKEN, so a dependency/action compromise can silently re-upload a backdoored wheel without any commit; users auditing the tagged source would see clean code while the installed asset differs. Because 'latest' is resolved at runtime and no checksums are published, users also cannot TOFU-verify anything after the fact.

Location: install.sh:122

View details on OpenHack →