fix: reject ambiguous module routes
A module can register both `GET /events/:id` and `GET /events/new`. Driven through the pinned router, `/events/new` reached the parameter handler under `demo.events.read` when the parameter route registered first, and the static handler under `demo.events.create` when it registered second. Nothing rejected the pair, so declaration order decided which permission guarded the path. That is a permission policy, not a routing preference, and it must not be inferred from array position. Two routes of one module now overlap when they share a method and a segment count and, at every position, either both segments are the same static literal or at least one is a parameter. Under this grammar — static literals or `:name` parameters, no wildcard, regex, optional, or catch-all — that is exactly "some concrete request path matches both". `moduleRoutesOverlap` implements it in the contracts package, where path semantics already live and Hono cannot reach. Core checks it during staged registration, after the existing duplicate check, so identical shapes (including paths differing only in parameter name) keep returning MODULE_ROUTE_DUPLICATE and a genuine intersection returns the new MODULE_ROUTE_OVERLAP. The rejected module publishes none of its staged routes or capabilities, no start hook runs, and no listener binds. Rejection rather than a specificity rule: ranking static above parameter would still silently pick which permission applies. Disjoint routes keep their order; different methods, different segment counts, and the same local path in two different modules (each has its own platform-owned mount prefix) all remain legal. The same requests also pinned down what handlers actually receive. Route declarations are validated; route *parameters* are not, and the two are unrelated. A single encoded segment arrives decoded as `/../admin`, `a\b`, an embedded NUL, CR/LF, `1; drop`, or non-ASCII text — none of which any declared path could contain. The contract now says so explicitly: decoded values are untrusted, module-owned input that a handler must validate against its own exact domain grammar before any database, filesystem, command, or identifier use, and re-encoding is not a substitute. No generic validator, path-normalization layer, or route field was added, because module parameters are module-owned domain types and one platform-wide pattern would either reject legitimate values or approve meaningless ones. Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
ekklesia
co-authored by
Claude Opus 5
Claude Opus 5
parent
4a34a8203c
commit
800ecfdb92
@@ -562,6 +562,141 @@ describe("module HTTP routes", () => {
|
||||
expect(runtimeIssueCodes(error)).toEqual(["MODULE_ROUTE_DUPLICATE"]);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["parameter registered first", "/events/:id", "/events/new"],
|
||||
["static registered first", "/events/new", "/events/:id"],
|
||||
["multi-position, parameter first", "/events/:id/edit", "/events/new/:action"],
|
||||
["multi-position, static first", "/events/new/:action", "/events/:id/edit"],
|
||||
["parameters on both sides", "/a/:left/c", "/a/b/:right"],
|
||||
])("rejects routes that can both match one request path (%s) regardless of registration order", async (_label, firstPath, secondPath) => {
|
||||
const modulesDirectory = await createModulesDirectory();
|
||||
// Deliberately *different* permissions: the defect this rejects is that whichever route
|
||||
// registered first would decide which permission governs the ambiguous path.
|
||||
await createRuntimeModule(modulesDirectory, "overlap", {
|
||||
manifest: manifestFor("overlap", {
|
||||
permissions: [
|
||||
permissionDeclaration("overlap.events.read"),
|
||||
permissionDeclaration("overlap.events.create"),
|
||||
],
|
||||
}),
|
||||
serverSource: `export default {
|
||||
id: "overlap", version: "0.1.0",
|
||||
register({ http }) {
|
||||
http.route({ method: "GET", path: "${firstPath}", permission: "overlap.events.read", maxBodyBytes: 1024, handler: ${noopHandlerSource()} });
|
||||
http.route({ method: "GET", path: "${secondPath}", permission: "overlap.events.create", maxBodyBytes: 1024, handler: ${noopHandlerSource()} });
|
||||
}
|
||||
};`,
|
||||
});
|
||||
|
||||
const error = await captureRuntimeError(modulesDirectory);
|
||||
expect(runtimeIssueCodes(error)).toEqual(["MODULE_ROUTE_OVERLAP"]);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["two different static literals", "/events/new", "/events/archive"],
|
||||
["different segment counts", "/events/:id", "/events/:id/edit"],
|
||||
["a different static prefix", "/events/:id", "/people/:id"],
|
||||
["module root against a one-segment path", "/", "/events"],
|
||||
])("still allows disjoint routes (%s) and preserves their registration order", async (_label, firstPath, secondPath) => {
|
||||
const modulesDirectory = await createModulesDirectory();
|
||||
await createRuntimeModule(modulesDirectory, "disjoint", {
|
||||
manifest: manifestFor("disjoint", {
|
||||
permissions: [permissionDeclaration("disjoint.events.read")],
|
||||
}),
|
||||
serverSource: `export default {
|
||||
id: "disjoint", version: "0.1.0",
|
||||
register({ http }) {
|
||||
http.route({ method: "GET", path: "${firstPath}", permission: "disjoint.events.read", maxBodyBytes: 1024, handler: ${noopHandlerSource()} });
|
||||
http.route({ method: "GET", path: "${secondPath}", permission: "disjoint.events.read", maxBodyBytes: 1024, handler: ${noopHandlerSource()} });
|
||||
}
|
||||
};`,
|
||||
});
|
||||
|
||||
const runtime = await startModuleRuntime({
|
||||
moduleSdkVersion: "0.1.0",
|
||||
modulesDirectory,
|
||||
platformVersion: "0.1.0",
|
||||
services: fakeModuleRuntimeServices(),
|
||||
});
|
||||
expect(runtime.routes.map((route) => route.path)).toEqual([firstPath, secondPath]);
|
||||
await runtime.stop();
|
||||
});
|
||||
|
||||
it("allows the same overlapping local path under different methods", async () => {
|
||||
const modulesDirectory = await createModulesDirectory();
|
||||
await createRuntimeModule(modulesDirectory, "methods", {
|
||||
manifest: manifestFor("methods", {
|
||||
permissions: [permissionDeclaration("methods.events.read")],
|
||||
}),
|
||||
serverSource: `export default {
|
||||
id: "methods", version: "0.1.0",
|
||||
register({ http }) {
|
||||
http.route({ method: "GET", path: "/events/:id", permission: "methods.events.read", maxBodyBytes: 1024, handler: ${noopHandlerSource()} });
|
||||
http.route({ method: "POST", path: "/events/new", permission: "methods.events.read", maxBodyBytes: 1024, handler: ${noopHandlerSource()} });
|
||||
}
|
||||
};`,
|
||||
});
|
||||
|
||||
const runtime = await startModuleRuntime({
|
||||
moduleSdkVersion: "0.1.0",
|
||||
modulesDirectory,
|
||||
platformVersion: "0.1.0",
|
||||
services: fakeModuleRuntimeServices(),
|
||||
});
|
||||
expect(runtime.routes).toHaveLength(2);
|
||||
await runtime.stop();
|
||||
});
|
||||
|
||||
it("allows two different modules to declare the same overlapping local paths", async () => {
|
||||
const modulesDirectory = await createModulesDirectory();
|
||||
for (const moduleId of ["alpha", "beta"]) {
|
||||
await createRuntimeModule(modulesDirectory, moduleId, {
|
||||
manifest: manifestFor(moduleId, {
|
||||
permissions: [permissionDeclaration(`${moduleId}.events.read`)],
|
||||
}),
|
||||
serverSource: `export default {
|
||||
id: "${moduleId}", version: "0.1.0",
|
||||
register({ http }) {
|
||||
http.route({ method: "GET", path: "/events/:id", permission: "${moduleId}.events.read", maxBodyBytes: 1024, handler: ${noopHandlerSource()} });
|
||||
}
|
||||
};`,
|
||||
});
|
||||
}
|
||||
|
||||
// Each module has its own platform-owned mount prefix, so these can never collide.
|
||||
const runtime = await startModuleRuntime({
|
||||
moduleSdkVersion: "0.1.0",
|
||||
modulesDirectory,
|
||||
platformVersion: "0.1.0",
|
||||
services: fakeModuleRuntimeServices(),
|
||||
});
|
||||
expect(runtime.routes.map((route) => route.moduleId).sort()).toEqual(["alpha", "beta"]);
|
||||
await runtime.stop();
|
||||
});
|
||||
|
||||
it("publishes no route from a module whose registration was rejected for an overlap", async () => {
|
||||
const modulesDirectory = await createModulesDirectory();
|
||||
await createRuntimeModule(modulesDirectory, "partial", {
|
||||
manifest: manifestFor("partial", {
|
||||
permissions: [permissionDeclaration("partial.events.read")],
|
||||
}),
|
||||
serverSource: `export default {
|
||||
id: "partial", version: "0.1.0",
|
||||
register({ http }) {
|
||||
http.route({ method: "GET", path: "/healthy", permission: "partial.events.read", maxBodyBytes: 1024, handler: ${noopHandlerSource()} });
|
||||
http.route({ method: "GET", path: "/events/:id", permission: "partial.events.read", maxBodyBytes: 1024, handler: ${noopHandlerSource()} });
|
||||
http.route({ method: "GET", path: "/events/new", permission: "partial.events.read", maxBodyBytes: 1024, handler: ${noopHandlerSource()} });
|
||||
},
|
||||
start() { throw new Error("start must never run for a rejected registration"); }
|
||||
};`,
|
||||
});
|
||||
|
||||
const error = await captureRuntimeError(modulesDirectory);
|
||||
expect(runtimeIssueCodes(error)).toEqual(["MODULE_ROUTE_OVERLAP"]);
|
||||
// The earlier, perfectly valid `/healthy` route is not published either: registration is
|
||||
// all-or-nothing, and the start hook above would have thrown had it ever run.
|
||||
});
|
||||
|
||||
it("fails a malformed route with its specific structured issue code", async () => {
|
||||
const badMethodDirectory = await createModulesDirectory();
|
||||
await createRuntimeModule(badMethodDirectory, "bad-method", {
|
||||
|
||||
Reference in New Issue
Block a user