@porulle/core 0.10.8 → 0.13.0

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

@@ -34,10 +34,13 @@ export type FieldType = "text" | "number" | "boolean" | "date" | "json" | "relat
 export interface EntityFieldDefinition {
   name: string;
   type: FieldType;
+  filterable?: boolean;
+  localized?: boolean;
   unit?: string;
   schema?: unknown;
   target?: string;
   options?: string[];
+  sortOrder?: number;
 }
 
 export interface EntityVariantConfig {
@@ -197,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;
   /**
@@ -255,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,
@@ -141,8 +142,12 @@ export type {
 } from "./modules/payments/adapter.js";
 export { defineChannelConnector } from "./modules/channels/adapter.js";
 export type {
+  ChannelCatalogImage,
   ChannelCatalogItem,
+  ChannelCatalogLocalizedAttributes,
+  ChannelCatalogOptionType,
   ChannelCatalogPage,
+  ChannelCatalogPrice,
   ChannelCatalogVariant,
   ChannelConnector,
   ChannelConnectorCapabilities,
@@ -150,6 +155,14 @@ export type {
   ChannelOrderLine,
   ChannelOrderSlice,
   ChannelConnectorError,
+  ChannelPushCatalogField,
+  ChannelPushCatalogImage,
+  ChannelPushCatalogIntent,
+  ChannelPushCatalogItem,
+  ChannelPushCatalogItemOutcome,
+  ChannelPushCatalogPreviousField,
+  ChannelPushCatalogResult,
+  ChannelPushCatalogVariant,
   ChannelOrderStatus,
   ChannelPushOrderResult,
   ChannelRefundResult,
@@ -169,14 +182,20 @@ export type {
   SearchSuggestParams,
 } from "./modules/search/adapter.js";
 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,
@@ -235,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 {

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

@@ -1,6 +1,6 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../runtime/kernel.js";
-import { assertPermission } from "../../auth/permissions.js";
+import { assertPermission, requireUserId } from "../../auth/permissions.js";
 import type { Actor } from "../../auth/types.js";
 import type { AppEnv } from "./utils.js";
 import {
@@ -16,27 +16,30 @@ import {
   updateProfileRoute,
   createAddressRoute,
 } from "./schemas/customer-portal.js";
-import { isUUID, mapErrorToStatus } from "./utils.js";
+import { isUUID, mapErrorToStatus, markRoutePermissionGuard } from "./utils.js";
+
+type AuthenticatedActor = Actor & { userId: string };
 
 export function createCustomerPortalRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
-  router.use("*", async (c, next) => {
-    if (!c.get("actor")) {
+  router.use("*", markRoutePermissionGuard(async (c, next) => {
+    const actor = c.get("actor") as Actor | null;
+    if (!actor?.userId) {
       return c.json(
         { error: { code: "FORBIDDEN", message: "Authentication required." } },
         401,
       );
     }
     await next();
-  });
+  }));
 
   /**
    * Resolves an actor whose userId is the customer profile UUID (not the Better Auth user ID).
    * Required so that `assertOwnership(actor, order.customerId)` compares UUIDs correctly,
    * since orders.customer_id stores the customer profile UUID, not the Better Auth string ID.
    */
-  async function resolveCustomerActor(actor: Actor): Promise<Actor | null> {
+  async function resolveCustomerActor(actor: AuthenticatedActor): Promise<AuthenticatedActor | null> {
     const customer = await kernel.services.customers.getByUserId(actor.userId, actor);
     if (!customer.ok) return null;
     return { ...actor, userId: customer.value.id };
@@ -44,7 +47,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getProfileRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const customer = await kernel.services.customers.getByUserId(actor.userId, actor);
     if (!customer.ok) return c.json({ error: customer.error }, 404);
     return c.json({ data: customer.value });
@@ -52,7 +55,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(updateProfileRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     assertPermission(actor, "customers:update:self");
     const result = await kernel.services.customers.updateByUserId(
       actor.userId,
@@ -64,7 +67,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
   });
 
   router.openapi(listAddressesRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const addresses = await kernel.services.customers.getAddresses(
       actor.userId,
       actor,
@@ -74,7 +77,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(createAddressRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const result = await kernel.services.customers.addAddress(
       actor.userId,
       c.req.valid("json") as Parameters<typeof kernel.services.customers.addAddress>[1],
@@ -86,7 +89,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(deleteAddressRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const result = await kernel.services.customers.deleteAddress(
       actor.userId,
       c.req.param("id"),
@@ -98,23 +101,27 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listCustomerOrdersRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     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 } });
-    const result = await kernel.services.orders.listByCustomer(customerResult.value.id, {
-      page: Number.parseInt(c.req.query("page") ?? "1", 10),
-      limit: Number.parseInt(c.req.query("limit") ?? "20", 10),
-      ...(status !== undefined ? { status } : {}),
-    });
-    if (!result.ok) return c.json({ error: result.error }, 500);
+    const result = await kernel.services.orders.listByCustomer(
+      customerResult.value.id,
+      {
+        page: Number.parseInt(c.req.query("page") ?? "1", 10),
+        limit: Number.parseInt(c.req.query("limit") ?? "20", 10),
+        ...(status !== undefined ? { status } : {}),
+      },
+      actor,
+    );
+    if (!result.ok) return c.json({ error: result.error }, mapErrorToStatus(result.error));
     return c.json({ data: result.value.items, meta: result.value.pagination });
   });
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getCustomerOrderRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const id = c.req.param("idOrNumber");
     const customerActor = await resolveCustomerActor(actor);
     if (!customerActor) return c.json({ error: { code: "NOT_FOUND", message: "Customer profile not found." } }, 404);
@@ -129,7 +136,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getOrderTrackingRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const id = c.req.param("idOrNumber");
     const customerActor = await resolveCustomerActor(actor);
     if (!customerActor) return c.json({ error: { code: "NOT_FOUND", message: "Customer profile not found." } }, 404);
@@ -167,7 +174,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getOrderDownloadsRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const customerActor = await resolveCustomerActor(actor);
     if (!customerActor) return c.json({ error: { code: "NOT_FOUND", message: "Customer profile not found." } }, 404);
     const orderResult = await kernel.services.orders.getById(
@@ -209,7 +216,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listCoursesRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const result = await kernel.services.fulfillment.getDigitalAccess(
       actor.userId,
       "course",
@@ -230,7 +237,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(reorderRoute, async (c) => {
-    const actor = c.get("actor") as Actor;
+    const actor = c.get("actor") as AuthenticatedActor;
     const customerActor = await resolveCustomerActor(actor);
     if (!customerActor) return c.json({ error: { code: "NOT_FOUND", message: "Customer profile not found." } }, 404);
     const orderResult = await kernel.services.orders.getById(
@@ -246,7 +253,7 @@ export function createCustomerPortalRoutes(kernel: Kernel) {
 
     const cartResult = await kernel.services.cart.create(
       {
-        customerId: actor.userId,
+        customerId: requireUserId(actor),
         currency: orderResult.value.currency,
       },
       actor,

package/src/interfaces/rest/index.ts

@@ -21,6 +21,8 @@ import { adminJobRoutes } from "./routes/admin-jobs.js";
 import { compensationFailureAdminRoutes } from "./routes/admin/compensation-failures.js";
 import { adminPermissionsRoutes } from "./routes/admin/permissions.js";
 import { adminStaffRoutes } from "./routes/admin/staff.js";
+import { adminEntityFieldDefinitionRoutes } from "./routes/admin/entity-field-definitions.js";
+import { adminCustomFieldProposalRoutes } from "./routes/admin/custom-field-proposals.js";
 import { customerRoutes } from "./routes/customers.js";
 import { documentRoutes } from "./routes/documents.js";
 import { settingsRoutes } from "./routes/settings.js";
@@ -94,6 +96,8 @@ export function createRestRoutes(kernel: Kernel) {
   router.route("/admin", compensationFailureAdminRoutes(kernel));
   router.route("/admin", adminPermissionsRoutes(kernel));
   router.route("/admin", adminStaffRoutes(kernel));
+  router.route("/admin", adminEntityFieldDefinitionRoutes(kernel));
+  router.route("/admin", adminCustomFieldProposalRoutes(kernel));
 
   // API Reference (Scalar) — disabled in production unless config.exposeOpenApiSpec is true
   const exposeSpec = kernel.config.exposeOpenApiSpec ?? (process.env.NODE_ENV !== "production");