import type { APIRequestContext, APIResponse } from "@playwright/test"; export type PortalInvitationEntrypoint = "admin" | "contact" | "project"; export const portalSetupMailFixtureInputs = ["E2E_PORTAL_SETUP_MAIL_FIXTURE_URL", "E2E_PORTAL_SETUP_MAIL_FIXTURE_KEY"] as const; const DEFAULT_POLL_TIMEOUT_MS = 45_000; const MAX_POLL_TIMEOUT_MS = 90_000; const POLL_INTERVAL_MS = 1_000; const DELIVERY_TIMESTAMP_TOLERANCE_MS = 5_000; const SETUP_TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/u; type PortalSetupMailFixtureResponse = { readonly correlationKey?: unknown; readonly recipient?: unknown; readonly source?: unknown; readonly purpose?: unknown; readonly deliveredAt?: unknown; readonly setupUrl?: unknown; }; export type PortalSetupJourneyContext = { readonly origin: string; readonly tenantPathPrefix: string; readonly portalRootPath: string; readonly projectsPath: string; }; /** * Test-only mailbox contract for VA-P26a. * * The endpoint receives a POST with `{ correlationKey, recipient, source, * purpose: "setup", deliveredAfter }`. `202`, `204`, and `404` mean that the * freshly delivered message in the dedicated disposable inbox is not visible * yet. A ready response is `200` JSON and must echo those fields plus * `deliveredAt` and the capability-bearing `setupUrl`. The adapter must observe * actual provider delivery; reading HiveGrid's database, outbox, or queue is not * a valid implementation of this contract. The endpoint, response body, and * setup URL are deliberately never included in thrown errors because they can * contain credentials or a live one-time token. */ export async function waitForPortalSetupMailLink( request: APIRequestContext, input: { readonly endpoint: string; readonly fixtureToken?: string; readonly correlationKey: string; readonly recipient: string; readonly entrypoint: PortalInvitationEntrypoint; readonly deliveredAfter: Date; readonly portalBaseUrl: string; readonly portalCustomDomainBaseUrl?: string; readonly tenantSlug: string; readonly timeoutMs?: number; /** Unit-test seam; production callers use the fixed one-second interval. */ readonly pollIntervalMs?: number; } ): Promise { const endpoint = requireSafeFixtureEndpoint(input.endpoint, Boolean(input.fixtureToken)); const expectedPortalOrigin = requireSafeOrigin(input.portalBaseUrl, "E2E_PORTAL_BASE_URL"); const expectedCustomPortalOrigin = input.portalCustomDomainBaseUrl ? requireSafeHttpsRootOrigin(input.portalCustomDomainBaseUrl, "E2E_PORTAL_CUSTOM_DOMAIN_BASE_URL") : undefined; const timeoutMs = input.timeoutMs ?? portalSetupMailFixtureTimeoutMs(); const source = input.entrypoint === "admin" ? "portal_admin_invite" : input.entrypoint === "contact" ? "portal_contact_invite" : "portal_project_invite"; const deadline = Date.now() + timeoutMs; const pollIntervalMs = normalizePollInterval(input.pollIntervalMs); for (;;) { const remainingMs = deadline - Date.now(); if (remainingMs <= 0) { throw new Error("Portal setup mail fixture did not return a fresh matching setup mail before the configured timeout."); } let response: APIResponse; try { response = await request.post(endpoint.href, { data: { correlationKey: input.correlationKey, recipient: input.recipient, source, purpose: "setup", deliveredAfter: input.deliveredAfter.toISOString(), }, failOnStatusCode: false, headers: { "Cache-Control": "no-store", ...(input.fixtureToken ? { Authorization: `Bearer ${input.fixtureToken}` } : {}), }, maxRedirects: 0, timeout: Math.min(5_000, remainingMs), }); } catch { // A mailbox/readiness adapter may briefly be unavailable while the mail // worker or provider catches up. Keep the live capability and endpoint // out of errors and retry only within the bounded poll deadline. await wait(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now()))); continue; } if ([202, 204, 404].includes(response.status())) { await wait(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now()))); continue; } if ([408, 425, 429].includes(response.status()) || response.status() >= 500) { await wait(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now()))); continue; } if (response.status() !== 200) { throw new Error(`Portal setup mail fixture returned unexpected HTTP status ${response.status()}.`); } const payload = (await response.json().catch(() => null)) as PortalSetupMailFixtureResponse | null; if (!payload || typeof payload !== "object") { throw new Error("Portal setup mail fixture returned an invalid JSON contract."); } if ( payload.correlationKey !== input.correlationKey || normalizeEmail(payload.recipient) !== normalizeEmail(input.recipient) || payload.source !== source || payload.purpose !== "setup" ) { throw new Error("Portal setup mail fixture returned a response for a different invitation contract."); } const deliveredAt = typeof payload.deliveredAt === "string" ? new Date(payload.deliveredAt) : null; if (!deliveredAt || !Number.isFinite(deliveredAt.getTime())) { throw new Error("Portal setup mail fixture returned an invalid delivery timestamp."); } // Provider timestamps often have only second precision and the browser // runner and mailbox adapter can differ by a few seconds. The unique // correlation key + recipient remains the primary freshness boundary. if (deliveredAt.getTime() + DELIVERY_TIMESTAMP_TOLERANCE_MS < input.deliveredAfter.getTime()) { await wait(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now()))); continue; } if (typeof payload.setupUrl !== "string") { throw new Error("Portal setup mail fixture response is missing its setup URL."); } return requireSafeSetupUrl(payload.setupUrl, expectedPortalOrigin, input.tenantSlug, expectedCustomPortalOrigin); } } /** * Re-validates the capability without exposing it and derives the only portal * origin/path mode the browser journey may use. Standard-host routes retain * the tenant prefix; an explicitly allowlisted custom host uses root routes. */ export function derivePortalSetupJourneyContext( setupUrl: string, input: { readonly portalBaseUrl: string; readonly portalCustomDomainBaseUrl?: string; readonly tenantSlug: string; } ): PortalSetupJourneyContext { const standardOrigin = requireSafeOrigin(input.portalBaseUrl, "E2E_PORTAL_BASE_URL"); const customOrigin = input.portalCustomDomainBaseUrl ? requireSafeHttpsRootOrigin(input.portalCustomDomainBaseUrl, "E2E_PORTAL_CUSTOM_DOMAIN_BASE_URL") : undefined; const safeSetupUrl = requireSafeSetupUrl(setupUrl, standardOrigin, input.tenantSlug, customOrigin); const effectiveOrigin = new URL(safeSetupUrl).origin; const tenantPathPrefix = effectiveOrigin === standardOrigin ? `/${encodeURIComponent(input.tenantSlug)}` : ""; return { origin: effectiveOrigin, tenantPathPrefix, portalRootPath: tenantPathPrefix || "/", projectsPath: `${tenantPathPrefix}/projects`, }; } export function isExpectedPortalJourneyLocation(url: URL, journey: PortalSetupJourneyContext, expectedPath: string): boolean { return url.origin === journey.origin && normalizePortalPath(url.pathname) === expectedPath && !url.search && !url.hash; } export function isExpectedPortalProjectDetailLocation(url: URL, journey: PortalSetupJourneyContext): boolean { if (url.origin !== journey.origin || url.search || url.hash) return false; const prefix = `${journey.projectsPath}/`; if (!url.pathname.startsWith(prefix)) return false; const projectId = url.pathname.slice(prefix.length); return projectId.length > 0 && !projectId.includes("/"); } export function assertPortalSetupNavigationHasNoRedirect(response: { readonly request: () => { readonly redirectedFrom: () => unknown | null } }): void { if (response.request().redirectedFrom() !== null) { throw new Error("VA-P26a setup capability navigation used a forbidden redirect chain."); } } export function portalSetupMailFixtureTimeoutMs(env: NodeJS.ProcessEnv = process.env): number { const raw = env.E2E_PORTAL_SETUP_MAIL_FIXTURE_TIMEOUT_MS?.trim(); if (!raw) return DEFAULT_POLL_TIMEOUT_MS; const value = Number(raw); if (!Number.isSafeInteger(value) || value < 1_000 || value > MAX_POLL_TIMEOUT_MS) { throw new Error(`E2E_PORTAL_SETUP_MAIL_FIXTURE_TIMEOUT_MS must be an integer from 1000 to ${MAX_POLL_TIMEOUT_MS}.`); } return value; } function normalizePollInterval(value: number | undefined): number { if (value === undefined) return POLL_INTERVAL_MS; if (!Number.isSafeInteger(value) || value < 1 || value > POLL_INTERVAL_MS) { throw new Error(`Portal setup mail fixture poll interval must be an integer from 1 to ${POLL_INTERVAL_MS}.`); } return value; } export function portalSetupMailFixtureNeedsToken(rawEndpoint: string): boolean { const endpoint = parseHttpUrl(rawEndpoint, "E2E_PORTAL_SETUP_MAIL_FIXTURE_URL"); const loopback = isLoopbackHostname(endpoint.hostname); if (!loopback && endpoint.protocol !== "https:") { throw new Error("E2E_PORTAL_SETUP_MAIL_FIXTURE_URL must use HTTPS outside loopback."); } return !loopback; } function requireSafeFixtureEndpoint(rawEndpoint: string, hasToken: boolean): URL { const endpoint = parseHttpUrl(rawEndpoint, "E2E_PORTAL_SETUP_MAIL_FIXTURE_URL"); const loopback = isLoopbackHostname(endpoint.hostname); if (loopback && hasToken) { throw new Error("E2E_PORTAL_SETUP_MAIL_FIXTURE_TOKEN must be unset for a loopback mail fixture."); } if (!loopback && endpoint.protocol !== "https:") { throw new Error("E2E_PORTAL_SETUP_MAIL_FIXTURE_URL must use HTTPS outside loopback."); } if (!loopback && !hasToken) { throw new Error("E2E_PORTAL_SETUP_MAIL_FIXTURE_TOKEN is required for a non-loopback mail fixture."); } return endpoint; } function requireSafeOrigin(rawUrl: string, inputName: string): string { const url = parseHttpUrl(rawUrl, inputName); if (!isLoopbackHostname(url.hostname) && url.protocol !== "https:") { throw new Error(`${inputName} must use HTTPS outside loopback.`); } return url.origin; } function requireSafeHttpsRootOrigin(rawUrl: string, inputName: string): string { const url = parseHttpUrl(rawUrl, inputName); if (url.protocol !== "https:" || url.pathname !== "/" || url.search || url.hash) { throw new Error(`${inputName} must be an exact HTTPS root origin.`); } return url.origin; } function requireSafeSetupUrl(rawUrl: string, expectedOrigin: string, tenantSlug: string, expectedCustomOrigin?: string): string { const setupUrl = parseHttpUrl(rawUrl, "portal setup mail fixture setupUrl"); if (setupUrl.username || setupUrl.password || setupUrl.search || setupUrl.hash) { throw new Error("Portal setup mail fixture returned a setup URL outside the expected portal host contract."); } const expectedPrefix = setupUrl.origin === expectedOrigin ? `/${encodeURIComponent(tenantSlug)}/setup/` : expectedCustomOrigin && setupUrl.origin === expectedCustomOrigin ? "/setup/" : null; if (!expectedPrefix) { throw new Error("Portal setup mail fixture returned a setup URL outside the expected portal host contract."); } if (!setupUrl.pathname.startsWith(expectedPrefix)) { throw new Error("Portal setup mail fixture returned a setup URL outside the expected setup route."); } const token = setupUrl.pathname.slice(expectedPrefix.length); if (!SETUP_TOKEN_PATTERN.test(token)) { throw new Error("Portal setup mail fixture returned an invalid setup capability shape."); } return setupUrl.href; } function parseHttpUrl(rawUrl: string, inputName: string): URL { let url: URL; try { url = new URL(rawUrl); } catch { throw new Error(`${inputName} must be an absolute HTTP(S) URL.`); } if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) { throw new Error(`${inputName} must be an absolute HTTP(S) URL without embedded credentials.`); } return url; } function normalizeEmail(value: unknown): string | null { return typeof value === "string" ? value.trim().toLocaleLowerCase("en-US") : null; } function normalizePortalPath(pathname: string): string { return pathname === "/" ? pathname : pathname.replace(/\/$/u, ""); } function isLoopbackHostname(hostname: string): boolean { return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]"; } async function wait(milliseconds: number): Promise { await new Promise((resolve) => setTimeout(resolve, milliseconds)); }