@porulle/core 0.10.8 → 0.13.0

package/src/interfaces/rest/routes/checkout.ts

@@ -22,8 +22,8 @@ import type { PluginDb } from "../../../kernel/database/plugin-types.js";
 import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
 import { isCommerceError } from "../../../kernel/errors.js";
 import { assertPermission } from "../../../auth/permissions.js";
-import { resolveOrgId } from "../../../auth/org.js";
-import { makeDeterministicId, makeId } from "../../../utils/id.js";
+import { resolveOrgIdForCommerce } from "../../../auth/org.js";
+import { makeDeterministicId, makeId, makeIdempotencyScope } from "../../../utils/id.js";
 import type { ShippingAddress } from "../../../modules/shipping/calculator.js";
 import type { Actor } from "../../../auth/types.js";
 
@@ -85,50 +85,48 @@ export function checkoutRoutes(kernel: Kernel) {
     const body = c.req.valid("json");
 
     const actor = c.get("actor");
+    const cartSecret = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
 
-    // Idempotent replay: a re-submitted checkout (offline POS queue, network
-    // retry) returns the already-created order BEFORE the pipeline runs — no
-    // double payment authorization, no duplicate order.
+    // Idempotent replay is authorized by the order service before payment runs.
+    // This preflight only preserves the no-double-payment fast path; the create
+    // primitive repeats the same binding for direct callers and race losers.
+    let replay: Awaited<ReturnType<typeof kernel.services.orders.getByIdempotencyKey>> | undefined;
     if (body.idempotencyKey) {
-      const replay = await kernel.services.orders.getByIdempotencyKey(
+      replay = await kernel.services.orders.getByIdempotencyKey(
         body.idempotencyKey,
         actor,
+        undefined,
+        cartSecret,
       );
-      if (replay.ok && replay.value) {
-        // IDOR guard: an idempotency key must only replay the requester's OWN
-        // order. Without this, a same-org customer who supplies/guesses another
-        // customer's key would receive that customer's order (PII, totals, lines).
-        let canActForOthers = false;
-        try {
-          assertPermission(actor, "customers:read");
-          canActForOthers = true;
-        } catch {
-          canActForOthers = false;
-        }
-        const ownCustomer = actor
-          ? await resolveCheckoutCustomerUuid(kernel.services.customers, actor, undefined)
-          : undefined;
-        const replayCustomer = replay.value.customerId ?? null;
-        const ownsOrder =
-          (replayCustomer !== null && replayCustomer === ownCustomer) ||
-          (replayCustomer === null && !ownCustomer);
-        if (canActForOthers || ownsOrder) {
-          return c.json({ data: replay.value }, 201);
-        }
-        return c.json(
-          {
-            error: {
-              code: "IDEMPOTENCY_CONFLICT",
-              message: "Idempotency key does not belong to this account.",
-            },
-          },
-          409,
-        );
+      if (!replay.ok) {
+        return c.json(mapErrorToResponse(replay.error), mapErrorToStatus(replay.error));
       }
+      if (replay.value) return c.json({ data: replay.value }, 201);
     }
 
+    // Authenticate the cart once at the HTTP boundary. Guest checkout is
+    // authorized by the cart secret; customer checkout is authorized by the
+    // customer cart ownership check. The hook pipeline uses its explicit
+    // internal cart-read path instead of carrying this credential inward.
+    const cartAccess = await kernel.services.cart.getById(
+      body.cartId,
+      actor,
+      undefined,
+      cartSecret,
+    );
+    if (!cartAccess.ok) {
+      return c.json(
+        mapErrorToResponse(cartAccess.error),
+        mapErrorToStatus(cartAccess.error),
+      );
+    }
+    const idempotencyScope = body.idempotencyKey
+      ? await makeIdempotencyScope(actor, cartSecret, body.cartId)
+      : undefined;
     const orderId = body.idempotencyKey
-      ? await makeDeterministicId(`checkout:${resolveOrgId(actor)}:${body.idempotencyKey}`)
+      ? await makeDeterministicId(
+          `checkout:${resolveOrgIdForCommerce(actor, kernel.config)}:${idempotencyScope}:${body.idempotencyKey}`,
+        )
       : makeId();
     const checkoutData: CheckoutData = {
       checkoutId: makeId(),
@@ -203,6 +201,7 @@ export function checkoutRoutes(kernel: Kernel) {
       context: { moduleName: "checkout" },
       origin: "rest",
       database: { db: kernel.database.db as PluginDb },
+      commerceConfig: kernel.config,
     });
 
     let pipelineStage = "validate-and-calculate";
@@ -293,6 +292,7 @@ export function checkoutRoutes(kernel: Kernel) {
       pipelineStage = "create-order";
       const order = await kernel.services.orders.create(orderPayload, actor, undefined, {
         trustedPricing: true,
+        ...(cartSecret !== undefined ? { guestCredential: cartSecret } : {}),
       });
 
       if (!order.ok) {
@@ -379,7 +379,10 @@ export function checkoutRoutes(kernel: Kernel) {
       // Validation, payment authorization, or compensated completion may fail
       // after the cart's atomic active -> checking_out claim. Release only
       // that transient state so the shopper can correct the problem and retry.
-      await kernel.services.cart.releaseCheckoutClaim(body.cartId).catch(
+      // Releasing is scoped to this attempt's claim token: an attempt that lost
+      // the claim never held it, so its failure cannot reopen a cart another
+      // checkout is still working through.
+      await kernel.services.cart.releaseCheckoutClaim(body.cartId, checkoutData.checkoutId).catch(
         (releaseError: unknown) => {
           console.error("[checkout] Failed to release cart claim:", {
             cartId: body.cartId,

package/src/interfaces/rest/routes/documents.ts

@@ -6,7 +6,7 @@ import {
   invoicePdfRoute,
   receiptHtmlRoute,
 } from "../schemas/documents.js";
-import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requireAnyPerm } from "../utils.js";
 
 /**
  * Order document rendering (issue #47). Mounted under /orders. Access
@@ -16,10 +16,15 @@ import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
 export function documentRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
+  router.use("/*", requireAnyPerm(["orders:read", "orders:read:own"]));
+
   router.openapi(invoicePdfRoute, async (c) => {
+    const guestCredential = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
     const result = await kernel.services.documents.renderInvoicePdf(
       c.req.param("id"),
       c.get("actor"),
+      undefined,
+      guestCredential,
     );
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
     return c.body(result.value.pdf.slice().buffer as ArrayBuffer, 200, {
@@ -29,18 +34,24 @@ export function documentRoutes(kernel: Kernel) {
   });
 
   router.openapi(invoiceHtmlRoute, async (c) => {
+    const guestCredential = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
     const result = await kernel.services.documents.renderInvoiceHtml(
       c.req.param("id"),
       c.get("actor"),
+      undefined,
+      guestCredential,
     );
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
     return c.html(result.value.html);
   });
 
   router.openapi(receiptHtmlRoute, async (c) => {
+    const guestCredential = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
     const result = await kernel.services.documents.renderReceiptHtml(
       c.req.param("id"),
       c.get("actor"),
+      undefined,
+      guestCredential,
     );
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
     return c.html(result.value.html);
@@ -48,10 +59,13 @@ export function documentRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(emailInvoiceRoute, async (c) => {
+    const guestCredential = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
     const result = await kernel.services.documents.emailInvoice(
       c.req.param("id"),
       c.req.valid("json").to,
       c.get("actor"),
+      undefined,
+      guestCredential,
     );
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
     return c.json({ data: result.value });

package/src/interfaces/rest/routes/inventory.ts

@@ -24,6 +24,8 @@ export function inventoryRoutes(kernel: Kernel) {
   router.use("/warehouses", requirePerm("inventory:read"));
   router.use("/reserve", requirePerm("inventory:adjust"));
   router.use("/release", requirePerm("inventory:adjust"));
+  router.use("/check", requirePerm("inventory:read"));
+  router.use("/adjust", requirePerm("inventory:adjust"));
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listInventoryLevelsRoute, async (c) => {

package/src/interfaces/rest/routes/media.ts

@@ -2,13 +2,14 @@ import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../runtime/kernel.js";
 import type { AttachMediaInput } from "../../../modules/media/service.js";
 import { attachMediaRoute, getMediaRoute, deleteMediaRoute } from "../schemas/media.js";
-import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requireMethodPerm, requirePerm } from "../utils.js";
 
 export function mediaRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
   // Upload requires authentication + media:write permission
   router.use("/upload", requirePerm("media:write"));
+  router.use("/:id", requireMethodPerm(["DELETE"], "media:write"));
 
   router.post("/upload", async (c) => {
     // No storage configured (the default no-op adapter) → media is disabled.
@@ -43,16 +44,20 @@ export function mediaRoutes(kernel: Kernel) {
 
   router.openapi(getMediaRoute, async (c) => {
     const signed = c.req.query("signed") === "true";
+    const actor = c.get("actor");
+
+    if (!actor && !signed) {
+      return c.json({ error: { code: "NOT_FOUND", message: "Media not found." } }, 404);
+    }
 
     // Signed URLs require authentication
-    if (signed && !c.get("actor")) {
+    if (signed && !actor) {
       return c.json(
         { error: { code: "UNAUTHORIZED", message: "Authentication required for signed URLs." } },
         401,
       );
     }
 
-    const actor = c.get("actor");
     const result = signed
       ? await kernel.services.media.getSignedUrl(c.req.param("id"), undefined, actor)
       : await kernel.services.media.getUrl(c.req.param("id"), actor);

package/src/interfaces/rest/routes/orders.ts

@@ -1,7 +1,7 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../runtime/kernel.js";
 import { changeOrderStatusRoute, listOrdersRoute, orderLookupRoute, getOrderRoute, getOrderFulfillmentsRoute, createOrderRoute, quoteOrderRoute, refundOrderRoute, captureOrderRoute, createOrderFulfillmentRoute, addOrderLineItemRoute, updateOrderLineItemRoute, removeOrderLineItemRoute, refundOrderLinesRoute, undoOrderRefundRoute, listOrderRefundsRoute, refundCapStatusRoute, createOrderNoteRoute, listOrderNotesRoute, deleteOrderNoteRoute, orderTimelineRoute } from "../schemas/orders.js";
-import { type AppEnv, isUUID, mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils.js";
+import { type AppEnv, isUUID, mapErrorToResponse, mapErrorToStatus, parsePagination, requireAnyPerm, requireMethodPerm, requirePerm } from "../utils.js";
 import type { CreateOrderInput } from "../../../modules/orders/service.js";
 import { computeOrderPricing } from "../../../modules/orders/quote.js";
 import { assertPermission } from "../../../auth/permissions.js";
@@ -9,6 +9,13 @@ import { assertPermission } from "../../../auth/permissions.js";
 export function orderRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
+  router.use("/", requireMethodPerm(["GET"], "orders:read"));
+  router.use("/", requireMethodPerm(["POST"], "orders:create"));
+  router.use("/lookup", requirePerm("orders:read"));
+  router.use("/:idOrNumber", requireAnyPerm(["orders:read", "orders:read:own"]));
+  router.use("/:id/*", requireAnyPerm(["orders:read", "orders:read:own", "orders:update", "orders:manage"]));
+  router.use("/refunds/cap", requirePerm("orders:read"));
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listOrdersRoute, async (c) => {
     const pagination = parsePagination(c.req.query());
@@ -54,9 +61,10 @@ export function orderRoutes(kernel: Kernel) {
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getOrderRoute, async (c) => {
     const idOrNumber = c.req.param("idOrNumber");
+    const guestCredential = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
     const result = isUUID(idOrNumber)
-      ? await kernel.services.orders.getById(idOrNumber, c.get("actor"))
-      : await kernel.services.orders.getByNumber(idOrNumber, c.get("actor"));
+      ? await kernel.services.orders.getById(idOrNumber, c.get("actor"), undefined, guestCredential)
+      : await kernel.services.orders.getByNumber(idOrNumber, c.get("actor"), undefined, guestCredential);
 
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
     return c.json({ data: result.value });
@@ -65,12 +73,15 @@ export function orderRoutes(kernel: Kernel) {
   // @ts-expect-error -- openapi handler union return type
   router.openapi(createOrderRoute, async (c) => {
     try {
-      assertPermission(c.get("actor"), "orders:manage");
+      assertPermission(c.get("actor"), "orders:create");
     } catch (error) {
       return c.json(mapErrorToResponse(error), mapErrorToStatus(error));
     }
     const body = c.req.valid("json") as CreateOrderInput;
-    const result = await kernel.services.orders.create(body, c.get("actor"));
+    const guestCredential = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
+    const result = await kernel.services.orders.create(body, c.get("actor"), undefined, {
+      ...(guestCredential !== undefined ? { guestCredential } : {}),
+    });
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
     return c.json({ data: result.value }, 201);
   });
@@ -273,8 +284,15 @@ export function orderRoutes(kernel: Kernel) {
     const actor = c.get("actor");
     const orderId = c.req.param("id");
 
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return c.json(mapErrorToResponse(error), mapErrorToStatus(error));
+    }
+    const guestCredential = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
+
     // Verify the order exists and the actor has access before recording
-    const orderResult = await kernel.services.orders.getById(orderId, actor);
+    const orderResult = await kernel.services.orders.getById(orderId, actor, undefined, guestCredential);
     if (!orderResult.ok) return c.json(mapErrorToResponse(orderResult.error), mapErrorToStatus(orderResult.error));
 
     const body = c.req.valid("json") as {
@@ -298,11 +316,12 @@ export function orderRoutes(kernel: Kernel) {
   router.openapi(getOrderFulfillmentsRoute, async (c) => {
     const orderId = c.req.param("id");
     const actor = c.get("actor");
+    const guestCredential = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
 
     // Verify the order exists and the actor has access before returning fulfillments
     const orderResult = isUUID(orderId)
-      ? await kernel.services.orders.getById(orderId, actor)
-      : await kernel.services.orders.getByNumber(orderId, actor);
+      ? await kernel.services.orders.getById(orderId, actor, undefined, guestCredential)
+      : await kernel.services.orders.getByNumber(orderId, actor, undefined, guestCredential);
 
     if (!orderResult.ok) return c.json(mapErrorToResponse(orderResult.error), mapErrorToStatus(orderResult.error));
 

package/src/interfaces/rest/routes/pricing.ts

@@ -1,5 +1,5 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
-import { resolveOrgId } from "../../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../../auth/org.js";
 import { CommerceValidationError } from "../../../kernel/errors.js";
 import type { DrizzleDatabase } from "../../../kernel/database/drizzle-db.js";
 import { CatalogRepository } from "../../../modules/catalog/repository/index.js";
@@ -98,7 +98,7 @@ export function pricingRoutes(kernel: Kernel) {
 
     if (input.entityId) {
       const catalogRepo = new CatalogRepository(kernel.database.db as DrizzleDatabase);
-      const orgId = resolveOrgId(actor);
+      const orgId = resolveOrgIdForCommerce(actor, kernel.config);
       const entity = await catalogRepo.findEntityById(input.entityId);
       if (!entity || entity.organizationId !== orgId) {
         return c.json(

package/src/interfaces/rest/routes/promotions.ts

@@ -3,8 +3,9 @@ import { rateLimiter } from "hono-rate-limiter";
 import type { Kernel } from "../../../runtime/kernel.js";
 import { createPromotionRoute, updatePromotionRoute, validatePromotionRoute, deactivatePromotionRoute, listPromotionsRoute } from "../schemas/promotions.js";
 import type { PromotionStatusFilter } from "../../../modules/promotions/service.js";
-import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
-import { resolveOrgId } from "../../../auth/org.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requireMethodPerm, requirePerm } from "../utils.js";
+import { resolveOrgIdForCommerce } from "../../../auth/org.js";
+import { assertPermission } from "../../../auth/permissions.js";
 
 export function promotionRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
@@ -59,7 +60,7 @@ export function promotionRoutes(kernel: Kernel) {
   router.openapi(validatePromotionRoute, async (c) => {
     const payload = c.req.valid("json");
     const actor = c.get("actor");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, kernel.config);
 
     // Apply (not just validate) so the response carries the authoritative
     // discount the cart would receive — the same computation checkout runs.
@@ -84,10 +85,7 @@ export function promotionRoutes(kernel: Kernel) {
 
   // Guard inline (not via router.use("/:id")) because a "/:id" middleware
   // would also match single-segment routes like POST /validate.
-  router.use("/:id", async (c, next) => {
-    if (c.req.method !== "PATCH") return next();
-    return requirePerm("promotions:manage")(c, next);
-  });
+  router.use("/:id", requireMethodPerm(["PATCH"], "promotions:manage"));
 
   // @ts-expect-error -- openapi() enforces strict response typing but our handler
   // returns union responses (200 | 400 | 404 | 422). The route definition
@@ -95,7 +93,12 @@ export function promotionRoutes(kernel: Kernel) {
   router.openapi(updatePromotionRoute, async (c) => {
     const body = c.req.valid("json");
     const actor = c.get("actor");
-    const orgId = resolveOrgId(actor);
+    try {
+      assertPermission(actor, "promotions:manage");
+    } catch (error) {
+      return c.json(mapErrorToResponse(error), mapErrorToStatus(error));
+    }
+    const orgId = resolveOrgIdForCommerce(actor, kernel.config);
     const result = await kernel.services.promotions.update(orgId, c.req.param("id"), body, actor);
     if (!result.ok) {
       return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
@@ -110,7 +113,7 @@ export function promotionRoutes(kernel: Kernel) {
   // contract; the handler returns dynamic status.
   router.openapi(deactivatePromotionRoute, async (c) => {
     const actor = c.get("actor");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, kernel.config);
     const result = await kernel.services.promotions.deactivate(orgId, c.req.param("id"));
     if (!result.ok) {
       return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));

package/src/interfaces/rest/routes/search.ts

@@ -1,11 +1,15 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../runtime/kernel.js";
 import { searchRoute, suggestRoute } from "../schemas/search.js";
-import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+
+const SAFE_ATTRIBUTE_NAME = /^[A-Za-z0-9_-]+$/;
 
 export function searchRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
+  router.use("/*", requirePerm("catalog:read"));
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(searchRoute, async (c) => {
     try {
@@ -21,6 +25,19 @@ export function searchRoutes(kernel: Kernel) {
         .map((facet) => facet.trim())
         .filter(Boolean);
 
+      const attributes: Record<string, string | string[]> = {};
+      for (const [key, values] of Object.entries(c.req.queries())) {
+        if (!key.startsWith("attr.")) continue;
+        const name = key.slice("attr.".length);
+        if (!SAFE_ATTRIBUTE_NAME.test(name)) {
+          return c.json(
+            { error: "invalid_argument", field: key, message: `Invalid attribute filter name: ${name}` },
+            422,
+          );
+        }
+        attributes[name] = values.length === 1 ? values[0]! : values;
+      }
+
       const result = await kernel.services.search.query({
         query: q,
         page,
@@ -30,6 +47,7 @@ export function searchRoutes(kernel: Kernel) {
           ...(category ? { category } : {}),
           ...(brand ? { brand } : {}),
           ...(status ? { status } : {}),
+          ...(Object.keys(attributes).length > 0 ? { attributes } : {}),
         },
         ...(facets.length > 0 ? { facets } : {}),
       }, { actor: c.get("actor"), tx: null, requestId: "" });

package/src/interfaces/rest/schemas/admin-custom-field-proposals.ts

@@ -0,0 +1,29 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+
+const ProposalResponse = z.object({
+  data: z.object({
+    items: z.array(z.any()),
+    total: z.number(),
+    page: z.number(),
+    limit: z.number(),
+  }),
+});
+
+const ListQuery = z.object({
+  entityType: z.string().min(1).optional(),
+  page: z.string().max(10).optional(),
+  limit: z.string().max(10).optional(),
+});
+
+export const listCustomFieldProposalsRoute = createRoute({
+  method: "get",
+  path: "/custom-field-proposals",
+  tags: ["Admin"],
+  summary: "List proposed custom-field values",
+  request: { query: ListQuery },
+  responses: {
+    200: { content: { "application/json": { schema: ProposalResponse } }, description: "Proposed custom fields." },
+    ...errorResponses,
+  },
+});

package/src/interfaces/rest/schemas/admin-entity-field-definitions.ts

@@ -0,0 +1,120 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+
+const FieldType = z.enum([
+  "text",
+  "number",
+  "boolean",
+  "date",
+  "json",
+  "relation",
+  "select",
+]);
+
+const CreateBody = z
+  .object({
+    entityType: z.string().min(1),
+    name: z.string().min(1),
+    type: FieldType,
+    unit: z.string().nullable().optional(),
+    options: z.array(z.string()).nullable().optional(),
+    target: z.string().nullable().optional(),
+    filterable: z.boolean().optional(),
+    localized: z.boolean().optional(),
+    sortOrder: z.number().int().optional(),
+  })
+  .openapi("CreateEntityFieldDefinitionRequest");
+
+const UpdateBody = z
+  .object({
+    entityType: z.string().min(1).optional(),
+    name: z.string().min(1).optional(),
+    type: FieldType.optional(),
+    unit: z.string().nullable().optional(),
+    options: z.array(z.string()).nullable().optional(),
+    target: z.string().nullable().optional(),
+    filterable: z.boolean().optional(),
+    localized: z.boolean().optional(),
+    sortOrder: z.number().int().optional(),
+  })
+  .openapi("UpdateEntityFieldDefinitionRequest");
+
+const IdParam = z.object({ id: z.uuid() });
+const ListQuery = z.object({ entityType: z.string().min(1).optional() });
+const DataResponse = z
+  .object({ data: z.any() })
+  .openapi("EntityFieldDefinitionResponse");
+
+export const createEntityFieldDefinitionRoute = createRoute({
+  method: "post",
+  path: "/entity-field-definitions",
+  tags: ["Admin"],
+  summary: "Create a runtime entity field definition",
+  request: {
+    body: {
+      content: { "application/json": { schema: CreateBody } },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: DataResponse } },
+      description: "Definition created.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const listEntityFieldDefinitionsRoute = createRoute({
+  method: "get",
+  path: "/entity-field-definitions",
+  tags: ["Admin"],
+  summary: "List runtime entity field definitions",
+  request: { query: ListQuery },
+  responses: {
+    200: {
+      content: { "application/json": { schema: DataResponse } },
+      description: "Definitions.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const updateEntityFieldDefinitionRoute = createRoute({
+  method: "patch",
+  path: "/entity-field-definitions/{id}",
+  tags: ["Admin"],
+  summary: "Update a runtime entity field definition",
+  request: {
+    params: IdParam,
+    body: {
+      content: { "application/json": { schema: UpdateBody } },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: DataResponse } },
+      description: "Definition updated.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const archiveEntityFieldDefinitionRoute = createRoute({
+  method: "post",
+  path: "/entity-field-definitions/{id}/archive",
+  tags: ["Admin"],
+  summary: "Archive a runtime entity field definition",
+  request: { params: IdParam },
+  responses: {
+    200: {
+      content: { "application/json": { schema: DataResponse } },
+      description: "Definition archived.",
+    },
+    ...errorResponses,
+  },
+});
+
+export type CreateEntityFieldDefinitionBody = z.infer<typeof CreateBody>;
+export type UpdateEntityFieldDefinitionBody = z.infer<typeof UpdateBody>;