@porulle/core 0.40.0 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/core",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/auth/middleware.ts

@@ -17,6 +17,33 @@ function emptyToNull(value: string | null | undefined): string | null {
 // `catalog:read` here would 401 every public storefront read.
 export { DEFAULT_CUSTOMER_PERMISSIONS } from "./actor.js";
 
+/**
+ * The challenge RFC 9110 §15.5.2 requires on a 401: it "MUST include a WWW-Authenticate header
+ * field containing at least one challenge applicable to the target resource". Without it a 401
+ * names no scheme, so it is advice a generic HTTP client cannot act on.
+ *
+ * `Bearer` and nothing else. Both credentials this API accepts — the session cookie the mobile
+ * client holds and the `x-api-key` a machine holds — are presented as bearer-style tokens, and a
+ * `Basic` challenge would make a browser render a native credential prompt over a JSON API.
+ *
+ * The realm is a constant. It must never carry the organization or vendor, which would disclose
+ * tenancy to a caller that has not authenticated.
+ */
+export const AUTHENTICATE_CHALLENGE = 'Bearer realm="api"';
+
+/**
+ * Attach the challenge to a 401, and to nothing else.
+ *
+ * NOT unconditional: §15.5.4 asks no challenge of a 403, and offering one there tells a caller who
+ * IS authenticated to try authenticating again. An existing header is left alone so a plugin or a
+ * route can answer with a more specific challenge than this default.
+ */
+export function applyAuthenticateChallenge(response: Response): void {
+  if (response.status !== 401) return;
+  if (response.headers.has("www-authenticate")) return;
+  response.headers.set("www-authenticate", AUTHENTICATE_CHALLENGE);
+}
+
 const LEGACY_STORE_RESOLVER_WARN_COOLDOWN_MS = 60_000;
 let lastLegacyStoreResolverWarnAt = 0;
 
@@ -24,7 +51,15 @@ export function authMiddleware(
   auth: AuthInstance,
   config: CommerceConfig,
 ): MiddlewareHandler {
-  return async (c, next) => {
+  /**
+   * The resolution body. It has FIVE `next()` call sites and four of them `return` immediately
+   * after — a signed-in caller leaves at the `if (actor)` branch, an API-key caller at its own,
+   * and only an anonymous caller reaches the last one. Anything that must run for EVERY request
+   * therefore cannot live at the bottom of this function: it would fire for one caller class and
+   * silently skip the rest. Measured, not assumed — a header set at the bottom reached an
+   * anonymous 401 and never reached a signed-in 403.
+   */
+  const resolve: MiddlewareHandler = async (c, next) => {
     if (isIdentityFreeRoute(c.req.method, c.req.path, config)) {
       c.set("actor", null);
       await next();
@@ -238,4 +273,28 @@ export function authMiddleware(
     }
     await next();
   };
+
+  // ONE boundary around all five of the body's exits. A 401 leaves this server by five routes —
+  // `requirePerm` and `requireAnyPerm` in interfaces/rest/utils.ts, the plugin router's inline
+  // refusal, the customer portal's own, and a thrown `CommerceUnauthorizedError` shaped by
+  // `mapErrorToResponse` — and every one of them unwinds through here whichever way the body
+  // returned. So one line covers all five, and any sixth refusal added later, which five copies of
+  // the rule could not.
+  //
+  // The only 401 that does NOT reach this point is one produced by `app.onError`: by then every
+  // `await next()` in the chain has already rejected. runtime/server.ts calls the same helper there.
+  return async (c, next) => {
+    // The body RETURNS a Response on one path — the strict-org-resolution 503 — and Hono assigns
+    // that return value over `c.res` after this handler finishes. Dropping it on the floor turned
+    // two `ORG_RESOLUTION_FAILED` rows red, and challenging `c.res` instead of the returned object
+    // would have mutated a response that was about to be replaced. Both cases are handled by
+    // challenging whichever object is actually going to be sent.
+    const returned = await resolve(c, next);
+    if (returned instanceof Response) {
+      applyAuthenticateChallenge(returned);
+      return returned;
+    }
+    applyAuthenticateChallenge(c.res);
+    return;
+  };
 }

package/src/auth/permissions.ts

@@ -41,15 +41,17 @@ export function assertPermission(actor: Actor | null, required: string): void {
   );
 }
 
-// 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.");
+  // Written exactly as `assertPermission` above, and for the same two reasons: `actor === null`
+  // is redundant at runtime because the predicate already covers it, and load-bearing at compile
+  // time because a boolean predicate narrows nothing and the lines below read off `actor`.
+  //
+  // Hoisting the predicate is what makes the rest of this function readable: an `api_key` actor
+  // presented a credential and a `userId: ""` actor is a credential with a blank identity, so
+  // neither satisfies the predicate and both fall through to the 403 below — telling either to
+  // authenticate would be advice it cannot act on.
+  if (actor === null || isUnauthenticatedActor(actor)) {
+    throw new CommerceUnauthorizedError(AUTHENTICATION_REQUIRED_MESSAGE);
   }
   if (actor.permissions.includes("*:*")) return;
   if (!actor.userId || !resourceOwnerId) {

package/src/hooks/checkout.ts

@@ -4,6 +4,7 @@ import type { CompensationFailuresRepository } from "../kernel/compensation/repo
 import type { AfterHook, BeforeHook } from "../kernel/hooks/types.js";
 import type { ShippingAddress } from "../modules/shipping/calculator.js";
 import type { AppliedPromotion } from "../modules/promotions/service.js";
+import type { PriceResolutionContext } from "../modules/pricing/service.js";
 import { runCompensationChain } from "../kernel/compensation/executor.js";
 import type { CompensationContext } from "../kernel/compensation/types.js";
 import type { TxContext } from "../kernel/database/tx-context.js";
@@ -209,14 +210,7 @@ export const resolveCurrentPrices: BeforeHook<CheckoutData> = async ({
   context,
 }) => {
   const pricing = context.services.pricing as {
-    resolve(params: {
-      entityId: string;
-      variantId?: string;
-      currency: string;
-      quantity: number;
-      customerId?: string;
-      customerGroupIds?: string[];
-    }, actor?: unknown): Promise<
+    resolve(params: PriceResolutionContext, actor?: unknown): Promise<
       | {
           ok: true;
           value: {
@@ -239,7 +233,6 @@ export const resolveCurrentPrices: BeforeHook<CheckoutData> = async ({
       currency: data.currency,
       quantity: item.quantity,
       ...(item.variantId !== undefined ? { variantId: item.variantId } : {}),
-      ...(data.customerId !== undefined ? { customerId: data.customerId } : {}),
       ...(data.customerGroupIds !== undefined
         ? { customerGroupIds: data.customerGroupIds }
         : {}),

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

@@ -125,7 +125,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
     const status = c.req.query("status");
     // Resolve customer profile UUID from Better Auth userId
     const customerResult = await kernel.services.customers.getByUserId(actor.userId, actor);
-    if (!customerResult.ok) return c.json({ data: [], meta: { total: 0, page: 1, limit: 20, totalPages: 0 } });
+    if (!customerResult.ok) return c.json({ data: [], meta: { pagination: { page: 1, limit: 20, total: 0, totalPages: 0 } } });
     const result = await kernel.services.orders.listByCustomer(
       customerResult.value.id,
       {

package/src/interfaces/rest/schemas/responses.ts

@@ -56,6 +56,9 @@ export const CustomerAddressSchema = createSelectSchema(customerAddresses).opena
 export const CatalogEntitySchema = createSelectSchema(sellableEntities, {
   // Override jsonb → narrow to object (drizzle-zod maps jsonb to a wide union)
   metadata: z.record(z.string(), z.unknown()).openapi({ example: { weight: 200, material: "cotton" } }),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  publishedAt: z.string().datetime().nullable(),
 }).openapi("CatalogEntity");
 
 // ─── Jobs ────────────────────────────────────────────────────────────────────
@@ -77,10 +80,13 @@ export function paginatedResponse<T extends z.ZodType>(schema: T, name: string)
   return z.object({
     data: z.array(schema),
     meta: z.object({
-      page: z.number(),
-      limit: z.number(),
-      total: z.number().optional(),
-    }).optional(),
+      pagination: z.object({
+        page: z.number(),
+        limit: z.number(),
+        total: z.number(),
+        totalPages: z.number(),
+      }),
+    }),
   }).openapi(name);
 }
 

package/src/modules/cart/service.ts

@@ -1,7 +1,6 @@
 import { resolveOrgIdForCommerce } from "../../auth/org.js";
 import {
   AUTHENTICATION_REQUIRED_MESSAGE,
-  assertOwnership,
   assertPermission,
   isUnauthenticatedActor,
 } from "../../auth/permissions.js";

package/src/modules/pricing/service.ts

@@ -62,7 +62,6 @@ export interface PriceResolutionContext {
   variantId?: string;
   currency: string;
   quantity: number;
-  customerId?: string;
   customerGroupIds?: string[];
   timestamp?: Date;
 }

package/src/runtime/kernel-register-hooks.ts

@@ -3,7 +3,6 @@ import { HookRegistry, type HookHandler } from "../kernel/hooks/registry.js";
 import { deliverWebhooks } from "../modules/webhooks/hook.js";
 import { syncToSearchIndex } from "../modules/search/hooks.js";
 import { auditHooks } from "../modules/audit/hooks.js";
-import { sendOrderStatusEmail } from "../hooks/order-emails.js";
 
 export function registerConfiguredKernelHooks(
   config: CommerceConfig,
@@ -40,7 +39,6 @@ export function registerConfiguredKernelHooks(
 
   hooks.append("orders.afterCreate", deliverWebhooks);
   hooks.append("orders.afterStatusChange", deliverWebhooks);
-  hooks.append("orders.afterStatusChange", sendOrderStatusEmail as (...args: unknown[]) => unknown);
   hooks.append("catalog.afterCreate", deliverWebhooks);
   hooks.append("catalog.afterUpdate", deliverWebhooks);
   hooks.append("catalog.afterDelete", deliverWebhooks);

package/src/runtime/server.ts

@@ -10,7 +10,7 @@ import { createClientIpResolver } from "./client-ip.js";
 import type { Actor } from "../auth/types.js";
 import type { AuthInstance } from "../auth/setup.js";
 import type { CommerceConfig } from "../config/types.js";
-import { authMiddleware } from "../auth/middleware.js";
+import { applyAuthenticateChallenge, authMiddleware } from "../auth/middleware.js";
 import { resolveOrgIdForCommerce } from "../auth/org.js";
 import { organizationGuard } from "../auth/organization-guard.js";
 import type { DrizzleDatabase } from "../kernel/database/drizzle-db.js";
@@ -371,7 +371,12 @@ export async function createServer(config: CommerceConfig) {
   const isProd = process.env.NODE_ENV === "production";
   app.onError((err, c) => {
     const { body, status } = mapErrorToResponse(err, isProd, logger);
-    return c.json(body, status);
+    const response = c.json(body, status);
+    // The one 401 the auth middleware cannot reach: by the time onError runs, every `await next()`
+    // in the chain has already rejected, so its post-next step never executes. Same helper, so the
+    // rule lives in one place even though it is applied in two.
+    applyAuthenticateChallenge(response);
+    return response;
   });
 
   // ─── Routes ──────────────────────────────────────────────────────────

package/dist/hooks/order-emails.d.ts

@@ -1,16 +0,0 @@
-/**
- * Order lifecycle email notifications.
- *
- * Sends emails on status changes: confirmed, fulfilled, cancelled, refunded.
- * Registered as an orders.afterStatusChange hook.
- */
-import type { AfterHook } from "../kernel/hooks/types.js";
-interface StatusChangeResult {
-    orderId: string;
-    customerId?: string | null;
-    newStatus: string;
-    previousStatus: string;
-}
-export declare const sendOrderStatusEmail: AfterHook<StatusChangeResult>;
-export {};
-//# sourceMappingURL=order-emails.d.ts.map

package/dist/hooks/order-emails.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"order-emails.d.ts","sourceRoot":"","sources":["../../src/hooks/order-emails.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,UAAU,kBAAkB;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,oBAAoB,EAAE,SAAS,CAAC,kBAAkB,CA6C9D,CAAC"}

package/dist/hooks/order-emails.js

@@ -1,44 +0,0 @@
-/**
- * Order lifecycle email notifications.
- *
- * Sends emails on status changes: confirmed, fulfilled, cancelled, refunded.
- * Registered as an orders.afterStatusChange hook.
- */
-export const sendOrderStatusEmail = async ({ result, context, }) => {
-    const email = context.services.email;
-    if (!email?.send)
-        return;
-    // Only send for customer-facing status changes
-    const notifiableStatuses = ["confirmed", "processing", "fulfilled", "cancelled", "refunded"];
-    if (!notifiableStatuses.includes(result.newStatus))
-        return;
-    // Look up customer email
-    const customerId = result.customerId;
-    if (!customerId)
-        return;
-    const customers = context.services.customers;
-    if (!customers)
-        return;
-    try {
-        const customer = await customers.getByUserId(customerId, context.actor);
-        if (!customer.ok || !customer.value?.email)
-            return;
-        await email.send({
-            template: "order-status-change",
-            to: customer.value.email,
-            data: {
-                orderId: result.orderId,
-                newStatus: result.newStatus,
-                previousStatus: result.previousStatus,
-            },
-        });
-    }
-    catch (err) {
-        // Email failure must not break the order flow
-        context.logger.warn("Order status email failed", {
-            orderId: result.orderId,
-            newStatus: result.newStatus,
-            error: err instanceof Error ? err.message : String(err),
-        });
-    }
-};

package/src/hooks/order-emails.ts

@@ -1,62 +0,0 @@
-/**
- * Order lifecycle email notifications.
- *
- * Sends emails on status changes: confirmed, fulfilled, cancelled, refunded.
- * Registered as an orders.afterStatusChange hook.
- */
-
-import type { AfterHook } from "../kernel/hooks/types.js";
-
-interface StatusChangeResult {
-  orderId: string;
-  customerId?: string | null;
-  newStatus: string;
-  previousStatus: string;
-}
-
-export const sendOrderStatusEmail: AfterHook<StatusChangeResult> = async ({
-  result,
-  context,
-}) => {
-  const email = context.services.email as
-    | { send(input: { template: string; to: string; data?: Record<string, unknown> }): Promise<void> }
-    | undefined;
-
-  if (!email?.send) return;
-
-  // Only send for customer-facing status changes
-  const notifiableStatuses = ["confirmed", "processing", "fulfilled", "cancelled", "refunded"];
-  if (!notifiableStatuses.includes(result.newStatus)) return;
-
-  // Look up customer email
-  const customerId = result.customerId;
-  if (!customerId) return;
-
-  const customers = context.services.customers as
-    | { getByUserId(id: string, actor?: unknown): Promise<{ ok: boolean; value?: { email?: string | null } }> }
-    | undefined;
-
-  if (!customers) return;
-
-  try {
-    const customer = await customers.getByUserId(customerId, context.actor);
-    if (!customer.ok || !customer.value?.email) return;
-
-    await email.send({
-      template: "order-status-change",
-      to: customer.value.email,
-      data: {
-        orderId: result.orderId,
-        newStatus: result.newStatus,
-        previousStatus: result.previousStatus,
-      },
-    });
-  } catch (err) {
-    // Email failure must not break the order flow
-    context.logger.warn("Order status email failed", {
-      orderId: result.orderId,
-      newStatus: result.newStatus,
-      error: err instanceof Error ? err.message : String(err),
-    });
-  }
-};