@porulle/core 0.39.0 → 0.40.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/core",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "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/kernel/hooks/executor.ts

@@ -104,13 +104,13 @@ export async function runBeforeHooks<T>(
   return current;
 }
 
-export async function runAfterHooks<T>(
-  hooks: AfterHook<T>[],
-  originalData: T | null,
-  committedResult: T,
+export async function runAfterHooks<TResult, TData = TResult>(
+  hooks: AfterHook<TResult, TData>[],
+  originalData: TData | null,
+  committedResult: TResult,
   operation: HookOperation,
   context: HookContext,
-  runsInTransaction: (hook: AfterHook<T>) => boolean = () => false,
+  runsInTransaction: (hook: AfterHook<TResult, TData>) => boolean = () => false,
 ): Promise<HookReport> {
   const errors: HookError[] = [];
   for (const hook of hooks) {

package/src/kernel/hooks/types.ts

@@ -50,9 +50,18 @@ export type BeforeHook<TData> = (args: {
   context: HookContext;
 }) => Promise<TData> | TData;
 
-export type AfterHook<TData> = (args: {
+/**
+ * `data` is what went in, `result` is what was committed. For most operations
+ * those are the same shape, so `TData` defaults to `TResult` and a single type
+ * argument keeps its old meaning.
+ *
+ * They differ where the committed entity is not the input: a status change
+ * commits a hydrated order but its input is the transition itself, and a hook
+ * that cannot see which transition occurred cannot act on one.
+ */
+export type AfterHook<TResult, TData = TResult> = (args: {
   data: TData | null;
-  result: TData;
+  result: TResult;
   operation: HookOperation;
   context: HookContext;
 }) => Promise<void> | void;

package/src/modules/orders/service.ts

@@ -134,7 +134,14 @@ type StatusChangeHookInput = {
   reason?: string;
 };
 type BeforeStatusChangeHook = BeforeHook<StatusChangeHookInput>;
-type AfterStatusChangeHook = AfterHook<HydratedOrder>;
+/**
+ * `result` is the committed, hydrated order; `data` is the transition that
+ * produced it. A subscriber that must act on *which* transition occurred — the
+ * channel connector pushes an order to its merchant only when it leaves
+ * `pending_payment` — cannot read that from the order alone, because the order
+ * carries only the status it now has.
+ */
+type AfterStatusChangeHook = AfterHook<HydratedOrder, StatusChangeHookInput>;
 
 function context(
   actor: Actor | null,
@@ -1254,7 +1261,7 @@ export class OrderService {
     const hydrated = await this.hydrateOrder(cas, ctx);
     const report = await runAfterHooks(
       afterHooks,
-      null,
+      statusHookInput,
       hydrated,
       "statusChange",
       hookCtx,

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 ──────────────────────────────────────────────────────────