@porulle/core 0.10.8 → 0.13.0

package/src/interfaces/rest/route-coverage.ts

@@ -0,0 +1,103 @@
+import type { RouterRoute } from "hono/types";
+import { isRoutePermissionGuard } from "./utils.js";
+
+export type PublicRoute = {
+  method: string;
+  path: string;
+  justification: string;
+};
+
+export const PUBLIC_ROUTES: readonly PublicRoute[] = [
+  { method: "GET", path: "/api/health", justification: "Load balancers need an unauthenticated liveness probe." },
+  { method: "GET", path: "/api/reference", justification: "The development API explorer is intentionally public when enabled." },
+  { method: "GET", path: "/api/doc", justification: "The generated OpenAPI document is public when documentation exposure is enabled." },
+  { method: "GET", path: "/api/doc-ext", justification: "The enriched OpenAPI document is public when documentation exposure is enabled." },
+  { method: "POST", path: "/api/carts", justification: "Anonymous storefront shoppers create secret-backed guest carts." },
+  { method: "GET", path: "/api/carts/:id", justification: "Guest cart reads require the cart secret; customer carts require ownership in the service." },
+  { method: "POST", path: "/api/carts/:id/items", justification: "Anonymous storefront shoppers add items to a secret-backed guest cart." },
+  { method: "PATCH", path: "/api/carts/:id/items/:itemId", justification: "Anonymous storefront shoppers change quantities in a secret-backed guest cart." },
+  { method: "DELETE", path: "/api/carts/:id/items/:itemId", justification: "Anonymous storefront shoppers remove items from a secret-backed guest cart." },
+  { method: "POST", path: "/api/checkout", justification: "Anonymous storefront checkout is authorized by the customer actor and cart/payment pipeline." },
+  { method: "GET", path: "/api/media/:id", justification: "Public media assets redirect to their configured public storage URL; signed URLs still require an actor in the handler." },
+  { method: "POST", path: "/api/promotions/validate", justification: "Storefront shoppers validate a promotion code before checkout; the route is rate-limited." },
+  { method: "POST", path: "/api/payments/webhook", justification: "The payment provider authenticates this endpoint with its signed webhook payload." },
+];
+
+type RouteTableApp = {
+  routes: readonly RouterRoute[];
+};
+
+type ComposedRouteHandler = {
+  __COMPOSED_HANDLER?: unknown;
+};
+
+function hasPermissionGuard(handler: unknown, method?: string, seen = new Set<unknown>()): boolean {
+  if (typeof handler !== "function" || seen.has(handler)) return false;
+  seen.add(handler);
+  if (isRoutePermissionGuard(handler, method)) return true;
+  const composed = (handler as unknown as ComposedRouteHandler).__COMPOSED_HANDLER;
+  return hasPermissionGuard(composed, method, seen);
+}
+
+function splitPath(path: string): string[] {
+  return path.split("/").filter(Boolean);
+}
+
+function pathPatternCovers(pattern: string, target: string): boolean {
+  const patternParts = splitPath(pattern);
+  const targetParts = splitPath(target);
+  const wildcardIndex = patternParts.indexOf("*");
+  if (wildcardIndex >= 0) {
+    if (wildcardIndex !== patternParts.length - 1 || targetParts.length < wildcardIndex) return false;
+  } else if (patternParts.length !== targetParts.length) {
+    return false;
+  }
+
+  return patternParts.every((part, index) => {
+    if (part === "*") return true;
+    const targetPart = targetParts[index];
+    return part.startsWith(":") || part === targetPart;
+  });
+}
+
+function publicRouteCovers(route: RouterRoute): boolean {
+  return PUBLIC_ROUTES.some((publicRoute) =>
+    publicRoute.method === route.method && pathPatternCovers(publicRoute.path, route.path),
+  );
+}
+
+function routeKey(route: RouterRoute): string {
+  return `${route.method} ${route.path}`;
+}
+
+export function findUncoveredRoutes(app: RouteTableApp): string[] {
+  const routes = app.routes;
+  const guardedRoutes = routes
+    .map((route, index) => ({ route, index }))
+    .filter(({ route }) => route.method === "ALL" && hasPermissionGuard(route.handler));
+  const endpoints = new Map<string, { route: RouterRoute; index: number }>();
+
+  for (const [index, route] of routes.entries()) {
+    if (route.method === "ALL") continue;
+    const key = routeKey(route);
+    if (!endpoints.has(key)) endpoints.set(key, { route, index });
+  }
+
+  return [...endpoints.values()]
+    .filter(({ route, index }) => {
+      if (publicRouteCovers(route)) return false;
+      const directlyGuarded = hasPermissionGuard(route.handler, route.method);
+      const coveredByMiddleware = guardedRoutes.some(({ route: guard, index: guardIndex }) =>
+        guardIndex <= index && pathPatternCovers(guard.path, route.path) && hasPermissionGuard(guard.handler, route.method),
+      );
+      return !directlyGuarded && !coveredByMiddleware;
+    })
+    .map(({ route }) => routeKey(route));
+}
+
+export function assertRouteCoverage(app: RouteTableApp): void {
+  const uncovered = findUncoveredRoutes(app);
+  if (uncovered.length > 0) {
+    throw new Error(`Unclassified routes: ${uncovered.join(", ")}`);
+  }
+}

package/src/interfaces/rest/router.ts

@@ -28,10 +28,11 @@
 
 import { createRoute, z } from "@hono/zod-openapi";
 import { ErrorSchema } from "./schemas/shared.js";
-import { mapErrorToResponse, mapErrorToStatus } from "./utils.js";
+import { mapErrorToResponse, mapErrorToStatus, markRoutePermissionGuard } from "./utils.js";
+import type { CommerceConfig } from "../../config/types.js";
 import type { PluginRouteRegistration } from "../../kernel/plugin/manifest.js";
 import { createScopedDb } from "../../kernel/database/scoped-db.js";
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
 
 // ─── Shared OpenAPI Error Responses ──────────────────────────────────────────
 
@@ -61,8 +62,8 @@ export interface RouteHandlerContext {
   /** Path parameters, auto-extracted from {id} segments. */
   params: Record<string, string>;
   /** Authenticated actor. Guaranteed non-null if .auth() or .permission() was called. */
-  actor: { userId: string; role: string; permissions: string[]; vendorId?: string | null; [key: string]: unknown } | null;
-  /** Resolved organization ID. Derived from actor.organizationId, falls back to DEFAULT_ORG_ID. */
+  actor: { userId: string | null; role: string; permissions: string[]; vendorId?: string | null; [key: string]: unknown } | null;
+  /** Resolved organization ID. Derived from actor.organizationId or the deployment config. */
   orgId: string;
   /** Kernel services (orders, cart, inventory, etc.) */
   services: Record<string, unknown>;
@@ -91,7 +92,7 @@ class RouteChain {
     private fullPath: string,
     private tag: string,
     private routesList: PluginRouteRegistration[],
-    private pluginCtx?: { services: Record<string, unknown>; db: unknown },
+    private pluginCtx?: { config?: CommerceConfig; services: Record<string, unknown>; db: unknown },
   ) {
     const paramNames = extractPathParams(fullPath);
     if (paramNames.length > 0) {
@@ -214,6 +215,7 @@ class RouteChain {
 
         // Use plugin context if provided (plugin routes), fallback to kernel on Hono context (core routes)
         const kernel = pluginCtx ?? (ctx.get("kernel") as {
+          config?: CommerceConfig;
           services?: Record<string, unknown>;
           db?: unknown;
         } | undefined);
@@ -222,7 +224,7 @@ class RouteChain {
         // Plugin route handlers receive a db that auto-filters queries
         // and auto-stamps inserts with the actor's organizationId.
         const rawDb = kernel?.db;
-        const orgId = resolveOrgId(actor);
+        const orgId = resolveOrgIdForCommerce(actor, kernel?.config);
         const scopedDb = rawDb ? createScopedDb(rawDb as Record<string, unknown>, orgId) : rawDb;
 
         const handlerCtx: RouteHandlerContext = {
@@ -262,7 +264,10 @@ class RouteChain {
       }
     };
 
-    this.routesList.push({ openapi: routeConfig, handler: honoHandler as (...args: unknown[]) => unknown });
+    const registeredHandler = requireAuth || requiredPermission
+      ? markRoutePermissionGuard(honoHandler)
+      : honoHandler;
+    this.routesList.push({ openapi: routeConfig, handler: registeredHandler as (...args: unknown[]) => unknown });
   }
 }
 
@@ -271,12 +276,12 @@ class RouteChain {
 class RouterImpl {
   private _routes: PluginRouteRegistration[] = [];
   private _prefix: string;
-  private _pluginCtx: { services: Record<string, unknown>; db: unknown } | undefined;
+  private _pluginCtx: { config?: CommerceConfig; services: Record<string, unknown>; db: unknown } | undefined;
 
   constructor(
     private tag: string,
     prefix: string,
-    pluginCtx?: { services?: Record<string, unknown>; database?: { db: unknown } },
+    pluginCtx?: { config?: CommerceConfig; services?: Record<string, unknown>; database?: { db: unknown } },
   ) {
     // Normalize: ensure /api prefix, strip trailing slash
     let p = prefix.startsWith("/api") ? prefix : `/api${prefix}`;
@@ -286,6 +291,7 @@ class RouterImpl {
     // If plugin context is provided, wire services + db for handler access
     if (pluginCtx) {
       this._pluginCtx = {
+        ...(pluginCtx.config !== undefined ? { config: pluginCtx.config } : {}),
         services: pluginCtx.services ?? {},
         db: pluginCtx.database?.db,
       };
@@ -330,6 +336,6 @@ class RouterImpl {
  * }
  * ```
  */
-export function router(tag: string, prefix: string, ctx?: { services?: Record<string, unknown>; database?: { db: unknown } }): RouterImpl {
+export function router(tag: string, prefix: string, ctx?: { config?: CommerceConfig; services?: Record<string, unknown>; database?: { db: unknown } }): RouterImpl {
   return new RouterImpl(tag, prefix, ctx);
 }

package/src/interfaces/rest/routes/admin/compensation-failures.ts

@@ -2,14 +2,14 @@ import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../../runtime/kernel.js";
 import type { Actor } from "../../../../auth/types.js";
 import { assertPermission } from "../../../../auth/permissions.js";
-import { resolveOrgId } from "../../../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../../../auth/org.js";
 import { CommerceValidationError } from "../../../../kernel/errors.js";
 import type { CompensationFailure } from "../../../../kernel/compensation/schema.js";
 import {
   listCompensationFailuresRoute,
   resolveCompensationFailureRoute,
 } from "../../schemas/compensation-failures.js";
-import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../../utils.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../../utils.js";
 
 function toIso(d: Date | null | undefined): string | null {
   if (d == null) return null;
@@ -67,11 +67,14 @@ function parseResolvedFilter(
 export function compensationFailureAdminRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
+  router.use("/compensation-failures", requirePerm("compensation:admin"));
+  router.use("/compensation-failures/*", requirePerm("compensation:admin"));
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listCompensationFailuresRoute, async (c) => {
     const actor = c.get("actor");
     assertPermission(actor, "compensation:admin");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, kernel.config);
     const resolvedParsed = parseResolvedFilter(c.req.query("resolved"));
     if (!resolvedParsed.ok) {
       return c.json(
@@ -116,7 +119,7 @@ export function compensationFailureAdminRoutes(kernel: Kernel) {
   router.openapi(resolveCompensationFailureRoute, async (c) => {
     const actor = c.get("actor");
     assertPermission(actor, "compensation:admin");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, kernel.config);
     const id = c.req.param("id");
     const body = c.req.valid("json");
 
@@ -147,7 +150,7 @@ export function compensationFailureAdminRoutes(kernel: Kernel) {
     const resolved = await kernel.services.compensationFailures.markResolved({
       id,
       organizationId: orgId,
-      resolvedBy: (actor as Actor).userId,
+      resolvedBy: (actor as Actor).userId ?? "system",
       ...(body.notes !== undefined ? { notes: body.notes } : {}),
     });
     if (!resolved.ok) {

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

@@ -0,0 +1,37 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../../runtime/kernel.js";
+import { resolveOrgIdForCommerce } from "../../../../auth/org.js";
+import {
+  listCustomFieldProposalsRoute,
+} from "../../schemas/admin-custom-field-proposals.js";
+import {
+  type AppEnv,
+  parsePagination,
+  requirePerm,
+} from "../../utils.js";
+
+export function adminCustomFieldProposalRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.use("/custom-field-proposals", requirePerm("catalog:update"));
+
+  router.openapi(listCustomFieldProposalsRoute, async (c) => {
+    const pagination = parsePagination(c.req.query());
+    const entityType = c.req.query("entityType");
+    const result = await kernel.services.catalog.repository.listProposedCustomFields(
+      resolveOrgIdForCommerce(c.get("actor"), kernel.config),
+      pagination,
+      entityType !== undefined ? { entityType } : undefined,
+    );
+    return c.json({
+      data: {
+        items: result.items,
+        total: result.total,
+        page: pagination.page,
+        limit: pagination.limit,
+      },
+    });
+  });
+
+  return router;
+}

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

@@ -0,0 +1,89 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../../runtime/kernel.js";
+import type {
+  CreateEntityFieldDefinitionInput,
+  UpdateEntityFieldDefinitionInput,
+} from "../../../../modules/catalog/service.js";
+import {
+  archiveEntityFieldDefinitionRoute,
+  createEntityFieldDefinitionRoute,
+  listEntityFieldDefinitionsRoute,
+  updateEntityFieldDefinitionRoute,
+} from "../../schemas/admin-entity-field-definitions.js";
+import {
+  type AppEnv,
+  mapErrorToResponse,
+  mapErrorToStatus,
+  requirePerm,
+} from "../../utils.js";
+
+export function adminEntityFieldDefinitionRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.use("/entity-field-definitions", requirePerm("catalog:update"));
+  router.use("/entity-field-definitions/:id", requirePerm("catalog:update"));
+  router.use(
+    "/entity-field-definitions/:id/archive",
+    requirePerm("catalog:update"),
+  );
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createEntityFieldDefinitionRoute, async (c) => {
+    const result = await kernel.services.catalog.createEntityFieldDefinition(
+      c.req.valid("json") as CreateEntityFieldDefinitionInput,
+      c.get("actor"),
+    );
+    if (!result.ok)
+      return c.json(
+        mapErrorToResponse(result.error),
+        mapErrorToStatus(result.error),
+      );
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listEntityFieldDefinitionsRoute, async (c) => {
+    const entityType = c.req.query("entityType");
+    const result = await kernel.services.catalog.listEntityFieldDefinitions(
+      c.get("actor"),
+      entityType,
+    );
+    if (!result.ok)
+      return c.json(
+        mapErrorToResponse(result.error),
+        mapErrorToStatus(result.error),
+      );
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(updateEntityFieldDefinitionRoute, async (c) => {
+    const result = await kernel.services.catalog.updateEntityFieldDefinition(
+      c.req.param("id"),
+      c.req.valid("json") as UpdateEntityFieldDefinitionInput,
+      c.get("actor"),
+    );
+    if (!result.ok)
+      return c.json(
+        mapErrorToResponse(result.error),
+        mapErrorToStatus(result.error),
+      );
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(archiveEntityFieldDefinitionRoute, async (c) => {
+    const result = await kernel.services.catalog.archiveEntityFieldDefinition(
+      c.req.param("id"),
+      c.get("actor"),
+    );
+    if (!result.ok)
+      return c.json(
+        mapErrorToResponse(result.error),
+        mapErrorToStatus(result.error),
+      );
+    return c.json({ data: result.value });
+  });
+
+  return router;
+}

package/src/interfaces/rest/routes/admin/permissions.ts

@@ -3,7 +3,7 @@ import type { Kernel } from "../../../../runtime/kernel.js";
 import type { CommerceConfig } from "../../../../config/types.js";
 import { assertPermission } from "../../../../auth/permissions.js";
 import { listAdminPermissionsRoute } from "../../schemas/admin-permissions.js";
-import type { AppEnv } from "../../utils.js";
+import { type AppEnv, requirePerm } from "../../utils.js";
 
 function flattenCoreRolePermissions(config: CommerceConfig): string[] {
   const roles = config.auth?.roles ?? {};
@@ -19,6 +19,8 @@ function flattenCoreRolePermissions(config: CommerceConfig): string[] {
 export function adminPermissionsRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
+  router.use("/permissions", requirePerm("admin"));
+
   router.openapi(listAdminPermissionsRoute, (c) => {
     const actor = c.get("actor");
     assertPermission(actor, "admin");