@open-mercato/core 0.4.8-develop-28cee031d6 → 0.4.8-develop-15259be22b

package/generated/entities/customer_role_acl/index.ts

@@ -0,0 +1,8 @@
+export const id = 'id'
+export const role = 'role'
+export const tenant_id = 'tenant_id'
+export const features_json = 'features_json'
+export const is_portal_admin = 'is_portal_admin'
+export const created_at = 'created_at'
+export const updated_at = 'updated_at'
+export const deleted_at = 'deleted_at'

package/generated/entities/customer_user/index.ts

@@ -0,0 +1,17 @@
+export const id = 'id'
+export const tenant_id = 'tenant_id'
+export const organization_id = 'organization_id'
+export const email = 'email'
+export const email_hash = 'email_hash'
+export const password_hash = 'password_hash'
+export const display_name = 'display_name'
+export const email_verified_at = 'email_verified_at'
+export const failed_login_attempts = 'failed_login_attempts'
+export const locked_until = 'locked_until'
+export const last_login_at = 'last_login_at'
+export const person_entity_id = 'person_entity_id'
+export const customer_entity_id = 'customer_entity_id'
+export const is_active = 'is_active'
+export const created_at = 'created_at'
+export const updated_at = 'updated_at'
+export const deleted_at = 'deleted_at'

package/generated/entities/customer_user_acl/index.ts

@@ -0,0 +1,8 @@
+export const id = 'id'
+export const user = 'user'
+export const tenant_id = 'tenant_id'
+export const features_json = 'features_json'
+export const is_portal_admin = 'is_portal_admin'
+export const created_at = 'created_at'
+export const updated_at = 'updated_at'
+export const deleted_at = 'deleted_at'

package/generated/entities/customer_user_email_verification/index.ts

@@ -0,0 +1,7 @@
+export const id = 'id'
+export const user = 'user'
+export const token = 'token'
+export const purpose = 'purpose'
+export const expires_at = 'expires_at'
+export const used_at = 'used_at'
+export const created_at = 'created_at'

package/generated/entities/customer_user_invitation/index.ts

@@ -0,0 +1,15 @@
+export const id = 'id'
+export const tenant_id = 'tenant_id'
+export const organization_id = 'organization_id'
+export const email = 'email'
+export const email_hash = 'email_hash'
+export const token = 'token'
+export const customer_entity_id = 'customer_entity_id'
+export const role_ids_json = 'role_ids_json'
+export const invited_by_user_id = 'invited_by_user_id'
+export const invited_by_customer_user_id = 'invited_by_customer_user_id'
+export const display_name = 'display_name'
+export const expires_at = 'expires_at'
+export const accepted_at = 'accepted_at'
+export const cancelled_at = 'cancelled_at'
+export const created_at = 'created_at'

package/generated/entities/customer_user_password_reset/index.ts

@@ -0,0 +1,6 @@
+export const id = 'id'
+export const user = 'user'
+export const token = 'token'
+export const expires_at = 'expires_at'
+export const used_at = 'used_at'
+export const created_at = 'created_at'

package/generated/entities/customer_user_role/index.ts

@@ -0,0 +1,5 @@
+export const id = 'id'
+export const user = 'user'
+export const role = 'role'
+export const created_at = 'created_at'
+export const deleted_at = 'deleted_at'

package/generated/entities/customer_user_session/index.ts

@@ -0,0 +1,9 @@
+export const id = 'id'
+export const user = 'user'
+export const token_hash = 'token_hash'
+export const ip_address = 'ip_address'
+export const user_agent = 'user_agent'
+export const expires_at = 'expires_at'
+export const last_used_at = 'last_used_at'
+export const created_at = 'created_at'
+export const deleted_at = 'deleted_at'

package/generated/entities/organization/index.ts

@@ -1,6 +1,7 @@
 export const id = 'id'
 export const tenant = 'tenant'
 export const name = 'name'
+export const slug = 'slug'
 export const is_active = 'is_active'
 export const parent_id = 'parent_id'
 export const root_id = 'root_id'

package/generated/entities.ids.generated.ts

@@ -30,7 +30,9 @@ export const M = {
   "translations": "translations",
   "inbox_ops": "inbox_ops",
   "payment_gateways": "payment_gateways",
-  "shipping_carriers": "shipping_carriers"
+  "shipping_carriers": "shipping_carriers",
+  "customer_accounts": "customer_accounts",
+  "portal": "portal"
 } as const
 export const E = {
   "dashboards": {
@@ -237,6 +239,17 @@ export const E = {
   },
   "shipping_carriers": {
     "carrier_shipment": "shipping_carriers:carrier_shipment"
+  },
+  "customer_accounts": {
+    "customer_user": "customer_accounts:customer_user",
+    "customer_role": "customer_accounts:customer_role",
+    "customer_role_acl": "customer_accounts:customer_role_acl",
+    "customer_user_role": "customer_accounts:customer_user_role",
+    "customer_user_acl": "customer_accounts:customer_user_acl",
+    "customer_user_session": "customer_accounts:customer_user_session",
+    "customer_user_email_verification": "customer_accounts:customer_user_email_verification",
+    "customer_user_password_reset": "customer_accounts:customer_user_password_reset",
+    "customer_user_invitation": "customer_accounts:customer_user_invitation"
   }
 } as const
 export type KnownModuleId = keyof typeof M

package/generated/entity-fields-registry.ts

@@ -38,10 +38,19 @@ import * as customer_entity from './entities/customer_entity/index'
 import * as customer_person_profile from './entities/customer_person_profile/index'
 import * as customer_pipeline from './entities/customer_pipeline/index'
 import * as customer_pipeline_stage from './entities/customer_pipeline_stage/index'
+import * as customer_role from './entities/customer_role/index'
+import * as customer_role_acl from './entities/customer_role_acl/index'
 import * as customer_settings from './entities/customer_settings/index'
 import * as customer_tag from './entities/customer_tag/index'
 import * as customer_tag_assignment from './entities/customer_tag_assignment/index'
 import * as customer_todo_link from './entities/customer_todo_link/index'
+import * as customer_user from './entities/customer_user/index'
+import * as customer_user_acl from './entities/customer_user_acl/index'
+import * as customer_user_email_verification from './entities/customer_user_email_verification/index'
+import * as customer_user_invitation from './entities/customer_user_invitation/index'
+import * as customer_user_password_reset from './entities/customer_user_password_reset/index'
+import * as customer_user_role from './entities/customer_user_role/index'
+import * as customer_user_session from './entities/customer_user_session/index'
 import * as dashboard_layout from './entities/dashboard_layout/index'
 import * as dashboard_role_widgets from './entities/dashboard_role_widgets/index'
 import * as dashboard_user_widgets from './entities/dashboard_user_widgets/index'
@@ -185,10 +194,19 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
   customer_person_profile,
   customer_pipeline,
   customer_pipeline_stage,
+  customer_role,
+  customer_role_acl,
   customer_settings,
   customer_tag,
   customer_tag_assignment,
   customer_todo_link,
+  customer_user,
+  customer_user_acl,
+  customer_user_email_verification,
+  customer_user_invitation,
+  customer_user_password_reset,
+  customer_user_role,
+  customer_user_session,
   dashboard_layout,
   dashboard_role_widgets,
   dashboard_user_widgets,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.4.8-develop-28cee031d6",
+  "version": "0.4.8-develop-15259be22b",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -217,10 +217,10 @@
     "semver": "^7.6.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.4.8-develop-28cee031d6"
+    "@open-mercato/shared": "0.4.8-develop-15259be22b"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.4.8-develop-28cee031d6",
+    "@open-mercato/shared": "0.4.8-develop-15259be22b",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",

package/src/modules/auth/services/rbacService.ts

@@ -4,6 +4,7 @@ import { getCurrentCacheTenant, runWithCacheTenant } from '@open-mercato/cache'
 import { UserAcl, RoleAcl, User, UserRole } from '@open-mercato/core/modules/auth/data/entities'
 import { ApiKey } from '@open-mercato/core/modules/api_keys/data/entities'
 import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { matchFeature as sharedMatchFeature, hasAllFeatures as sharedHasAllFeatures } from '@open-mercato/shared/lib/auth/featureMatch'
 
 interface AclData {
   isSuperAdmin: boolean
@@ -61,18 +62,11 @@ export class RbacService {
    * matchFeature('users.view', 'users.view') // true - exact match
    */
   private matchFeature(required: string, granted: string): boolean {
-    if (granted === '*') return true
-    if (granted.endsWith('.*')) {
-      const prefix = granted.slice(0, -2)
-      return required === prefix || required.startsWith(prefix + '.')
-    }
-    return granted === required
+    return sharedMatchFeature(required, granted)
   }
 
   public hasAllFeatures(required: string[], granted: string[]): boolean {
-    if (!required.length) return true
-    if (!granted.length) return false
-    return required.every((req) => granted.some((g) => this.matchFeature(req, g)))
+    return sharedHasAllFeatures(required, granted)
   }
 
   private getCacheKey(userId: string, scope: { tenantId: string | null; organizationId: string | null }): string {

package/src/modules/customer_accounts/AGENTS.md

@@ -0,0 +1,377 @@
+# Customer Accounts Module — Agent Guidelines
+
+Customer-facing identity and portal authentication with a two-tier RBAC model. This module manages customer user accounts, sessions, roles, invitations, and the authentication flow for the customer portal. It is separate from the internal `auth` module, which handles staff authentication.
+
+## MUST Rules
+
+1. **MUST hash passwords with `bcryptjs` (cost >= 10)** — never store plaintext passwords
+2. **MUST return minimal error messages on auth endpoints** — never reveal whether an email exists (use generic "Invalid email or password")
+3. **MUST rate-limit all public auth endpoints** (login, signup, password reset, magic link) — both per-email and per-IP
+4. **MUST validate all inputs with zod** — schemas live in `data/validators.ts`
+5. **MUST export `openApi`** from every API route file
+6. **MUST scope all queries by `tenantId`** and filter `deletedAt: null` for soft-deleted records
+7. **MUST NOT expose cross-tenant data** — session validation checks tenant match
+8. **MUST use `hashForLookup` for email-based lookups** — emails are stored with a deterministic hash for indexed queries
+9. **MUST use `hashToken` for storing session/verification/reset tokens** — raw tokens are never persisted
+10. **MUST emit events via `emitCustomerAccountsEvent`** for all state changes (login, signup, lock, password reset)
+11. **MUST NOT import staff auth services** — customer auth is a fully separate identity system
+
+## Data Model
+
+### Entities
+
+| Entity | Table | Purpose |
+|--------|-------|---------|
+| `CustomerUser` | `customer_users` | Customer user accounts with credentials and CRM links |
+| `CustomerRole` | `customer_roles` | Named role definitions (portal_admin, buyer, viewer) |
+| `CustomerRoleAcl` | `customer_role_acls` | Feature permissions assigned to roles |
+| `CustomerUserAcl` | `customer_user_acls` | Per-user feature overrides |
+| `CustomerUserRole` | `customer_user_roles` | User-to-role junction (M2M) |
+| `CustomerUserSession` | `customer_user_sessions` | Active sessions with hashed tokens |
+| `CustomerUserEmailVerification` | `customer_user_email_verifications` | Email verification and magic link tokens |
+| `CustomerUserPasswordReset` | `customer_user_password_resets` | Password reset tokens |
+| `CustomerUserInvitation` | `customer_user_invitations` | Pending user invitations with role pre-assignment |
+
+### Key Relationships
+
+- `CustomerUser.personEntityId` -> CRM person (optional FK to customers module)
+- `CustomerUser.customerEntityId` -> CRM company (optional FK to customers module)
+- `CustomerUserRole` links users to roles (M2M junction)
+- `CustomerRoleAcl` is 1:1 with `CustomerRole` per tenant
+- `CustomerUserAcl` is 1:1 with `CustomerUser` per tenant (overrides role-based features)
+
+### Custom Entities (ce.ts)
+
+Two custom entity definitions are registered:
+- `customer_accounts:customer_user` — labeled by `displayName`
+- `customer_accounts:customer_role` — labeled by `name`
+
+Both have `showInSidebar: false` and `defaultEditor: false`.
+
+## Authentication Flow
+
+### Login (`POST /api/login`)
+
+1. Rate-limit check (per-email + per-IP)
+2. Validate input with `loginSchema`
+3. Look up user by email hash + tenantId
+4. Check account active and not locked
+5. Verify password with bcrypt
+6. On failure: increment failed attempts, lock after 5 failures (15 min lockout)
+7. On success: reset failed attempts, update `lastLoginAt`
+8. Resolve RBAC features via `CustomerRbacService.loadAcl`
+9. Create session (raw token + hashed token persisted)
+10. Sign JWT with customer claims (`type: 'customer'`, features, CRM links)
+11. Set `customer_auth_token` (JWT, httpOnly) and `customer_session_token` (raw, httpOnly) cookies
+
+### Signup (`POST /api/signup`)
+
+1. Rate-limit check (per-IP)
+2. Validate input with `signupSchema`
+3. Check for existing user (generic error on duplicate)
+4. Create user with hashed password
+5. Assign default role (`isDefault: true`)
+6. Create email verification token
+7. Emit `customer_accounts.user.created` event (triggers CRM auto-link + staff notification)
+
+### Magic Link (`POST /api/magic-link/request` + `POST /api/magic-link/verify`)
+
+1. Request: rate-limit, find user, create magic link token (15 min TTL)
+2. Verify: validate token, mark used, create session
+
+### Password Reset (`POST /api/password/reset-request` + `POST /api/password/reset-confirm`)
+
+1. Request: rate-limit, find user, create reset token (60 min TTL)
+2. Confirm: validate token, mark used, update password hash
+
+### Email Verification (`POST /api/email/verify`)
+
+Validates token, sets `emailVerifiedAt` on the user.
+
+### Invitation Flow (`POST /api/admin/users-invite` + `POST /api/invitations/accept`)
+
+1. Admin or portal admin creates invitation with email, role IDs, optional company link
+2. Invitation token generated (72 hour TTL)
+3. Acceptance: creates user, assigns roles, marks email verified, marks invitation accepted
+
+### Session Refresh (`POST /api/portal/sessions-refresh`)
+
+Re-signs the JWT with fresh RBAC features using the long-lived session token.
+
+### Two-Cookie Strategy
+
+| Cookie | Content | TTL | Purpose |
+|--------|---------|-----|---------|
+| `customer_auth_token` | Signed JWT | 8 hours | Short-lived auth with embedded claims |
+| `customer_session_token` | Raw session token | 30 days | Long-lived session for JWT refresh |
+
+## Customer RBAC
+
+### Two-Layer Model (mirrors staff RBAC)
+
+1. **Role ACLs** (`CustomerRoleAcl`) — features assigned to roles
+2. **User ACLs** (`CustomerUserAcl`) — per-user overrides (takes precedence if present)
+
+Effective permissions = User ACL (if exists) OR aggregated Role ACLs.
+
+### Portal Admin Flag
+
+`isPortalAdmin: true` on a role/user ACL bypasses all feature checks (equivalent to staff `isSuperAdmin`).
+
+### Default Roles (seeded on tenant creation)
+
+| Role | Slug | Features | Portal Admin |
+|------|------|----------|-------------|
+| Portal Admin | `portal_admin` | `portal.*` | Yes |
+| Buyer | `buyer` | `portal.account.manage`, `portal.orders.*`, `portal.quotes.*`, `portal.invoices.view`, `portal.catalog.view` | No |
+| Viewer | `viewer` | `portal.account.manage`, `portal.orders.view`, `portal.invoices.view`, `portal.catalog.view` | No |
+
+### Feature Convention
+
+Customer portal features use the `portal.<area>.<action>` naming convention (e.g., `portal.orders.view`, `portal.catalog.view`).
+
+### Cross-Module Feature Merging
+
+Other modules can declare `defaultCustomerRoleFeatures` in their `setup.ts`. During `seedDefaults`, the customer_accounts module collects these from all enabled modules and merges them into the corresponding `CustomerRoleAcl` records.
+
+### Server-Side Auth Helpers
+
+| Helper | Import | Use |
+|--------|--------|-----|
+| `getCustomerAuthFromRequest` | `lib/customerAuth` | API routes — reads JWT from `Authorization` header or cookie |
+| `requireCustomerAuth` | `lib/customerAuth` | API routes — throws 401 if not authenticated |
+| `requireCustomerFeature` | `lib/customerAuth` | API routes — throws 403 if features missing |
+| `getCustomerAuthFromCookies` | `lib/customerAuthServer` | Server components — reads JWT from Next.js `cookies()` |
+
+### RBAC Check (Service)
+
+```typescript
+const customerRbacService = container.resolve('customerRbacService')
+const hasAccess = await customerRbacService.userHasAllFeatures(userId, ['portal.orders.view'], { tenantId, organizationId })
+```
+
+## Services and DI
+
+| DI Name | Class | Purpose |
+|---------|-------|---------|
+| `customerUserService` | `CustomerUserService` | User CRUD, password verification, lockout management |
+| `customerSessionService` | `CustomerSessionService` | Session creation, JWT signing, token lookup, revocation |
+| `customerTokenService` | `CustomerTokenService` | Email verification, magic link, and password reset tokens |
+| `customerRbacService` | `CustomerRbacService` | ACL resolution with cache, feature checks |
+| `customerInvitationService` | `CustomerInvitationService` | Invitation creation and acceptance |
+
+All services are registered as **scoped** (per-request) via `di.ts`.
+
+`CustomerRbacService` uses tag-based cache invalidation (`customer_rbac:user:<id>`, `customer_rbac:tenant:<id>`, `customer_rbac:all`) with a 5-minute TTL.
+
+## API Directory Structure
+
+```
+api/
+├── post/
+│   ├── login.ts                          # Customer login
+│   ├── signup.ts                         # Self-registration
+│   ├── email/verify.ts                   # Email verification
+│   ├── password/reset-request.ts         # Request password reset
+│   ├── password/reset-confirm.ts         # Confirm password reset
+│   ├── magic-link/request.ts             # Request magic link
+│   ├── magic-link/verify.ts              # Verify magic link
+│   ├── invitations/accept.ts             # Accept invitation
+│   ├── admin/users.ts                    # Admin: create user
+│   ├── admin/users-invite.ts             # Admin: invite user
+│   ├── admin/users/[id]/reset-password.ts # Admin: reset user password
+│   ├── admin/users/[id]/verify-email.ts  # Admin: force verify email
+│   ├── admin/roles.ts                    # Admin: create role
+│   ├── portal/logout.ts                  # Portal: logout
+│   ├── portal/sessions-refresh.ts        # Portal: refresh JWT
+│   ├── portal/password-change.ts         # Portal: change password
+│   ├── portal/users-invite.ts            # Portal admin: invite user
+│   └── portal/feature-check.ts           # Portal: check feature access
+├── get/
+│   ├── admin/users.ts                    # Admin: list users
+│   ├── admin/users/[id].ts              # Admin: get user detail
+│   ├── admin/roles.ts                    # Admin: list roles
+│   ├── admin/roles/[id].ts              # Admin: get role detail
+│   ├── portal/profile.ts                # Portal: get own profile
+│   ├── portal/sessions.ts               # Portal: list own sessions
+│   ├── portal/users.ts                  # Portal admin: list company users
+│   ├── portal/events/stream.ts          # Portal: SSE event stream
+│   ├── portal/notifications.ts          # Portal: list notifications
+│   └── portal/notifications/unread-count.ts # Portal: unread count
+├── put/
+│   ├── admin/users/[id].ts              # Admin: update user
+│   ├── admin/roles/[id].ts              # Admin: update role
+│   ├── admin/roles/[id]/acl.ts          # Admin: update role ACL
+│   ├── portal/profile.ts                # Portal: update own profile
+│   ├── portal/users/[id]/roles.ts       # Portal admin: assign roles
+│   ├── portal/notifications/[id]/read.ts     # Portal: mark notification read
+│   ├── portal/notifications/[id]/dismiss.ts  # Portal: dismiss notification
+│   └── portal/notifications/mark-all-read.ts # Portal: mark all read
+└── delete/
+    ├── admin/users/[id].ts              # Admin: soft-delete user
+    ├── admin/roles/[id].ts              # Admin: delete role
+    ├── portal/users/[id].ts             # Portal admin: remove user
+    └── portal/sessions/[id].ts          # Portal: revoke session
+```
+
+### API Scopes
+
+- **Public** (`/api/login`, `/api/signup`, `/api/password/*`, `/api/magic-link/*`, `/api/email/*`, `/api/invitations/*`) — unauthenticated, rate-limited
+- **Admin** (`/api/admin/*`) — requires staff auth + `customer_accounts.view` / `customer_accounts.manage` features
+- **Portal** (`/api/portal/*`) — requires customer auth (JWT), some endpoints require `isPortalAdmin`
+
+## Events
+
+Declared in `events.ts` via `createModuleEvents`. Emit with `emitCustomerAccountsEvent`.
+
+| Event ID | Category | Client Broadcast |
+|----------|----------|-----------------|
+| `customer_accounts.user.created` | crud | Yes |
+| `customer_accounts.user.updated` | crud | No |
+| `customer_accounts.user.deleted` | crud | No |
+| `customer_accounts.user.locked` | lifecycle | No |
+| `customer_accounts.user.unlocked` | lifecycle | No |
+| `customer_accounts.login.success` | lifecycle | No |
+| `customer_accounts.login.failed` | lifecycle | No |
+| `customer_accounts.email.verified` | lifecycle | No |
+| `customer_accounts.password.reset` | lifecycle | No |
+| `customer_accounts.role.created` | crud | No |
+| `customer_accounts.role.updated` | crud | No |
+| `customer_accounts.role.deleted` | crud | No |
+| `customer_accounts.invitation.accepted` | lifecycle | Yes |
+
+## Subscribers
+
+| Subscriber | Listens To | Purpose |
+|------------|-----------|---------|
+| `autoLinkCrm` | `customer_accounts.user.created` | Links new customer user to existing CRM person/company by email match |
+| `autoLinkCrmReverse` | `customers.person.created` | Links new CRM person to existing customer user by email match |
+| `notifyStaffOnSignup` | `customer_accounts.user.created` | Emits in-app notification to staff about new signups |
+
+All three are **persistent** subscribers (retried on failure).
+
+### CRM Auto-Linking Logic
+
+- **Forward** (`autoLinkCrm`): When a customer user signs up, searches CRM `CustomerEntity` (kind=person) for matching email. If found, sets `personEntityId` on the user. Also looks up the person's company via `customer_people.company_entity_id` and sets `customerEntityId`.
+- **Reverse** (`autoLinkCrmReverse`): When a CRM person is created, looks for an unlinked customer user with matching email hash and links them.
+
+## Workers
+
+| Worker | Queue | Purpose |
+|--------|-------|---------|
+| `cleanupExpiredSessions` | `customer-accounts-cleanup-sessions` | Deletes expired and soft-deleted sessions |
+| `cleanupExpiredTokens` | `customer-accounts-cleanup-tokens` | Deletes expired/used email verifications, password resets, and accepted/cancelled invitations |
+
+Both run with `concurrency: 1`.
+
+## Notification Types
+
+Declared in `notifications.ts` and `notifications.client.ts`.
+
+| Type | Severity | Trigger |
+|------|----------|---------|
+| `customer_accounts.user.signup` | info | New customer registration |
+| `customer_accounts.user.locked` | warning | Account locked after failed attempts |
+
+Both link to `/backend/customer_accounts/{sourceEntityId}` for staff review.
+
+## Widget Injection
+
+### Injection Table
+
+| Spot ID | Widget | Purpose |
+|---------|--------|---------|
+| `crud-form:customers:customer_person_profile:fields` | `account-status` | Shows portal account status on CRM person detail page |
+| `crud-form:customers:customer_company_profile:fields` | `company-users` | Shows portal users linked to a CRM company |
+
+Both inject as column 2 groups with priority 200, gated by `customer_accounts.view` feature.
+
+## Backend Pages
+
+| Path | Purpose |
+|------|---------|
+| `backend/page.tsx` | Customer accounts list (`/backend/customer_accounts`) |
+| `backend/customer_accounts/[id]/page.tsx` | User detail/edit |
+| `backend/customer_accounts/roles/page.tsx` | Role list |
+| `backend/customer_accounts/roles/create/page.tsx` | Create role |
+| `backend/customer_accounts/roles/[id]/page.tsx` | Role detail/edit ACL |
+
+## Security
+
+### Password Handling
+
+- Hash with `bcryptjs` cost 10 (`BCRYPT_COST = 10`)
+- Minimum 8 characters, maximum 128 characters
+- Never log password values
+
+### Account Lockout
+
+- 5 failed login attempts triggers 15-minute lockout
+- Failed attempts tracked per user in `failedLoginAttempts`
+- Lockout stored as `lockedUntil` timestamp
+- Successful login resets counter and clears lock
+
+### Rate Limiting
+
+All public endpoints have dual rate limits (per-identifier + per-IP). Defaults:
+
+| Endpoint | Per-Email | Per-IP | Block Duration |
+|----------|-----------|--------|----------------|
+| Login | 5/60s | 20/60s | 60s |
+| Signup | 3/60s | 10/60s | 120s |
+| Password Reset | 3/60s | 10/60s | 120s |
+| Magic Link | 3/60s | 10/60s | 120s |
+
+Configurable via environment variables (`CUSTOMER_LOGIN_POINTS`, `CUSTOMER_LOGIN_DURATION`, etc.) using `readEndpointRateLimitConfig`.
+
+### Token Security
+
+- Tokens generated with `crypto.randomBytes(32)` (base64url)
+- Tokens stored as SHA-256 hashes — raw tokens never persisted
+- TTLs: email verification 24h, magic link 15min, password reset 60min, invitation 72h
+
+### Email Privacy
+
+- Emails stored in plaintext but lookups use `hashForLookup` (deterministic hash)
+- Unique constraint on `(tenantId, emailHash)` prevents duplicates
+- Error messages never confirm whether an email is registered
+
+## Lib Utilities
+
+| File | Exports | Purpose |
+|------|---------|---------|
+| `lib/customerAuth.ts` | `getCustomerAuthFromRequest`, `requireCustomerAuth`, `requireCustomerFeature`, `CustomerAuthContext` | Request-level auth helpers for API routes |
+| `lib/customerAuthServer.ts` | `getCustomerAuthFromCookies` | Server component auth via Next.js `cookies()` |
+| `lib/rateLimiter.ts` | Rate limit configs, `checkAuthRateLimit`, `resetAuthRateLimit` | Dual rate limiting for all public endpoints |
+| `lib/tokenGenerator.ts` | `generateSecureToken`, `hashToken` | Cryptographic token generation and hashing |
+
+## ACL Features (Staff-Side)
+
+Declared in `acl.ts` — these control staff access to customer account management in the admin backend:
+
+| Feature | Purpose |
+|---------|---------|
+| `customer_accounts.view` | View customer accounts and roles |
+| `customer_accounts.manage` | Create, update, delete customer users |
+| `customer_accounts.roles.manage` | Create, update, delete customer roles and ACLs |
+| `customer_accounts.invite` | Invite customer users |
+
+Default role assignments (from `setup.ts`):
+- `superadmin`: `customer_accounts.*`
+- `admin`: `customer_accounts.*`
+
+## Key Directories
+
+| Directory | When to modify |
+|-----------|---------------|
+| `api/post/` | When adding new public or admin write endpoints |
+| `api/get/` | When adding read endpoints (admin or portal) |
+| `api/put/` | When adding update endpoints |
+| `api/delete/` | When adding deletion endpoints |
+| `backend/` | When changing admin UI pages for customer management |
+| `data/` | When changing ORM entities or zod validators |
+| `lib/` | When modifying auth helpers, rate limiting, or token generation |
+| `services/` | When modifying user, session, token, RBAC, or invitation logic |
+| `subscribers/` | When adding event-driven side effects (CRM linking, notifications) |
+| `workers/` | When modifying cleanup jobs for sessions/tokens |
+| `widgets/injection/` | When adding/modifying widgets injected into CRM forms |

package/src/modules/customer_accounts/acl.ts

@@ -0,0 +1,8 @@
+export const features = [
+  { id: 'customer_accounts.view', title: 'View customer accounts', module: 'customer_accounts' },
+  { id: 'customer_accounts.manage', title: 'Manage customer accounts', module: 'customer_accounts' },
+  { id: 'customer_accounts.roles.manage', title: 'Manage customer roles', module: 'customer_accounts' },
+  { id: 'customer_accounts.invite', title: 'Invite customer users', module: 'customer_accounts' },
+]
+
+export default features