@porulle/core 0.22.0 → 0.24.0

package/dist/modules/cart/service.js

@@ -1,6 +1,6 @@
 import { resolveOrgIdForCommerce } from "../../auth/org.js";
-import { assertPermission } from "../../auth/permissions.js";
-import { CommerceForbiddenError, CommerceNotFoundError, CommerceValidationError, toCommerceError, } from "../../kernel/errors.js";
+import { AUTHENTICATION_REQUIRED_MESSAGE, assertPermission, isUnauthenticatedActor, } from "../../auth/permissions.js";
+import { CommerceForbiddenError, CommerceNotFoundError, CommerceUnauthorizedError, CommerceValidationError, toCommerceError, } from "../../kernel/errors.js";
 import { runAfterHooks, runBeforeHooks } from "../../kernel/hooks/executor.js";
 import { createHookContext } from "../../kernel/hooks/create-context.js";
 import { Err, Ok } from "../../kernel/result.js";
@@ -191,12 +191,35 @@ export class CartService {
             item = updated;
         }
         else {
+            // A new line needs a price, and a price the system cannot determine is refused rather than
+            // invented. This used to read `processed.unitPriceSnapshot ?? 1000`: a silent default in a
+            // money path, which nothing in the response, the logs or the schema disclosed. An integrator
+            // found it by comparing a deployed cart reading 1000 against a catalog priced 14500-22800.
+            //
+            // A hook still wins when it supplies one, so bespoke pricing keeps its seam; otherwise the
+            // pricing step answers — the SAME step `resolveCurrentPrices` uses at checkout, so a cart and
+            // its order agree by construction rather than by an integrator remembering to install a hook.
+            const currency = processed.currency ?? cart.currency;
+            let unitPriceSnapshot = processed.unitPriceSnapshot;
+            if (unitPriceSnapshot === undefined) {
+                const resolved = await this.resolveUnitPrice({
+                    entityId: processed.entityId,
+                    currency,
+                    quantity,
+                    ...(processed.variantId != null
+                        ? { variantId: processed.variantId }
+                        : {}),
+                }, actor ?? null, ctx);
+                if (!resolved.ok)
+                    return resolved;
+                unitPriceSnapshot = resolved.value;
+            }
             item = await this.repo.createLineItem({
                 cartId: input.cartId,
                 entityId: processed.entityId,
                 quantity,
-                unitPriceSnapshot: processed.unitPriceSnapshot ?? 1000,
-                currency: processed.currency ?? cart.currency,
+                unitPriceSnapshot,
+                currency,
                 metadata: processed.metadata ?? {},
                 ...(processed.variantId !== undefined
                     ? { variantId: processed.variantId }
@@ -206,6 +229,23 @@ export class CartService {
         await runAfterHooks(afterHooks, null, item, "addItem", context);
         return Ok(item);
     }
+    /**
+     * The unit price for a new cart line, from the pricing step. Refuses — naming the entity and the
+     * currency — when no price is configured, when the pricing service is absent, or when resolution
+     * fails for any other reason: every one of those is a value the system cannot determine, and the
+     * defect this replaces was substituting a literal for exactly that.
+     */
+    async resolveUnitPrice(input, actor, ctx) {
+        const pricing = this.deps.services.pricing;
+        if (typeof pricing?.resolve !== "function") {
+            return Err(new CommerceValidationError(`Cannot resolve a unit price for ${input.entityId}: no pricing service is configured.`));
+        }
+        const resolved = await pricing.resolve(input, actor, ctx);
+        if (!resolved.ok) {
+            return Err(new CommerceValidationError(`Cannot resolve a unit price for ${input.entityId} (${input.currency}). Configure a price for it, or supply unitPriceSnapshot from a cart.beforeAddItem hook.`));
+        }
+        return Ok(resolved.value.finalAmount);
+    }
     async removeItem(cartId, itemId, actor, ctx, presentedSecret) {
         try {
             assertPermission(actor ?? null, "cart:update");
@@ -513,8 +553,8 @@ export class CartService {
         if (actor && actor.permissions.includes("*:*"))
             return;
         if (cart.customerId != null) {
-            if (!actor) {
-                throw new CommerceForbiddenError("Authentication required to read customer cart.");
+            if (isUnauthenticatedActor(actor)) {
+                throw new CommerceUnauthorizedError(AUTHENTICATION_REQUIRED_MESSAGE);
             }
             const profileId = await this.resolveActorCustomerId(actor, ctx);
             if (profileId !== cart.customerId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/core",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -62,8 +62,8 @@
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@porulle/eslint-config": "0.1.0",
-    "@porulle/typescript-config": "0.1.0"
+    "@porulle/typescript-config": "0.1.0",
+    "@porulle/eslint-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/auth/identity-free-routes.ts

@@ -0,0 +1,86 @@
+/**
+ * Routes that read no actor, so `authMiddleware` need not resolve one.
+ *
+ * THE DEFAULT IS TO RESOLVE. A route absent from this list keeps its actor,
+ * because the failure mode of the opposite default is silent: a route that
+ * stops receiving an actor does not throw, it 401s, or takes an anonymous
+ * branch and answers.
+ *
+ * Matching is EXACT on method and path — no patterns, no prefixes. A pattern is
+ * how one entry silently widens to cover a route that does need an identity,
+ * and this list is small enough that the cost of exactness is a line per route.
+ * A route with a path parameter therefore cannot be listed at all, which is the
+ * intended limit rather than an oversight.
+ *
+ * Entries are the routes whose handlers were read and shown to consult neither
+ * `c.get("actor")` nor anything derived from it. `/api/carts` and the rest of
+ * `PUBLIC_ROUTES` in `interfaces/rest/route-coverage.ts` are NOT here: they are
+ * public in the sense of needing no permission, and they still need the
+ * organization the anonymous actor carries. Public and identity-free are
+ * different properties and this list is the second one.
+ */
+export type IdentityFreeRoute = {
+  method: string;
+  path: string;
+  justification: string;
+};
+
+export const IDENTITY_FREE_ROUTES: readonly IdentityFreeRoute[] = [
+  {
+    method: "GET",
+    path: "/api/health",
+    justification:
+      "A liveness probe for load balancers; the handler issues its own SELECT 1 and reads no actor.",
+  },
+  {
+    method: "GET",
+    path: "/api/doc",
+    justification:
+      "The generated OpenAPI document is built from config and the route table, never from the caller.",
+  },
+  {
+    method: "GET",
+    path: "/api/doc-ext",
+    justification:
+      "The enriched OpenAPI document, same handler shape as /api/doc.",
+  },
+];
+
+const DEFAULT_KEYS = new Set(
+  IDENTITY_FREE_ROUTES.map((route) => `${route.method} ${route.path}`),
+);
+
+function normalize(entry: string): string {
+  const [method = "", ...rest] = entry.trim().split(/\s+/);
+  return `${method.toUpperCase()} ${rest.join(" ")}`;
+}
+
+/**
+ * An app declares its own with `auth.identityFreeRoutes: ["POST /api/payments/notify"]`.
+ *
+ * Additive only: a config entry can never remove one of the defaults above, so
+ * the narrowest thing an app can do to this set is widen it, and the widening
+ * is visible in its own configuration file.
+ *
+ * The routes that want this are app-local by nature — a signed payment notify,
+ * a tracked click-out — and they have no session, taking their organization
+ * from the payload they verified rather than from a resolver, which is what
+ * core's own `POST /api/payments/webhook` already does.
+ *
+ * WHAT AN ENTRY COSTS: `authMiddleware` is followed by the wrapper that opens
+ * the plugin database scope FROM THE RESOLVED ACTOR. A route listed here gets
+ * no actor, so it gets no scope, and every plugin read and write on that
+ * request runs with no organization predicate while the handler still answers
+ * normally. Such a route must open its own scope.
+ */
+export function isIdentityFreeRoute(
+  method: string,
+  path: string,
+  config?: { auth?: { identityFreeRoutes?: readonly string[] } },
+): boolean {
+  const key = `${method.toUpperCase()} ${path}`;
+  if (DEFAULT_KEYS.has(key)) return true;
+  const declared = config?.auth?.identityFreeRoutes;
+  if (!declared) return false;
+  return declared.some((entry) => normalize(entry) === key);
+}

package/src/auth/middleware.ts

@@ -6,6 +6,7 @@ import { getCustomerPermissions, resolveActor } from "./actor.js";
 import { DEFAULT_ORG_ID } from "./org.js";
 import { isCredentialRejection } from "./auth-failure.js";
 import { isStrictOrgResolution } from "./strict-org-resolution.js";
+import { isIdentityFreeRoute } from "./identity-free-routes.js";
 
 function emptyToNull(value: string | null | undefined): string | null {
   return value == null || value === "" ? null : value;
@@ -24,6 +25,12 @@ export function authMiddleware(
   config: CommerceConfig,
 ): MiddlewareHandler {
   return async (c, next) => {
+    if (isIdentityFreeRoute(c.req.method, c.req.path, config)) {
+      c.set("actor", null);
+      await next();
+      return;
+    }
+
     // Resolve the default org from config, falling back to deprecated constant
     const defaultOrgId = config.auth?.defaultOrganizationId ?? DEFAULT_ORG_ID;
 

package/src/auth/permissions.ts

@@ -1,6 +1,22 @@
-import { CommerceForbiddenError } from "../kernel/errors.js";
+import {
+  CommerceForbiddenError,
+  CommerceUnauthorizedError,
+} from "../kernel/errors.js";
 import type { Actor } from "./types.js";
 
+export const AUTHENTICATION_REQUIRED_MESSAGE = "Authentication required.";
+
+/**
+ * True when the request carried no credential at all. An API key actor
+ * (`type: "api_key"`) DID present one, whatever its referenceId, so it keeps
+ * 403 — telling it to authenticate would be a lie it cannot act on.
+ */
+export function isUnauthenticatedActor(
+  actor: Pick<Actor, "type" | "userId"> | null,
+): boolean {
+  return actor === null || (actor.type === "user" && actor.userId === null);
+}
+
 export function hasPermission(actor: Actor | null, required: string): boolean {
   if (!actor) return false;
   if (actor.permissions.includes("*:*")) return true;
@@ -12,13 +28,25 @@ export function hasPermission(actor: Actor | null, required: string): boolean {
 
 export function assertPermission(actor: Actor | null, required: string): void {
   if (hasPermission(actor, required)) return;
-  if (!actor) throw new CommerceForbiddenError("Authentication required.");
+  // `actor === null` is redundant at runtime — the predicate already covers it —
+  // and load-bearing at compile time: a boolean predicate narrows nothing, and
+  // the message below reads `actor.role`. Written this way rather than as a cast
+  // so it cannot start lying if the predicate changes.
+  if (actor === null || isUnauthenticatedActor(actor)) {
+    throw new CommerceUnauthorizedError(AUTHENTICATION_REQUIRED_MESSAGE);
+  }
 
   throw new CommerceForbiddenError(
     `Permission "${required}" is required. Your role "${actor.role}" does not include this permission.`,
   );
 }
 
+// NOT given the unauthenticated predicate, and the omission is deliberate.
+// `auth-permissions.test.ts` pins this refusal as 403 for a STAFF actor with a
+// null userId — a shape `resolveActor` cannot produce — so whether that means
+// "anonymous" or "a synthetic actor whose identity is broken" has to be decided
+// before the status can be. It is carded; no route reaches here with an
+// anonymous actor today.
 export function assertOwnership(actor: Actor | null, resourceOwnerId: string | null): void {
   if (!actor) {
     throw new CommerceForbiddenError("Authentication required.");

package/src/config/types.ts

@@ -199,6 +199,21 @@ export interface AuthConfig {
    * ```
    */
   storeResolver?: (request: Request) => string | null | Promise<string | null>;
+  /**
+   * Routes this app serves that read no actor, as `"<METHOD> <exact path>"` —
+   * e.g. `["POST /api/payments/notify", "GET /api/out/:token"]`. Matching is
+   * exact; there are no globs, because a glob is how one entry silently widens
+   * to cover a route that does need an identity.
+   *
+   * Additive to core's own list, and it can never remove one. Core's defaults
+   * are in `auth/identity-free-routes.ts` with the evidence for each.
+   *
+   * The route then resolves NO actor, which also means it gets no plugin
+   * database scope — that scope is derived from the actor. Such a route must
+   * open its own, the way a signed webhook builds its actor from the payload it
+   * verified. Listing a route that reads `c.get("actor")` will not fail loudly.
+   */
+  identityFreeRoutes?: readonly string[];
   /**
    * Governs two layers, and its default differs between them.
    *

package/src/index.ts

@@ -42,7 +42,15 @@ export { createSystemActor } from "./auth/system-actor.js";
 export { OrganizationService } from "./modules/organization/service.js";
 export { createScopedDb } from "./kernel/database/scoped-db.js";
 export type { ScopedOrganizationId } from "./kernel/database/scoped-db.js";
-export { assertOwnership, assertPermission, requireUserId } from "./auth/permissions.js";
+export { IDENTITY_FREE_ROUTES, isIdentityFreeRoute } from "./auth/identity-free-routes.js";
+export type { IdentityFreeRoute } from "./auth/identity-free-routes.js";
+export {
+  AUTHENTICATION_REQUIRED_MESSAGE,
+  assertOwnership,
+  assertPermission,
+  isUnauthenticatedActor,
+  requireUserId,
+} from "./auth/permissions.js";
 export type { AccessResult, AccessContext, AccessFn, WhereClause } from "./auth/access.js";
 export {
   accessOR,
@@ -127,6 +135,7 @@ export {
   CommerceNotFoundError,
   CommerceValidationError,
   CommerceForbiddenError,
+  CommerceUnauthorizedError,
   CommerceReauthRequiredError,
   CommerceConflictError,
   CommerceInvalidTransitionError,

package/src/interfaces/rest/customer-portal.ts

@@ -1,6 +1,11 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../runtime/kernel.js";
-import { assertPermission, requireUserId } from "../../auth/permissions.js";
+import {
+  AUTHENTICATION_REQUIRED_MESSAGE,
+  assertPermission,
+  isUnauthenticatedActor,
+  requireUserId,
+} from "../../auth/permissions.js";
 import type { Actor } from "../../auth/types.js";
 import type { AppEnv } from "./utils.js";
 import {
@@ -23,14 +28,29 @@ type AuthenticatedActor = Actor & { userId: string };
 export function createCustomerPortalRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
+  // Two refusals, because two different callers are being turned away and one
+  // answer cannot serve both. The second clause is also what makes the
+  // `AuthenticatedActor` cast below true: every route under this guard reads
+  // `actor.userId` as a string.
   router.use("*", markRoutePermissionGuard(async (c, next) => {
     const actor = c.get("actor") as Actor | null;
-    if (!actor?.userId) {
+    if (isUnauthenticatedActor(actor)) {
       return c.json(
-        { error: { code: "FORBIDDEN", message: "Authentication required." } },
+        { error: { code: "UNAUTHORIZED", message: AUTHENTICATION_REQUIRED_MESSAGE } },
         401,
       );
     }
+    if (!actor?.userId) {
+      return c.json(
+        {
+          error: {
+            code: "FORBIDDEN",
+            message: "The customer portal requires a signed-in user, not an API key.",
+          },
+        },
+        403,
+      );
+    }
     await next();
   }));
 

package/src/interfaces/rest/router.ts

@@ -33,7 +33,11 @@ import type { CommerceConfig } from "../../config/types.js";
 import type { PluginRouteRegistration } from "../../kernel/plugin/manifest.js";
 import { createScopedDb } from "../../kernel/database/scoped-db.js";
 import { resolveOrgIdForCommerce } from "../../auth/org.js";
-import { hasPermission } from "../../auth/permissions.js";
+import {
+  AUTHENTICATION_REQUIRED_MESSAGE,
+  hasPermission,
+  isUnauthenticatedActor,
+} from "../../auth/permissions.js";
 import type { Actor } from "../../auth/types.js";
 
 // ─── Shared OpenAPI Error Responses ──────────────────────────────────────────
@@ -63,7 +67,16 @@ export interface RouteHandlerContext {
   query: Record<string, unknown>;
   /** Path parameters, auto-extracted from {id} segments. */
   params: Record<string, string>;
-  /** Authenticated actor. Guaranteed non-null if .auth() or .permission() was called. */
+  /**
+   * Authenticated actor. Guaranteed non-null if .auth() or .permission() was called.
+   *
+   * Structural rather than `Actor` ON PURPOSE. This is the published plugin
+   * API: plugins outside this repository cast it to their own shapes, and
+   * three call sites in `plugin-layaway` alone read it as
+   * `{ userId: string } & Record<string, unknown>` — a cast TypeScript refuses
+   * against a closed `Actor`. Narrowing it is a breaking change to a published
+   * contract, not a tidy-up, and it belongs to a card that migrates the callers.
+   */
   actor: { userId: string | null; role: string; permissions: string[]; vendorId?: string | null; [key: string]: unknown } | null;
   /** Resolved organization ID. Derived from actor.organizationId or the deployment config. */
   orgId: string;
@@ -218,8 +231,13 @@ class RouteChain {
         // Order: auth first (401), then permission (403).
         const actor = ctx.get("actor") as RouteHandlerContext["actor"];
 
-        if ((requireAuth || requiredPermission) && !actor) {
-          return ctx.json({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }, 401);
+        // `RouteHandlerContext["actor"]` is deliberately structural — see its
+        // declaration — but the middleware only ever sets a real `Actor`. Read
+        // the two identity fields through that type here rather than narrowing
+        // the published one, which breaks every plugin that casts it.
+        const identity = actor as Pick<Actor, "type" | "userId"> | null;
+        if ((requireAuth || requiredPermission) && isUnauthenticatedActor(identity)) {
+          return ctx.json({ error: { code: "UNAUTHORIZED", message: AUTHENTICATION_REQUIRED_MESSAGE } }, 401);
         }
 
         if (requiredPermission) {

package/src/interfaces/rest/utils.ts

@@ -2,6 +2,10 @@ import type { CommerceError } from "../../kernel/errors.js";
 import { mapErrorToStatus } from "../../kernel/error-mapper.js";
 import { toCommerceError } from "../../kernel/errors.js";
 import type { Actor } from "../../auth/types.js";
+import {
+  AUTHENTICATION_REQUIRED_MESSAGE,
+  isUnauthenticatedActor,
+} from "../../auth/permissions.js";
 
 export const ROUTE_PERMISSION_GUARD = Symbol("porulle.routePermissionGuard");
 
@@ -21,6 +25,7 @@ export function markPublicRoute<T>(handler: T, methods?: readonly string[]): T {
 }
 
 type PermissionContext = {
+  get(key: "actor"): Pick<Actor, "type" | "userId" | "permissions"> | null;
   get(key: string): unknown;
   json(data: unknown, status: number): unknown;
   req: { method: string };
@@ -84,12 +89,9 @@ export { mapErrorToStatus };
  * Usage: router.post("/", requirePerm("webhooks:manage"), handler);
  */
 export function requirePerm(permission: string) {
-  const middleware = async (c: { get(key: string): unknown; json(data: unknown, status: number): unknown }, next: () => Promise<void>) => {
-    const actor = c.get("actor") as { permissions?: string[] } | null;
-    if (!actor) {
-      return c.json({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }, 401);
-    }
-    const perms = actor.permissions ?? [];
+  const middleware = async (c: PermissionContext, next: () => Promise<void>) => {
+    const actor = c.get("actor");
+    const perms = actor?.permissions ?? [];
     if (perms.includes(permission) || perms.includes("*:*")) {
       await next();
       return;
@@ -100,27 +102,30 @@ export function requirePerm(permission: string) {
       await next();
       return;
     }
+    if (isUnauthenticatedActor(actor)) {
+      return c.json({ error: { code: "UNAUTHORIZED", message: AUTHENTICATION_REQUIRED_MESSAGE } }, 401);
+    }
     return c.json({ error: { code: "FORBIDDEN", message: `Permission '${permission}' is required.` } }, 403);
   };
   return markRoutePermissionGuard(middleware);
 }
 
 export function requireAnyPerm(permissions: readonly string[]) {
-  const middleware = async (c: { get(key: string): unknown; json(data: unknown, status: number): unknown }, next: () => Promise<void>) => {
-    const actor = c.get("actor") as { permissions?: string[] } | null;
+  const middleware = async (c: PermissionContext, next: () => Promise<void>) => {
+    const actor = c.get("actor");
     const granted = actor?.permissions ?? [];
     const allowed = permissions.some((permission) =>
       granted.includes(permission) ||
       granted.includes("*:*") ||
       granted.includes(`${permission.split(":")[0]}:*`),
     );
-    if (!actor) {
-      return c.json({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }, 401);
-    }
     if (allowed) {
       await next();
       return;
     }
+    if (isUnauthenticatedActor(actor)) {
+      return c.json({ error: { code: "UNAUTHORIZED", message: AUTHENTICATION_REQUIRED_MESSAGE } }, 401);
+    }
     return c.json({ error: { code: "FORBIDDEN", message: `One of these permissions is required: ${permissions.join(", ")}.` } }, 403);
   };
   return markRoutePermissionGuard(middleware);

package/src/kernel/error-mapper.ts

@@ -7,6 +7,7 @@ const statusByCode: Record<string, ContentfulStatusCode> = {
   NOT_FOUND: 404,
   VALIDATION_FAILED: 422,
   FORBIDDEN: 403,
+  UNAUTHORIZED: 401,
   REAUTH_REQUIRED: 401,
   CSRF_ORIGIN_REJECTED: 403,
   CONFLICT: 409,

package/src/kernel/errors.ts

@@ -81,6 +81,14 @@ export class CommerceForbiddenError extends Error implements CommerceError {
   }
 }
 
+export class CommerceUnauthorizedError extends Error implements CommerceError {
+  code = "UNAUTHORIZED" as const;
+  constructor(message: string, public details?: unknown) {
+    super(message);
+    this.name = "CommerceUnauthorizedError";
+  }
+}
+
 export class CommerceCsrfError extends Error implements CommerceError {
   code = "CSRF_ORIGIN_REJECTED" as const;
   constructor(

package/src/modules/cart/service.ts

@@ -1,10 +1,16 @@
 import { resolveOrgIdForCommerce } from "../../auth/org.js";
-import { assertOwnership, assertPermission } from "../../auth/permissions.js";
+import {
+  AUTHENTICATION_REQUIRED_MESSAGE,
+  assertOwnership,
+  assertPermission,
+  isUnauthenticatedActor,
+} from "../../auth/permissions.js";
 import type { Actor } from "../../auth/types.js";
 import type { CommerceConfig } from "../../config/types.js";
 import {
   CommerceForbiddenError,
   CommerceNotFoundError,
+  CommerceUnauthorizedError,
   CommerceValidationError,
   toCommerceError,
 } from "../../kernel/errors.js";
@@ -318,13 +324,39 @@ export class CartService {
       );
       item = updated!;
     } else {
+      // A new line needs a price, and a price the system cannot determine is refused rather than
+      // invented. This used to read `processed.unitPriceSnapshot ?? 1000`: a silent default in a
+      // money path, which nothing in the response, the logs or the schema disclosed. An integrator
+      // found it by comparing a deployed cart reading 1000 against a catalog priced 14500-22800.
+      //
+      // A hook still wins when it supplies one, so bespoke pricing keeps its seam; otherwise the
+      // pricing step answers — the SAME step `resolveCurrentPrices` uses at checkout, so a cart and
+      // its order agree by construction rather than by an integrator remembering to install a hook.
+      const currency = processed.currency ?? cart.currency;
+      let unitPriceSnapshot = processed.unitPriceSnapshot;
+      if (unitPriceSnapshot === undefined) {
+        const resolved = await this.resolveUnitPrice(
+          {
+            entityId: processed.entityId,
+            currency,
+            quantity,
+            ...(processed.variantId != null
+              ? { variantId: processed.variantId }
+              : {}),
+          },
+          actor ?? null,
+          ctx,
+        );
+        if (!resolved.ok) return resolved;
+        unitPriceSnapshot = resolved.value;
+      }
       item = await this.repo.createLineItem(
         {
           cartId: input.cartId,
           entityId: processed.entityId,
           quantity,
-          unitPriceSnapshot: processed.unitPriceSnapshot ?? 1000,
-          currency: processed.currency ?? cart.currency,
+          unitPriceSnapshot,
+          currency,
           metadata: processed.metadata ?? {},
           ...(processed.variantId !== undefined
             ? { variantId: processed.variantId }
@@ -339,6 +371,56 @@ export class CartService {
     return Ok(item);
   }
 
+  /**
+   * The unit price for a new cart line, from the pricing step. Refuses — naming the entity and the
+   * currency — when no price is configured, when the pricing service is absent, or when resolution
+   * fails for any other reason: every one of those is a value the system cannot determine, and the
+   * defect this replaces was substituting a literal for exactly that.
+   */
+  private async resolveUnitPrice(
+    input: {
+      entityId: string;
+      currency: string;
+      quantity: number;
+      variantId?: string;
+    },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<number>> {
+    const pricing = this.deps.services.pricing as
+      | {
+          resolve(
+            params: {
+              entityId: string;
+              currency: string;
+              quantity: number;
+              variantId?: string;
+            },
+            actor?: Actor | null,
+            ctx?: TxContext,
+          ): Promise<Result<{ finalAmount: number }>>;
+        }
+      | undefined;
+
+    if (typeof pricing?.resolve !== "function") {
+      return Err(
+        new CommerceValidationError(
+          `Cannot resolve a unit price for ${input.entityId}: no pricing service is configured.`,
+        ),
+      );
+    }
+
+    const resolved = await pricing.resolve(input, actor, ctx);
+    if (!resolved.ok) {
+      return Err(
+        new CommerceValidationError(
+          `Cannot resolve a unit price for ${input.entityId} (${input.currency}). Configure a price for it, or supply unitPriceSnapshot from a cart.beforeAddItem hook.`,
+        ),
+      );
+    }
+    return Ok(resolved.value.finalAmount);
+  }
+
   async removeItem(
     cartId: string,
     itemId: string,
@@ -820,10 +902,8 @@ export class CartService {
     if (actor && actor.permissions.includes("*:*")) return;
 
     if (cart.customerId != null) {
-      if (!actor) {
-        throw new CommerceForbiddenError(
-          "Authentication required to read customer cart.",
-        );
+      if (isUnauthenticatedActor(actor)) {
+        throw new CommerceUnauthorizedError(AUTHENTICATION_REQUIRED_MESSAGE);
       }
       const profileId = await this.resolveActorCustomerId(actor, ctx);
       if (profileId !== cart.customerId) {