Skip to content

fix(api): validate discovery routes against the schemas their spec publishes #10225

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
loopover-orb merged 1 commit into from
Jul 31, 2026
Merged

fix(api): validate discovery routes against the schemas their spec publishes #10225

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 107 additions & 97 deletions apps/loopover-ui/public/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17130,6 +17130,109 @@
"funnel",
"note"
]
},
"FindOpportunitiesRequest": {
"type": "object",
"properties": {
"targets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"owner": {
"type": "string",
"minLength": 1,
"maxLength": 39
},
"repo": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"owner",
"repo"
]
},
"maxItems": 25
},
"searchQuery": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"goalSpec": {
"type": "object",
"properties": {
"lane": {
"type": "string",
"minLength": 1
},
"minRankScore": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"languages": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 30
},
"maxItems": 20
}
}
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50
}
}
},
"IssueRagRetrieveRequest": {
"type": "object",
"properties": {
"owner": {
"type": "string",
"maxLength": 39,
"minLength": 1
},
"repo": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"title": {
"type": "string",
"maxLength": 300,
"minLength": 1
},
"body": {
"type": "string",
"maxLength": 20000
},
"labels": {
"type": "array",
"items": {
"type": "string",
"maxLength": 100
},
"maxItems": 50
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 12
}
},
"required": [
"owner",
"repo",
"title"
]
}
},
"parameters": {},
Expand Down Expand Up @@ -23605,65 +23708,7 @@
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"targets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"owner": {
"type": "string",
"minLength": 1,
"maxLength": 39
},
"repo": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"owner",
"repo"
]
},
"maxItems": 25
},
"searchQuery": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"goalSpec": {
"type": "object",
"properties": {
"lane": {
"type": "string",
"minLength": 1
},
"minRankScore": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"languages": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 30
},
"maxItems": 20
}
}
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50
}
}
"$ref": "#/components/schemas/FindOpportunitiesRequest"
}
}
}
Expand Down Expand Up @@ -23700,7 +23745,8 @@
"operationId": "postOpportunitiesFind",
"tags": [
"Discovery"
]
],
"description": "Rank contribution opportunities across the given targets or search query. At least one of `targets` (non-empty) or `searchQuery` is required — JSON Schema cannot express that cross-field rule, so an empty body is rejected with reason `targets_or_search_query_required` (#10040)."
}
},
"/v1/issue-rag/retrieve": {
Expand All @@ -23710,43 +23756,7 @@
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"owner": {
"type": "string",
"maxLength": 39
},
"repo": {
"type": "string",
"maxLength": 100
},
"title": {
"type": "string",
"maxLength": 300
},
"body": {
"type": "string",
"maxLength": 20000
},
"labels": {
"type": "array",
"items": {
"type": "string",
"maxLength": 100
},
"maxItems": 50
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 12
}
},
"required": [
"owner",
"repo",
"title"
]
"$ref": "#/components/schemas/IssueRagRetrieveRequest"
}
}
}
Expand Down
23 changes: 18 additions & 5 deletions packages/loopover-contract/src/api-schemas.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import { z } from "zod";
import { checkBeforeStartSchema, slopRiskSchema, validateFocusManifestSchema, validateLinkedIssueSchema } from "./api-requests.js";
import { AGENT_ACTION_CLASSES, AUTONOMY_LEVELS } from "./enums.js";
import { MAX_CONTRIBUTOR_OPEN_ITEM_CAP, MAX_PRIORITY_ELIGIBILITY_WINDOW_MINUTES, MAX_REVIEW_NAG_COOLDOWN_DAYS } from "./limits.js";
import { FindOpportunitiesInput, RetrieveIssueContextInput } from "./tools/local-branch.js";

export const FindingSchema = z
.object({
Expand Down Expand Up @@ -433,6 +434,7 @@ export const RepositorySettingsSchema = z
autoProjectMilestoneMatchBackend: z.enum(["github", "linear"]).optional(),
gatePack: z.enum(["gittensor", "oss-anti-slop"]),
linkedIssueGateMode: z.enum(["off", "advisory", "block"]),
linkedIssueMaintainerExempt: z.boolean().nullable().optional(),
duplicatePrGateMode: z.enum(["off", "advisory", "block"]),
qualityGateMode: z.enum(["off", "advisory", "block"]),
qualityGateMinScore: z.number().nullable().optional(),
Expand Down Expand Up @@ -1053,11 +1055,14 @@ export const ScoreBreakdownResponseSchema = z
highestLeverageLever: z.unknown().optional(),
});

// #9310 — request/response schemas for the two discovery routes below, mirroring the MCP tools'
// own Zod shapes verbatim (src/mcp/server.ts's findOpportunitiesShape/issueRagShape, and
// FindOpportunitiesOutput/RetrieveIssueContextOutput in @loopover/contract) so the OpenAPI contract
// can't silently drift from what the
// MCP tools actually validate.
/**
* Request body for POST /v1/opportunities/find. Field-level parity with `FindOpportunitiesInput` in
* @loopover/contract (the `loopover_find_opportunities` MCP tool `inputSchema`) — #10040. Re-wrapped
* through the local `z.object` so `.openapi(...)` lands on the OpenAPI-extended zod, same pattern as
* `CheckBeforeStartRequestSchema`.
*/
export const FindOpportunitiesRequestSchema = z.object(FindOpportunitiesInput.shape);

export const FindOpportunitiesResponseSchema = z
.object({
status: z.string().optional(),
Expand Down Expand Up @@ -1093,6 +1098,12 @@ export const FindOpportunitiesResponseSchema = z
.optional(),
});

/**
* Request body for POST /v1/issue-rag/retrieve. Field-level parity with `RetrieveIssueContextInput` in
* @loopover/contract (the `loopover_retrieve_issue_context` MCP tool `inputSchema`) — #10040.
*/
export const IssueRagRetrieveRequestSchema = z.object(RetrieveIssueContextInput.shape);

export const IssueRagRetrieveResponseSchema = z
.object({
status: z.string().optional(),
Expand Down Expand Up @@ -2301,12 +2312,14 @@ export const CLI_PARAMETERISED_RESPONSE_SCHEMAS = {
* live in @loopover/contract/api-requests.
*/
export const CLI_REQUEST_SCHEMAS = {
"POST /v1/issue-rag/retrieve": IssueRagRetrieveRequestSchema,
"POST /v1/lint/boundary-tests": SuggestBoundaryTestsRequestSchema,
"POST /v1/lint/improvement-potential": CheckImprovementPotentialRequestSchema,
"POST /v1/lint/issue-slop": CheckIssueSlopRequestSchema,
"POST /v1/lint/open-pr-pressure": SimulateOpenPrPressureRequestSchema,
"POST /v1/lint/pr-text": LintPrTextRequestSchema,
"POST /v1/lint/slop-risk": CheckSlopRiskRequestSchema,
"POST /v1/opportunities/find": FindOpportunitiesRequestSchema,
"POST /v1/repos/{owner}/{repo}/agent/pending-actions": ProposeActionRequestSchema,
"POST /v1/repos/{owner}/{repo}/check-before-start": CheckBeforeStartRequestSchema,
"POST /v1/repos/{owner}/{repo}/validate-linked-issue": ValidateLinkedIssueRequestSchema,
Expand Down
8 changes: 5 additions & 3 deletions packages/loopover-contract/src/tools/local-branch.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -527,9 +527,11 @@ export const findOpportunitiesTool = defineTool({

/** Same: the remote copy carried the bounds, the stdio copy carried none. */
export const RetrieveIssueContextInput = z.object({
owner: z.string().max(39),
repo: z.string().max(100),
title: z.string().max(PREFLIGHT_LIMITS.titleChars),
// #10040: `.min(1)` matches `ownerRepoInput` and the hand-rolled `owner_and_repo_required` /
// `title_required` checks — the catalog previously published empty strings as valid.
owner: z.string().min(1).max(39),
repo: z.string().min(1).max(100),
title: z.string().min(1).max(PREFLIGHT_LIMITS.titleChars),
body: z.string().max(PREFLIGHT_LIMITS.bodyChars).optional(),
labels: z.array(z.string().max(PREFLIGHT_LIMITS.labelChars)).max(PREFLIGHT_LIMITS.labels).optional(),
topK: z.number().int().min(1).max(12).optional(),
Expand Down
23 changes: 18 additions & 5 deletions scripts/gen-contract-api-schemas.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -447,13 +447,26 @@ const CONTRACT_SRC = "packages/loopover-contract/src";
* output, broken build. Reading the directory means a constant can move, or a new module can appear,
* without this script knowing anything about it.
*
* `index.ts` is excluded because it re-exports the generated file (importing it back would be a cycle),
* and the generated file itself because a schema cannot import its own copy.
* One level of subdirectories is walked too (#10040): `tools/**` holds most of the package's zod
* declarations (`FindOpportunitiesInput`, `RetrieveIssueContextInput`, ...), and a scan that only saw
* `src/*.ts` would silently miss every one of them, the same "valid output, broken build" failure the
* top-level case above already guards against.
*
* `index.ts` is excluded at both levels because it re-exports the generated file (importing it back
* would be a cycle), and the generated file itself because a schema cannot import its own copy.
*/
export function contractModuleExports(): Map<string, ReadonlySet<string>> {
const modules = listModules(CONTRACT_SRC)
.filter((file) => file.endsWith(".ts") && file !== "index.ts" && file !== "api-schemas.ts")
.sort();
const files: string[] = [];
for (const entry of listModules(CONTRACT_SRC)) {
if (entry.endsWith(".ts")) {
files.push(entry);
continue;
}
for (const nested of listModules(`${CONTRACT_SRC}/${entry}`)) {
if (nested.endsWith(".ts")) files.push(`${entry}/${nested}`);
}
}
const modules = files.filter((file) => file !== "index.ts" && !file.endsWith("/index.ts") && file !== "api-schemas.ts").sort();
return new Map(modules.map((file) => [`./${file.replace(/\.ts$/, ".js")}`, new Set(exportedNames(readModule(`${CONTRACT_SRC}/${file}`)))]));
}

Expand Down
19 changes: 17 additions & 2 deletions src/api/routes.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,7 @@ import {
} from "../services/control-panel-roles";
import { runFindOpportunities, validateFindOpportunitiesInput, type FindOpportunitiesInput } from "../mcp/find-opportunities";
import { runIssueRagRetrieval, validateIssueRagInput, type IssueRagInput } from "../mcp/issue-rag";
import { FindOpportunitiesRequestSchema, IssueRagRetrieveRequestSchema } from "../openapi/schemas";
import { buildBoundaryTestGenerationFinding, buildBoundaryTestGenerationSpec } from "../signals/boundary-test-generation";
import { buildTestEvidenceReport } from "../signals/test-evidence";
import { buildStructuralImprovementAssessment } from "../signals/improvement";
Expand Down Expand Up @@ -3596,7 +3597,13 @@ export function createApp() {
/* v8 ignore next -- Protected middleware rejects unauthenticated private routes before route-specific guards. */
if (!identity) return c.json({ error: "unauthorized" }, 401);
const body = await c.req.json().catch(() => null);
const parsed = validateFindOpportunitiesInput((body ?? {}) as FindOpportunitiesInput);
// #10040: same zod object the OpenAPI document publishes — refuse before the hand-rolled
// cross-field / normalisation pass, and keep the existing invalid_request body shape.
const schemaParsed = FindOpportunitiesRequestSchema.safeParse(body ?? {});
if (!schemaParsed.success) {
return c.json({ status: "invalid_request", ranked: [], totalCandidates: 0, reason: "invalid_body" }, 400);
}
const parsed = validateFindOpportunitiesInput(schemaParsed.data as FindOpportunitiesInput);
if (!parsed.ok) {
return c.json({ status: "invalid_request", ranked: [], totalCandidates: 0, reason: parsed.reason }, 400);
}
Expand All @@ -3621,7 +3628,15 @@ export function createApp() {
/* v8 ignore next -- Protected middleware rejects unauthenticated private routes before route-specific guards. */
if (!identity) return c.json({ error: "unauthorized" }, 401);
const body = await c.req.json().catch(() => null);
const parsed = validateIssueRagInput((body ?? {}) as IssueRagInput);
// #10040: same zod object the OpenAPI document publishes — refuse before the hand-rolled pass.
const schemaParsed = IssueRagRetrieveRequestSchema.safeParse(body ?? {});
if (!schemaParsed.success) {
return c.json(
{ status: "invalid_request", repoFullName: "", reason: "invalid_body", telemetry: { attempted: false, injected: false, retrievedPaths: [] } },
400,
);
}
const parsed = validateIssueRagInput(schemaParsed.data as IssueRagInput);
if (!parsed.ok) {
return c.json({ status: "invalid_request", repoFullName: "", reason: parsed.reason, telemetry: { attempted: false, injected: false, retrievedPaths: [] } }, 400);
}
Expand Down
Loading
Loading