@porulle/core 0.11.0 → 0.14.0

package/src/auth/types.ts

@@ -1,6 +1,6 @@
 export interface Actor {
   type: "user" | "api_key";
-  userId: string;
+  userId: string | null;
   email: string | null;
   name: string;
   vendorId: string | null;

package/src/config/defaults.ts

@@ -24,10 +24,12 @@ export const defaultConfig: Partial<CommerceConfig> = {
           "catalog:update",
           "catalog:delete",
           "catalog:read",
+          "catalog:read:unpublished",
           "inventory:read",
           "inventory:adjust",
           "orders:read",
           "orders:create",
+          "orders:create:on-behalf",
           "orders:update",
           "orders:manage",
           "cart:create",

package/src/config/types.ts

@@ -200,10 +200,17 @@ export interface AuthConfig {
    */
   storeResolver?: (request: Request) => string | null | Promise<string | null>;
   /**
-   * When true, a failing `storeResolver` for anonymous requests returns HTTP 503
-   * instead of continuing with `actor = null` (legacy). Same behavior when env
-   * `STRICT_ORG_RESOLUTION` is `"true"`. Default false keeps backward-compatible
-   * fallback for single-store and lenient multi-store setups.
+   * Governs two layers, and its default differs between them.
+   *
+   * In the store-resolver middleware, `true` makes a failing `storeResolver`
+   * return HTTP 503 rather than continuing with `actor = null`; that layer
+   * still defaults to the lenient behaviour.
+   *
+   * In organization resolution it **fails closed by default**: an actor-less
+   * request with no explicit organization and no `defaultOrganizationId` is
+   * refused rather than served a fallback tenant. Set this to `false`, or the
+   * env var `STRICT_ORG_RESOLUTION` to `"false"`, to restore the old fallback
+   * during a migration.
    */
   strictOrgResolution?: boolean;
   /**
@@ -258,7 +265,25 @@ export interface CheckoutConfig {
   };
 }
 
+/**
+ * Decides whether a guest bearer credential (a cart secret) may still read a
+ * placed order. The authenticated customer who owns an order is never subject
+ * to this — ownership grants permanent access.
+ *
+ * Modelled on Vendure's `OrderByCodeAccessStrategy`: the value of the seam is
+ * that the policy has one home, rather than being an emergent property of the
+ * read path.
+ */
+export interface GuestOrderAccessStrategy {
+  canAccessOrder(order: { placedAt: Date }, now: Date): boolean;
+}
+
 export interface OrdersConfig {
+  /**
+   * How long a guest cart secret keeps reading an order after placement.
+   * Defaults to `windowedGuestOrderAccess("7d")`.
+   */
+  guestAccessStrategy?: GuestOrderAccessStrategy;
   hooks?: {
     beforeCreate?: BeforeHook<unknown>[];
     afterCreate?: AfterHook<unknown>[];
@@ -428,6 +453,8 @@ export interface CommerceConfig {
     api?: number;
     /** Requests per minute for auth endpoints. Default: 10. */
     auth?: number;
+    /** Requests per minute for session reads. Default: 120. */
+    session?: number;
     /** Requests per minute for checkout. Default: 5. */
     checkout?: number;
     /** Attempts per 15 minutes for sign-in per email. Default: 10. */

package/src/hooks/checkout.ts

@@ -1,5 +1,5 @@
 import { CommerceValidationError } from "../kernel/errors.js";
-import { resolveOrgId } from "../auth/org.js";
+import { resolveOrgIdForCommerce } from "../auth/org.js";
 import type { CompensationFailuresRepository } from "../kernel/compensation/repository.js";
 import type { AfterHook, BeforeHook } from "../kernel/hooks/types.js";
 import type { ShippingAddress } from "../modules/shipping/calculator.js";
@@ -97,7 +97,7 @@ export const validateCartNotEmpty: BeforeHook<CheckoutData> = async ({
   context,
 }) => {
   const cartService = context.services.cart as {
-    getById(id: string, actor?: unknown): Promise<
+    getByIdForInternalUse(id: string, organizationId: string, ctx?: TxContext): Promise<
       | {
           ok: true;
           value: {
@@ -114,7 +114,7 @@ export const validateCartNotEmpty: BeforeHook<CheckoutData> = async ({
         }
       | { ok: false }
     >;
-    claimForCheckout(cartId: string, ctx?: unknown): Promise<
+    claimForCheckout(cartId: string, claimToken: string, ctx?: unknown): Promise<
       | { ok: true; value: { id: string } }
       | { ok: false; error: { message: string } }
     >;
@@ -122,7 +122,9 @@ export const validateCartNotEmpty: BeforeHook<CheckoutData> = async ({
   const catalogService = context.services.catalog as {
     getById(
       id: string,
-      options?: { includeAttributes?: boolean },
+      options: { includeAttributes?: boolean } | undefined,
+      actor: unknown,
+      ctx?: TxContext,
     ): Promise<
       | {
           ok: true;
@@ -137,20 +139,25 @@ export const validateCartNotEmpty: BeforeHook<CheckoutData> = async ({
 
   // M1 fix: Atomically claim the cart for checkout (active → checking_out).
   // If a concurrent request already claimed it, this returns Err and we fail fast.
-  const claimed = await cartService.claimForCheckout(data.cartId, context.tx);
+  // The checkout id is the claim token, so only this attempt can release it.
+  const claimed = await cartService.claimForCheckout(data.cartId, data.checkoutId, context.tx);
   if (!claimed.ok) {
     throw new CommerceValidationError(
       "Cart is not available for checkout. It may have already been checked out by a concurrent request.",
     );
   }
 
-  const cart = await cartService.getById(data.cartId, context.actor);
+  const cart = await cartService.getByIdForInternalUse(
+    data.cartId,
+    resolveOrgIdForCommerce(context.actor, context.commerceConfig),
+    context.tx as TxContext | undefined,
+  );
   if (!cart.ok || cart.value.lineItems.length === 0) {
     throw new CommerceValidationError("Cannot checkout an empty cart.");
   }
 
   // Cross-org guard: prevent org B from checking out org A's cart
-  const actorOrgId = resolveOrgId(context.actor);
+  const actorOrgId = resolveOrgIdForCommerce(context.actor, context.commerceConfig);
   if (cart.value.organizationId && cart.value.organizationId !== actorOrgId) {
     throw new CommerceValidationError("Cart does not belong to this organization.");
   }
@@ -174,7 +181,7 @@ export const validateCartNotEmpty: BeforeHook<CheckoutData> = async ({
     cart.value.lineItems.map(async (item) => {
       const entity = await catalogService.getById(item.entityId, {
         includeAttributes: true,
-      });
+      }, context.actor, context.tx as TxContext | undefined);
       const title = entity.ok
         ? (entity.value.attributes?.[0]?.title ?? item.entityId)
         : item.entityId;
@@ -323,7 +330,7 @@ export const applyPromotionCodes: BeforeHook<CheckoutData> = async ({
   };
 
   const result = await promotions.applyPromotions({
-    orgId: resolveOrgId(context.actor),
+    orgId: resolveOrgIdForCommerce(context.actor, context.commerceConfig),
     cartId: data.cartId,
     currency: data.currency,
     subtotal: data.subtotal,
@@ -411,7 +418,7 @@ export const calculateTax: BeforeHook<CheckoutData> = async ({
     ...(data.shippingAddress !== undefined
       ? { toAddress: data.shippingAddress }
       : {}),
-  }, resolveOrgId(context.actor ?? null));
+  }, resolveOrgIdForCommerce(context.actor ?? null, context.commerceConfig));
 
   if (!calculated.ok) {
     throw new CommerceValidationError(
@@ -469,7 +476,7 @@ export const calculateShipping: BeforeHook<CheckoutData> = async ({
     })),
     subtotalAfterDiscount: Math.max(0, data.subtotal - data.discountTotal),
     currency: data.currency,
-    orgId: resolveOrgId(context.actor ?? null),
+    orgId: resolveOrgIdForCommerce(context.actor ?? null, context.commerceConfig),
     ...(data.shippingAddress !== undefined
       ? { address: data.shippingAddress }
       : {}),
@@ -546,7 +553,7 @@ export const authorizePayment: BeforeHook<CheckoutData> = async ({
       : {}),
     metadata: {
       ...(data.orderId !== undefined ? { orderId: data.orderId } : {}),
-      organizationId: resolveOrgId(context.actor),
+      organizationId: resolveOrgIdForCommerce(context.actor, context.commerceConfig),
       checkoutId: data.checkoutId,
       cartId: data.cartId,
     },

package/src/index.ts

@@ -3,6 +3,7 @@ export type {
   CommerceConfig,
   CommercePlugin,
   ApiKeyScopeDefinition,
+  GuestOrderAccessStrategy,
 } from "./config/types.js";
 export { defineCommercePlugin } from "./kernel/plugin/manifest.js";
 export type {
@@ -31,12 +32,17 @@ export type { Kernel } from "./runtime/kernel.js";
 // This avoids pulling drizzle-kit/tsx/esbuild into Turbopack's bundle graph.
 
 export type { Actor } from "./auth/types.js";
-export { resolveOrgId, ensureDefaultOrg, DEFAULT_ORG_ID } from "./auth/org.js";
+export {
+  AUTH_COOKIE_PREFIX,
+  resolveActor,
+  SESSION_COOKIE_NAME,
+} from "./auth/actor.js";
+export { resolveOrgId, resolveOrgIdForCommerce, ensureDefaultOrg, DEFAULT_ORG_ID } from "./auth/org.js";
 export { createSystemActor } from "./auth/system-actor.js";
 export { OrganizationService } from "./modules/organization/service.js";
 export { createScopedDb } from "./kernel/database/scoped-db.js";
 export type { ScopedOrganizationId } from "./kernel/database/scoped-db.js";
-export { assertOwnership, assertPermission } from "./auth/permissions.js";
+export { assertOwnership, assertPermission, requireUserId } from "./auth/permissions.js";
 export type { AccessResult, AccessContext, AccessFn, WhereClause } from "./auth/access.js";
 export {
   accessOR,
@@ -183,14 +189,18 @@ export type {
 export type { DatabaseAdapter } from "./kernel/database/adapter.js";
 export { isValidFieldPath, validateFieldPath } from "./modules/catalog/ownership.js";
 export type { FieldPath, FieldOwner } from "./modules/catalog/ownership.js";
+export type {
+  TxContext,
+  WithTransactionOptions,
+  CatalogWriteContext,
+  HookContextCarrier,
+} from "./kernel/database/tx-context.js";
 export {
   createTxContext,
   reuseOrCreateTxContext,
   withTransaction,
-} from "./kernel/database/tx-context.js";
-export type {
-  TxContext,
-  WithTransactionOptions,
+  isWriteContextTransactional,
+  resolveWriteContextHookContext,
 } from "./kernel/database/tx-context.js";
 export type {
   TaxAdapter,
@@ -249,6 +259,11 @@ export type { QueryInput, QueryResult } from "./kernel/query/executor.js";
 export type { CommerceModuleTypes } from "./types/commerce-types.js";
 
 export { staleOrderCleanupTask } from "./modules/orders/stale-order-cleanup.js";
+export {
+  windowedGuestOrderAccess,
+  defaultGuestOrderAccess,
+  parseAccessWindow,
+} from "./modules/orders/guest-access.js";
 export { COMMERCE_AGENT_SYSTEM_PROMPT } from "./utils/agent-prompt.js";
 
 export { DrizzleAnalyticsAdapter } from "./modules/analytics/drizzle-adapter.js";

package/src/interfaces/rest/audit-middleware.ts

@@ -95,12 +95,14 @@ export function auditMiddleware(kernel: Kernel): MiddlewareHandler {
     try {
       const requestId = c.get("requestId") as string | undefined;
       const ctx = createHookContext({
+        // Anonymous audit records retain actor: null; organization comes from the deployment config.
         actor: (c.get("actor") as Actor | null) ?? null,
         ...(requestId ? { requestId } : {}),
         logger: kernel.logger,
         services: kernel.services as unknown as ServiceContainer,
         database: { db: kernel.database.db as unknown as PluginDb },
         origin: "rest",
+        commerceConfig: kernel.config,
       });
       await kernel.services.audit.record({ entityType, entityId, event, payload, ctx });
     } catch {

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