create-mercato-app 0.5.1-develop.2652.0276e72e45 → 0.5.1-develop.2657.a01847a9fa

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mercato-app",
-  "version": "0.5.1-develop.2652.0276e72e45",
+  "version": "0.5.1-develop.2657.a01847a9fa",
   "type": "module",
   "description": "Create a new Open Mercato application",
   "main": "./dist/index.js",

package/template/src/app/(frontend)/[...slug]/page.tsx

@@ -1,7 +1,9 @@
 import { notFound, redirect } from 'next/navigation'
 import Link from 'next/link'
-import { findRouteManifestMatch } from '@open-mercato/shared/modules/registry'
+import { findRouteManifestMatch, registerFrontendRouteManifests } from '@open-mercato/shared/modules/registry'
 import { frontendRoutes } from '@/.mercato/generated/frontend-routes.generated'
+
+registerFrontendRouteManifests(frontendRoutes)
 import { getAuthFromCookies } from '@open-mercato/shared/lib/auth/server'
 import { AccessDeniedMessage } from '@open-mercato/ui/backend/detail'
 import type { AuthContext } from '@open-mercato/shared/lib/auth/server'

package/template/src/app/api/[...slug]/route.ts

@@ -1,14 +1,16 @@
 import { NextResponse, type NextRequest } from 'next/server'
-import { findApiRouteManifestMatch, registerBackendRouteManifests, type HttpMethod } from '@open-mercato/shared/modules/registry'
+import { findApiRouteManifestMatch, registerBackendRouteManifests, registerFrontendRouteManifests, type HttpMethod } from '@open-mercato/shared/modules/registry'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { apiRoutes } from '@/.mercato/generated/api-routes.generated'
 import { backendRoutes } from '@/.mercato/generated/backend-routes.generated'
+import { frontendRoutes } from '@/.mercato/generated/frontend-routes.generated'
 import { resolveAuthFromRequestDetailed } from '@open-mercato/shared/lib/auth/server'
 import { bootstrap } from '@/bootstrap'
 
 // Ensure all package registrations are initialized for API routes
 bootstrap()
 registerBackendRouteManifests(backendRoutes)
+registerFrontendRouteManifests(frontendRoutes)
 import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
@@ -134,7 +136,7 @@ async function checkAuthorization(
   req: NextRequest
 ): Promise<NextResponse | null> {
   const { t } = await resolveTranslations()
-  const requiresAuthentication = methodMetadata !== null && methodMetadata?.requireAuth !== false
+  const requiresAuthentication = methodMetadata?.requireAuth !== false
   if (requiresAuthentication && !auth) {
     return NextResponse.json({ error: t('api.errors.unauthorized', 'Unauthorized') }, { status: 401 })
   }