@open-mercato/ui 0.4.11-develop.2635.9f9e474720 → 0.5.0

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-Generated lucide registry with 83 icons -> /home/runner/work/open-mercato/open-mercato/packages/ui/src/backend/icons/lucideRegistry.generated.tsx
-Found 256 entry points
+Generated lucide registry with 127 icons -> /home/runner/work/open-mercato/open-mercato/packages/ui/src/backend/icons/lucideRegistry.generated.tsx
+Found 257 entry points
 ui built successfully

package/AGENTS.md

@@ -249,19 +249,43 @@ function MyPage({ orgSlug }) {
 | `section:portal:sidebar` | Navigation sidebar |
 | `section:portal:user-menu` | User dropdown |
 
-### Declarative Customer Auth in Page Metadata
+### Portal Page Metadata (REQUIRED)
 
-Portal pages can declare `requireCustomerAuth: true` and `requireCustomerFeatures` in their page metadata:
+Every portal page (any page under `frontend/[orgSlug]/portal/...`) MUST ship a sibling `page.meta.ts`. The `(frontend)` catch-all server-side enforces `requireCustomerAuth` and `requireCustomerFeatures` from the route manifest, so omitting metadata silently disables access control on a page that should be guarded.
+
+Authoring checklist for each portal page:
+- Public pages (`login`, `signup`, `verify`, anonymous landing): set `navHidden: true`. Do not set `requireCustomerAuth`.
+- Authenticated pages: set `requireCustomerAuth: true`.
+- Pages that need feature gating: add `requireCustomerFeatures: ['portal.<feature>']`. Wildcard grants like `portal.*` are honored by the shared matcher.
+- Pages that should appear in the portal sidebar: add a `nav` block (label + group). Pages without `nav` are routable but not auto-listed (correct for detail/edit pages).
 
 ```typescript
 // frontend/[orgSlug]/portal/orders/page.meta.ts
-export const metadata = {
+import type { PageMetadata } from '@open-mercato/shared/modules/registry'
+
+export const metadata: PageMetadata = {
   requireCustomerAuth: true,
   requireCustomerFeatures: ['portal.orders.view'],
-  navHidden: true,
+  titleKey: 'orders.nav.title',
+  title: 'Orders',
+  nav: {
+    label: 'Orders',
+    labelKey: 'orders.nav.title',
+    group: 'main', // 'main' | 'account'
+    order: 20,
+    icon: 'shopping-bag',
+  },
 }
+
+export default metadata
 ```
 
+The portal sidebar is built from these `nav` declarations by `/api/customer_accounts/portal/nav`, filtered by `CustomerRbacService` against the same `requireCustomerFeatures` that gates access. Granting the feature to a customer role is sufficient for the entry to appear — no separate menu-injection widget required.
+
+For external links or items without a backing portal page, keep using `usePortalInjectedMenuItems` widgets.
+
+Reference: see `packages/core/src/modules/portal/frontend/[orgSlug]/portal/{dashboard,profile,login,signup,verify}/page.meta.ts` for examples.
+
 ### Declarative Customer Role Features in setup.ts
 
 Modules can declare features to be merged into customer role ACLs:

package/agentic/standalone-guide.md

@@ -206,6 +206,103 @@ import {
 | `PortalNotificationBell` | `t` | Header bell icon with unread badge |
 | `PortalNotificationPanel` | — | Notification dropdown panel |
 
+### Portal Page Structure
+
+Every portal page is two files under `frontend/[orgSlug]/portal/<path>/`:
+
+```
+page.tsx        # Client component ("use client")
+page.meta.ts    # PageMetadata — access control + sidebar nav
+```
+
+Minimal page:
+
+```tsx
+"use client"
+import { usePortalContext } from '@open-mercato/ui/portal/PortalContext'
+import { PortalPageHeader } from '@open-mercato/ui/portal/components'
+
+export default function MyPortalPage({ params }: { params: { orgSlug: string } }) {
+  const { auth } = usePortalContext()
+  const { user, resolvedFeatures } = auth
+  return <PortalPageHeader title="Orders" />
+}
+```
+
+Prefer `usePortalContext()` inside pages wrapped by `PortalLayoutShell` — it reads server-hydrated auth and avoids client loading flashes. Reach for `useCustomerAuth(orgSlug)` only when the server wrapper is unavailable.
+
+Minimal `page.meta.ts`:
+
+```ts
+import type { PageMetadata } from '@open-mercato/shared/modules/registry'
+
+export const metadata: PageMetadata = {
+  requireCustomerAuth: true,
+  requireCustomerFeatures: ['portal.orders.view'],
+  titleKey: 'portal.orders.title',
+  title: 'Orders',
+  nav: { label: 'Orders', labelKey: 'portal.nav.orders', group: 'main', order: 20 },
+}
+
+export default metadata
+```
+
+- Public pages (login, signup, verify, forgot/reset-password): omit `requireCustomerAuth`; set `navHidden: true`.
+- Authenticated pages without sidebar presence (detail/create/edit): set `requireCustomerAuth: true`, **omit** `nav`.
+- Sidebar-visible pages: include a `nav` block. Feature-gated pages are automatically hidden when the user lacks grants.
+
+Reference: `packages/core/src/modules/portal/frontend/[orgSlug]/portal/{dashboard,profile}/page.{tsx,meta.ts}`.
+
+### Portal Feature-Gating Contract
+
+Single source of truth: `requireCustomerFeatures` in `page.meta.ts`. The same list is enforced in three layers:
+
+| Layer | Where | Effect |
+|---|---|---|
+| Page access | `apps/mercato/src/app/(frontend)/[...slug]/page.tsx` | Server-side gate via `CustomerRbacService.userHasAllFeatures()` — missing feature blocks render |
+| Sidebar entry | `/api/customer_accounts/portal/nav` → `buildPortalNav()` at `packages/ui/src/portal/utils/nav.ts` | Same check — missing feature omits the entry |
+| Injection widgets | `usePortalInjectedMenuItems` / `usePortalDashboardWidgets` | `/api/customer_accounts/portal/feature-check` + `hasAllFeatures()` — missing feature filters the widget |
+
+Granting a customer role a feature (e.g. `portal.orders.view`) is sufficient to (a) reach the page, (b) see the sidebar entry, (c) see widgets gated by that feature. No separate menu-injection widget is required for sidebar presence when the page is backed by `page.meta.ts` with a `nav` block.
+
+**MUST** resolve features via `hasAllFeatures` / `matchFeature` from `@open-mercato/shared/security/features`. Raw `Array.includes()` or `Set.has()` on feature arrays misses wildcards (`portal.*`) and is a bug.
+
+Declare features in `acl.ts`; ship defaults per role via `defaultCustomerRoleFeatures` in `setup.ts`. Never rely on client-side checks alone as the access gate.
+
+### Portal SPA CSRF Posture
+
+Dual cookies set by login (`packages/core/src/modules/customer_accounts/api/login.ts`):
+
+| Cookie | Contents | TTL | Flags |
+|---|---|---|---|
+| `customer_auth_token` | Short-lived JWT | 8h | `httpOnly`, `sameSite: 'lax'`, `secure` in prod, `path: '/'` |
+| `customer_session_token` | Raw session token (hashed at rest) | 30d (env: `CUSTOMER_SESSION_TTL_DAYS`) | same as above |
+
+Primary CSRF defense: `SameSite=lax` + same-origin deployment. No explicit CSRF token — the browser blocks cross-origin POSTs.
+
+Rules:
+- Use `apiCall` for every write — it uses `credentials: 'same-origin'` and sets JSON headers.
+- Never expose either cookie to JS. `httpOnly` is load-bearing; do not add companion cookies that mirror session state.
+- Never accept cross-origin POSTs on portal routes. Cross-origin use cases are explicit exceptions: per-tenant origin allowlist + CSRF token + re-auth.
+- `sameSite: 'lax'` lets GET navigations carry cookies — keep all state-changing side effects behind POST/PUT/PATCH/DELETE.
+- Logout (`api/portal/logout.ts`) clears both cookies with `maxAge: 0`. Mirror this shape for any new logout-style endpoints.
+
+Concurrent sessions are capped at `MAX_CUSTOMER_SESSIONS_PER_USER` (default 5) in `customerSessionService.createSession()`. New sessions above the cap soft-delete the oldest active session.
+
+### Portal XSS Discipline (Injected Widgets)
+
+Third-party widgets render inside the authenticated portal and inherit user cookies. Enforce stricter discipline than first-party code because widgets load from arbitrary modules.
+
+- **Forbidden**: `dangerouslySetInnerHTML` anywhere in portal injection widgets. Render structured data, not raw HTML.
+- **Labels and user-facing text**: always through `useT()`; render as text children, never as HTML.
+- **Icons**: Lucide components (`lucide-react`). No inline `<svg>` composed from user-controlled strings.
+- **Asset URLs** (`src`, `href`, `action`, `srcDoc`): must not be user-controlled unless validated server-side against an allowlist.
+- **No `eval`, `new Function`, `setTimeout(string)`**, or similar dynamic code paths.
+- **Event-handler payloads** from SSE: validate shape (`isPortalBroadcastEvent` guards dispatch; never trust `event.data` to be well-formed without schema validation).
+- **Styles**: no user-controlled strings in `style` props, CSS variables, or `className` built from untrusted input.
+
+Prefer components that accept structured props over ones accepting `children` / `innerHTML` — the host keeps control of escaping.
+
 ### PortalShell Usage
 
 ```tsx

package/build.mjs

@@ -9,13 +9,15 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 function normalizeKebabIconName(input) {
   const trimmed = input.trim()
   if (!trimmed) return ''
-  if (!trimmed.includes('-') && !trimmed.includes('_') && !trimmed.includes(' ') && /[A-Z]/.test(trimmed)) {
-    return trimmed
+  const withoutPrefix = trimmed.startsWith('lucide:') ? trimmed.slice('lucide:'.length) : trimmed
+  if (!withoutPrefix) return ''
+  if (!withoutPrefix.includes('-') && !withoutPrefix.includes('_') && !withoutPrefix.includes(' ') && /[A-Z]/.test(withoutPrefix)) {
+    return withoutPrefix
       .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
       .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
       .toLowerCase()
   }
-  return trimmed
+  return withoutPrefix
     .replace(/[_\s]+/g, '-')
     .replace(/-+/g, '-')
     .toLowerCase()
@@ -109,13 +111,15 @@ ${registryEntries ? `${registryEntries}\n` : ''}}
 function normalizeKebabIconName(input: string): string {
   const trimmed = input.trim()
   if (!trimmed) return ''
-  if (!trimmed.includes('-') && !trimmed.includes('_') && !trimmed.includes(' ') && /[A-Z]/.test(trimmed)) {
-    return trimmed
+  const withoutPrefix = trimmed.startsWith('lucide:') ? trimmed.slice('lucide:'.length) : trimmed
+  if (!withoutPrefix) return ''
+  if (!withoutPrefix.includes('-') && !withoutPrefix.includes('_') && !withoutPrefix.includes(' ') && /[A-Z]/.test(withoutPrefix)) {
+    return withoutPrefix
       .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
       .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
       .toLowerCase()
   }
-  return trimmed
+  return withoutPrefix
     .replace(/[_\\s]+/g, '-')
     .replace(/-+/g, '-')
     .toLowerCase()

package/dist/backend/AppShell.js

@@ -46,6 +46,7 @@ function convertInjectedMenuItemToSidebarItem(item, title) {
     title,
     defaultTitle: title,
     icon: resolveInjectedIcon(item.icon) ?? void 0,
+    iconName: item.icon,
     enabled: true,
     hidden: false,
     pageContext: "main"
@@ -200,8 +201,12 @@ function resolveItemKey(item) {
 function SerializedIcon({ markup }) {
   return /* @__PURE__ */ jsx("span", { "aria-hidden": "true", dangerouslySetInnerHTML: { __html: markup } });
 }
-function renderIcon(icon, iconMarkup, fallback) {
+function renderIcon(icon, iconName, iconMarkup, fallback) {
   if (icon) return icon;
+  if (iconName) {
+    const resolved = resolveInjectedIcon(iconName);
+    if (resolved) return resolved;
+  }
   if (iconMarkup) return /* @__PURE__ */ jsx(SerializedIcon, { markup: iconMarkup });
   return fallback;
 }
@@ -657,6 +662,7 @@ function AppShellBody({ productName, email, groups, rightHeaderSlot, children, s
                     isActive && /* @__PURE__ */ jsx("span", { className: "absolute left-0 top-1 bottom-1 w-0.5 rounded bg-foreground" }),
                     /* @__PURE__ */ jsx("span", { className: `flex items-center justify-center shrink-0 ${compact ? "" : "text-muted-foreground"}`, children: renderIcon(
                       item.icon,
+                      item.iconName,
                       item.iconMarkup,
                       item.href.includes("/backend/entities/user/") && item.href.endsWith("/records") ? DataTableIcon : DefaultIcon
                     ) }),
@@ -992,7 +998,12 @@ function AppShellBody({ productName, email, groups, rightHeaderSlot, children, s
                       onClick: () => setMobileOpen(false),
                       children: [
                         isParentActive ? /* @__PURE__ */ jsx("span", { className: "absolute left-0 top-1 bottom-1 w-0.5 rounded bg-foreground" }) : null,
-                        /* @__PURE__ */ jsx("span", { className: `flex items-center justify-center shrink-0 ${compact ? "" : "text-muted-foreground"}`, children: renderIcon(i.icon, i.iconMarkup, DefaultIcon) }),
+                        /* @__PURE__ */ jsx("span", { className: `flex items-center justify-center shrink-0 ${compact ? "" : "text-muted-foreground"}`, children: renderIcon(
+                          i.icon,
+                          i.iconName,
+                          i.iconMarkup,
+                          DefaultIcon
+                        ) }),
                         !compact && /* @__PURE__ */ jsx("span", { children: i.title })
                       ]
                     }
@@ -1013,6 +1024,7 @@ function AppShellBody({ productName, email, groups, rightHeaderSlot, children, s
                           childActive ? /* @__PURE__ */ jsx("span", { className: "absolute left-0 top-1 bottom-1 w-0.5 rounded bg-foreground" }) : null,
                           /* @__PURE__ */ jsx("span", { className: `flex items-center justify-center shrink-0 ${compact ? "" : "text-muted-foreground"}`, children: renderIcon(
                             c.icon,
+                            c.iconName,
                             c.iconMarkup,
                             c.href.includes("/backend/entities/user/") && c.href.endsWith("/records") ? DataTableIcon : DefaultIcon
                           ) }),
@@ -1257,6 +1269,7 @@ AppShell.cloneGroups = function cloneGroups(groups) {
     title: item.title,
     defaultTitle: item.defaultTitle,
     icon: item.icon,
+    iconName: item.iconName,
     iconMarkup: item.iconMarkup,
     enabled: item.enabled,
     hidden: item.hidden,