fix(codegen): generated routes say they are unauthenticated in every port (#367)

The TypeScript route generators already said so, showed how to guard the mount, and
offered `expose` for per-verb control. The C#, Java, Kotlin and Python route
generators said nothing, so an adopter mounting them got open CRUD over every table
with no warning. That is how the first real app ended up throwing route codegen away.

Each now emits a doc comment on the generated register method / controller / router:
- the endpoints are unauthenticated;
- how to guard them in that framework (C#: map on a group with
  RequireAuthorization(); Spring: require authentication for the controller's path;
  FastAPI: include_router with a dependency);
- a row-ownership rule cannot be expressed on a mount, so eject the generator
  (`dotnet meta eject`, `mvn metaobjects:eject`, `metaobjects eject`) and hand-write
  those endpoints. Non-TS REST templates are frozen for features, so they get no
  `expose` option; eject is the per-verb path there.

The Kotlin example names the path in prose rather than a `/**` glob: Kotlin nests block
comments, so `/*` inside a KDoc would leave the comment unclosed and the controller
would not compile. The snapshot test compares text and the compile gate excludes
controllers, so nothing would have caught it.

Tests: C# codegen 569 pass / conformance 1117 pass; codegen-spring 297, codegen-kotlin
387 (snapshots updated, both compile gates green); Python 2145 pass, compile gate green.
Showcase regenerated with each port's own CLI; `verify --codegen` in sync for C# and
Python, site payload fresh.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M1mRRB1K2WdYy82kntMQdx

Author: dmealing

examples/showcase/.metaobjects/.gen-state/.hashes.json

@@ -4,13 +4,13 @@
   "generated/csharp/SubscriberBlurbPayload.g.cs": "6b1ce5b5a4018c647586d86125718c4764ae5d6eeb94e9545e8006a7ec2b2b6f",
   "generated/csharp/SubscriberFilterAllowlist.g.cs": "7428d47f6ccb64bb315266ee0564fa3803736623a34ab491435c042848c5d472",
   "generated/csharp/SubscriberNames.g.cs": "91f6eba78657b31fceef7021c6ca6bd799524dcb5120acbc8fcbe18786787174",
-  "generated/csharp/SubscriberRoutes.g.cs": "41058cfbeb017e6b145d0288721d40e1d27e54b9cd398d82a13dbd62b39c3fb8",
+  "generated/csharp/SubscriberRoutes.g.cs": "4afe6a906696bbb7ce07466e99bd3419fb86449b3fa8bec54366cbc1112631f5",
   "generated/python/Subscriber.py": "9dd4c0acea47f99d1daf79930f9de2e400f30780ebce6c63f023be528a72b762",
   "generated/python/SubscriberBlurbPayload.py": "a5ef8a08e63efbe0f73e39a21a368cff5150c68cc8beeea6e8aab0c755f8bbdd",
   "generated/python/__init__.py": "daa04cec586768866d0996c779f62073e6773fe63750ff668327991fac2fd0f5",
   "generated/python/subscriber_filter_allowlist.py": "b0414cc95ff3982c80a0e1a06839f090c0b423e41f5a94275df93426cea09df5",
   "generated/python/subscriber_names.py": "269637a02bf9b46f55658b58cb42f83196c03a877e1e2101337847fd406c1561",
-  "generated/python/subscriber_router.py": "7cf221a042731a1f1c939fbd30db10414787bacbd59ff6dbe759669b045e6737",
+  "generated/python/subscriber_router.py": "23ed325ce7d146172e137e8e320d98ed07c652f6fc9e3095132def01a61a1371",
   "generated/ts/Subscriber.queries.ts": "2a142561bd9bcc3cfb88e6c306aafc638e982d48b0d07f71a79d810be16adf14",
   "generated/ts/Subscriber.routes.ts": "887b0aa76d32cf12fa1d16f0eae52fbc795ca8d8a29588b7089b6eb478f0cd93",
   "generated/ts/Subscriber.ts": "f19eeac95d012580f1b9023d807a8b9c893fb1a2ee983cf085fe958b65cbaba9",

examples/showcase/generated/csharp/SubscriberRoutes.g.cs

@@ -24,6 +24,13 @@ public static class SubscriberRoutes
     {
     };
 
+    /// <summary>Maps <c>Subscriber</c> REST routes. Unauthenticated — see remarks.</summary>
+    /// <remarks>
+    /// These endpoints are unauthenticated. Guard them by mapping on a group that requires
+    /// authorization, e.g. <c>app.MapGroup("").RequireAuthorization().MapSubscriberRoutes();</c>
+    /// A row-ownership rule ("only the owner may read this row") cannot be expressed on a mount:
+    /// eject this generator with <c>dotnet meta eject</c> and hand-write those endpoints.
+    /// </remarks>
     public static IEndpointRouteBuilder MapSubscriberRoutes(this IEndpointRouteBuilder app, string prefix = "/api")
     {
         app.MapGet(prefix + "/subscribers", async (HttpContext http, AppDbContext db) =>

examples/showcase/generated/python/subscriber_router.py

@@ -1,7 +1,15 @@
 # @generated by metaobjects — DO NOT EDIT.
 # Source metadata: Subscriber (acme::Subscriber)
 # Extend in your own module (e.g. Subscriber_extra.py) — nothing imports it for you.
-"""GENERATED — REST router for Subscriber entity. Implements the cross-port API contract."""
+"""GENERATED — REST router for Subscriber entity. Implements the cross-port API contract.
+
+Auth: these endpoints are unauthenticated. To guard them, include the router with a
+dependency, e.g. `app.include_router(router, dependencies=[Depends(require_auth)])`.
+
+A row-ownership rule ("only the owner may read this row") cannot be expressed as a
+router dependency: eject this generator with `metaobjects eject` and hand-write
+those endpoints.
+"""
 
 from __future__ import annotations
 

server/csharp/MetaObjects.Codegen/Generators/RoutesGenerator.cs

@@ -68,6 +68,22 @@ protected override EmittedFile GenerateOne(MetaObject entity, GenContext ctx)
         return GenerateStandardRoutes(entity, ctx);
     }
 
+    // #367 — a generated route file carries no auth by default; ASP.NET Core applies no
+    // policy to a bare Map* call, and an adopter that doesn't notice ships it open. The XML
+    // doc on the mount method is the one place a consumer reads before wiring it into their
+    // host, so it says so and shows the fix rather than leaving it to a README nobody opens.
+    private static void AppendUnauthenticatedRoutesDoc(StringBuilder sb, string cls, bool readOnly)
+    {
+        var verbs = readOnly ? "read endpoints" : "endpoints";
+        sb.AppendLine($"    /// <summary>Maps <c>{cls}</c> REST routes. Unauthenticated — see remarks.</summary>");
+        sb.AppendLine("    /// <remarks>");
+        sb.AppendLine($"    /// These {verbs} are unauthenticated. Guard them by mapping on a group that requires");
+        sb.AppendLine($"    /// authorization, e.g. <c>app.MapGroup(\"\").RequireAuthorization().Map{cls}Routes();</c>");
+        sb.AppendLine("    /// A row-ownership rule (\"only the owner may read this row\") cannot be expressed on a mount:");
+        sb.AppendLine($"    /// eject this generator with <c>dotnet meta eject</c> and hand-write those {verbs}.");
+        sb.AppendLine("    /// </remarks>");
+    }
+
     protected virtual EmittedFile GenerateStandardRoutes(MetaObject entity, GenContext ctx)
     {
         var cls = CSharpNaming.Pascal(entity.Name);
@@ -157,6 +173,7 @@ protected virtual EmittedFile GenerateStandardRoutes(MetaObject entity, GenConte
         sb.AppendLine("    };");
         sb.AppendLine();
         AppendSortDefaultOrder(sb, entity, "SortDefaultDesc");
+        AppendUnauthenticatedRoutesDoc(sb, cls, isProjection);
         sb.AppendLine($"    public static IEndpointRouteBuilder Map{cls}Routes(this IEndpointRouteBuilder app, string prefix = \"/api\")");
         sb.AppendLine("    {");
 
@@ -448,6 +465,7 @@ protected virtual EmittedFile GenerateTphRoutes(MetaObject baseEntity, TphPlan t
             AppendSortDefaultOrder(sb, st.Entity, $"{subClsName}SortDefaultDesc");
         }
 
+        AppendUnauthenticatedRoutesDoc(sb, baseCls, readOnly: false);
         sb.AppendLine($"    public static IEndpointRouteBuilder Map{baseCls}Routes(this IEndpointRouteBuilder app, string prefix = \"/api\")");
         sb.AppendLine("    {");
 

server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinSpringControllerGenerator.kt

@@ -344,7 +344,16 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
 
             appendRowToMapper(this, shortName, entity, readObj)
 
-            append("/** GENERATED — REST controller for ${shortName} entity. Implements the cross-port API contract. */\n")
+            append("/**\n")
+            append(" * GENERATED — REST controller for ${shortName} entity. Implements the cross-port API contract.\n")
+            append(" *\n")
+            // No `/**` glob in the example: Kotlin NESTS block comments, so a `/*` inside this
+            // KDoc would open a comment that never closes and the file would not compile.
+            append(" * Auth: these endpoints are unauthenticated. In your Spring Security config, require\n")
+            append(" * authentication for `$routeBase` and every path under it (`requestMatchers` + `authenticated()`).\n")
+            append(" * A row-ownership rule (\"only the owner may read this row\") can't be expressed in path\n")
+            append(" * config — eject this generator with `mvn metaobjects:eject` and hand-write those endpoints.\n")
+            append(" */\n")
             append("@RestController\n")
             append("@RequestMapping(\"$routeBase\")\n")
             // FR-036: `validator` is always injected (POST + present-PATCH-value enforcement).
@@ -771,7 +780,15 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
             for (field in scalarFields) append("    ${field.name} = row[$table.${field.name}],\n")
             append(")\n\n")
 
-            append("/** GENERATED — TPH discriminator-base controller for $shortName (polymorphic + per-subtype CRUD). */\n")
+            append("/**\n")
+            append(" * GENERATED — TPH discriminator-base controller for $shortName (polymorphic + per-subtype CRUD).\n")
+            append(" *\n")
+            // No `/**` glob in the example: Kotlin NESTS block comments (see emit()).
+            append(" * Auth: these endpoints are unauthenticated. In your Spring Security config, require\n")
+            append(" * authentication for `$routeBase` and every path under it (`requestMatchers` + `authenticated()`).\n")
+            append(" * A row-ownership rule (\"only the owner may read this row\") can't be expressed in path\n")
+            append(" * config — eject this generator with `mvn metaobjects:eject` and hand-write those endpoints.\n")
+            append(" */\n")
             append("@RestController\n")
             append("@RequestMapping(\"$routeBase\")\n")
             // FR-036: the per-subtype PATCH tristate binds present values through the Spring-configured
@@ -1728,7 +1745,15 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
             emitFilterPipeline(this, shortName, readObj, allowlistName, scalarFields)
             appendRowToMapper(this, shortName, entity, readObj)
 
-            append("/** GENERATED — READ-ONLY REST controller for the ${shortName} projection. */\n")
+            append("/**\n")
+            append(" * GENERATED — READ-ONLY REST controller for the ${shortName} projection.\n")
+            append(" *\n")
+            // No `/**` glob in the example: Kotlin NESTS block comments (see emit()).
+            append(" * Auth: these read endpoints are unauthenticated. In your Spring Security config, require\n")
+            append(" * authentication for `$routeBase` and every path under it (`requestMatchers` + `authenticated()`).\n")
+            append(" * A row-ownership rule (\"only the owner may read this row\") can't be expressed in path\n")
+            append(" * config — eject this generator with `mvn metaobjects:eject` and hand-write those endpoints.\n")
+            append(" */\n")
             append("@RestController\n")
             append("@RequestMapping(\"$routeBase\")\n")
             // No constructor at all: nothing here binds a request body, so injecting an

server/java/codegen-kotlin/src/test/resources/snapshots/entity-with-controller/acme/blog/AuthorController.kt

@@ -273,7 +273,14 @@ private fun rowToAuthor(row: ResultRow): Author = Author(
     name = row[AuthorTable.name],
 )
 
-/** GENERATED — REST controller for Author entity. Implements the cross-port API contract. */
+/**
+ * GENERATED — REST controller for Author entity. Implements the cross-port API contract.
+ *
+ * Auth: these endpoints are unauthenticated. In your Spring Security config, require
+ * authentication for `/api/authors` and every path under it (`requestMatchers` + `authenticated()`).
+ * A row-ownership rule ("only the owner may read this row") can't be expressed in path
+ * config — eject this generator with `mvn metaobjects:eject` and hand-write those endpoints.
+ */
 @RestController
 @RequestMapping("/api/authors")
 class AuthorController(private val objectMapper: ObjectMapper, private val validator: Validator) {

server/java/codegen-kotlin/src/test/resources/snapshots/entity-with-tph/acme/auth/AuthController.kt

@@ -309,7 +309,14 @@ private fun rowToAuth(row: ResultRow): Auth = Auth(
     priorAuthNumber = row[AuthTable.priorAuthNumber],
 )
 
-/** GENERATED — TPH discriminator-base controller for Auth (polymorphic + per-subtype CRUD). */
+/**
+ * GENERATED — TPH discriminator-base controller for Auth (polymorphic + per-subtype CRUD).
+ *
+ * Auth: these endpoints are unauthenticated. In your Spring Security config, require
+ * authentication for `/api/auths` and every path under it (`requestMatchers` + `authenticated()`).
+ * A row-ownership rule ("only the owner may read this row") can't be expressed in path
+ * config — eject this generator with `mvn metaobjects:eject` and hand-write those endpoints.
+ */
 @RestController
 @RequestMapping("/api/auths")
 class AuthController(private val objectMapper: ObjectMapper, private val validator: Validator) {

server/java/codegen-kotlin/src/test/resources/snapshots/entity-with-tph/acme/auth/AuthLineController.kt

@@ -272,7 +272,14 @@ private fun rowToAuthLine(row: ResultRow): AuthLine = AuthLine(
     label = row[AuthLineTable.label],
 )
 
-/** GENERATED — REST controller for AuthLine entity. Implements the cross-port API contract. */
+/**
+ * GENERATED — REST controller for AuthLine entity. Implements the cross-port API contract.
+ *
+ * Auth: these endpoints are unauthenticated. In your Spring Security config, require
+ * authentication for `/api/auth_lines` and every path under it (`requestMatchers` + `authenticated()`).
+ * A row-ownership rule ("only the owner may read this row") can't be expressed in path
+ * config — eject this generator with `mvn metaobjects:eject` and hand-write those endpoints.
+ */
 @RestController
 @RequestMapping("/api/auth_lines")
 class AuthLineController(private val objectMapper: ObjectMapper, private val validator: Validator) {

server/java/codegen-kotlin/src/test/resources/snapshots/entity-with-view/acme/report/SalesReportController.kt

@@ -274,7 +274,14 @@ private fun rowToSalesReport(row: ResultRow): SalesReport = SalesReport(
     totalCents = row[SalesReportTable.totalCents],
 )
 
-/** GENERATED — READ-ONLY REST controller for the SalesReport projection. */
+/**
+ * GENERATED — READ-ONLY REST controller for the SalesReport projection.
+ *
+ * Auth: these read endpoints are unauthenticated. In your Spring Security config, require
+ * authentication for `/api/sales_reports` and every path under it (`requestMatchers` + `authenticated()`).
+ * A row-ownership rule ("only the owner may read this row") can't be expressed in path
+ * config — eject this generator with `mvn metaobjects:eject` and hand-write those endpoints.
+ */
 @RestController
 @RequestMapping("/api/sales_reports")
 class SalesReportController {

server/java/codegen-spring/src/main/java/com/metaobjects/generator/spring/SpringControllerGenerator.java

@@ -220,8 +220,17 @@ protected void emit(MetaObject entity, Path outRoot) {
         src.append("import java.util.Map;\n");
         src.append("import java.util.Set;\n\n");
 
-        src.append("/** GENERATED — REST controller for ").append(shortName)
-           .append(" entity. Implements the cross-port API contract. */\n");
+        src.append("/**\n");
+        src.append(" * GENERATED — REST controller for ").append(shortName)
+           .append(" entity. Implements the cross-port API contract.\n");
+        src.append(" *\n");
+        src.append(" * <p>Auth: these endpoints are unauthenticated. Require authentication for this path in\n");
+        src.append(" * your Spring Security config, e.g. {@code http.authorizeHttpRequests(a ->\n");
+        src.append(" * a.requestMatchers(\"").append(routeBase).append("/**\").authenticated())}.\n");
+        src.append(" * A row-ownership rule (\"only the owner may read this row\") can't be expressed in path\n");
+        src.append(" * config — eject this generator with {@code mvn metaobjects:eject} and hand-write those\n");
+        src.append(" * endpoints.\n");
+        src.append(" */\n");
         src.append("@RestController\n");
         src.append("@RequestMapping(\"").append(routeBase).append("\")\n");
         src.append("public class ").append(controllerName).append(" {\n\n");
@@ -552,6 +561,13 @@ protected void emitReadOnly(MetaObject entity, Path outRoot) {
            .append(" projection.\n");
         src.append(" * Implements the cross-port API contract: GET list + GET by id; every write\n");
         src.append(" * verb answers 405 {\"error\": \"method_not_allowed\"}.\n");
+        src.append(" *\n");
+        src.append(" * <p>Auth: these read endpoints are unauthenticated. Require authentication for this path\n");
+        src.append(" * in your Spring Security config, e.g. {@code http.authorizeHttpRequests(a ->\n");
+        src.append(" * a.requestMatchers(\"").append(routeBase).append("/**\").authenticated())}.\n");
+        src.append(" * A row-ownership rule (\"only the owner may read this row\") can't be expressed in path\n");
+        src.append(" * config — eject this generator with {@code mvn metaobjects:eject} and hand-write those\n");
+        src.append(" * endpoints.\n");
         src.append(" */\n");
         src.append("@RestController\n");
         src.append("@RequestMapping(\"").append(routeBase).append("\")\n");
@@ -800,8 +816,18 @@ protected void emitTph(MetaObject base, TphPlan.Plan plan, Path outRoot) {
         src.append("import java.util.Map;\n");
         src.append("import java.util.Set;\n\n");
 
-        src.append("/** GENERATED — TPH discriminator-base controller for ").append(shortName)
-           .append(" (polymorphic collection + per-subtype CRUD). Implements the cross-port API contract. */\n");
+        src.append("/**\n");
+        src.append(" * GENERATED — TPH discriminator-base controller for ").append(shortName)
+           .append(" (polymorphic collection + per-subtype CRUD).\n");
+        src.append(" * Implements the cross-port API contract.\n");
+        src.append(" *\n");
+        src.append(" * <p>Auth: these endpoints are unauthenticated. Require authentication for this path in\n");
+        src.append(" * your Spring Security config, e.g. {@code http.authorizeHttpRequests(a ->\n");
+        src.append(" * a.requestMatchers(\"").append(routeBase).append("/**\").authenticated())}.\n");
+        src.append(" * A row-ownership rule (\"only the owner may read this row\") can't be expressed in path\n");
+        src.append(" * config — eject this generator with {@code mvn metaobjects:eject} and hand-write those\n");
+        src.append(" * endpoints.\n");
+        src.append(" */\n");
         src.append("@RestController\n");
         src.append("@RequestMapping(\"").append(routeBase).append("\")\n");
         src.append("public class ").append(controllerName).append(" {\n\n");