@porulle/core 0.11.0 → 0.13.0

package/src/interfaces/rest/customer-portal.ts

@@ -1,6 +1,6 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../runtime/kernel.js";
-import { assertPermission } from "../../auth/permissions.js";
+import { assertPermission, requireUserId } from "../../auth/permissions.js";
 import type { Actor } from "../../auth/types.js";
 import type { AppEnv } from "./utils.js";
 import {
@@ -16,27 +16,30 @@ import {
   updateProfileRoute,
   createAddressRoute,
 } from "./schemas/customer-portal.js";
-import { isUUID, mapErrorToStatus } from "./utils.js";
+import { isUUID, mapErrorToStatus, markRoutePermissionGuard } from "./utils.js";
+
+type AuthenticatedActor = Actor & { userId: string };
 
 export function createCustomerPortalRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
-  router.use("*", async (c, next) => {
-    if (!c.get("actor")) {
+  router.use("*", markRoutePermissionGuard(async (c, next) => {
+    const actor = c.get("actor") as Actor | null;
+    if (!actor?.userId) {
       return c.json(
         { error: { code: "FORBIDDEN", message: "Authentication required." } },
         401,
       );
     }
     await next();
-  });
+  }));
 
   /**
    * Resolves an actor whose userId is the customer profile UUID (not the Better Auth user ID).
    * Required so that `assertOwnership(actor, order.customerId)` compares UUIDs correctly,
    * since orders.customer_id stores the customer profile UUID, not the Better Auth string ID.
    */
-  async function resolveCustomerActor(actor: Actor): Promise<Actor | null> {
+  async function resolveCustomerActor(actor: AuthenticatedActor): Promise<AuthenticatedActor | null> {
     const customer = await kernel.services.customers.getByUserId(actor.userId, actor);
     if (!customer.ok) return null;
     return { ...actor, userId: customer.value.id };
@@ -44,7 +47,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getProfileRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const customer = await kernel.services.customers.getByUserId(actor.userId, actor);
     if (!customer.ok) return c.json({ error: customer.error }, 404);
     return c.json({ data: customer.value });
@@ -52,7 +55,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(updateProfileRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     assertPermission(actor, "customers:update:self");
     const result = await kernel.services.customers.updateByUserId(
       actor.userId,
@@ -64,7 +67,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
   });
 
   router.openapi(listAddressesRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const addresses = await kernel.services.customers.getAddresses(
       actor.userId,
       actor,
@@ -74,7 +77,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(createAddressRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const result = await kernel.services.customers.addAddress(
       actor.userId,
       c.req.valid("json") as Parameters<typeof kernel.services.customers.addAddress>[1],
@@ -86,7 +89,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(deleteAddressRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const result = await kernel.services.customers.deleteAddress(
       actor.userId,
       c.req.param("id"),
@@ -98,23 +101,27 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listCustomerOrdersRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const status = c.req.query("status");
     // Resolve customer profile UUID from Better Auth userId
     const customerResult = await kernel.services.customers.getByUserId(actor.userId, actor);
     if (!customerResult.ok) return c.json({ data: [], meta: { total: 0, page: 1, limit: 20, totalPages: 0 } });
-    const result = await kernel.services.orders.listByCustomer(customerResult.value.id, {
-      page: Number.parseInt(c.req.query("page") ?? "1", 10),
-      limit: Number.parseInt(c.req.query("limit") ?? "20", 10),
-      ...(status !== undefined ? { status } : {}),
-    });
-    if (!result.ok) return c.json({ error: result.error }, 500);
+    const result = await kernel.services.orders.listByCustomer(
+      customerResult.value.id,
+      {
+        page: Number.parseInt(c.req.query("page") ?? "1", 10),
+        limit: Number.parseInt(c.req.query("limit") ?? "20", 10),
+        ...(status !== undefined ? { status } : {}),
+      },
+      actor,
+    );
+    if (!result.ok) return c.json({ error: result.error }, mapErrorToStatus(result.error));
     return c.json({ data: result.value.items, meta: result.value.pagination });
   });
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getCustomerOrderRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const id = c.req.param("idOrNumber");
     const customerActor = await resolveCustomerActor(actor);
     if (!customerActor) return c.json({ error: { code: "NOT_FOUND", message: "Customer profile not found." } }, 404);
@@ -129,7 +136,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getOrderTrackingRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const id = c.req.param("idOrNumber");
     const customerActor = await resolveCustomerActor(actor);
     if (!customerActor) return c.json({ error: { code: "NOT_FOUND", message: "Customer profile not found." } }, 404);
@@ -167,7 +174,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getOrderDownloadsRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const customerActor = await resolveCustomerActor(actor);
     if (!customerActor) return c.json({ error: { code: "NOT_FOUND", message: "Customer profile not found." } }, 404);
     const orderResult = await kernel.services.orders.getById(
@@ -209,7 +216,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listCoursesRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const result = await kernel.services.fulfillment.getDigitalAccess(
       actor.userId,
       "course",
@@ -230,7 +237,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(reorderRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const customerActor = await resolveCustomerActor(actor);
     if (!customerActor) return c.json({ error: { code: "NOT_FOUND", message: "Customer profile not found." } }, 404);
     const orderResult = await kernel.services.orders.getById(
@@ -246,7 +253,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
     const cartResult = await kernel.services.cart.create(
       {
-        customerId: actor.userId,
+        customerId: requireUserId(actor),
         currency: orderResult.value.currency,
       },
       actor,

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

@@ -1,6 +1,6 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../../runtime/kernel.js";
-import { resolveOrgId } from "../../../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../../../auth/org.js";
 import {
   listCustomFieldProposalsRoute,
 } from "../../schemas/admin-custom-field-proposals.js";
@@ -19,7 +19,7 @@ export function adminCustomFieldProposalRoutes(kernel: Kernel) {
     const pagination = parsePagination(c.req.query());
     const entityType = c.req.query("entityType");
     const result = await kernel.services.catalog.repository.listProposedCustomFields(
-      resolveOrgId(c.get("actor")),
+      resolveOrgIdForCommerce(c.get("actor"), kernel.config),
       pagination,
       entityType !== undefined ? { entityType } : undefined,
     );

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");