@porulle/core 0.11.0 → 0.13.0

package/src/auth/organization-guard.ts

@@ -0,0 +1,158 @@
+import type { MiddlewareHandler } from "hono";
+import { and, eq } from "drizzle-orm";
+import type { CommerceConfig } from "../config/types.js";
+import type { DrizzleDatabase } from "../kernel/database/drizzle-db.js";
+import { invitation, member } from "./auth-schema.js";
+import { canGrantRole, granterForRole, isCompositeRole } from "./role-authority.js";
+
+/**
+ * Guards Better Auth's organization endpoints, which this repository mounts but
+ * does not govern.
+ *
+ * Red-team round 6 found two problems behind that mount.
+ *
+ * Invitation acceptance re-checked nothing: an invitation minted a member at
+ * the authority its inviter held up to seven days ago, so a demoted or revoked
+ * inviter's outstanding invitation still handed out ownership — a full
+ * organization takeover. Acceptance now re-reads the inviter's current
+ * authority before the grant is allowed through.
+ *
+ * And the plugin's own membership writers are a second role-changing surface
+ * running none of the rules `admin/staff.ts` enforces: no permission
+ * containment, no rank floor, no last-owner invariant, and they accept
+ * comma-composite role strings that `admin/staff.ts` refuses. They are refused
+ * here. `admin/staff.ts` is this repository's governed membership surface, and
+ * having one is worth more than making two of them agree.
+ */
+
+const ORGANIZATION_PREFIX = "/api/auth/organization/";
+
+/**
+ * Better Auth endpoints that write membership or define what a role may do.
+ *
+ * `invite-member` currently throws for every role instead of refusing: the
+ * plugin is configured with commerce permission arrays where its access-control
+ * model expects `Role` objects exposing `.authorize()`, so its permission check
+ * dies of type confusion. That is fail-closed by accident, and the accident is
+ * one "fix the roles wiring" commit away from being fail-open. Refusing here
+ * makes the closure deliberate, so repairing that wiring cannot quietly open an
+ * ungoverned door. `update-member-role` is not even inert today — Better Auth
+ * short-circuits it for organization creators, so an owner reaches it.
+ */
+const REFUSED_ENDPOINTS = new Set([
+  "invite-member",
+  "update-member-role",
+  "remove-member",
+  "leave",
+  "create-role",
+  "update-role",
+  "delete-role",
+]);
+
+function endpointName(path: string): string | null {
+  const normalized = path.replace(/\/+$/, "");
+  return normalized.startsWith(ORGANIZATION_PREFIX)
+    ? normalized.slice(ORGANIZATION_PREFIX.length)
+    : null;
+}
+
+async function readJsonBody(request: Request): Promise<Record<string, unknown>> {
+  try {
+    return (await request.clone().json()) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+export function organizationGuard(
+  db: DrizzleDatabase,
+  config: CommerceConfig,
+): MiddlewareHandler {
+  return async (c, next) => {
+    if (c.req.method !== "POST") {
+      await next();
+      return;
+    }
+
+    const endpoint = endpointName(c.req.path);
+    if (endpoint === null) {
+      await next();
+      return;
+    }
+
+    if (REFUSED_ENDPOINTS.has(endpoint)) {
+      return c.json(
+        {
+          error: {
+            code: "FORBIDDEN",
+            message: `"${endpoint}" is not a governed membership surface. Use /api/admin/staff, which enforces permission containment, the rank floor, and the last-owner invariant.`,
+          },
+        },
+        403,
+      );
+    }
+
+    if (endpoint !== "accept-invitation") {
+      await next();
+      return;
+    }
+
+    const body = await readJsonBody(c.req.raw);
+    const invitationId = typeof body.invitationId === "string" ? body.invitationId : null;
+    if (!invitationId) {
+      await next();
+      return;
+    }
+
+    const rows = await db
+      .select()
+      .from(invitation)
+      .where(eq(invitation.id, invitationId));
+    const pending = rows[0];
+    // Missing, already-answered, or expired invitations are Better Auth's own
+    // error surface — do not duplicate its messages here.
+    if (!pending || pending.status !== "pending") {
+      await next();
+      return;
+    }
+
+    const invitedRole = pending.role ?? "member";
+    const inviterRows = await db
+      .select({ role: member.role })
+      .from(member)
+      .where(
+        and(
+          eq(member.organizationId, pending.organizationId),
+          eq(member.userId, pending.inviterId),
+        ),
+      );
+    const inviterRole = inviterRows[0]?.role;
+
+    const stillAuthorized =
+      inviterRole !== undefined &&
+      !isCompositeRole(invitedRole) &&
+      canGrantRole(config, granterForRole(config, inviterRole), invitedRole);
+
+    if (stillAuthorized) {
+      await next();
+      return;
+    }
+
+    // The grant is dead: burn it rather than leaving it to be retried.
+    await db
+      .update(invitation)
+      .set({ status: "canceled" })
+      .where(and(eq(invitation.id, invitationId), eq(invitation.status, "pending")));
+
+    return c.json(
+      {
+        error: {
+          code: "FORBIDDEN",
+          message:
+            "This invitation is no longer valid: the member who sent it can no longer grant that role.",
+        },
+      },
+      403,
+    );
+  };
+}

package/src/auth/permissions.ts

@@ -1,16 +1,18 @@
 import { CommerceForbiddenError } from "../kernel/errors.js";
 import type { Actor } from "./types.js";
 
-export function assertPermission(actor: Actor | null, required: string): void {
-  if (!actor) {
-    throw new CommerceForbiddenError("Authentication required.");
-  }
-
-  if (actor.permissions.includes("*:*")) return;
+export function hasPermission(actor: Actor | null, required: string): boolean {
+  if (!actor) return false;
+  if (actor.permissions.includes("*:*")) return true;
 
   const [resource] = required.split(":");
-  if (resource && actor.permissions.includes(`${resource}:*`)) return;
-  if (actor.permissions.includes(required)) return;
+  if (resource && actor.permissions.includes(`${resource}:*`)) return true;
+  return actor.permissions.includes(required);
+}
+
+export function assertPermission(actor: Actor | null, required: string): void {
+  if (hasPermission(actor, required)) return;
+  if (!actor) throw new CommerceForbiddenError("Authentication required.");
 
   throw new CommerceForbiddenError(
     `Permission "${required}" is required. Your role "${actor.role}" does not include this permission.`,
@@ -22,7 +24,28 @@ export function assertOwnership(actor: Actor | null, resourceOwnerId: string | n
     throw new CommerceForbiddenError("Authentication required.");
   }
   if (actor.permissions.includes("*:*")) return;
+  if (!actor.userId || !resourceOwnerId) {
+    throw new CommerceForbiddenError("You do not have access to this resource.");
+  }
   if (actor.userId !== resourceOwnerId) {
     throw new CommerceForbiddenError("You do not have access to this resource.");
   }
 }
+
+/**
+ * The actor's user id, for code that keys a per-person resource on it.
+ *
+ * An actor without a user identity — a store resolver, an API key — has no
+ * owner key at all. Passing its absence through as one would make every such
+ * caller look like the same person, so this refuses instead of returning a
+ * value that reads as an identity.
+ */
+export function requireUserId(actor: Pick<Actor, "userId"> | null): string {
+  if (!actor) {
+    throw new CommerceForbiddenError("Authentication required.");
+  }
+  if (!actor.userId) {
+    throw new CommerceForbiddenError("This action requires a signed-in user.");
+  }
+  return actor.userId;
+}

package/src/auth/role-authority.ts

@@ -0,0 +1,107 @@
+import type { CommerceConfig } from "../config/types.js";
+
+const BUILTIN_ROLE_RANK: Record<string, number> = {
+  owner: 3,
+  admin: 2,
+};
+const CUSTOM_ROLE_RANK = 1;
+
+/**
+ * Who may grant which role.
+ *
+ * Every surface that mints or changes a membership answers this question, and
+ * they must all answer it the same way — the admin staff routes, and the guard
+ * in front of Better Auth's organization endpoints. Red-team round 6 found the
+ * takeover that follows from two surfaces disagreeing, so the arithmetic lives
+ * here and nowhere else.
+ */
+
+/**
+ * Better Auth stores a member's role as a comma-separated list, so `"owner"`
+ * and `"owner,admin"` are both owners to it. Commerce role lookups are exact
+ * string matches, which is how a composite string used to read as an unknown
+ * custom role on one side and an owner on the other.
+ */
+export function roleParts(role: string | null | undefined): string[] {
+  return (role ?? "")
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+export function isCompositeRole(role: string | null | undefined): boolean {
+  return roleParts(role).length > 1;
+}
+
+/** True when any part of the role string is `owner`, matching Better Auth. */
+export function isOwnerRole(role: string | null | undefined): boolean {
+  return roleParts(role).includes("owner");
+}
+
+export function permissionsForRole(config: CommerceConfig, role: string): string[] {
+  return config.auth?.roles?.[role]?.permissions ?? [];
+}
+
+export function hasPermissionFromList(
+  actorPermissions: readonly string[],
+  required: string,
+): boolean {
+  if (actorPermissions.includes("*:*")) return true;
+
+  const [resource] = required.split(":");
+  if (resource && actorPermissions.includes(`${resource}:*`)) return true;
+  return actorPermissions.includes(required);
+}
+
+/**
+ * The role's privilege rank. A composite role ranks as its strongest part, so
+ * `"owner,admin"` cannot slip past a rank floor by failing an exact lookup.
+ */
+export function roleRank(config: CommerceConfig, role: string | null | undefined): number {
+  const ranks = roleParts(role).map((part) => {
+    const builtin = BUILTIN_ROLE_RANK[part];
+    if (builtin !== undefined) return builtin;
+    if (permissionsForRole(config, part).includes("*:*")) return BUILTIN_ROLE_RANK["admin"]!;
+    return CUSTOM_ROLE_RANK;
+  });
+  return ranks.length > 0 ? Math.max(...ranks) : CUSTOM_ROLE_RANK;
+}
+
+export interface Granter {
+  role: string;
+  permissions: readonly string[];
+}
+
+/**
+ * A granter may assign `targetRole` only when it already holds every permission
+ * that role carries (containment) and outranks or equals it (rank floor).
+ */
+export function canGrantRole(
+  config: CommerceConfig,
+  granter: Granter | null,
+  targetRole: string,
+): boolean {
+  if (!granter) return false;
+  const contains = permissionsForRole(config, targetRole).every((permission) =>
+    hasPermissionFromList(granter.permissions, permission),
+  );
+  return contains && roleRank(config, granter.role) >= roleRank(config, targetRole);
+}
+
+/**
+ * The granter a stored membership row represents. Permissions come from the
+ * role's current definition, which is the whole point of re-checking authority
+ * later: the row is re-read, not the authority the actor had when they acted.
+ */
+export function granterForRole(config: CommerceConfig, role: string): Granter {
+  return { role, permissions: permissionsForRole(config, role) };
+}
+
+export function validRoles(config: CommerceConfig): Set<string> {
+  return new Set([
+    ...Object.keys(config.auth?.roles ?? {}),
+    "owner",
+    "admin",
+    "member",
+  ]);
+}

package/src/auth/setup.ts

@@ -65,6 +65,23 @@ export function createAuth(
     | ReturnType<typeof jwt>
     | ReturnType<typeof bearer>
   > = [
+    // These are commerce permission arrays, not Better Auth access-control
+    // `Role` objects exposing `.authorize()`. Its organization plugin therefore
+    // cannot evaluate a permission with them, and every check reaching its
+    // authorize loop throws instead of deciding — fail-closed, but by type
+    // confusion rather than by intent.
+    //
+    // That is deliberate and stays. This repository does not use Better Auth's
+    // access-control model: `admin/staff.ts` is the governed membership
+    // surface, and `auth/role-authority.ts` holds the arithmetic. Handing the
+    // plugin real `Role` objects would stand up a second permission model to
+    // keep in agreement with the first, which is how the two layers disagreed
+    // about composite roles and owner counting in the first place.
+    //
+    // What must not be relied on is the throw. `auth/organization-guard.ts`
+    // refuses the plugin's membership writers outright, so repairing this
+    // wiring cannot turn an accidental closure into an open door. Pin that
+    // guard's test before changing anything here.
     organization({
       roles: (config.auth?.roles ?? {}) as unknown as Record<string, Role | undefined>,
     }),

package/src/auth/strict-org-resolution.ts

@@ -7,8 +7,14 @@ export function setBootStrictOrgResolution(strict: boolean): void {
 }
 
 export function isStrictOrgResolution(config?: CommerceConfig | null): boolean {
+  // Fail closed by default. Without an actor there is no tenant, and silently
+  // resolving to a default organization served one merchant's data to
+  // unauthenticated callers on every unguarded or allowlisted read path.
+  // Single-tenant deployments that relied on that fallback opt out explicitly.
+  if (config?.auth?.strictOrgResolution === false) return false;
+  if (process.env.STRICT_ORG_RESOLUTION === "false") return false;
   if (config?.auth?.strictOrgResolution === true) return true;
   if (process.env.STRICT_ORG_RESOLUTION === "true") return true;
   if ((config === undefined || config === null) && _bootStrictOrgResolution) return true;
-  return false;
+  return true;
 }

package/src/auth/types.ts

@@ -1,6 +1,6 @@
 export interface Actor {
   type: "user" | "api_key";
-  userId: string;
+  userId: string | null;
   email: string | null;
   name: string;
   vendorId: string | null;

package/src/config/defaults.ts

@@ -24,10 +24,12 @@ export const defaultConfig: Partial<CommerceConfig> = {
           "catalog:update",
           "catalog:delete",
           "catalog:read",
+          "catalog:read:unpublished",
           "inventory:read",
           "inventory:adjust",
           "orders:read",
           "orders:create",
+          "orders:create:on-behalf",
           "orders:update",
           "orders:manage",
           "cart:create",

package/src/config/types.ts

@@ -200,10 +200,17 @@ export interface AuthConfig {
    */
   storeResolver?: (request: Request) => string | null | Promise<string | null>;
   /**
-   * When true, a failing `storeResolver` for anonymous requests returns HTTP 503
-   * instead of continuing with `actor = null` (legacy). Same behavior when env
-   * `STRICT_ORG_RESOLUTION` is `"true"`. Default false keeps backward-compatible
-   * fallback for single-store and lenient multi-store setups.
+   * Governs two layers, and its default differs between them.
+   *
+   * In the store-resolver middleware, `true` makes a failing `storeResolver`
+   * return HTTP 503 rather than continuing with `actor = null`; that layer
+   * still defaults to the lenient behaviour.
+   *
+   * In organization resolution it **fails closed by default**: an actor-less
+   * request with no explicit organization and no `defaultOrganizationId` is
+   * refused rather than served a fallback tenant. Set this to `false`, or the
+   * env var `STRICT_ORG_RESOLUTION` to `"false"`, to restore the old fallback
+   * during a migration.
    */
   strictOrgResolution?: boolean;
   /**
@@ -258,7 +265,25 @@ export interface CheckoutConfig {
   };
 }
 
+/**
+ * Decides whether a guest bearer credential (a cart secret) may still read a
+ * placed order. The authenticated customer who owns an order is never subject
+ * to this — ownership grants permanent access.
+ *
+ * Modelled on Vendure's `OrderByCodeAccessStrategy`: the value of the seam is
+ * that the policy has one home, rather than being an emergent property of the
+ * read path.
+ */
+export interface GuestOrderAccessStrategy {
+  canAccessOrder(order: { placedAt: Date }, now: Date): boolean;
+}
+
 export interface OrdersConfig {
+  /**
+   * How long a guest cart secret keeps reading an order after placement.
+   * Defaults to `windowedGuestOrderAccess("7d")`.
+   */
+  guestAccessStrategy?: GuestOrderAccessStrategy;
   hooks?: {
     beforeCreate?: BeforeHook<unknown>[];
     afterCreate?: AfterHook<unknown>[];

package/src/hooks/checkout.ts

@@ -1,5 +1,5 @@
 import { CommerceValidationError } from "../kernel/errors.js";
-import { resolveOrgId } from "../auth/org.js";
+import { resolveOrgIdForCommerce } from "../auth/org.js";
 import type { CompensationFailuresRepository } from "../kernel/compensation/repository.js";
 import type { AfterHook, BeforeHook } from "../kernel/hooks/types.js";
 import type { ShippingAddress } from "../modules/shipping/calculator.js";
@@ -97,7 +97,7 @@ export const validateCartNotEmpty: BeforeHook<CheckoutData> = async ({
   context,
 }) => {
   const cartService = context.services.cart as {
-    getById(id: string, actor?: unknown): Promise<
+    getByIdForInternalUse(id: string, organizationId: string, ctx?: TxContext): Promise<
       | {
           ok: true;
           value: {
@@ -114,7 +114,7 @@ export const validateCartNotEmpty: BeforeHook<CheckoutData> = async ({
         }
       | { ok: false }
     >;
-    claimForCheckout(cartId: string, ctx?: unknown): Promise<
+    claimForCheckout(cartId: string, claimToken: string, ctx?: unknown): Promise<
       | { ok: true; value: { id: string } }
       | { ok: false; error: { message: string } }
     >;
@@ -122,7 +122,9 @@ export const validateCartNotEmpty: BeforeHook<CheckoutData> = async ({
   const catalogService = context.services.catalog as {
     getById(
       id: string,
-      options?: { includeAttributes?: boolean },
+      options: { includeAttributes?: boolean } | undefined,
+      actor: unknown,
+      ctx?: TxContext,
     ): Promise<
       | {
           ok: true;
@@ -137,20 +139,25 @@ export const validateCartNotEmpty: BeforeHook<CheckoutData> = async ({
 
   // M1 fix: Atomically claim the cart for checkout (active → checking_out).
   // If a concurrent request already claimed it, this returns Err and we fail fast.
-  const claimed = await cartService.claimForCheckout(data.cartId, context.tx);
+  // The checkout id is the claim token, so only this attempt can release it.
+  const claimed = await cartService.claimForCheckout(data.cartId, data.checkoutId, context.tx);
   if (!claimed.ok) {
     throw new CommerceValidationError(
       "Cart is not available for checkout. It may have already been checked out by a concurrent request.",
     );
   }
 
-  const cart = await cartService.getById(data.cartId, context.actor);
+  const cart = await cartService.getByIdForInternalUse(
+    data.cartId,
+    resolveOrgIdForCommerce(context.actor, context.commerceConfig),
+    context.tx as TxContext | undefined,
+  );
   if (!cart.ok || cart.value.lineItems.length === 0) {
     throw new CommerceValidationError("Cannot checkout an empty cart.");
   }
 
   // Cross-org guard: prevent org B from checking out org A's cart
-  const actorOrgId = resolveOrgId(context.actor);
+  const actorOrgId = resolveOrgIdForCommerce(context.actor, context.commerceConfig);
   if (cart.value.organizationId && cart.value.organizationId !== actorOrgId) {
     throw new CommerceValidationError("Cart does not belong to this organization.");
   }
@@ -174,7 +181,7 @@ export const validateCartNotEmpty: BeforeHook<CheckoutData> = async ({
     cart.value.lineItems.map(async (item) => {
       const entity = await catalogService.getById(item.entityId, {
         includeAttributes: true,
-      });
+      }, context.actor, context.tx as TxContext | undefined);
       const title = entity.ok
         ? (entity.value.attributes?.[0]?.title ?? item.entityId)
         : item.entityId;
@@ -323,7 +330,7 @@ export const applyPromotionCodes: BeforeHook<CheckoutData> = async ({
   };
 
   const result = await promotions.applyPromotions({
-    orgId: resolveOrgId(context.actor),
+    orgId: resolveOrgIdForCommerce(context.actor, context.commerceConfig),
     cartId: data.cartId,
     currency: data.currency,
     subtotal: data.subtotal,
@@ -411,7 +418,7 @@ export const calculateTax: BeforeHook<CheckoutData> = async ({
     ...(data.shippingAddress !== undefined
       ? { toAddress: data.shippingAddress }
       : {}),
-  }, resolveOrgId(context.actor ?? null));
+  }, resolveOrgIdForCommerce(context.actor ?? null, context.commerceConfig));
 
   if (!calculated.ok) {
     throw new CommerceValidationError(
@@ -469,7 +476,7 @@ export const calculateShipping: BeforeHook<CheckoutData> = async ({
     })),
     subtotalAfterDiscount: Math.max(0, data.subtotal - data.discountTotal),
     currency: data.currency,
-    orgId: resolveOrgId(context.actor ?? null),
+    orgId: resolveOrgIdForCommerce(context.actor ?? null, context.commerceConfig),
     ...(data.shippingAddress !== undefined
       ? { address: data.shippingAddress }
       : {}),
@@ -546,7 +553,7 @@ export const authorizePayment: BeforeHook<CheckoutData> = async ({
       : {}),
     metadata: {
       ...(data.orderId !== undefined ? { orderId: data.orderId } : {}),
-      organizationId: resolveOrgId(context.actor),
+      organizationId: resolveOrgIdForCommerce(context.actor, context.commerceConfig),
       checkoutId: data.checkoutId,
       cartId: data.cartId,
     },

package/src/index.ts

@@ -3,6 +3,7 @@ export type {
   CommerceConfig,
   CommercePlugin,
   ApiKeyScopeDefinition,
+  GuestOrderAccessStrategy,
 } from "./config/types.js";
 export { defineCommercePlugin } from "./kernel/plugin/manifest.js";
 export type {
@@ -31,12 +32,12 @@ export type { Kernel } from "./runtime/kernel.js";
 // This avoids pulling drizzle-kit/tsx/esbuild into Turbopack's bundle graph.
 
 export type { Actor } from "./auth/types.js";
-export { resolveOrgId, ensureDefaultOrg, DEFAULT_ORG_ID } from "./auth/org.js";
+export { resolveOrgId, resolveOrgIdForCommerce, ensureDefaultOrg, DEFAULT_ORG_ID } from "./auth/org.js";
 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 } from "./auth/permissions.js";
+export { assertOwnership, assertPermission, requireUserId } from "./auth/permissions.js";
 export type { AccessResult, AccessContext, AccessFn, WhereClause } from "./auth/access.js";
 export {
   accessOR,
@@ -183,14 +184,18 @@ export type {
 export type { DatabaseAdapter } from "./kernel/database/adapter.js";
 export { isValidFieldPath, validateFieldPath } from "./modules/catalog/ownership.js";
 export type { FieldPath, FieldOwner } from "./modules/catalog/ownership.js";
+export type {
+  TxContext,
+  WithTransactionOptions,
+  CatalogWriteContext,
+  HookContextCarrier,
+} from "./kernel/database/tx-context.js";
 export {
   createTxContext,
   reuseOrCreateTxContext,
   withTransaction,
-} from "./kernel/database/tx-context.js";
-export type {
-  TxContext,
-  WithTransactionOptions,
+  isWriteContextTransactional,
+  resolveWriteContextHookContext,
 } from "./kernel/database/tx-context.js";
 export type {
   TaxAdapter,
@@ -249,6 +254,11 @@ export type { QueryInput, QueryResult } from "./kernel/query/executor.js";
 export type { CommerceModuleTypes } from "./types/commerce-types.js";
 
 export { staleOrderCleanupTask } from "./modules/orders/stale-order-cleanup.js";
+export {
+  windowedGuestOrderAccess,
+  defaultGuestOrderAccess,
+  parseAccessWindow,
+} from "./modules/orders/guest-access.js";
 export { COMMERCE_AGENT_SYSTEM_PROMPT } from "./utils/agent-prompt.js";
 
 export { DrizzleAnalyticsAdapter } from "./modules/analytics/drizzle-adapter.js";

package/src/interfaces/rest/audit-middleware.ts

@@ -95,12 +95,14 @@ export function auditMiddleware(kernel: Kernel): MiddlewareHandler {
     try {
       const requestId = c.get("requestId") as string | undefined;
       const ctx = createHookContext({
+        // Anonymous audit records retain actor: null; organization comes from the deployment config.
         actor: (c.get("actor") as Actor | null) ?? null,
         ...(requestId ? { requestId } : {}),
         logger: kernel.logger,
         services: kernel.services as unknown as ServiceContainer,
         database: { db: kernel.database.db as unknown as PluginDb },
         origin: "rest",
+        commerceConfig: kernel.config,
       });
       await kernel.services.audit.record({ entityType, entityId, event, payload, ctx });
     } catch {