@open-mercato/cli 0.5.1-develop.2652.0276e72e45 → 0.5.1-develop.2663.2c29774b5b

package/dist/agentic/guides/ui.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/dist/lib/generators/module-registry.js

@@ -679,7 +679,7 @@ function detectExportedHttpMethods(sourceFile) {
   return knownMethods.filter((method) => exportedMethods.has(method));
 }
 function buildPageRouteProps(metaExpr, routePath) {
-  return `pattern: ${toLiteral(routePath || "/")}, requireAuth: (${metaExpr})?.requireAuth, requireRoles: (${metaExpr})?.requireRoles, requireFeatures: (${metaExpr})?.requireFeatures, requireCustomerAuth: (${metaExpr})?.requireCustomerAuth, requireCustomerFeatures: (${metaExpr})?.requireCustomerFeatures, title: (${metaExpr})?.pageTitle ?? (${metaExpr})?.title, titleKey: (${metaExpr})?.pageTitleKey ?? (${metaExpr})?.titleKey, group: (${metaExpr})?.pageGroup ?? (${metaExpr})?.group, groupKey: (${metaExpr})?.pageGroupKey ?? (${metaExpr})?.groupKey, icon: (${metaExpr})?.icon, order: (${metaExpr})?.pageOrder ?? (${metaExpr})?.order, priority: (${metaExpr})?.pagePriority ?? (${metaExpr})?.priority, navHidden: (${metaExpr})?.navHidden, visible: (${metaExpr})?.visible, enabled: (${metaExpr})?.enabled, breadcrumb: (${metaExpr})?.breadcrumb, pageContext: (${metaExpr})?.pageContext, placement: (${metaExpr})?.placement`;
+  return `pattern: ${toLiteral(routePath || "/")}, requireAuth: (${metaExpr})?.requireAuth, requireRoles: (${metaExpr})?.requireRoles, requireFeatures: (${metaExpr})?.requireFeatures, requireCustomerAuth: (${metaExpr})?.requireCustomerAuth, requireCustomerFeatures: (${metaExpr})?.requireCustomerFeatures, nav: (${metaExpr})?.nav, title: (${metaExpr})?.pageTitle ?? (${metaExpr})?.title, titleKey: (${metaExpr})?.pageTitleKey ?? (${metaExpr})?.titleKey, group: (${metaExpr})?.pageGroup ?? (${metaExpr})?.group, groupKey: (${metaExpr})?.pageGroupKey ?? (${metaExpr})?.groupKey, icon: (${metaExpr})?.icon, order: (${metaExpr})?.pageOrder ?? (${metaExpr})?.order, priority: (${metaExpr})?.pagePriority ?? (${metaExpr})?.priority, navHidden: (${metaExpr})?.navHidden, visible: (${metaExpr})?.visible, enabled: (${metaExpr})?.enabled, breadcrumb: (${metaExpr})?.breadcrumb, pageContext: (${metaExpr})?.pageContext, placement: (${metaExpr})?.placement`;
 }
 function normalizeBreadcrumb(raw) {
   if (!Array.isArray(raw)) return void 0;
@@ -706,6 +706,19 @@ function normalizePlacement(raw) {
     order: typeof source.order === "number" ? source.order : void 0
   };
 }
+function normalizePortalNav(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const source = raw;
+  if (typeof source.label !== "string" || source.label.length === 0) return void 0;
+  const group = source.group === "main" || source.group === "account" ? source.group : void 0;
+  return {
+    label: source.label,
+    labelKey: typeof source.labelKey === "string" ? source.labelKey : void 0,
+    group,
+    order: typeof source.order === "number" ? source.order : void 0,
+    icon: typeof source.icon === "string" ? source.icon : void 0
+  };
+}
 function normalizePageMetadata(raw) {
   if (!raw || typeof raw !== "object") return null;
   const source = raw;
@@ -735,6 +748,8 @@ function normalizePageMetadata(raw) {
   if (breadcrumb) normalized.breadcrumb = breadcrumb;
   const placement = normalizePlacement(source.placement);
   if (placement) normalized.placement = placement;
+  const nav = normalizePortalNav(source.nav);
+  if (nav) normalized.nav = nav;
   if (typeof source.icon === "string") normalized.icon = source.icon;
   return Object.keys(normalized).length > 0 ? normalized : null;
 }
@@ -1446,6 +1461,7 @@ function buildPageRouteEntries(metaExpr, routePath) {
     { name: "requireFeatures", value: optionalPropertyAccess(meta, "requireFeatures") },
     { name: "requireCustomerAuth", value: optionalPropertyAccess(meta, "requireCustomerAuth") },
     { name: "requireCustomerFeatures", value: optionalPropertyAccess(meta, "requireCustomerFeatures") },
+    { name: "nav", value: optionalPropertyAccess(meta, "nav") },
     {
       name: "title",
       value: nullishCoalesce([
@@ -2265,13 +2281,15 @@ async function generateModuleRegistry(options) {
   {
     const bootstrapPlugins = [...pluginRegistry.values()].filter((p) => p.bootstrapRegistration);
     const allEntryImports = [
-      buildImportStatement(`{ backendRoutes }`, `./backend-routes.generated`)
+      buildImportStatement(`{ backendRoutes }`, `./backend-routes.generated`),
+      buildImportStatement(`{ frontendRoutes }`, `./frontend-routes.generated`)
     ];
     const allRegImports = [
-      `import { registerBackendRouteManifests } from '@open-mercato/shared/modules/registry'`
+      `import { registerBackendRouteManifests, registerFrontendRouteManifests } from '@open-mercato/shared/modules/registry'`
     ];
     const allCalls = [
-      `registerBackendRouteManifests(backendRoutes)`
+      `registerBackendRouteManifests(backendRoutes)`,
+      `registerFrontendRouteManifests(frontendRoutes)`
     ];
     for (const plugin of bootstrapPlugins) {
       const reg = plugin.bootstrapRegistration;