@porulle/core 0.11.0 → 0.13.0

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,13 +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 {

package/src/interfaces/rest/utils.ts

@@ -3,6 +3,25 @@ import { mapErrorToStatus } from "../../kernel/error-mapper.js";
 import { toCommerceError } from "../../kernel/errors.js";
 import type { Actor } from "../../auth/types.js";
 
+export const ROUTE_PERMISSION_GUARD = Symbol("porulle.routePermissionGuard");
+
+type RouteGuardHandler = {
+  [ROUTE_PERMISSION_GUARD]?: { methods?: readonly string[] };
+};
+
+export function markRoutePermissionGuard<T>(handler: T, methods?: readonly string[]): T {
+  if (typeof handler === "function") {
+    Object.defineProperty(handler, ROUTE_PERMISSION_GUARD, { value: { methods } });
+  }
+  return handler;
+}
+
+type PermissionContext = {
+  get(key: string): unknown;
+  json(data: unknown, status: number): unknown;
+  req: { method: string };
+};
+
 /**
  * Shared Hono environment type for all sub-routers.
  * Matches the Variables set by middleware in the top-level server app.
@@ -61,7 +80,7 @@ export { mapErrorToStatus };
  * Usage: router.post("/", requirePerm("webhooks:manage"), handler);
  */
 export function requirePerm(permission: string) {
-  return async (c: { get(key: string): unknown; json(data: unknown, status: number): unknown }, next: () => Promise<void>) => {
+  const middleware = async (c: { get(key: string): unknown; json(data: unknown, status: number): unknown }, next: () => Promise<void>) => {
     const actor = c.get("actor") as { permissions?: string[] } | null;
     if (!actor) {
       return c.json({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }, 401);
@@ -79,6 +98,46 @@ export function requirePerm(permission: string) {
     }
     return c.json({ error: { code: "FORBIDDEN", message: `Permission '${permission}' is required.` } }, 403);
   };
+  return markRoutePermissionGuard(middleware);
+}
+
+export function requireAnyPerm(permissions: readonly string[]) {
+  const middleware = async (c: { get(key: string): unknown; json(data: unknown, status: number): unknown }, next: () => Promise<void>) => {
+    const actor = c.get("actor") as { permissions?: string[] } | null;
+    const granted = actor?.permissions ?? [];
+    const allowed = permissions.some((permission) =>
+      granted.includes(permission) ||
+      granted.includes("*:*") ||
+      granted.includes(`${permission.split(":")[0]}:*`),
+    );
+    if (!actor) {
+      return c.json({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }, 401);
+    }
+    if (allowed) {
+      await next();
+      return;
+    }
+    return c.json({ error: { code: "FORBIDDEN", message: `One of these permissions is required: ${permissions.join(", ")}.` } }, 403);
+  };
+  return markRoutePermissionGuard(middleware);
+}
+
+export function requireMethodPerm(methods: readonly string[], permission: string) {
+  const permissionGuard = requirePerm(permission);
+  const middleware = async (c: PermissionContext, next: () => Promise<void>) => {
+    if (!methods.includes(c.req.method)) {
+      await next();
+      return;
+    }
+    return permissionGuard(c, next);
+  };
+  return markRoutePermissionGuard(middleware, methods);
+}
+
+export function isRoutePermissionGuard(handler: unknown, method?: string): boolean {
+  if (typeof handler !== "function") return false;
+  const guard = (handler as unknown as RouteGuardHandler)[ROUTE_PERMISSION_GUARD];
+  return Boolean(guard && (!method || !guard.methods || guard.methods.includes(method)));
 }
 
 export function parseSort(
@@ -100,5 +159,5 @@ export function parseSort(
 }
 
 export function isUUID(value: string): boolean {
-  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
 }

package/src/kernel/compensation/executor.ts

@@ -1,4 +1,4 @@
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
 import type { CompensationContext, Step } from "./types.js";
 import type { Result } from "../result.js";
 
@@ -85,7 +85,7 @@ export async function runCompensationChain<TInput>(
           );
           if (ctx.failureRepository) {
             try {
-              const orgId = resolveOrgId(ctx.hook.actor);
+              const orgId = resolveOrgIdForCommerce(ctx.hook.actor, ctx.hook.commerceConfig);
               const recordResult = await ctx.failureRepository.record(
                 {
                   organizationId: orgId,

package/src/kernel/database/tx-context.ts

@@ -6,11 +6,19 @@ export interface TxContext<TTx = unknown> {
   tx: TTx;
   actor: Actor | null;
   requestId: string;
+  hookContext?: Record<string, unknown>;
 }
 
+export interface HookContextCarrier {
+  hookContext?: Record<string, unknown>;
+}
+
+export type CatalogWriteContext<TTx = unknown> = TxContext<TTx> | HookContextCarrier;
+
 export interface WithTransactionOptions {
   actor: Actor | null;
   requestId?: string;
+  hookContext?: Record<string, unknown>;
 }
 
 export function createTxContext<TTx>(
@@ -21,6 +29,7 @@ export function createTxContext<TTx>(
     tx,
     actor: options.actor,
     requestId: options.requestId ?? randomUUID(),
+    ...(options.hookContext ? { hookContext: options.hookContext } : {}),
   };
 }
 
@@ -44,3 +53,19 @@ export function reuseOrCreateTxContext<TTx>(
   }
   return createTxContext(tx, options);
 }
+
+function hookContextFromWriteContext(ctx?: CatalogWriteContext): Record<string, unknown> | undefined {
+  return ctx?.hookContext;
+}
+
+function isTransactionalWriteContext<TTx>(ctx: CatalogWriteContext<TTx>): ctx is TxContext<TTx> {
+  return "tx" in ctx && ctx.tx != null;
+}
+
+export function resolveWriteContextHookContext(ctx?: CatalogWriteContext): Record<string, unknown> | undefined {
+  return hookContextFromWriteContext(ctx);
+}
+
+export function isWriteContextTransactional<TTx>(ctx?: CatalogWriteContext<TTx>): ctx is TxContext<TTx> {
+  return ctx != null && isTransactionalWriteContext(ctx);
+}

package/src/kernel/hooks/create-context.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { Actor } from "../../auth/types.js";
+import type { CommerceConfig } from "../../config/types.js";
 import type { JobsAdapter } from "../jobs/adapter.js";
 import { NullJobsAdapter } from "../jobs/adapter.js";
 import type { PluginDb } from "../database/plugin-types.js";
@@ -21,6 +22,7 @@ export interface CreateHookContextArgs {
    * @deprecated Pass {@link CreateHookContextArgs.database} or {@link CreateHookContextArgs.db} instead.
    */
   kernel?: { database: { db: PluginDb } };
+  commerceConfig?: CommerceConfig | null;
 }
 
 const nullJobs = new NullJobsAdapter();
@@ -48,5 +50,6 @@ export function createHookContext(args: CreateHookContextArgs): HookContext {
     origin: args.origin ?? "rest",
     jobs: args.jobs ?? nullJobs,
     db,
+    ...(args.commerceConfig !== undefined ? { commerceConfig: args.commerceConfig } : {}),
   };
 }

package/src/kernel/hooks/types.ts

@@ -1,4 +1,5 @@
 import type { Actor } from "../../auth/types.js";
+import type { CommerceConfig } from "../../config/types.js";
 import type { JobsAdapter } from "../jobs/adapter.js";
 import type { PluginDb } from "../database/plugin-types.js";
 
@@ -40,6 +41,7 @@ export interface HookContext {
    * Populated by `createHookContext` when callers pass `db`, `database`, or `kernel`.
    */
   db: PluginDb;
+  commerceConfig?: CommerceConfig | null;
 }
 
 export type BeforeHook<TData> = (args: {

package/src/kernel/plugin/manifest.ts

@@ -2,7 +2,8 @@ import type { Hono } from "hono";
 import type { OpenAPIHono, RouteConfig } from "@hono/zod-openapi";
 import type { PluginDb } from "../database/plugin-types.js";
 import type { DatabaseAdapter } from "../database/adapter.js";
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
+import { isRoutePermissionGuard, markRoutePermissionGuard } from "../../interfaces/rest/utils.js";
 import { createScopedDb } from "../database/scoped-db.js";
 import {
   getPluginDatabaseScopeOrganizationId,
@@ -97,7 +98,7 @@ function buildPluginContextDatabase(
 ): PluginContext["database"] {
   const orgGetter = () =>
     getPluginDatabaseScopeOrganizationId() ??
-    resolveOrgId(null, undefined, commerceConfig);
+    resolveOrgIdForCommerce(null, commerceConfig);
 
   const scopedDb = createScopedDb(rawDb, orgGetter);
   const warnUnscoped = createRateLimitedUnscopedAccessWarning(logger);
@@ -288,7 +289,7 @@ export function defineCommercePlugin(
             const wrappedHandler = async (...args: unknown[]) => {
               const c = args[0] as { get?: (key: string) => unknown } | undefined;
               const actor = c?.get?.("actor");
-              const orgId = resolveOrgId(actor, undefined, k.config);
+              const orgId = resolveOrgIdForCommerce(actor, k.config);
               try {
                 return await runWithPluginDatabaseScope(orgId, async () => {
                   const out = originalHandler(...args);
@@ -305,19 +306,22 @@ export function defineCommercePlugin(
                 throw err; // re-throw so global handler still catches
               }
             };
+            const registeredHandler = isRoutePermissionGuard(originalHandler)
+              ? markRoutePermissionGuard(wrappedHandler)
+              : wrappedHandler;
 
             if ("openapi" in route) {
               // OpenAPI route: validated by Zod, appears in /api/doc
               // Hono type interop — OpenAPIHono.openapi() expects strict RouteConfig+Handler
               // generics that can't be statically resolved for dynamic plugin routes.
               // @ts-expect-error -- dynamic plugin routes cannot satisfy Hono's strict handler generics
-              (app as OpenAPIHono).openapi(route.openapi, wrappedHandler);
+              (app as OpenAPIHono).openapi(route.openapi, registeredHandler);
             } else {
               // Legacy route: raw handler, invisible to OpenAPI spec.
               // Explicit dispatch avoids casting Hono to a Record.
               // Handler cast is a single `as any` (Hono's overloaded method
               // signatures can't unify with our generic handler shape).
-              const h = wrappedHandler as any;
+              const h = registeredHandler as any;
               switch (route.method.toLowerCase()) {
                 case "get":     app.get(route.path, h); break;
                 case "post":    app.post(route.path, h); break;

package/src/modules/analytics/service.ts

@@ -9,7 +9,7 @@
 import type { CommerceConfig } from "../../config/types.js";
 import { CommerceValidationError } from "../../kernel/errors.js";
 import { Err, Ok, type Result } from "../../kernel/result.js";
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
 import type { Actor } from "../../auth/types.js";
 import type { ReportParams, RetailReportsEngine } from "./reports.js";
 import { RETAIL_REPORTS } from "./reports.js";
@@ -135,7 +135,7 @@ export class AnalyticsService {
     if (!this.deps.reports) {
       return Err(new CommerceValidationError("Retail reports are not available."));
     }
-    const orgId = resolveOrgId(actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? null, this.deps.config);
     return this.deps.reports.run(name, params, orgId);
   }
 

package/src/modules/audit/service.ts

@@ -3,7 +3,7 @@ import type { InferSelectModel } from "drizzle-orm";
 import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
 import type { TxContext } from "../../kernel/database/tx-context.js";
 import type { HookContext } from "../../kernel/hooks/types.js";
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
 import { auditLog } from "./schema.js";
 
 export type AuditEntry = InferSelectModel<typeof auditLog>;
@@ -47,7 +47,7 @@ export function createNullAuditService(): AuditService {
     async record(args) {
       entries.push({
         id: crypto.randomUUID(),
-        organizationId: resolveOrgId(args.ctx.actor),
+        organizationId: resolveOrgIdForCommerce(args.ctx.actor, args.ctx.commerceConfig),
         entityType: args.entityType,
         entityId: args.entityId,
         event: args.event,
@@ -94,7 +94,7 @@ export function createAuditService(db: DrizzleDatabase): AuditService {
           : db;
 
       await dbOrTx.insert(auditLog).values({
-        organizationId: resolveOrgId(ctx.actor),
+        organizationId: resolveOrgIdForCommerce(ctx.actor, ctx.commerceConfig),
         entityType,
         entityId,
         event,

package/src/modules/cart/repository/index.ts

@@ -130,34 +130,48 @@ export class CartRepository {
   }
 
   /**
-   * Atomically transitions a cart from "active" to "checking_out".
-   * Returns the updated cart if the transition succeeded, or undefined if
-   * the cart was not in "active" status (e.g., a concurrent checkout already
-   * claimed it). This prevents TOCTOU race conditions on double-checkout.
+   * Atomically transitions a cart from "active" to "checking_out" and records
+   * `claimToken` as the holder of that claim. Returns the updated cart if the
+   * transition succeeded, or undefined if the cart was not in "active" status
+   * (e.g., a concurrent checkout already claimed it). This prevents TOCTOU race
+   * conditions on double-checkout.
    */
   async transitionToCheckingOut(
     id: string,
+    claimToken: string,
     ctx?: TxContext,
   ): Promise<Cart | undefined> {
     const db = this.getDb(ctx);
     const rows = await db
       .update(carts)
-      .set({ status: "checking_out", updatedAt: new Date() })
+      .set({ status: "checking_out", checkoutClaimToken: claimToken, updatedAt: new Date() })
       .where(and(eq(carts.id, id), eq(carts.status, "active")))
       .returning();
     return rows[0];
   }
 
-  /** Release only an in-progress checkout claim; terminal cart states are untouched. */
+  /**
+   * Release an in-progress checkout claim held by `claimToken`. Terminal cart
+   * states are untouched, and so is a claim held by a different checkout
+   * attempt — a losing attempt's failure path must not reopen the cart the
+   * winner is still checking out.
+   */
   async releaseCheckoutClaim(
     id: string,
+    claimToken: string,
     ctx?: TxContext,
   ): Promise<Cart | undefined> {
     const db = this.getDb(ctx);
     const rows = await db
       .update(carts)
-      .set({ status: "active", updatedAt: new Date() })
-      .where(and(eq(carts.id, id), eq(carts.status, "checking_out")))
+      .set({ status: "active", checkoutClaimToken: null, updatedAt: new Date() })
+      .where(
+        and(
+          eq(carts.id, id),
+          eq(carts.status, "checking_out"),
+          eq(carts.checkoutClaimToken, claimToken),
+        ),
+      )
       .returning();
     return rows[0];
   }

package/src/modules/cart/schema.ts

@@ -15,6 +15,10 @@ export const carts = pgTable("carts", {
   // Shopper contact for guest carts — enables abandoned-checkout recovery
   email: text("email"),
   secret: text("secret"),
+  // Owner of an in-progress `checking_out` claim. Minted by the checkout
+  // attempt that wins the CAS; only that holder may release the claim, so a
+  // losing attempt's failure path cannot unwind the winner's claim.
+  checkoutClaimToken: text("checkout_claim_token"),
   metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
   expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
   createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),