@porulle/core 0.10.8 → 0.13.0

package/dist/interfaces/rest/routes/admin/staff.js

@@ -1,9 +1,10 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { eq, and } from "drizzle-orm";
 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, createStaffRoute, inviteStaffRoute, listStaffInvitationsRoute, listStaffRolesRoute, updateStaffRoleRoute, revokeStaffRoute, } from "../../schemas/admin-staff.js";
+import { canGrantRole, granterForRole, isCompositeRole, isOwnerRole, roleRank, validRoles, } from "../../../../auth/role-authority.js";
 import { requirePerm } from "../../utils.js";
 /**
  * Admin staff / RBAC surface (issue #46).
@@ -20,32 +21,19 @@ export function adminStaffRoutes(kernel) {
     router.use("/staff/:id", requirePerm("staff:manage"));
     router.use("/staff/invitations", requirePerm("staff:manage"));
     router.use("/staff/roles", requirePerm("staff:manage"));
-    function validRoles() {
-        return new Set([
-            ...Object.keys(config.auth?.roles ?? {}),
-            "owner",
-            "admin",
-            "member",
-        ]);
-    }
     function invalidRole(c, role) {
         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 = {
-        owner: 3,
-        admin: 2,
-    };
-    const CUSTOM_ROLE_RANK = 1;
-    function roleRank(role) {
-        return BUILTIN_ROLE_RANK[role] ?? CUSTOM_ROLE_RANK;
+    function rankOf(role) {
+        return roleRank(config, role);
     }
-    function canGrantRole(actorRole, targetRole) {
-        return roleRank(actorRole) >= roleRank(targetRole);
+    function actorCanGrantRole(actor, targetRole) {
+        return canGrantRole(config, actor ? { role: actor.role, permissions: actor.permissions } : null, targetRole);
     }
     function insufficientPrivilege(c, targetRole) {
         return c.json({
@@ -55,15 +43,61 @@ export function adminStaffRoutes(kernel) {
             },
         }, 403);
     }
-    async function countOwners(orgId) {
-        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(orgId, run) {
+        return kernel.database.transaction(async (raw) => {
+            const tx = raw;
+            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, inviterUserId, newRole) {
+        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,
@@ -82,10 +116,10 @@ export function adminStaffRoutes(kernel) {
     router.openapi(createStaffRoute, async (c) => {
         const body = c.req.valid("json");
         const actor = c.get("actor");
-        const orgId = resolveOrgId(actor);
-        if (!validRoles().has(body.role))
+        const orgId = resolveOrgIdForCommerce(actor, config);
+        if (isCompositeRole(body.role) || !validRoles(config).has(body.role))
             return invalidRole(c, body.role);
-        if (!canGrantRole(actor.role, 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) {
@@ -114,9 +148,11 @@ export function adminStaffRoutes(kernel) {
     router.openapi(inviteStaffRoute, async (c) => {
         const body = c.req.valid("json");
         const actor = c.get("actor");
-        const orgId = resolveOrgId(actor);
-        if (!validRoles().has(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({
@@ -126,13 +162,13 @@ export function adminStaffRoutes(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)
@@ -151,55 +187,79 @@ export function adminStaffRoutes(kernel) {
     router.openapi(updateStaffRoleRoute, async (c) => {
         const body = c.req.valid("json");
         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))
+        if (isCompositeRole(body.role) || !validRoles(config).has(body.role))
             return invalidRole(c, body.role);
-        if (!canGrantRole(actor.role, body.role))
+        if (!actorCanGrantRole(actor, 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) {
+        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" };
+            // 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 };
+            }
+            if (isOwnerRole(target.role) && !isOwnerRole(body.role) && ownerIds.length <= 1) {
+                return { kind: "last-owner" };
+            }
+            const updated = await tx
+                .update(member)
+                .set({ role: body.role })
+                .where(eq(member.id, id))
+                .returning();
+            return { kind: "updated", target, row: updated[0] };
+        });
+        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" };
+            // 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 };
+            }
+            if (isOwnerRole(target.role) && ownerIds.length <= 1) {
+                return { kind: "last-owner" };
+            }
+            await tx.delete(member).where(eq(member.id, id));
+            return { kind: "deleted", target };
+        });
+        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 } });
     });
     return router;

package/dist/interfaces/rest/routes/admin-jobs.js

@@ -3,14 +3,14 @@ import { eq, and, desc } from "drizzle-orm";
 import { commerceJobs } from "../../../kernel/jobs/schema.js";
 import { listFailedJobsRoute, retryJobRoute } from "../schemas/admin-jobs.js";
 import { requirePerm } from "../utils.js";
-import { resolveOrgId } from "../../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../../auth/org.js";
 export function adminJobRoutes(kernel) {
     const router = new OpenAPIHono();
     const db = kernel.database.db;
     router.use("/jobs/failed", requirePerm("jobs:admin"));
     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
@@ -28,7 +28,7 @@ export function adminJobRoutes(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/dist/interfaces/rest/routes/audit.js

@@ -1,7 +1,7 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { listAuditRoute, listEntityAuditRoute } from "../schemas/audit.js";
 import { requirePerm } from "../utils.js";
-import { resolveOrgId } from "../../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../../auth/org.js";
 export function auditRoutes(kernel) {
     const router = new OpenAPIHono();
     /**
@@ -11,7 +11,7 @@ export function auditRoutes(kernel) {
     router.use("/", requirePerm("audit:read"));
     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"),
@@ -31,7 +31,7 @@ export function auditRoutes(kernel) {
     router.use("/:entityType/:entityId", requirePerm("audit:read"));
     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/dist/interfaces/rest/routes/carts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"carts.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/carts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGzD,OAAO,EAAE,KAAK,MAAM,EAAyD,MAAM,aAAa,CAAC;AAEjG,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,gCA+IxC"}
+{"version":3,"file":"carts.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/carts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGzD,OAAO,EAAE,KAAK,MAAM,EAAyF,MAAM,aAAa,CAAC;AAEjI,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,gCAyJxC"}

package/dist/interfaces/rest/routes/carts.js

@@ -1,13 +1,18 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { createCartRoute, addCartItemRoute, updateCartItemQuantityRoute, getCartRoute, removeCartItemRoute, listCartsRoute, recoverCartRoute } from "../schemas/carts.js";
-import { mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils.js";
+import { mapErrorToResponse, mapErrorToStatus, parsePagination, requireMethodPerm, requirePerm } from "../utils.js";
 export function cartRoutes(kernel) {
     const router = new OpenAPIHono();
+    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"), actor);
         if (!result.ok)
             return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
@@ -53,13 +58,8 @@ export function cartRoutes(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);
+        const result = await kernel.services.cart.getById(c.req.param("id"), actor, undefined, secretHeader ?? undefined);
         if (!result.ok)
             return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
         return c.json({ data: result.value });
@@ -68,7 +68,8 @@ export function cartRoutes(kernel) {
     // returns union responses (201 | 400 | 422). The route definition documents the
     // contract; the handler returns dynamic status.
     router.openapi(addCartItemRoute, async (c) => {
-        const result = await kernel.services.cart.addItem({ ...c.req.valid("json"), cartId: c.req.param("id") }, c.get("actor"));
+        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") }, c.get("actor"), undefined, secret);
         if (!result.ok)
             return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
         return c.json({ data: result.value }, 201);
@@ -78,18 +79,20 @@ export function cartRoutes(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"),
             itemId: c.req.param("itemId"),
             quantity: body.quantity,
-        }, c.get("actor"));
+        }, c.get("actor"), undefined, secret);
         if (!result.ok)
             return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
         return c.json({ data: result.value });
     });
     // @ts-expect-error -- openapi handler union return type
     router.openapi(removeCartItemRoute, async (c) => {
-        const result = await kernel.services.cart.removeItem(c.req.param("id"), c.req.param("itemId"), c.get("actor"));
+        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(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
         return c.json({ data: { deleted: true } });

package/dist/interfaces/rest/routes/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAgDzD,OAAO,EACL,KAAK,MAAM,EAMZ,MAAM,aAAa,CAAC;AAErB,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,gCAuf3C"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAoDzD,OAAO,EACL,KAAK,MAAM,EAOZ,MAAM,aAAa,CAAC;AAErB,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,gCAklB3C"}

package/dist/interfaces/rest/routes/catalog.js

@@ -1,8 +1,35 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
-import { listEntitiesRoute, getEntityRoute, getEntityAttributesRoute, listCategoriesRoute, listBrandsRoute, deleteEntityRoute, deleteCategoryRoute, deleteBrandRoute, removeEntityFromCategoryRoute, removeEntityFromBrandRoute, publishEntityRoute, archiveEntityRoute, discontinueEntityRoute, addEntityToCategoryRoute, addEntityToBrandRoute, createEntityRoute, updateEntityRoute, setEntityAttributesRoute, createCategoryRoute, archiveCategoryRoute, restoreCategoryRoute, updateCategoryRoute, createBrandRoute, updateBrandRoute, createOptionTypeRoute, createOptionValueRoute, createVariantRoute, generateVariantsRoute, quickVariantRoute, bulkVariantsRoute, } from "../schemas/catalog.js";
-import { mapErrorToResponse, mapErrorToStatus, parseInclude, parsePagination, parseSort, } from "../utils.js";
+import { listEntitiesRoute, getEntityRoute, getEntityAttributesRoute, listFieldOwnershipRoute, setFieldOwnershipRoute, listCategoriesRoute, listBrandsRoute, deleteEntityRoute, deleteCategoryRoute, deleteBrandRoute, removeEntityFromCategoryRoute, removeEntityFromBrandRoute, publishEntityRoute, archiveEntityRoute, discontinueEntityRoute, addEntityToCategoryRoute, addEntityToBrandRoute, createEntityRoute, updateEntityRoute, setEntityAttributesRoute, approveCustomFieldRoute, rejectCustomFieldRoute, createCategoryRoute, archiveCategoryRoute, restoreCategoryRoute, updateCategoryRoute, createBrandRoute, updateBrandRoute, createOptionTypeRoute, createOptionValueRoute, createVariantRoute, generateVariantsRoute, quickVariantRoute, bulkVariantsRoute, } from "../schemas/catalog.js";
+import { mapErrorToResponse, mapErrorToStatus, parseInclude, parsePagination, parseSort, requirePerm, } from "../utils.js";
 export function catalogRoutes(kernel) {
     const router = new OpenAPIHono();
+    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) => {
+        const result = await kernel.services.catalog.listFieldOwnership(c.req.param("id"), c.get("actor"), undefined, c.req.query("storeId"));
+        if (!result.ok) {
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        }
+        return c.json({ data: result.value });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(setFieldOwnershipRoute, async (c) => {
+        const body = c.req.valid("json");
+        const result = await kernel.services.catalog.setFieldOwner(c.req.param("id"), body.fieldPath, body.storeId ?? null, body.owner, c.get("actor"), undefined, body.variantId ?? null);
+        if (!result.ok) {
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        }
+        return c.json({ data: { updated: true } });
+    });
     // @ts-expect-error -- openapi handler union return type
     router.openapi(listEntitiesRoute, async (c) => {
         try {
@@ -43,9 +70,10 @@ export function catalogRoutes(kernel) {
                     includeMedia: include.has("media"),
                     includeInventory: include.has("inventory"),
                     includePricing: include.has("pricing"),
+                    includeCustomFields: include.has("customFields"),
                 };
                 const hydrated = await Promise.all(result.value.items.map(async (item) => {
-                    const full = await kernel.services.catalog.getById(item.id, includeOptions);
+                    const full = await kernel.services.catalog.getById(item.id, includeOptions, c.get("actor"));
                     return full.ok ? full.value : item;
                 }));
                 withIncludes = hydrated;
@@ -77,6 +105,7 @@ export function catalogRoutes(kernel) {
                 includeMedia: include.has("media"),
                 includeInventory: include.has("inventory"),
                 includePricing: include.has("pricing"),
+                includeCustomFields: include.has("customFields"),
             };
             const actor = c.get("actor");
             const result = isUUID
@@ -146,8 +175,22 @@ export function catalogRoutes(kernel) {
         return c.json({ data: { updated: true } });
     });
     // @ts-expect-error -- openapi handler union return type
+    router.openapi(approveCustomFieldRoute, async (c) => {
+        const result = await kernel.services.catalog.approveCustomField(c.req.param("id"), c.req.param("fieldName"), c.req.query("locale") ?? "en", c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(rejectCustomFieldRoute, async (c) => {
+        const result = await kernel.services.catalog.rejectCustomField(c.req.param("id"), c.req.param("fieldName"), c.req.query("locale") ?? "en", c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value });
+    });
+    // @ts-expect-error -- openapi handler union return type
     router.openapi(getEntityAttributesRoute, async (c) => {
-        const result = await kernel.services.catalog.getAttributes(c.req.param("id"), c.req.param("locale"));
+        const result = await kernel.services.catalog.getAttributes(c.req.param("id"), c.req.param("locale"), c.get("actor"));
         if (!result.ok)
             return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
         return c.json({ data: result.value });

package/dist/interfaces/rest/routes/checkout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/checkout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAoBzD,OAAO,EAAE,KAAK,MAAM,EAAwC,MAAM,aAAa,CAAC;AAMhF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,WAAW,CAAC,EAC1C,KAAK,EAAE,KAAK,GAAG,IAAI,EACnB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmC7B;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,gCAgV5C"}
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/checkout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAoBzD,OAAO,EAAE,KAAK,MAAM,EAAwC,MAAM,aAAa,CAAC;AAMhF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,WAAW,CAAC,EAC1C,KAAK,EAAE,KAAK,GAAG,IAAI,EACnB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmC7B;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,gCAmV5C"}

package/dist/interfaces/rest/routes/checkout.js

@@ -6,8 +6,8 @@ import { createHookContext } from "../../../kernel/hooks/create-context.js";
 import { 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";
 /**
  * SEC-07 — resolve the customer profile a checkout order is attributed to.
  * A self-service actor may ONLY attribute the order to its own customer
@@ -60,42 +60,32 @@ export function checkoutRoutes(kernel) {
     router.openapi(checkoutRoute, async (c) => {
         const body = c.req.valid("json");
         const actor = c.get("actor");
-        // 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.
+        const cartSecret = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret") ?? undefined;
+        // 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;
         if (body.idempotencyKey) {
-            const replay = await kernel.services.orders.getByIdempotencyKey(body.idempotencyKey, actor);
-            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);
+            replay = await kernel.services.orders.getByIdempotencyKey(body.idempotencyKey, actor, undefined, cartSecret);
+            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 = {
             checkoutId: makeId(),
@@ -166,6 +156,7 @@ export function checkoutRoutes(kernel) {
             context: { moduleName: "checkout" },
             origin: "rest",
             database: { db: kernel.database.db },
+            commerceConfig: kernel.config,
         });
         let pipelineStage = "validate-and-calculate";
         try {
@@ -237,6 +228,7 @@ export function checkoutRoutes(kernel) {
             pipelineStage = "create-order";
             const order = await kernel.services.orders.create(orderPayload, actor, undefined, {
                 trustedPricing: true,
+                ...(cartSecret !== undefined ? { guestCredential: cartSecret } : {}),
             });
             if (!order.ok) {
                 return c.json(mapErrorToResponse(order.error), mapErrorToStatus(order.error));
@@ -304,7 +296,10 @@ export function checkoutRoutes(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((releaseError) => {
+            // 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) => {
                 console.error("[checkout] Failed to release cart claim:", {
                     cartId: body.cartId,
                     error: releaseError instanceof Error ? releaseError.message : String(releaseError),

package/dist/interfaces/rest/routes/documents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAOzD,OAAO,EAAE,KAAK,MAAM,EAAwC,MAAM,aAAa,CAAC;AAEhF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,gCA6C5C"}
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAOzD,OAAO,EAAE,KAAK,MAAM,EAAwD,MAAM,aAAa,CAAC;AAEhG;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,gCA2D5C"}