@porulle/core 0.7.0 → 0.9.0

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

@@ -0,0 +1,206 @@
+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 { makeId } from "../../../../utils/id.js";
+import { listStaffRoute, createStaffRoute, inviteStaffRoute, listStaffInvitationsRoute, listStaffRolesRoute, updateStaffRoleRoute, revokeStaffRoute, } from "../../schemas/admin-staff.js";
+import { requirePerm } from "../../utils.js";
+/**
+ * Admin staff / RBAC surface (issue #46).
+ *
+ * Surfaces the Better Auth `member` table as first-class admin REST:
+ * list staff, add an existing user with a role, invite by email, change
+ * role, revoke — plus the role → permission mapping roles resolve to.
+ */
+export function adminStaffRoutes(kernel) {
+    const router = new OpenAPIHono();
+    const db = kernel.database.db;
+    const config = kernel.config;
+    router.use("/staff", requirePerm("staff:manage"));
+    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(", ")}.`,
+            },
+        }, 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 canGrantRole(actorRole, targetRole) {
+        return roleRank(actorRole) >= roleRank(targetRole);
+    }
+    function insufficientPrivilege(c, targetRole) {
+        return c.json({
+            error: {
+                code: "FORBIDDEN",
+                message: `Cannot assign role "${targetRole}": your role does not have sufficient privilege.`,
+            },
+        }, 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;
+    }
+    router.openapi(listStaffRoute, async (c) => {
+        const orgId = resolveOrgId(c.get("actor"));
+        const rows = await db
+            .select({
+            id: member.id,
+            userId: member.userId,
+            role: member.role,
+            createdAt: member.createdAt,
+            email: user.email,
+            name: user.name,
+        })
+            .from(member)
+            .leftJoin(user, eq(member.userId, user.id))
+            .where(eq(member.organizationId, orgId));
+        return c.json({ data: rows });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    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))
+            return invalidRole(c, body.role);
+        if (!canGrantRole(actor.role, body.role))
+            return insufficientPrivilege(c, body.role);
+        const users = await db.select().from(user).where(eq(user.id, body.userId));
+        if (users.length === 0) {
+            return c.json({ error: { code: "NOT_FOUND", message: "User not found." } }, 404);
+        }
+        const existing = await db
+            .select({ id: member.id })
+            .from(member)
+            .where(and(eq(member.organizationId, orgId), eq(member.userId, body.userId)));
+        if (existing.length > 0) {
+            return c.json({ error: { code: "VALIDATION_FAILED", message: "User is already a member of this organization." } }, 422);
+        }
+        const rows = await db
+            .insert(member)
+            .values({
+            id: makeId(),
+            organizationId: orgId,
+            userId: body.userId,
+            role: body.role,
+            createdAt: new Date(),
+        })
+            .returning();
+        return c.json({ data: rows[0] }, 201);
+    });
+    // @ts-expect-error -- openapi handler union return type
+    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))
+            return invalidRole(c, body.role);
+        const rows = await db
+            .insert(invitation)
+            .values({
+            id: makeId(),
+            organizationId: orgId,
+            email: body.email,
+            role: body.role,
+            status: "pending",
+            expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+            inviterId: actor.userId,
+        })
+            .returning();
+        return c.json({ data: rows[0] }, 201);
+    });
+    router.openapi(listStaffInvitationsRoute, async (c) => {
+        const orgId = resolveOrgId(c.get("actor"));
+        const rows = await db
+            .select()
+            .from(invitation)
+            .where(and(eq(invitation.organizationId, orgId), eq(invitation.status, "pending")));
+        return c.json({ data: rows });
+    });
+    router.openapi(listStaffRolesRoute, async (c) => {
+        const roles = config.auth?.roles ?? {};
+        const data = Object.entries(roles).map(([role, def]) => ({
+            role,
+            permissions: def.permissions,
+        }));
+        return c.json({ data });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(updateStaffRoleRoute, async (c) => {
+        const body = c.req.valid("json");
+        const actor = c.get("actor");
+        const orgId = resolveOrgId(actor);
+        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) {
+            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) {
+            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] });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(revokeStaffRoute, async (c) => {
+        const actor = c.get("actor");
+        const orgId = resolveOrgId(actor);
+        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) {
+            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) {
+            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));
+        return c.json({ data: { deleted: true } });
+    });
+    return router;
+}

package/dist/interfaces/rest/routes/analytics.d.ts

@@ -0,0 +1,5 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { type AppEnv } from "../utils.js";
+export declare function analyticsRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=analytics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAEzD,OAAO,EAAE,KAAK,MAAM,EAAqD,MAAM,aAAa,CAAC;AAE7F,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,gCA2B7C"}

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

@@ -0,0 +1,24 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { getReportRoute, listReportsRoute } from "../schemas/analytics.js";
+import { mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+export function analyticsRoutes(kernel) {
+    const router = new OpenAPIHono();
+    router.use("/reports", requirePerm("analytics:read"));
+    router.use("/reports/:name", requirePerm("analytics:read"));
+    router.openapi(listReportsRoute, (c) => {
+        return c.json({ data: kernel.services.analytics.listReports() });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(getReportRoute, async (c) => {
+        const { date, from, to } = c.req.valid("query");
+        const result = await kernel.services.analytics.getReport(c.req.param("name"), {
+            ...(date !== undefined ? { date } : {}),
+            ...(from !== undefined ? { from } : {}),
+            ...(to !== undefined ? { to } : {}),
+        }, c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value });
+    });
+    return router;
+}

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,EAAwC,MAAM,aAAa,CAAC;AAEhF,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,gCA6FxC"}
+{"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"}

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

@@ -1,6 +1,6 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
-import { createCartRoute, addCartItemRoute, updateCartItemQuantityRoute, getCartRoute, removeCartItemRoute } from "../schemas/carts.js";
-import { mapErrorToResponse, mapErrorToStatus } from "../utils.js";
+import { createCartRoute, addCartItemRoute, updateCartItemQuantityRoute, getCartRoute, removeCartItemRoute, listCartsRoute, recoverCartRoute } from "../schemas/carts.js";
+import { mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils.js";
 export function cartRoutes(kernel) {
     const router = new OpenAPIHono();
     // @ts-expect-error -- openapi() enforces strict response typing but our handler
@@ -14,6 +14,43 @@ export function cartRoutes(kernel) {
         return c.json({ data: result.value }, 201);
     });
     // @ts-expect-error -- openapi handler union return type
+    router.openapi(listCartsRoute, async (c) => {
+        const actor = c.get("actor");
+        const pagination = parsePagination(c.req.query());
+        const status = c.req.query("status");
+        const olderThanRaw = c.req.query("olderThan");
+        const hasCustomerRaw = c.req.query("hasCustomer");
+        let olderThan;
+        if (olderThanRaw) {
+            const d = new Date(olderThanRaw);
+            if (Number.isNaN(d.getTime())) {
+                return c.json({ error: { code: "VALIDATION_FAILED", message: "olderThan must be an ISO timestamp." } }, 422);
+            }
+            olderThan = d;
+        }
+        const result = await kernel.services.cart.list({
+            page: pagination.page,
+            limit: pagination.limit,
+            ...(status !== undefined ? { status } : {}),
+            ...(olderThan !== undefined ? { olderThan } : {}),
+            ...(hasCustomerRaw === "true" ? { hasCustomer: true } : {}),
+            ...(hasCustomerRaw === "false" ? { hasCustomer: false } : {}),
+        }, actor);
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({
+            data: result.value.items,
+            meta: { pagination: result.value.pagination },
+        });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(recoverCartRoute, async (c) => {
+        const result = await kernel.services.cart.recover(c.req.param("id"), 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(getCartRoute, async (c) => {
         const actor = c.get("actor");
         // Guest carts are gated by the cart secret; clients pass it as either

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;AA8CzD,OAAO,EACL,KAAK,MAAM,EAMZ,MAAM,aAAa,CAAC;AAErB,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,gCAud3C"}
+{"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"}

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

@@ -1,5 +1,5 @@
 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, } from "../schemas/catalog.js";
+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";
 export function catalogRoutes(kernel) {
     const router = new OpenAPIHono();
@@ -273,6 +273,22 @@ export function catalogRoutes(kernel) {
         return c.json({ data: result.value }, 201);
     });
     // @ts-expect-error -- openapi handler union return type
+    router.openapi(quickVariantRoute, async (c) => {
+        const body = c.req.valid("json");
+        const result = await kernel.services.catalog.quickCreateVariant(c.req.param("id"), body, c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value }, result.value.created ? 201 : 200);
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(bulkVariantsRoute, async (c) => {
+        const body = c.req.valid("json");
+        const result = await kernel.services.catalog.bulkCreateVariants(c.req.param("id"), body, c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value }, 201);
+    });
+    // @ts-expect-error -- openapi handler union return type
     router.openapi(generateVariantsRoute, async (c) => {
         const body = c.req.valid("json");
         const result = await kernel.services.catalog.generateVariants(c.req.param("id"), body, c.get("actor"));

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

@@ -1,5 +1,14 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../runtime/kernel.js";
 import { type AppEnv } from "../utils.js";
+import type { Actor } from "../../../auth/types.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
+ * profile; only actors with org-level `customers:read` (staff/clienteling) may
+ * name an arbitrary `customerId`. Returns undefined for guests / unresolved
+ * (guest checkout). Exported for unit testing.
+ */
+export declare function resolveCheckoutCustomerUuid(customers: Kernel["services"]["customers"], actor: Actor | null, customerId: string | undefined): Promise<string | undefined>;
 export declare function checkoutRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
 //# sourceMappingURL=checkout.d.ts.map

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;AAKhF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,gCAsQ5C"}
+{"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;AAKhF,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,gCA2S5C"}

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

@@ -5,7 +5,52 @@ import { runAfterHooks, runBeforeHooks } from "../../../kernel/hooks/executor.js
 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 { makeId } 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
+ * profile; only actors with org-level `customers:read` (staff/clienteling) may
+ * name an arbitrary `customerId`. Returns undefined for guests / unresolved
+ * (guest checkout). Exported for unit testing.
+ */
+export async function resolveCheckoutCustomerUuid(customers, actor, customerId) {
+    const actorUserId = actor?.userId;
+    let canActForOthers = false;
+    if (actorUserId) {
+        try {
+            assertPermission(actor, "customers:read");
+            canActForOthers = true;
+        }
+        catch {
+            canActForOthers = false;
+        }
+    }
+    if (customerId) {
+        const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        if (uuidRe.test(customerId)) {
+            const byId = await customers.getById(customerId, actor);
+            // Honor a profile UUID only if it is the actor's own, or the actor may
+            // act for other customers.
+            if (byId.ok && (canActForOthers || byId.value.userId === actorUserId)) {
+                return byId.value.id;
+            }
+        }
+        if (canActForOthers) {
+            // Staff may resolve/create a customer by a supplied user_id.
+            const byUser = await customers.getByUserId(customerId, actor);
+            if (byUser.ok)
+                return byUser.value.id;
+        }
+    }
+    // Self-service default: the authenticated actor's own customer profile.
+    if (actorUserId && !canActForOthers) {
+        const own = await customers.getByUserId(actorUserId, actor);
+        if (own.ok)
+            return own.value.id;
+    }
+    return undefined;
+}
 export function checkoutRoutes(kernel) {
     const router = new OpenAPIHono();
     // @ts-expect-error -- openapi() enforces strict response typing but our handler
@@ -14,6 +59,40 @@ 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.
+        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);
+            }
+        }
         const checkoutData = {
             checkoutId: makeId(),
             cartId: body.cartId,
@@ -84,27 +163,14 @@ export function checkoutRoutes(kernel) {
             // If Stripe takes 5s, the DB connection pool is not affected.
             context.tx = null;
             const processed = await runBeforeHooks(paymentHooks, validated, "create", context);
-            // Resolve customer profile UUID from customerId (may be a profile UUID or a Better Auth user_id)
-            let customerUuid = undefined;
-            if (processed.customerId) {
-                const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-                if (uuidRe.test(processed.customerId)) {
-                    // Looks like a profile UUID — try direct lookup (no auto-create)
-                    const byIdResult = await kernel.services.customers.getById(processed.customerId, actor);
-                    if (byIdResult.ok) {
-                        customerUuid = byIdResult.value.id;
-                    }
-                }
-                if (!customerUuid) {
-                    // Fall back to user_id lookup (auto-creates customer profile if needed)
-                    const byUserIdResult = await kernel.services.customers.getByUserId(processed.customerId, actor);
-                    if (byUserIdResult.ok) {
-                        customerUuid = byUserIdResult.value.id;
-                    }
-                }
-                // If both lookups fail, we still allow guest checkout (customerUuid remains undefined)
-            }
+            // SEC-07: resolve the order's customer server-side. A self-service actor
+            // can only attribute the order to its own profile; a client-supplied
+            // foreign customerId is ignored unless the actor is staff.
+            const customerUuid = await resolveCheckoutCustomerUuid(kernel.services.customers, actor, processed.customerId);
             const orderPayload = {
+                ...(body.idempotencyKey !== undefined
+                    ? { idempotencyKey: body.idempotencyKey }
+                    : {}),
                 currency: processed.currency,
                 subtotal: processed.subtotal,
                 taxTotal: processed.taxTotal,
@@ -133,6 +199,11 @@ export function checkoutRoutes(kernel) {
                         quantity: lineItem.quantity,
                         unitPrice: lineItem.resolvedUnitPrice ?? 0,
                         totalPrice: lineItem.resolvedTotal ?? 0,
+                        // Per-line tax from product tax classes (issue #57)
+                        taxAmount: lineItem.taxAmount ?? 0,
+                        ...(lineItem.discountAmount !== undefined
+                            ? { discountAmount: lineItem.discountAmount }
+                            : {}),
                     };
                     return lineItem.variantId !== undefined
                         ? { ...payload, variantId: lineItem.variantId }
@@ -142,7 +213,12 @@ export function checkoutRoutes(kernel) {
                     ? { customerId: customerUuid }
                     : {}),
             };
-            const order = await kernel.services.orders.create(orderPayload, actor);
+            // Checkout is a trusted, already-server-priced pipeline (resolveCurrentPrices
+            // + promotions/tax) and reserves stock in its own after-hooks — so it hands
+            // the order primitive precomputed totals rather than re-deriving them.
+            const order = await kernel.services.orders.create(orderPayload, actor, undefined, {
+                trustedPricing: true,
+            });
             if (!order.ok) {
                 return c.json(mapErrorToResponse(order.error), mapErrorToStatus(order.error));
             }

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

@@ -0,0 +1,10 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { type AppEnv } from "../utils.js";
+/**
+ * Order document rendering (issue #47). Mounted under /orders. Access
+ * control rides on OrderService.getById (orders:read, or orders:read:own
+ * for the order's customer), so no extra scope is needed here.
+ */
+export declare function documentRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=documents.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,40 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { emailInvoiceRoute, invoiceHtmlRoute, invoicePdfRoute, receiptHtmlRoute, } from "../schemas/documents.js";
+import { mapErrorToResponse, mapErrorToStatus } from "../utils.js";
+/**
+ * Order document rendering (issue #47). Mounted under /orders. Access
+ * control rides on OrderService.getById (orders:read, or orders:read:own
+ * for the order's customer), so no extra scope is needed here.
+ */
+export function documentRoutes(kernel) {
+    const router = new OpenAPIHono();
+    router.openapi(invoicePdfRoute, async (c) => {
+        const result = await kernel.services.documents.renderInvoicePdf(c.req.param("id"), c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.body(result.value.pdf.slice().buffer, 200, {
+            "content-type": "application/pdf",
+            "content-disposition": `inline; filename="invoice-${result.value.invoiceNumber}.pdf"`,
+        });
+    });
+    router.openapi(invoiceHtmlRoute, async (c) => {
+        const result = await kernel.services.documents.renderInvoiceHtml(c.req.param("id"), c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.html(result.value.html);
+    });
+    router.openapi(receiptHtmlRoute, async (c) => {
+        const result = await kernel.services.documents.renderReceiptHtml(c.req.param("id"), c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.html(result.value.html);
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(emailInvoiceRoute, async (c) => {
+        const result = await kernel.services.documents.emailInvoice(c.req.param("id"), c.req.valid("json").to, c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value });
+    });
+    return router;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"inventory.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/inventory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAUzD,OAAO,EAAE,KAAK,MAAM,EAAqD,MAAM,aAAa,CAAC;AAE7F,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,gCAiF7C"}
+{"version":3,"file":"inventory.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/inventory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAUzD,OAAO,EAAE,KAAK,MAAM,EAAqD,MAAM,aAAa,CAAC;AAE7F,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,gCA+F7C"}

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

@@ -5,6 +5,13 @@ export function inventoryRoutes(kernel) {
     const router = new OpenAPIHono();
     // Inventory levels listing requires inventory:read
     router.use("/levels", requirePerm("inventory:read"));
+    // Warehouse config + reservation are staff operations, never public. Gate them
+    // at the route (reserve/release are also called internally by checkout with the
+    // customer's actor, so the service itself must stay callable — the boundary is
+    // the HTTP route). Blocks anonymous (401) and customers lacking the perm (403).
+    router.use("/warehouses", requirePerm("inventory:read"));
+    router.use("/reserve", requirePerm("inventory:adjust"));
+    router.use("/release", requirePerm("inventory:adjust"));
     // @ts-expect-error -- openapi handler union return type
     router.openapi(listInventoryLevelsRoute, async (c) => {
         const actor = c.get("actor");
@@ -59,6 +66,12 @@ export function inventoryRoutes(kernel) {
     router.openapi(createWarehouseRoute, async (c) => {
         const body = c.req.valid("json");
         const actor = c.get("actor");
+        // Creating a warehouse (write) needs the higher inventory:adjust perm; the
+        // router.use above already requires inventory:read for the /warehouses path.
+        const perms = actor?.permissions ?? [];
+        if (!(perms.includes("inventory:adjust") || perms.includes("inventory:*") || perms.includes("*:*"))) {
+            return c.json({ error: { code: "FORBIDDEN", message: "Permission 'inventory:adjust' is required." } }, 403);
+        }
         const result = await kernel.services.inventory.createWarehouse(body, actor);
         if (!result.ok)
             return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));

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

@@ -1 +1 @@
-{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/orders.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAEzD,OAAO,EAAE,KAAK,MAAM,EAAiE,MAAM,aAAa,CAAC;AAGzG,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,gCA8HzC"}
+{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/orders.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAEzD,OAAO,EAAE,KAAK,MAAM,EAAiE,MAAM,aAAa,CAAC;AAIzG,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,gCAgRzC"}