PSA/ee/docs/plans/2025-10-25-client-portal-tenant-deep-links-plan.md

Title: Client Portal Tenant Deep Links Plan
Date: 2025-10-25

## Status – 2025-10-25
- **Draft**: Auth, email, and support stakeholders aligned on requirements; execution has not started.

## Overview / Rationale
- Canonical client-portal links currently rely on email + user type, which breaks when a contact belongs to more than one tenant.
- Adding a stable slug derived from the tenant UUID lets every canonical deep link carry tenant context without exposing internal IDs.
- Embedding tenant-specific links in outbound messages eliminates guesswork for recipients and keeps vanity-domain behaviour unchanged.

## Problem
- Client portal authentication only scopes by email + `user_type`, so duplicate emails across tenants collide during `signIn('credentials')`.
- Canonical links like `/auth/client-portal/signin` and `/client-portal/tickets` lack tenant hints, causing silent failures or cross-tenant access.
- Vanity domains infer tenant from the host, but canonical flows cannot distinguish tenants without user prompts or manual support intervention.

## Goals
- Require and persist an explicit tenant identifier for all canonical client-portal logins while keeping vanity-detected flows untouched.
- Generate tenant-scoped deep links across invitations, ticket updates, onboarding, and admin tooling using a shared helper.
- Provide a self-service recovery path (email capture ➝ tenant-specific email) that avoids exposing tenant membership in the public UI.
- Instrument errors and mismatches so support can detect broken links quickly.

## Non-Goals
- Building a public tenant-picker UI or exposing tenant rosters to unauthenticated visitors.
- Modifying MSP/internal authentication or replacing NextAuth/Auth.js infrastructure.
- Reworking OTT-based vanity handoffs or the portal domain provisioning workflow.

## Current State Snapshot
- `server/src/components/auth/ClientLoginForm.tsx` posts `signIn('credentials', { email, password, userType: 'client' })` without tenant info.
- `server/src/app/auth/client-portal/signin/page.tsx` renders `ClientPortalSignIn` and only derives branding/locale from vanity domains via `portalDomain`.
- `server/src/lib/actions/auth.tsx` → `authenticateUser` calls `User.findUserByEmailAndType` in `server/src/lib/models/user.tsx`, so canonical logins short-circuit on the first matching user.
- NextAuth configuration (`server/src/app/api/auth/[...nextauth]/options.ts`) stores `token.tenant` but never validates the tenant during the credentials flow.
- Email producers (`server/src/lib/actions/portal-actions/portalInvitationActions.ts`, `server/src/lib/eventBus/subscribers/ticketEmailSubscriber.ts`, `ee/temporal-workflows/src/activities/email-activities.ts`) assemble portal URLs manually and never append tenant context.
- `portal_domains` (20250919120000 migration) enforces a single vanity domain per tenant; canonical host lives in `canonical_host` but we do not surface slugs.
- OTT issuance/consumption for vanity domains (`server/src/app/api/client-portal/domain-session/route.ts`) already transports the tenant ID and should keep working untouched.

## Key Constraints & Considerations
- Slugs must be deterministic, short, and unique per tenant; collisions (while unlikely) need a regeneration pathway without changing the canonical tenant UUID. [ed: SKIP]
- Deep links must survive existing query parameters (`ticket`, `callbackUrl`, Temporal workflow params) without double-encoding.
- Temporal workers and background jobs rely on the same Postgres instance; any slug lookup helper must work in both the Next.js app and the worker runtime.
- New UI components must follow `docs/AI_coding_standards.md` (Radix-based primitives, deterministic component IDs).
- Avoid leaking tenancy information through error messages or network timing [ed: NETWORK TIMING ATTACK PREVENTION IS OVERKILL]; the recovery flow should only expose tenant names inside the authenticated email response. 

## Proposed Approach

### Phase 0 – Tenant Slug Foundations
- **Slug utility**: introduce a deterministic helper (e.g., `buildTenantPortalSlug(tenantId: string)`) that slices the tenant UUID into `${uuid.slice(0,6)}${uuid.slice(-6)}` (lowercase hex) and exposes reverse lookup via a lightweight repository wrapper.
- **Collision handling**: document the deterministic formula, add unit tests confirming uniqueness against fixture data, and provide a guardrail that logs (rather than stores) suspected collisions for manual follow-up.
- **Caching**: wrap slug lookups with `unstable_cache` (canonical host paths) and Temporal-side memoization so repeated calls avoid extra DB fetches.
- **Docs**: update `docs/client_portal_overview.md` to describe slug calculation, expected format, and the fact that slugs are derived on the fly rather than persisted.

### Phase 1 – Auth & Session Hardening
- **Client entrypoint**: update `server/src/app/auth/client-portal/signin/page.tsx` and `ClientPortalSignIn` to read `tenant` (slug) from `searchParams`, seed it into context, and pass through to `ClientLoginForm`.
- **Form payload**: extend `ClientLoginForm` to keep the slug in local state, include it in `signIn('credentials', { tenant: slug })`, and add hidden inputs/IDs respecting the reflection system.
- **NextAuth credentials provider**: modify `server/src/app/api/auth/[...nextauth]/options.ts` so `authorize` resolves the slug ➝ tenant ID, enforces tenant membership, and throws typed errors (`TENANT_MISSING`, `TENANT_MISMATCH`, `TENANT_UNKNOWN`).
- **Backend lookup**: add `User.findUserByEmailTenantAndType` in `server/src/lib/models/user.tsx` and update `authenticateUser` to require a tenant when `userType === 'client'` and the request targets the canonical host.
- **Session persistence**: ensure the JWT callback writes both `token.tenant` and `token.tenantSlug` (for downstream middleware/UI) and keep the session callback in sync.
- **Middleware**: tighten `server/src/middleware.ts` to append `tenant=<slug>` when redirecting canonical requests and to reject canonical sign-ins lacking a slug (they will fall through to the recovery flow in Phase 3).
- **Regression coverage**: add unit tests for the new model helper, credentials provider behaviour, and middleware enforcement; extend Playwright login specs with a slugged canonical scenario.

### Phase 2 – Deep Link Generation
- **URL helper**: create `server/src/lib/url/clientPortalUrls.ts` exporting `buildClientPortalUrl({ tenantId, path, query, preferVanity })` that picks vanity host when available, otherwise canonical host + `tenant=<slug>`.
- **Email touchpoints**:
  - Update `sendPortalInvitation` (`server/src/lib/actions/portal-actions/portalInvitationActions.ts`) to use the helper for setup URLs.
  - Update ticket notification subscriber (`server/src/lib/eventBus/subscribers/ticketEmailSubscriber.ts`) to build portal links through the helper while preserving `ticket` params.
  - Extend Temporal email activities (`ee/temporal-workflows/src/activities/email-activities.ts`) to request the slug via a lightweight REST endpoint or shared DB call (add service wrapper if direct DB access is unavailable).
  - Audit other templates (`server/src/lib/email/*`, Temporal workflows) for `/auth/client-portal/` references and migrate them to the helper.
- **Admin tooling**: add a “Copy portal login link” action in `server/src/components/settings/general/UserManagement.tsx` (client portal tab) that calls a new server action returning the slugged URL; ensure button IDs follow the standards (e.g., `copy-client-portal-link-button`).
- **Portal domain guardrails**: ensure `getPortalDomain` returns both vanity domain metadata and tenant ID so helper calls can compute the slug without duplicated lookups.

### Phase 3 – Canonical Recovery Flow & UX
- **UI flow**: when `/auth/client-portal/signin` lacks `tenant`, render a new `ClientPortalTenantDiscovery` component prompting for email only (ID: `tenant-discovery-form`).
- **Server action**: implement `requestTenantLoginLinksAction(email)` that:
  - Normalizes email and finds all client users across tenants via the new lookup helper.
  - Sends a branded email (new template under `server/src/lib/email/clientPortalTenantRecoveryEmail.ts`) listing one or more tenant-specific login links (vanity if active, canonical + slug otherwise).
  - Records audit logs / rate limits to prevent abuse (e.g., store last request in `tenant_recovery_requests` table or reuse notification logs).
- **Email content**: localize strings, ensure links include slug, and include fallback instructions when no tenant is found.
- **Security**: return a generic “Check your email” toast regardless of matches to avoid account enumeration; throttle repeated submissions per IP/email.
- **Callback handling**: preserve `callbackUrl` in generated links (store in the email payload, append to the query when present).

### Phase 4 – Telemetry, Docs & Rollout
- **Logging**: add structured logs + PostHog events for `tenant_slug_missing`, `tenant_mismatch`, recovery email sends, and recovery throttling.
- **Documentation**: update `docs/client_portal_overview.md` and relevant runbooks to describe slug usage, helper APIs, and how to diagnose slug collisions or mismatch reports.
- **Feature flag & rollout**: gate slug enforcement behind an env flag (e.g., `CLIENT_PORTAL_REQUIRE_TENANT_SLUG`) for staged rollout; enable in staging first, monitor, then production.
- **Cleanup**: once stable, remove temporary logging noise and finalise TODO comments.

## Testing & Rollout
- **Unit**: cover slug helper, user lookup, NextAuth authorize callback, middleware redirect logic, URL builder permutations.
- **Integration**: expand Playwright suites (`client-portal-login-e2e`, `client-portal-vanity-session`, `client-portal-redirects`) with slugged canonical runs and recovery email flow (mock provider).
- **Email snapshots**: add Jest snapshots for invitation/ticket/recovery emails to confirm the correct host + `tenant` query.
- **Temporal**: add activity tests ensuring the helper resolves vanity vs canonical correctly when running in the worker.
- **Monitoring**: verify dashboards post-deploy for login failures segmented by error reason; add alert thresholds for sustained `tenant_mismatch` spikes.

## Observability & Support
- Surface slug + tenant ID in support tooling (e.g., add to `server/src/components/contacts/ContactPortalTab.tsx`) so agents can copy canonical links quickly.
- Add Kibana/PostHog dashboards tracking recovery email volume, mismatches, and suspected slug collisions (duplicate computations for the same tenant ID).
- Update runbooks so support teams know how to validate the computed slug, confirm tenant membership, and invalidate caches when slug discrepancies are reported.

## Acceptance Testing
- **Canonical slug flow**: use an invite/welcome email, ensure login succeeds, session includes correct tenant/slug, and return paths honour `callbackUrl`.
- **Canonical recovery**: visit `/auth/client-portal/signin` without slug, submit an email:
  - Single-tenant email delivers one slugged link that logs in successfully.
  - Multi-tenant email yields one link per tenant with appropriate branding.
  - Unknown email still shows the generic confirmation while delivering a “not found” message.
- **Vanity domain**: confirm vanity-host login bypasses slug requirement, OTT handoff still works, and discovery form remains hidden.
- **Admin tooling**: copy-link action returns vanity URL when configured, otherwise canonical host + slug, and the link logs in correctly.
- **Regression**: rerun existing Playwright journeys plus any new tests introduced above.

## Open Questions
- Do we need an ops-facing flow to handle rare slug collisions (e.g., temporarily overriding the slug helper for affected tenants)?
- Should recovery emails include tenant logos/branding pulled from `tenant_settings.settings.branding` for better recognition?
- Can we rely on direct DB reads from Temporal, or do we need a small internal API endpoint to fetch slug + vanity metadata?