@porulle/core 0.11.0 → 0.13.0

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

@@ -4,7 +4,7 @@ import type { Kernel } from "../../../../runtime/kernel.js";
 import type { CommerceConfig } from "../../../../config/types.js";
 import type { DrizzleDatabase } from "../../../../kernel/database/drizzle-db.js";
 import { member, user, invitation } from "../../../../auth/auth-schema.js";
-import { resolveOrgId } from "../../../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../../../auth/org.js";
 import { makeId } from "../../../../utils/id.js";
 import {
   listStaffRoute,
@@ -15,6 +15,15 @@ import {
   updateStaffRoleRoute,
   revokeStaffRoute,
 } from "../../schemas/admin-staff.js";
+import type { Actor } from "../../../../auth/types.js";
+import {
+  canGrantRole,
+  granterForRole,
+  isCompositeRole,
+  isOwnerRole,
+  roleRank,
+  validRoles,
+} from "../../../../auth/role-authority.js";
 import { type AppEnv, requirePerm } from "../../utils.js";
 
 /**
@@ -34,39 +43,28 @@ export function adminStaffRoutes(kernel: Kernel) {
   router.use("/staff/invitations", requirePerm("staff:manage"));
   router.use("/staff/roles", requirePerm("staff:manage"));
 
-  function validRoles(): Set<string> {
-    return new Set([
-      ...Object.keys(config.auth?.roles ?? {}),
-      "owner",
-      "admin",
-      "member",
-    ]);
-  }
-
   function invalidRole(c: { json: (d: unknown, s: number) => unknown }, role: string) {
     return c.json(
       {
         error: {
           code: "VALIDATION_FAILED",
-          message: `Unknown role "${role}". Valid roles: ${[...validRoles()].join(", ")}.`,
+          message: `Unknown role "${role}". Valid roles: ${[...validRoles(config)].join(", ")}.`,
         },
       },
       422,
     );
   }
 
-  const BUILTIN_ROLE_RANK: Record<string, number> = {
-    owner: 3,
-    admin: 2,
-  };
-  const CUSTOM_ROLE_RANK = 1;
-
-  function roleRank(role: string): number {
-    return BUILTIN_ROLE_RANK[role] ?? CUSTOM_ROLE_RANK;
+  function rankOf(role: string | null | undefined): number {
+    return roleRank(config, role);
   }
 
-  function canGrantRole(actorRole: string, targetRole: string): boolean {
-    return roleRank(actorRole) >= roleRank(targetRole);
+  function actorCanGrantRole(actor: Actor | null, targetRole: string): boolean {
+    return canGrantRole(
+      config,
+      actor ? { role: actor.role, permissions: actor.permissions } : null,
+      targetRole,
+    );
   }
 
   function insufficientPrivilege(
@@ -84,16 +82,81 @@ export function adminStaffRoutes(kernel: Kernel) {
     );
   }
 
-  async function countOwners(orgId: string): Promise<number> {
-    const rows = await db
-      .select({ id: member.id })
-      .from(member)
-      .where(and(eq(member.organizationId, orgId), eq(member.role, "owner")));
-    return rows.length;
+  /**
+   * Runs a membership mutation with the organization's member rows locked, so
+   * the last-owner check and the write it guards cannot be interleaved.
+   *
+   * Counting owners and then mutating as two statements let two owners revoke
+   * each other concurrently: both read `count = 2`, both proceed, and the
+   * organization is left with none. The lock makes the second transaction
+   * re-read after the first commits, so it sees the count it must respect.
+   *
+   * The whole member set is locked, not just the owner rows, because an owner
+   * is any member whose role string contains `owner` — a predicate SQL cannot
+   * express as cheaply as the JS filter below. Membership writes are rare
+   * administrative actions, so serialising them per organization is free.
+   * `ORDER BY id` fixes the lock order and keeps two concurrent revocations
+   * from deadlocking each other.
+   */
+  async function withMembershipLock<T>(
+    orgId: string,
+    run: (tx: DrizzleDatabase, ownerIds: string[]) => Promise<T>,
+  ): Promise<T> {
+    return kernel.database.transaction(async (raw) => {
+      const tx = raw as DrizzleDatabase;
+      const locked = await tx
+        .select({ id: member.id, role: member.role })
+        .from(member)
+        .where(eq(member.organizationId, orgId))
+        .orderBy(member.id)
+        .for("update");
+      const ownerIds = locked
+        .filter((row) => isOwnerRole(row.role))
+        .map((row) => row.id);
+      return run(tx, ownerIds);
+    });
+  }
+
+  /**
+   * Cancels the member's pending invitations that their role can no longer
+   * grant. Acceptance re-checks the inviter's authority too, so this is not
+   * what closes the takeover — it keeps the invitation list honest and stops a
+   * dead grant sitting there for the rest of its seven-day life.
+   *
+   * `newRole` is null when the membership is being revoked outright.
+   */
+  async function cancelUngrantableInvitations(
+    orgId: string,
+    inviterUserId: string,
+    newRole: string | null,
+  ): Promise<void> {
+    const pending = await db
+      .select({ id: invitation.id, role: invitation.role })
+      .from(invitation)
+      .where(
+        and(
+          eq(invitation.organizationId, orgId),
+          eq(invitation.inviterId, inviterUserId),
+          eq(invitation.status, "pending"),
+        ),
+      );
+
+    const dead = pending.filter(
+      (row) =>
+        newRole === null ||
+        !canGrantRole(config, granterForRole(config, newRole), row.role ?? "member"),
+    );
+
+    for (const row of dead) {
+      await db
+        .update(invitation)
+        .set({ status: "canceled" })
+        .where(eq(invitation.id, row.id));
+    }
   }
 
   router.openapi(listStaffRoute, async (c) => {
-    const orgId = resolveOrgId(c.get("actor"));
+    const orgId = resolveOrgIdForCommerce(c.get("actor"), config);
     const rows = await db
       .select({
         id: member.id,
@@ -113,10 +176,10 @@ export function adminStaffRoutes(kernel: Kernel) {
   router.openapi(createStaffRoute, async (c) => {
     const body = c.req.valid("json") as { userId: string; role: string };
     const actor = c.get("actor");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, config);
 
-    if (!validRoles().has(body.role)) return invalidRole(c, body.role);
-    if (!canGrantRole(actor!.role, body.role)) return insufficientPrivilege(c, body.role);
+    if (isCompositeRole(body.role) || !validRoles(config).has(body.role)) return invalidRole(c, body.role);
+    if (!actorCanGrantRole(actor, body.role)) return insufficientPrivilege(c, body.role);
 
     const users = await db.select().from(user).where(eq(user.id, body.userId));
     if (users.length === 0) {
@@ -151,10 +214,10 @@ export function adminStaffRoutes(kernel: Kernel) {
   router.openapi(inviteStaffRoute, async (c) => {
     const body = c.req.valid("json") as { email: string; role: string };
     const actor = c.get("actor");
-    const orgId = resolveOrgId(actor);
-
-    if (!validRoles().has(body.role)) return invalidRole(c, body.role);
+    const orgId = resolveOrgIdForCommerce(actor, config);
 
+    if (isCompositeRole(body.role) || !validRoles(config).has(body.role)) return invalidRole(c, body.role);
+    if (!actorCanGrantRole(actor, body.role)) return insufficientPrivilege(c, body.role);
     const rows = await db
       .insert(invitation)
       .values({
@@ -164,14 +227,14 @@ export function adminStaffRoutes(kernel: Kernel) {
         role: body.role,
         status: "pending",
         expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
-        inviterId: actor!.userId,
+        inviterId: actor?.userId ?? "system",
       })
       .returning();
     return c.json({ data: rows[0] }, 201);
   });
 
   router.openapi(listStaffInvitationsRoute, async (c) => {
-    const orgId = resolveOrgId(c.get("actor"));
+    const orgId = resolveOrgIdForCommerce(c.get("actor"), config);
     const rows = await db
       .select()
       .from(invitation)
@@ -192,67 +255,93 @@ export function adminStaffRoutes(kernel: Kernel) {
   router.openapi(updateStaffRoleRoute, async (c) => {
     const body = c.req.valid("json") as { role: string };
     const actor = c.get("actor");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, config);
     const id = c.req.param("id");
 
-    if (!validRoles().has(body.role)) return invalidRole(c, body.role);
-    if (!canGrantRole(actor!.role, body.role)) return insufficientPrivilege(c, body.role);
-
-    const rows = await db
-      .select()
-      .from(member)
-      .where(and(eq(member.organizationId, orgId), eq(member.id, id)));
-    const target = rows[0];
-    if (!target) {
+    if (isCompositeRole(body.role) || !validRoles(config).has(body.role)) return invalidRole(c, body.role);
+    if (!actorCanGrantRole(actor, body.role)) return insufficientPrivilege(c, body.role);
+
+    const outcome = await withMembershipLock(orgId, async (tx, ownerIds) => {
+      const rows = await tx
+        .select()
+        .from(member)
+        .where(and(eq(member.organizationId, orgId), eq(member.id, id)));
+      const target = rows[0];
+      if (!target) return { kind: "not-found" } as const;
+
+      // SEC-18/R-02: the actor must also outrank (or equal) the target's CURRENT
+      // role, else an admin could demote an owner they do not outrank.
+      if (rankOf(actor!.role) < rankOf(target.role)) {
+        return { kind: "outranked", role: target.role } as const;
+      }
+
+      if (isOwnerRole(target.role) && !isOwnerRole(body.role) && ownerIds.length <= 1) {
+        return { kind: "last-owner" } as const;
+      }
+
+      const updated = await tx
+        .update(member)
+        .set({ role: body.role })
+        .where(eq(member.id, id))
+        .returning();
+      return { kind: "updated", target, row: updated[0] } as const;
+    });
+
+    if (outcome.kind === "not-found") {
       return c.json({ error: { code: "NOT_FOUND", message: "Staff member not found." } }, 404);
     }
-
-    // SEC-18/R-02: the actor must also outrank (or equal) the target's CURRENT
-    // role, else an admin could demote an owner they do not outrank.
-    if (!canGrantRole(actor!.role, target.role)) return insufficientPrivilege(c, target.role);
-
-    if (target.role === "owner" && body.role !== "owner" && (await countOwners(orgId)) <= 1) {
+    if (outcome.kind === "outranked") return insufficientPrivilege(c, outcome.role);
+    if (outcome.kind === "last-owner") {
       return c.json(
         { error: { code: "VALIDATION_FAILED", message: "Cannot demote the organization's last owner." } },
         422,
       );
     }
 
-    const updated = await db
-      .update(member)
-      .set({ role: body.role })
-      .where(eq(member.id, id))
-      .returning();
-    return c.json({ data: updated[0] });
+    await cancelUngrantableInvitations(orgId, outcome.target.userId, body.role);
+    return c.json({ data: outcome.row });
   });
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(revokeStaffRoute, async (c) => {
     const actor = c.get("actor");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, config);
     const id = c.req.param("id");
 
-    const rows = await db
-      .select()
-      .from(member)
-      .where(and(eq(member.organizationId, orgId), eq(member.id, id)));
-    const target = rows[0];
-    if (!target) {
+    const outcome = await withMembershipLock(orgId, async (tx, ownerIds) => {
+      const rows = await tx
+        .select()
+        .from(member)
+        .where(and(eq(member.organizationId, orgId), eq(member.id, id)));
+      const target = rows[0];
+      if (!target) return { kind: "not-found" } as const;
+
+      // SEC-18/R-02: the actor must outrank (or equal) the target's current role
+      // to revoke it — an admin cannot revoke an owner.
+      if (rankOf(actor!.role) < rankOf(target.role)) {
+        return { kind: "outranked", role: target.role } as const;
+      }
+
+      if (isOwnerRole(target.role) && ownerIds.length <= 1) {
+        return { kind: "last-owner" } as const;
+      }
+
+      await tx.delete(member).where(eq(member.id, id));
+      return { kind: "deleted", target } as const;
+    });
+
+    if (outcome.kind === "not-found") {
       return c.json({ error: { code: "NOT_FOUND", message: "Staff member not found." } }, 404);
     }
-
-    // SEC-18/R-02: the actor must outrank (or equal) the target's current role
-    // to revoke it — an admin cannot revoke an owner.
-    if (!canGrantRole(actor!.role, target.role)) return insufficientPrivilege(c, target.role);
-
-    if (target.role === "owner" && (await countOwners(orgId)) <= 1) {
+    if (outcome.kind === "outranked") return insufficientPrivilege(c, outcome.role);
+    if (outcome.kind === "last-owner") {
       return c.json(
         { error: { code: "VALIDATION_FAILED", message: "Cannot revoke the organization's last owner." } },
         422,
       );
     }
 
-    await db.delete(member).where(eq(member.id, id));
+    await cancelUngrantableInvitations(orgId, outcome.target.userId, null);
     return c.json({ data: { deleted: true } });
   });
 

package/src/interfaces/rest/routes/admin-jobs.ts

@@ -5,7 +5,7 @@ import type { Kernel } from "../../../runtime/kernel.js";
 import { commerceJobs } from "../../../kernel/jobs/schema.js";
 import { listFailedJobsRoute, retryJobRoute } from "../schemas/admin-jobs.js";
 import { type AppEnv, requirePerm } from "../utils.js";
-import { resolveOrgId } from "../../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../../auth/org.js";
 
 type Db = PgDatabase<PgQueryResultHKT, Record<string, unknown>>;
 
@@ -17,7 +17,7 @@ export function adminJobRoutes(kernel: Kernel) {
 
   router.openapi(listFailedJobsRoute, async (c) => {
     const actor = c.get("actor");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, kernel.config);
     const limit = Math.min(Number(c.req.query("limit") ?? "50"), 100);
     const conditions = [eq(commerceJobs.status, "failed")];
     // Scope to org unless wildcard admin
@@ -37,7 +37,7 @@ export function adminJobRoutes(kernel: Kernel) {
   // @ts-expect-error -- openapi handler union return type
   router.openapi(retryJobRoute, async (c) => {
     const actor = c.get("actor");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, kernel.config);
     const id = c.req.param("id");
     const conditions = [eq(commerceJobs.id, id)];
     // Scope to org unless wildcard admin

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

@@ -2,7 +2,7 @@ import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../runtime/kernel.js";
 import { listAuditRoute, listEntityAuditRoute } from "../schemas/audit.js";
 import { type AppEnv, requirePerm } from "../utils.js";
-import { resolveOrgId } from "../../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../../auth/org.js";
 
 export function auditRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
@@ -15,7 +15,7 @@ export function auditRoutes(kernel: Kernel) {
 
   router.openapi(listAuditRoute, async (c) => {
     const actor = c.get("actor");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, kernel.config);
     const entries = await kernel.services.audit.list({
       organizationId: orgId,
       entityType: c.req.query("entityType"),
@@ -37,7 +37,7 @@ export function auditRoutes(kernel: Kernel) {
 
   router.openapi(listEntityAuditRoute, async (c) => {
     const actor = c.get("actor");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, kernel.config);
     const entries = await kernel.services.audit.listForEntity({
       organizationId: orgId,
       entityType: c.req.param("entityType"),

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

@@ -2,16 +2,22 @@ import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../runtime/kernel.js";
 import type { CreateCartInput, AddCartItemInput } from "../../../modules/cart/schemas.js";
 import { createCartRoute, addCartItemRoute, updateCartItemQuantityRoute, getCartRoute, removeCartItemRoute, listCartsRoute, recoverCartRoute } from "../schemas/carts.js";
-import { type AppEnv, mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, parsePagination, requireMethodPerm, requirePerm } from "../utils.js";
 
 export function cartRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
+  router.use("/", requireMethodPerm(["GET"], "cart:manage"));
+  router.use("/:id/recover", requirePerm("cart:manage"));
+
   // @ts-expect-error -- openapi() enforces strict response typing but our handler
   // returns union responses (201 | 400 | 422). The route definition documents the
   // contract; the handler returns dynamic status.
   router.openapi(createCartRoute, async (c) => {
     const actor = c.get("actor");
+    if (!actor) {
+      return c.json({ error: { code: "NOT_FOUND", message: "Cart not found." } }, 404);
+    }
     const result = await kernel.services.cart.create(c.req.valid("json") as CreateCartInput, actor);
     if (!result.ok)
       return c.json(
@@ -74,17 +80,12 @@ export function cartRoutes(kernel: Kernel) {
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getCartRoute, async (c) => {
     const actor = c.get("actor");
-    // Guest carts are gated by the cart secret; clients pass it as either
-    // ?secret=... or X-Cart-Secret. Customer carts ignore the secret and
-    // require ownership instead.
-    const secretParam = c.req.query("secret");
     const secretHeader = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret");
-    const secret = secretParam ?? secretHeader ?? undefined;
     const result = await kernel.services.cart.getById(
       c.req.param("id"),
       actor,
       undefined,
-      secret,
+      secretHeader ?? undefined,
     );
     if (!result.ok)
       return c.json(
@@ -98,9 +99,12 @@ export function cartRoutes(kernel: Kernel) {
   // returns union responses (201 | 400 | 422). The route definition documents the
   // contract; the handler returns dynamic status.
   router.openapi(addCartItemRoute, async (c) => {
+    const secret = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
     const result = await kernel.services.cart.addItem(
       { ...c.req.valid("json"), cartId: c.req.param("id") } as AddCartItemInput,
       c.get("actor"),
+      undefined,
+      secret,
     );
     if (!result.ok)
       return c.json(
@@ -115,6 +119,7 @@ export function cartRoutes(kernel: Kernel) {
   // contract; the handler returns dynamic status.
   router.openapi(updateCartItemQuantityRoute, async (c) => {
     const body = c.req.valid("json");
+    const secret = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
     const result = await kernel.services.cart.updateQuantity(
       {
         cartId: c.req.param("id"),
@@ -122,6 +127,8 @@ export function cartRoutes(kernel: Kernel) {
         quantity: body.quantity,
       },
       c.get("actor"),
+      undefined,
+      secret,
     );
     if (!result.ok)
       return c.json(
@@ -133,10 +140,13 @@ export function cartRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(removeCartItemRoute, async (c) => {
+    const secret = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
     const result = await kernel.services.cart.removeItem(
       c.req.param("id"),
       c.req.param("itemId"),
       c.get("actor"),
+      undefined,
+      secret,
     );
     if (!result.ok)
       return c.json(

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

@@ -64,8 +64,17 @@ import {
 export function catalogRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
+  router.use("/entities/*", requirePerm("catalog:read"));
+  router.use("/categories", requirePerm("catalog:read"));
+  router.use("/brands", requirePerm("catalog:read"));
+
   router.use("/entities/:id/custom-fields/:fieldName/approve", requirePerm("catalog:update"));
   router.use("/entities/:id/custom-fields/:fieldName/reject", requirePerm("catalog:update"));
+  router.use("/categories/:categoryId", requirePerm("catalog:update"));
+  router.use("/categories/:categoryId/*", requirePerm("catalog:update"));
+  router.use("/brands/:brandId", requirePerm("catalog:update"));
+  router.use("/brands/:brandId/*", requirePerm("catalog:update"));
+  router.use("/options/:optionTypeId/values", requirePerm("catalog:update"));
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listFieldOwnershipRoute, async (c) => {
@@ -159,6 +168,7 @@ export function catalogRoutes(kernel: Kernel) {
             const full = await kernel.services.catalog.getById(
               item.id,
               includeOptions,
+              c.get("actor"),
             );
             return full.ok ? full.value : item;
           }),
@@ -358,6 +368,7 @@ export function catalogRoutes(kernel: Kernel) {
     const result = await kernel.services.catalog.getAttributes(
       c.req.param("id"),
       c.req.param("locale"),
+      c.get("actor"),
     );
     if (!result.ok)
       return c.json(

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

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