@bbradar/mcp 0.1.13 → 0.1.16

package/dist/server.js

@@ -20,6 +20,7 @@ const MAX_FIND_TARGET_SAMPLE_PROGRAMS = 10;
 const MAX_FIND_TARGET_SAMPLES = 20;
 const MAX_FIND_UPSTREAM_REQUEST_BUDGET = 50;
 const DEFAULT_FIND_UPSTREAM_REQUEST_BUDGET = 20;
+const DEFAULT_RESOLVE_UPSTREAM_REQUEST_BUDGET = 4;
 const MAX_ACCEPTED_NUMERIC_LIMIT = 1_000;
 const PROGRAM_COLLECTION_CONCURRENCY = 4;
 const TARGET_SAMPLE_CONCURRENCY = 3;
@@ -30,10 +31,12 @@ const MAX_FILTER_TARGET_SAMPLE_PROGRAMS = 25;
 const MAX_LOCAL_EXPORT_RESOURCES = 25;
 const EXPORT_PREVIEW_LIMIT = 25;
 const STALE_PROGRAM_ID_RESOLVE_PAGES = 1;
-const STALE_PROGRAM_ID_RESOLVE_BUDGET = 1;
+const STALE_PROGRAM_ID_RESOLVE_BUDGET = 8;
 const PROGRAM_FALLBACK_CACHE_MAX_ENTRIES = 200;
 const MAX_RESOLVE_SEARCH_QUERIES = 4;
+const MAX_DIRECT_HANDLE_RESOLUTION_REQUESTS = 8;
 const SDK_VERSION = "1.29.0";
+const PROGRAM_ID_PLATFORM_GUESSES = ["HackerOne", "Bugcrowd", "Intigriti", "HackenProof", "YesWeHack", "Cantina", "Code4rena", "Immunefi"];
 const WEB3_TAGS = ["web3", "crypto", "blockchain", "smart-contract", "smart contract", "defi", "nft", "ethereum", "solana", "solidity"];
 const WEB3_CONTEST_SIGNALS = ["contest", "audit", "competitive", "code4rena", "sherlock", "cantina", "codehawks", "hats", "spearbit", "warden"];
 const VDP_SIGNALS = ["vdp", "disclosure", "responsible disclosure", "vulnerability disclosure", "no bounty", "non-bounty", "no reward"];
@@ -44,6 +47,15 @@ const PROGRAM_RESOLUTION_STOP_WORDS = new Set([
     "targets",
     "scope",
     "scopes",
+    "network",
+    "networks",
+    "protocol",
+    "protocols",
+    "bug",
+    "bugs",
+    "bounty",
+    "bounties",
+    "security",
     "new",
     "latest",
     "recent",
@@ -406,7 +418,7 @@ export function createBbradarServer(client, config) {
             max_pages: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(3),
             max_results: z.number().int().min(1).max(25).default(10),
             output_mode: programListModeSchema.default("compact"),
-            upstream_request_budget: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(DEFAULT_FIND_UPSTREAM_REQUEST_BUDGET)
+            upstream_request_budget: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(DEFAULT_RESOLVE_UPSTREAM_REQUEST_BUDGET)
         },
         outputSchema: {
             ...programListOutputShape(),
@@ -439,7 +451,7 @@ export function createBbradarServer(client, config) {
             target_list_mode: targetListModeSchema.default("identifiers"),
             max_resolve_pages: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(3),
             output_mode: programListModeSchema.default("compact"),
-            upstream_request_budget: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(DEFAULT_FIND_UPSTREAM_REQUEST_BUDGET)
+            upstream_request_budget: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(DEFAULT_RESOLVE_UPSTREAM_REQUEST_BUDGET)
         },
         outputSchema: {
             ...apiEnvelopeOutputShape(),
@@ -462,7 +474,7 @@ export function createBbradarServer(client, config) {
             tags: tagListSchema(),
             opportunity_levels: z.array(opportunityLevelSchema).max(4).default([]),
             max_resolve_pages: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(3),
-            upstream_request_budget: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(DEFAULT_FIND_UPSTREAM_REQUEST_BUDGET),
+            upstream_request_budget: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(DEFAULT_RESOLVE_UPSTREAM_REQUEST_BUDGET),
             include_out_of_scope: z.boolean().default(false),
             include_ineligible: z.boolean().default(false),
             strict_scope_filter: z.boolean().default(true),
@@ -2126,14 +2138,13 @@ async function resolveProgramNameIdentifier(client, config, requestedProgramName
     }
     const sourceRequests = readArray(resolution.source_requests).filter((request) => readObject(request) !== undefined);
     const warnings = readArray(resolution.warnings).filter((warning) => typeof warning === "string");
-    const fallbackWarning = `Resolved program name ${requestedProgramName} to program_id ${match.resolvedProgramId}.`;
     return {
         requestedProgramId: requestedProgramName,
         resolvedProgramId: match.resolvedProgramId,
         query,
         reason: "program_name",
         sourceRequests,
-        warnings: uniqueStrings([...warnings, fallbackWarning]),
+        warnings: uniqueStrings(warnings),
         resolution
     };
 }
@@ -2347,6 +2358,7 @@ async function resolveProgram(client, config, input) {
     const maxPages = clampLimit("max_pages", input.max_pages, MAX_FIND_PROGRAM_PAGES, warnings);
     const searchQueries = programResolutionSearchQueries(input.query);
     const collected = await collectProgramsForResolution(client, {
+        query: input.query,
         searchQueries,
         isHighConfidenceMatch: (programs) => hasHighConfidenceProgramResolutionMatch(programs, config.webBaseUrl, input.query),
         scorePrograms: (programs) => bestProgramResolutionScore(programs, config.webBaseUrl, input.query),
@@ -2357,7 +2369,9 @@ async function resolveProgram(client, config, input) {
         budget,
         warnings
     });
-    const matches = collected.programs
+    const sourceRequests = [...collected.sourceRequests];
+    let targetLookup;
+    let matches = collected.programs
         .map((program) => {
         const candidate = toProgramCandidate(program, config.webBaseUrl);
         const match = programResolutionMatch(candidate, input.query);
@@ -2366,14 +2380,58 @@ async function resolveProgram(client, config, input) {
         .filter((entry) => entry.match.score > 0)
         .sort((left, right) => right.match.score - left.match.score || compareProgramCandidates(left.candidate, right.candidate, "best_hunt_value"))
         .slice(0, input.max_results);
+    if (matches.length === 0 && queryLooksLikeTargetIdentifier(input.query)) {
+        targetLookup = await findProgramsByTarget(client, config, {
+            target_query: input.query,
+            match_mode: "smart",
+            platforms: input.platforms,
+            tags: input.tags,
+            use_api_search: true,
+            max_pages: 1,
+            max_results: input.max_results,
+            include_out_of_scope: false,
+            include_ineligible: false,
+            max_targets_per_program: 3,
+            target_list_mode: "identifiers",
+            upstream_request_budget: Math.max(1, budget.remaining)
+        });
+        sourceRequests.push(...readArray(targetLookup.source_requests).filter((request) => readObject(request) !== undefined));
+        for (const warning of readArray(targetLookup.warnings)) {
+            if (typeof warning === "string") {
+                addUniqueWarning(warnings, warning);
+            }
+        }
+        const targetBudget = readObject(targetLookup.upstream_budget);
+        const targetBudgetUsed = numberField(targetBudget, "used") ?? 0;
+        budget.remaining = Math.max(0, budget.remaining - targetBudgetUsed);
+        matches = readArray(targetLookup.matches)
+            .map((entry) => {
+            const matchEntry = readObject(entry);
+            const program = readObject(matchEntry?.program);
+            if (!program) {
+                return undefined;
+            }
+            return {
+                candidate: toProgramCandidate(program, config.webBaseUrl),
+                match: {
+                    score: 75,
+                    fields: ["targets"],
+                    reasons: ["target search matched query"]
+                }
+            };
+        })
+            .filter((entry) => entry !== undefined)
+            .slice(0, input.max_results);
+    }
     const programs = matches.map((entry) => formatProgram(entry.candidate.program, input.output_mode));
     const payload = stripUndefined({
         request_id: randomUUID(),
-        source_requests: collected.sourceRequests,
+        source_requests: sourceRequests,
         warnings: warnings.length > 0 ? warnings : undefined,
         query: {
             text: input.query,
             search_queries: searchQueries,
+            target_search_queries: readObject(targetLookup?.filters)?.target_search_queries,
             platforms: input.platforms.length > 0 ? input.platforms : undefined,
             tags: input.tags.length > 0 ? input.tags : undefined
         },
@@ -2398,7 +2456,8 @@ async function resolveProgram(client, config, input) {
         meta: {
             returned: programs.length,
             programs_scanned: collected.programsScanned,
-            upstream_requests_scanned: collected.requestsScanned
+            upstream_requests_scanned: collected.requestsScanned,
+            target_lookup_returned: numberField(readObject(targetLookup?.meta), "returned")
         }
     });
     rememberResolveProgram(config, input, payload);
@@ -3091,16 +3150,43 @@ function findRecentByType(client, config, input) {
 }
 async function findProgramsByTarget(client, config, input) {
     const warnings = [];
+    const budget = {
+        initial: input.upstream_request_budget,
+        remaining: input.upstream_request_budget
+    };
+    const sourceRequests = [];
+    const matches = [];
+    const directHandles = await collectDirectHandlePrograms(client, {
+        query: input.target_query,
+        platforms: input.platforms,
+        budget,
+        warnings,
+        source: "target_query_program_id_guess",
+        maxProgramIds: 1,
+        stopOnFirstMatch: true
+    });
+    sourceRequests.push(...directHandles.sourceRequests);
+    await appendProgramTargetMatches(client, input, budget, warnings, sourceRequests, matches, directHandles.programs.map((program) => toProgramCandidate(program, config.webBaseUrl)));
+    if (matches.length > 0 && input.match_mode === "smart") {
+        return programsByTargetResult(input, warnings, sourceRequests, matches, budget, {
+            source: "direct_program_handle_targets",
+            rankingScope: {
+                mode: "direct_program_handle",
+                possibly_incomplete: false
+            },
+            meta: {
+                returned: matches.length,
+                programs_scanned: directHandles.programsScanned,
+                target_lists_checked: sourceRequests.filter((request) => request.source === "program_targets").length
+            }
+        });
+    }
     if (input.use_api_search) {
         const directResult = await searchProgramsByTargetApi(client, config, input, warnings);
         if (directResult) {
             return directResult;
         }
     }
-    const budget = {
-        initial: input.upstream_request_budget,
-        remaining: input.upstream_request_budget
-    };
     const maxPages = clampLimit("max_pages", input.max_pages, MAX_FIND_PROGRAM_PAGES, warnings);
     const collected = await collectPrograms(client, {
         platforms: input.platforms,
@@ -3111,11 +3197,27 @@ async function findProgramsByTarget(client, config, input) {
         budget,
         warnings
     });
-    const sourceRequests = [...collected.sourceRequests];
-    const matches = [];
+    sourceRequests.push(...collected.sourceRequests);
     const candidates = collected.programs
         .map((program) => toProgramCandidate(program, config.webBaseUrl))
         .sort((left, right) => compareProgramCandidates(left, right, "best_hunt_value"));
+    await appendProgramTargetMatches(client, input, budget, warnings, sourceRequests, matches, candidates);
+    return programsByTargetResult(input, warnings, sourceRequests, matches, budget, {
+        source: "sampled_program_targets",
+        rankingScope: {
+            mode: "sampled",
+            max_pages_scanned_per_source: maxPages,
+            upstream_total_pages: collected.totalPagesBySource,
+            possibly_incomplete: isRankingPossiblyIncomplete(collected.totalPagesBySource, maxPages)
+        },
+        meta: {
+            returned: matches.length,
+            programs_scanned: directHandles.programsScanned + collected.programsScanned,
+            target_lists_checked: sourceRequests.filter((request) => request.source === "program_targets").length
+        }
+    });
+}
+async function appendProgramTargetMatches(client, input, budget, warnings, sourceRequests, matches, candidates) {
     for (const candidate of candidates) {
         if (matches.length >= input.max_results) {
             break;
@@ -3125,7 +3227,9 @@ async function findProgramsByTarget(client, config, input) {
             continue;
         }
         if (!tryConsumeBudget(budget)) {
-            addUniqueWarning(warnings, "Upstream request budget was exhausted before all candidate target lists could be checked.");
+            if (matches.length === 0) {
+                addUniqueWarning(warnings, "Upstream request budget was exhausted before all candidate target lists could be checked.");
+            }
             break;
         }
         const targetsApi = await client.getProgramTargets(programId);
@@ -3157,6 +3261,8 @@ async function findProgramsByTarget(client, config, input) {
             total_targets_checked: targets.length
         }));
     }
+}
+function programsByTargetResult(input, warnings, sourceRequests, matches, budget, options) {
     return stripUndefined({
         request_id: randomUUID(),
         source_requests: sourceRequests,
@@ -3166,7 +3272,7 @@ async function findProgramsByTarget(client, config, input) {
             match_mode: input.match_mode,
             platforms: input.platforms.length > 0 ? input.platforms : undefined,
             tags: input.tags.length > 0 ? input.tags : undefined,
-            source: "sampled_program_targets",
+            source: options.source,
             include_out_of_scope: input.include_out_of_scope,
             include_ineligible: input.include_ineligible,
             target_list_mode: input.target_list_mode
@@ -3177,63 +3283,79 @@ async function findProgramsByTarget(client, config, input) {
             used: budget.initial - budget.remaining,
             remaining: budget.remaining
         },
-        ranking_scope: {
-            mode: "sampled",
-            max_pages_scanned_per_source: maxPages,
-            upstream_total_pages: collected.totalPagesBySource,
-            possibly_incomplete: isRankingPossiblyIncomplete(collected.totalPagesBySource, maxPages)
-        },
-        meta: {
-            returned: matches.length,
-            programs_scanned: collected.programsScanned,
-            target_lists_checked: sourceRequests.filter((request) => request.source === "program_targets").length
-        }
+        ranking_scope: options.rankingScope,
+        meta: options.meta
     });
 }
 async function searchProgramsByTargetApi(client, config, input, warnings) {
-    let api;
-    try {
-        api = await client.searchTargets({
-            q: input.target_query,
-            match_mode: upstreamTargetMatchMode(input.match_mode),
-            platforms: input.platforms,
-            tags: input.tags,
-            include_out_of_scope: input.include_out_of_scope,
-            include_ineligible: input.include_ineligible,
-            page: 1,
-            page_size: Math.max(input.max_results * input.max_targets_per_program, input.max_results)
-        });
-    }
-    catch (error) {
-        if (error instanceof BBRadarApiError && (error.status === 404 || error.status === 405)) {
-            warnings.push("Direct target search API is unavailable; fell back to sampled program target lists.");
-            return undefined;
-        }
-        throw error;
-    }
-    const data = readObject(api.data);
-    const rawMatches = readTargetSearchRows(data);
+    const searchQueries = targetApiSearchQueries(input.target_query);
     const grouped = new Map();
-    for (const row of rawMatches) {
-        const program = addProgramResourceLinks(sanitizeProgram(readObject(row.program) ?? readObject(readObject(row.target)?.program) ?? row, config.webBaseUrl));
-        const programId = stringField(program, "id") ?? stringField(row, "program_id");
-        const target = sanitizeTarget(readObject(row.target) ?? row);
-        if (!programId || !targetIdentifier(target)) {
-            continue;
+    const sourceRequests = [];
+    let rawMatchesScanned = 0;
+    let lastMeta;
+    for (const searchQuery of searchQueries) {
+        let api;
+        try {
+            api = await client.searchTargets({
+                q: searchQuery,
+                match_mode: upstreamTargetMatchMode(input.match_mode),
+                platforms: input.platforms,
+                tags: input.tags,
+                include_out_of_scope: input.include_out_of_scope,
+                include_ineligible: input.include_ineligible,
+                page: 1,
+                page_size: Math.max(input.max_results * input.max_targets_per_program, input.max_results)
+            });
         }
-        if (!targetHasAllowedScope(target, {
-            include_out_of_scope: input.include_out_of_scope,
-            include_ineligible: input.include_ineligible,
-            strict_scope_filter: false
-        })) {
-            continue;
+        catch (error) {
+            if (error instanceof BBRadarApiError && (error.status === 404 || error.status === 405)) {
+                warnings.push("Direct target search API is unavailable; fell back to sampled program target lists.");
+                return undefined;
+            }
+            throw error;
         }
-        if (!targetMatchesQuery(target, input.target_query, input.match_mode)) {
-            continue;
+        const data = readObject(api.data);
+        const rawMatches = readTargetSearchRows(data);
+        rawMatchesScanned += rawMatches.length;
+        lastMeta = readObject(sanitizeJson(data?.meta)) ?? lastMeta;
+        sourceRequests.push({
+            source: "target_search",
+            query: searchQuery,
+            api_match_mode: upstreamTargetMatchMode(input.match_mode),
+            request_id: api.requestId,
+            upstream_request_id: api.upstreamRequestId,
+            ...apiSourceMetadata(api)
+        });
+        for (const row of rawMatches) {
+            const rowProgram = sanitizeProgram(readObject(row.program) ?? row, config.webBaseUrl);
+            const rowProgramId = stringField(rowProgram, "id") ?? stringField(row, "program_id");
+            const targets = targetSearchRowTargets(row);
+            for (const targetSource of targets) {
+                const target = sanitizeTarget(targetSource);
+                const nestedProgram = sanitizeProgram(readObject(targetSource.program), config.webBaseUrl);
+                const program = stringField(nestedProgram, "id") ? nestedProgram : rowProgram;
+                const programId = stringField(program, "id") ?? rowProgramId ?? stringField(targetSource, "program_id");
+                if (!programId || !targetIdentifier(target)) {
+                    continue;
+                }
+                if (!targetHasAllowedScope(target, {
+                    include_out_of_scope: input.include_out_of_scope,
+                    include_ineligible: input.include_ineligible,
+                    strict_scope_filter: false
+                })) {
+                    continue;
+                }
+                if (!targetMatchesQuery(target, input.target_query, input.match_mode)) {
+                    continue;
+                }
+                const existing = grouped.get(programId) ?? { program: addProgramResourceLinks({ ...program, id: programId }), targets: [] };
+                existing.targets.push(target);
+                grouped.set(programId, existing);
+            }
+        }
+        if (grouped.size >= input.max_results) {
+            break;
         }
-        const existing = grouped.get(programId) ?? { program: { ...program, id: programId }, targets: [] };
-        existing.targets.push(target);
-        grouped.set(programId, existing);
     }
     const matches = [...grouped.values()].slice(0, input.max_results).map((entry) => stripUndefined({
         program: formatProgram(entry.program, "compact"),
@@ -3245,21 +3367,13 @@ async function searchProgramsByTargetApi(client, config, input, warnings) {
         warnings.push("Direct target search returned no smart matches; fell back to sampled program target lists.");
         return undefined;
     }
-    const sanitizedMeta = readObject(sanitizeJson(data?.meta));
     return stripUndefined({
         request_id: randomUUID(),
-        source_requests: [
-            {
-                source: "target_search",
-                api_match_mode: upstreamTargetMatchMode(input.match_mode),
-                request_id: api.requestId,
-                upstream_request_id: api.upstreamRequestId,
-                ...apiSourceMetadata(api)
-            }
-        ],
+        source_requests: sourceRequests,
         warnings: warnings.length > 0 ? warnings : undefined,
         filters: {
             target_query: input.target_query,
+            target_search_queries: searchQueries.length > 1 ? searchQueries : undefined,
             match_mode: input.match_mode,
             platforms: input.platforms.length > 0 ? input.platforms : undefined,
             tags: input.tags.length > 0 ? input.tags : undefined,
@@ -3271,19 +3385,52 @@ async function searchProgramsByTargetApi(client, config, input, warnings) {
         matches,
         programs: matches.map((match) => readObject(match.program)).filter((program) => program !== undefined),
         meta: stripUndefined({
-            ...(sanitizedMeta ?? {}),
+            ...(lastMeta ?? {}),
             returned: matches.length,
-            target_search_rows_scanned: rawMatches.length
+            target_search_rows_scanned: rawMatchesScanned
         })
     });
 }
 function readTargetSearchRows(data) {
-    return [data?.results, data?.matches, data?.targets]
+    return [data?.results, data?.matches, data?.programs, data?.targets]
         .map(readArray)
         .find((rows) => rows.length > 0)
         ?.map((row) => readObject(row))
         .filter((row) => row !== undefined) ?? [];
 }
+function targetSearchRowTargets(row) {
+    const directTarget = readObject(row.target);
+    const arrays = [
+        row.targets,
+        row.matched_targets,
+        row.matching_targets,
+        row.target_matches,
+        row.scope
+    ]
+        .flatMap(readArray)
+        .map(targetSearchEntryToTarget)
+        .filter((target) => target !== undefined);
+    if (directTarget) {
+        return [directTarget, ...arrays];
+    }
+    if (arrays.length > 0) {
+        return arrays;
+    }
+    if (targetIdentifier(row)) {
+        return [row];
+    }
+    return [];
+}
+function targetSearchEntryToTarget(entry) {
+    if (typeof entry === "string") {
+        return { identifier: entry };
+    }
+    const object = readObject(entry);
+    if (!object) {
+        return undefined;
+    }
+    return readObject(object.target) ?? object;
+}
 function rewardThresholdFilters(minReward, mode) {
     return {
         min_bounty_min: minReward !== undefined && mode === "min_at_least" ? minReward : undefined,
@@ -5451,9 +5598,27 @@ async function collectProgramsForResolution(client, options) {
     const collections = [];
     const queryCollections = [];
     const queries = options.searchQueries.length > 0 ? options.searchQueries : [undefined];
+    const primaryDirectProgramIds = new Set(directProgramIdCandidates(options.query, options.platforms).slice(0, 1));
+    if (primaryDirectProgramIds.size > 0 && options.budget.remaining > 0) {
+        const primaryDirectHandles = await collectDirectHandlePrograms(client, {
+            query: options.query,
+            platforms: options.platforms,
+            budget: options.budget,
+            warnings: options.warnings,
+            source: "program_id_handle_guess",
+            maxProgramIds: 1,
+            stopOnFirstMatch: true
+        });
+        if (primaryDirectHandles.programs.length > 0 || primaryDirectHandles.requestsScanned > 0) {
+            collections.push(primaryDirectHandles);
+        }
+        if (primaryDirectHandles.programs.length > 0 && options.isHighConfidenceMatch?.(mergeProgramCollections(collections).programs)) {
+            return mergeProgramCollections(collections);
+        }
+    }
     for (const search of queries) {
         if (options.budget.remaining <= 0) {
-            addUniqueWarning(options.warnings, "Upstream request budget was exhausted before all program name search variants could be checked.");
+            addUniqueWarning(options.warnings, "Program name search stopped at the request budget; pass a higher upstream_request_budget for a deeper resolution attempt.");
             break;
         }
         const collection = await collectPrograms(client, {
@@ -5472,6 +5637,23 @@ async function collectProgramsForResolution(client, options) {
             return mergeProgramCollections(collections);
         }
     }
+    if (options.budget.remaining > 0) {
+        const directHandles = await collectDirectHandlePrograms(client, {
+            query: options.query,
+            platforms: options.platforms,
+            budget: options.budget,
+            warnings: options.warnings,
+            source: "program_id_handle_guess",
+            skipProgramIds: primaryDirectProgramIds,
+            stopOnFirstMatch: true
+        });
+        if (directHandles.programs.length > 0 || directHandles.requestsScanned > 0) {
+            collections.push(directHandles);
+        }
+        if (directHandles.programs.length > 0 && options.isHighConfidenceMatch?.(mergeProgramCollections(collections).programs)) {
+            return mergeProgramCollections(collections);
+        }
+    }
     if (options.max_pages > 1) {
         const search = bestResolutionDeepSearch(queryCollections, options.scorePrograms) ?? queries[0];
         if (options.budget.remaining <= 0) {
@@ -5532,6 +5714,152 @@ function mergeProgramCollections(collections) {
         totalPagesBySource
     };
 }
+async function collectDirectHandlePrograms(client, options) {
+    const programIds = directProgramIdCandidates(options.query, options.platforms)
+        .filter((programId) => !options.skipProgramIds?.has(programId))
+        .slice(0, options.maxProgramIds ?? MAX_DIRECT_HANDLE_RESOLUTION_REQUESTS);
+    const programs = [];
+    const sourceRequests = [];
+    let requestsScanned = 0;
+    for (const programId of programIds) {
+        if (!tryConsumeBudget(options.budget)) {
+            break;
+        }
+        requestsScanned += 1;
+        try {
+            const api = await client.getProgram(programId);
+            programs.push(api.data);
+            sourceRequests.push({
+                source: options.source,
+                program_id: programId,
+                request_id: api.requestId,
+                upstream_request_id: api.upstreamRequestId,
+                ...apiSourceMetadata(api)
+            });
+            if (options.stopOnFirstMatch) {
+                break;
+            }
+        }
+        catch (error) {
+            if (error instanceof BBRadarApiError && error.status === 404) {
+                sourceRequests.push({
+                    source: options.source,
+                    endpoint: "program_detail",
+                    program_id: programId,
+                    request_id: error.requestId,
+                    upstream_request_id: error.upstreamRequestId,
+                    status: error.status
+                });
+                if (!tryConsumeBudget(options.budget)) {
+                    break;
+                }
+                requestsScanned += 1;
+                try {
+                    const targetsApi = await client.getProgramTargets(programId);
+                    const targetsData = readObject(targetsApi.data);
+                    const targets = readArray(targetsData?.targets).map(sanitizeTarget);
+                    if (targets.length > 0) {
+                        programs.push(syntheticProgramFromProgramId(programId, targets));
+                    }
+                    sourceRequests.push({
+                        source: options.source,
+                        endpoint: "program_targets",
+                        program_id: programId,
+                        request_id: targetsApi.requestId,
+                        upstream_request_id: targetsApi.upstreamRequestId,
+                        ...apiSourceMetadata(targetsApi)
+                    });
+                    if (targets.length > 0 && options.stopOnFirstMatch) {
+                        break;
+                    }
+                }
+                catch (targetError) {
+                    if (targetError instanceof BBRadarApiError && targetError.status === 404) {
+                        sourceRequests.push({
+                            source: options.source,
+                            endpoint: "program_targets",
+                            program_id: programId,
+                            request_id: targetError.requestId,
+                            upstream_request_id: targetError.upstreamRequestId,
+                            status: targetError.status
+                        });
+                        continue;
+                    }
+                    throw targetError;
+                }
+                continue;
+            }
+            throw error;
+        }
+    }
+    return {
+        programs,
+        sourceRequests,
+        requestsScanned,
+        programsScanned: programs.length,
+        totalPagesBySource: programs.length > 0 ? { [options.source]: 1 } : {}
+    };
+}
+function syntheticProgramFromProgramId(programId, targets) {
+    const separatorIndex = programId.indexOf(":");
+    const platform = separatorIndex >= 0 ? programId.slice(0, separatorIndex) : undefined;
+    const handle = separatorIndex >= 0 ? programId.slice(separatorIndex + 1) : programId;
+    const scopeTags = uniqueStrings(targets.flatMap((target) => readStringArrayField(target, "scope_tags")));
+    return stripUndefined({
+        id: programId,
+        handle,
+        name: titleizeProgramHandle(handle),
+        platform,
+        scope_tags: scopeTags,
+        target_counts: {
+            total: targets.length,
+            in_scope: targets.filter((target) => target.in_scope === true).length,
+            out_of_scope: targets.filter((target) => target.in_scope === false).length,
+            eligible_for_bounty: targets.filter((target) => target.eligible_for_bounty === true).length,
+            wildcard: targets.filter(targetIsWildcard).length
+        }
+    });
+}
+function titleizeProgramHandle(handle) {
+    return handle
+        .split(/[-_.\s]+/)
+        .filter(Boolean)
+        .map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+function directProgramIdCandidates(query, platforms) {
+    const platformGuesses = (platforms.length > 0 ? platforms : PROGRAM_ID_PLATFORM_GUESSES).map(canonicalProgramIdPlatform);
+    const handles = directProgramHandleVariants(query);
+    return uniqueStrings(platformGuesses.flatMap((platform) => handles.map((handle) => `${platform}:${handle}`))).slice(0, MAX_DIRECT_HANDLE_RESOLUTION_REQUESTS);
+}
+function canonicalProgramIdPlatform(platform) {
+    const normalized = normalizeTag(platform).replace(/[^a-z0-9]/g, "");
+    const knownPlatforms = {
+        hackerone: "HackerOne",
+        bugcrowd: "Bugcrowd",
+        intigriti: "Intigriti",
+        hackenproof: "HackenProof",
+        yeswehack: "YesWeHack",
+        cantina: "Cantina",
+        code4rena: "Code4rena",
+        immunefi: "Immunefi"
+    };
+    return knownPlatforms[normalized] ?? platform.trim();
+}
+function directProgramHandleVariants(query) {
+    const handleText = query.includes(":") ? query.slice(query.indexOf(":") + 1) : query;
+    const normalized = normalizeTargetIdentifierForMatch(handleText);
+    const dashed = normalized.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    const compact = dashed.replace(/-/g, "");
+    const tokens = [...meaningfulProgramQueryTokens(handleText)];
+    return uniqueStrings([
+        ...targetBrandTokens(handleText),
+        dashed,
+        compact,
+        tokens.join("-"),
+        tokens.join("")
+    ]).filter((handle) => /^[a-z0-9][a-z0-9_.-]{3,100}$/i.test(handle));
+}
 async function collectProgramSources(client, sources, options) {
     const pages = [];
     await mapWithConcurrency(sources.map((source, sourceIndex) => ({ source, sourceIndex })), PROGRAM_COLLECTION_CONCURRENCY, async ({ source, sourceIndex }) => {
@@ -6299,7 +6627,7 @@ function targetMatchesQuery(target, query, mode) {
     if (mode === "wildcard") {
         return profile.values.some((value) => queryValues.some((queryValue) => targetWildcardMatch(value, queryValue)));
     }
-    const containsMatch = profile.values.some((value) => queryValues.some((queryValue) => value.includes(queryValue) || queryValue.includes(value)));
+    const containsMatch = profile.values.some((value) => queryValues.some((queryValue) => targetContainsMatch(value, queryValue)));
     if (mode === "contains") {
         return containsMatch;
     }
@@ -6345,6 +6673,19 @@ function targetSearchProfile(target) {
 function targetQueryVariants(query) {
     return targetStringVariants(query);
 }
+function targetApiSearchQueries(query) {
+    const normalized = normalizeTargetIdentifierForMatch(query);
+    const brandDomains = targetBrandTokens(query).flatMap((token) => [`${token}.com`, `*.${token}.com`]);
+    return uniqueStrings([
+        normalized,
+        ...targetQueryVariants(query),
+        ...brandDomains
+    ].filter((entry) => entry !== undefined && entry.length >= 2)).slice(0, MAX_RESOLVE_SEARCH_QUERIES);
+}
+function queryLooksLikeTargetIdentifier(query) {
+    const normalized = normalizeTargetIdentifierForMatch(query);
+    return /[./*:]/.test(normalized);
+}
 function targetStringVariants(value) {
     const normalized = normalizeTargetIdentifierForMatch(value);
     if (!normalized) {
@@ -6373,6 +6714,15 @@ function targetSuffixMatch(value, query) {
 function targetWildcardMatch(value, query) {
     return wildcardTargetMatch(query, value) || wildcardTargetMatch(value, query);
 }
+function targetContainsMatch(value, query) {
+    if (value.includes(query)) {
+        return true;
+    }
+    return targetValueCanContainQuery(value) && query.includes(value);
+}
+function targetValueCanContainQuery(value) {
+    return value.includes(".") || value.includes("/") || value.includes("*") || value.includes(":");
+}
 function targetTokensMatch(targetTokens, query) {
     const queryTokens = [...targetTokenSet(query)];
     if (queryTokens.length === 0) {
@@ -6389,6 +6739,17 @@ function targetTokenSet(value) {
     const meaningfulTokens = tokens.filter((token) => !TARGET_QUERY_STOP_WORDS.has(token));
     return new Set(meaningfulTokens.length > 0 ? meaningfulTokens : tokens);
 }
+function targetBrandTokens(value) {
+    const normalized = stripLeadingTargetWildcard(normalizeTargetIdentifierForMatch(value));
+    const host = targetHostVariant(normalized) ?? (normalized.includes(".") && !normalized.includes("/") ? normalized : undefined);
+    const hostBrand = host
+        ?.split(".")
+        .filter(Boolean)
+        .slice(-2, -1)
+        .find((token) => token.length >= 3 && !TARGET_QUERY_STOP_WORDS.has(token));
+    const textTokens = [...targetTokenSet(normalized)].filter((token) => token.length >= 4);
+    return uniqueStrings([hostBrand, ...textTokens].filter((entry) => entry !== undefined));
+}
 function normalizeTargetIdentifierForMatch(value) {
     const normalized = value
         .trim()