[mirror] Make recursive lookups honor -p/--allow-private-address

[yashwant86]

Mirror of upstream fedify-dev#718 for benchmark. Do not merge.

---

Summary by MergeMonkey

• Docs & Guides:
  • Updated CLI docs to reflect that recursive lookups now honor the `-p`/`--allow-private-address` flag.
  • Clarified that private address filtering applies to URLs discovered during traversal.
• What's New:
  • Recursive lookups now respect `-p`/`--allow-private-address` flag to allow private/localhost targets in traversal.
  • Added detection of private context URLs in recursive JSON-LD fetches with targeted error messaging.
• Bug Fixes:
  • Fixed recursive lookups to always block private JSON-LD context URLs regardless of `-p` flag, preventing SSRF via context injection.
• Refactors:
  • Added comprehensive test suite for recursive private address handling with local test server.

[bot-mergemonkey]

⚡ Risk Assessment — NEEDS-TESTING · ~25 min review

Focus areas: Async/await correctness in test helpers · Private IP detection logic and edge cases · JSON-LD context error parsing robustness

Assessment: Adds private address filtering to recursive lookups with new detection logic and test infrastructure.

Walkthrough

User runs fedify lookup --recurse --allow-private-address on a localhost URL. The CLI now checks each discovered target URL against a fast private-address detector (localhost, RFC1918, link-local IPs) before fetching. If allowed by the flag, private targets are fetched; if blocked, a targeted error message suggests the flag. JSON-LD context URLs are always blocked for SSRF safety, with a separate error message explaining the restriction.

Changes

Files	Summary
Documentation Updates docs/cli.md CHANGES.md	Updated documentation to reflect that recursive lookups now honor the `-p`/`--allow-private-address` flag, clarifying behavior for private/localhost targets in traversal.
Private Address Detection & Recursive Lookup Policy packages/cli/src/lookup.ts	Implemented private address detection for recursive lookups: added `getPrivateUrlCandidate()` to identify private IPs/localhost without DNS, `isPrivateAddressTarget()` for target validation, `getPrivateContextUrl()` to detect blocked private JSON-LD contexts, and separate hint functions for target vs. context errors. Recursive targets now respect `-p` flag while contexts remain always-blocked for SSRF safety.
Recursive Lookup Test Suite packages/cli/src/lookup.test.ts	Added test infrastructure: `withRecursiveLookupServer()` for local test server with configurable context paths, `captureStderr()` for error message validation, and three integration tests verifying private address handling (default rejection, allowed with flag, context always blocked).

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI
    participant PrivateDetector
    participant Fetcher
    participant ContextLoader
    User->>CLI: lookup --recurse --allow-private-address URL
    CLI->>Fetcher: fetch root URL
    Fetcher->>CLI: return object with inReplyTo
    CLI->>PrivateDetector: check inReplyTo target
    alt Target is private
        PrivateDetector->>CLI: isPrivateAddressTarget=true
        alt allowPrivateAddress flag set
            CLI->>Fetcher: fetch private target
            Fetcher->>CLI: return object
        else flag not set
            CLI->>CLI: printRecursivePrivateAddressHint()
            CLI->>User: error: use -p flag
        end
    else Target is public
        PrivateDetector->>CLI: isPrivateAddressTarget=false
        CLI->>Fetcher: fetch target
    end
    CLI->>ContextLoader: load @context URL
    alt Context URL is private
        ContextLoader->>CLI: error (always blocked)
        CLI->>CLI: printRecursivePrivateContextHint()
        CLI->>User: error: context always blocked
    else Context URL is public
        ContextLoader->>CLI: context loaded
    end

Loading

Dig Deeper With Commands

• /review <file-path> <function-optional>
• /chat <file-path> "<question>"
• /roast <file-path>

Runs only when explicitly triggered.