Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/scripts/portal-setup-mail-fixture.test.ts
T

327 lines
13 KiB
TypeScript

import type { APIRequestContext, APIResponse } from "@playwright/test";
import { describe, expect, it, vi } from "vitest";
import {
assertPortalSetupNavigationHasNoRedirect,
derivePortalSetupJourneyContext,
isExpectedPortalJourneyLocation,
isExpectedPortalProjectDetailLocation,
waitForPortalSetupMailLink,
} from "../tests/e2e/utils/portal-setup-mail-fixture";
import { requireCanonicalE2eLocalPath } from "../tests/e2e/utils/local-path";
const setupToken = "s".repeat(43);
const commonInput = {
endpoint: "http://127.0.0.1:4010/setup-mail",
correlationKey: "run-123",
recipient: "customer@example.test",
entrypoint: "admin" as const,
deliveredAfter: new Date("2026-07-18T12:00:10.000Z"),
portalBaseUrl: "http://127.0.0.1:3000",
tenantSlug: "demo-pro-crm",
timeoutMs: 1_000,
pollIntervalMs: 1,
};
describe("portal setup mail fixture", () => {
it("retries transient transport, server, and stale-delivery responses before accepting a fresh correlated link", async () => {
const post = vi
.fn()
.mockRejectedValueOnce(new Error("temporary transport failure"))
.mockResolvedValueOnce(response(503))
.mockResolvedValueOnce(
response(200, {
correlationKey: commonInput.correlationKey,
recipient: commonInput.recipient,
source: "portal_admin_invite",
purpose: "setup",
deliveredAt: "2026-07-18T11:59:50.000Z",
setupUrl: `${commonInput.portalBaseUrl}/${commonInput.tenantSlug}/setup/${setupToken}`,
}),
)
.mockResolvedValueOnce(
response(200, {
correlationKey: commonInput.correlationKey,
recipient: commonInput.recipient,
source: "portal_admin_invite",
purpose: "setup",
// Four seconds earlier is within the documented second-precision /
// runner-clock tolerance.
deliveredAt: "2026-07-18T12:00:06.000Z",
setupUrl: `${commonInput.portalBaseUrl}/${commonInput.tenantSlug}/setup/${setupToken}`,
}),
);
await expect(waitForPortalSetupMailLink(requestWith(post), commonInput)).resolves.toBe(
`${commonInput.portalBaseUrl}/${commonInput.tenantSlug}/setup/${setupToken}`,
);
expect(post).toHaveBeenCalledTimes(4);
expect(post).toHaveBeenLastCalledWith(
commonInput.endpoint,
expect.objectContaining({
data: expect.objectContaining({
correlationKey: commonInput.correlationKey,
recipient: commonInput.recipient,
purpose: "setup",
source: "portal_admin_invite",
}),
headers: { "Cache-Control": "no-store" },
maxRedirects: 0,
}),
);
});
it("requires authenticated HTTPS for a non-loopback mailbox adapter", async () => {
const post = vi.fn();
await expect(
waitForPortalSetupMailLink(requestWith(post), {
...commonInput,
endpoint: "https://mail-fixture.example.test/setup-mail",
}),
).rejects.toThrow("E2E_PORTAL_SETUP_MAIL_FIXTURE_TOKEN is required");
expect(post).not.toHaveBeenCalled();
});
it("rejects bearer credentials before contacting a loopback mailbox adapter", async () => {
const post = vi.fn();
const fixtureToken = "loopback-secret-must-not-be-sent";
const error = await waitForPortalSetupMailLink(requestWith(post), {
...commonInput,
fixtureToken,
}).catch((caught: unknown) => caught);
expect(error).toBeInstanceOf(Error);
expect((error as Error).message).toContain("must be unset for a loopback mail fixture");
expect((error as Error).message).not.toContain(fixtureToken);
expect((error as Error).message).not.toContain(commonInput.endpoint);
expect(post).not.toHaveBeenCalled();
});
it("maps the contact entrypoint to the canonical contact invitation source", async () => {
const post = vi.fn().mockResolvedValue(
response(200, {
correlationKey: commonInput.correlationKey,
recipient: commonInput.recipient,
source: "portal_contact_invite",
purpose: "setup",
deliveredAt: commonInput.deliveredAfter.toISOString(),
setupUrl: `${commonInput.portalBaseUrl}/${commonInput.tenantSlug}/setup/${setupToken}`,
}),
);
await expect(waitForPortalSetupMailLink(requestWith(post), { ...commonInput, entrypoint: "contact" })).resolves.toBe(
`${commonInput.portalBaseUrl}/${commonInput.tenantSlug}/setup/${setupToken}`,
);
expect(post).toHaveBeenCalledWith(
commonInput.endpoint,
expect.objectContaining({ data: expect.objectContaining({ source: "portal_contact_invite" }) }),
);
});
it("accepts an exact configured custom-domain root with the custom setup route", async () => {
const customOrigin = "https://portal.customer.example.test";
const setupUrl = `${customOrigin}/setup/${setupToken}`;
const post = vi.fn().mockResolvedValue(
response(200, {
correlationKey: commonInput.correlationKey,
recipient: commonInput.recipient,
source: "portal_admin_invite",
purpose: "setup",
deliveredAt: commonInput.deliveredAfter.toISOString(),
setupUrl,
}),
);
await expect(
waitForPortalSetupMailLink(requestWith(post), {
...commonInput,
portalCustomDomainBaseUrl: customOrigin,
}),
).resolves.toBe(setupUrl);
});
it("rejects unconfigured custom origins and the tenant-prefixed path on a configured custom origin", async () => {
const customOrigin = "https://portal.customer.example.test";
const responsePayload = (setupUrl: string) => ({
correlationKey: commonInput.correlationKey,
recipient: commonInput.recipient,
source: "portal_admin_invite",
purpose: "setup",
deliveredAt: commonInput.deliveredAfter.toISOString(),
setupUrl,
});
await expect(
waitForPortalSetupMailLink(requestWith(vi.fn().mockResolvedValue(response(200, responsePayload(`${customOrigin}/setup/${setupToken}`)))), commonInput)
).rejects.toThrow("outside the expected portal host contract");
await expect(
waitForPortalSetupMailLink(
requestWith(vi.fn().mockResolvedValue(response(200, responsePayload(`${customOrigin}/${commonInput.tenantSlug}/setup/${setupToken}`)))),
{ ...commonInput, portalCustomDomainBaseUrl: customOrigin }
)
).rejects.toThrow("outside the expected setup route");
});
it("rejects tracking wrappers even when a custom origin is configured", async () => {
const trackingUrl = `https://tracking.example.test/redirect/${setupToken}`;
const post = vi.fn().mockResolvedValue(
response(200, {
correlationKey: commonInput.correlationKey,
recipient: commonInput.recipient,
source: "portal_admin_invite",
purpose: "setup",
deliveredAt: commonInput.deliveredAfter.toISOString(),
setupUrl: trackingUrl,
})
);
await expect(
waitForPortalSetupMailLink(requestWith(post), {
...commonInput,
portalCustomDomainBaseUrl: "https://portal.customer.example.test",
})
).rejects.toThrow("outside the expected portal host contract");
});
it("never includes a mailbox endpoint, bearer token, or setup URL in contract errors", async () => {
const endpoint = "https://mail-fixture.example.test/private-path";
const fixtureToken = "fixture-secret-value";
const leakedSetupUrl = `https://evil.example.test/demo-pro-crm/setup/${setupToken}`;
const post = vi.fn().mockResolvedValue(
response(200, {
correlationKey: commonInput.correlationKey,
recipient: commonInput.recipient,
source: "portal_admin_invite",
purpose: "setup",
deliveredAt: commonInput.deliveredAfter.toISOString(),
setupUrl: leakedSetupUrl,
}),
);
const error = await waitForPortalSetupMailLink(requestWith(post), {
...commonInput,
endpoint,
fixtureToken,
}).catch((caught: unknown) => caught);
expect(error).toBeInstanceOf(Error);
const message = (error as Error).message;
expect(message).toContain("outside the expected portal host contract");
expect(message).not.toContain(endpoint);
expect(message).not.toContain(fixtureToken);
expect(message).not.toContain(leakedSetupUrl);
});
});
describe("portal setup journey context", () => {
it("derives tenant-prefixed paths for the standard portal origin", () => {
expect(derivePortalSetupJourneyContext(`${commonInput.portalBaseUrl}/${commonInput.tenantSlug}/setup/${setupToken}`, commonInput)).toEqual({
origin: commonInput.portalBaseUrl,
tenantPathPrefix: `/${commonInput.tenantSlug}`,
portalRootPath: `/${commonInput.tenantSlug}`,
projectsPath: `/${commonInput.tenantSlug}/projects`,
});
});
it("derives root paths only for the exact configured custom origin", () => {
const customOrigin = "https://portal.customer.example.test";
expect(
derivePortalSetupJourneyContext(`${customOrigin}/setup/${setupToken}`, {
...commonInput,
portalCustomDomainBaseUrl: customOrigin,
})
).toEqual({
origin: customOrigin,
tenantPathPrefix: "",
portalRootPath: "/",
projectsPath: "/projects",
});
});
it("rejects a setup journey on an unconfigured or different custom origin", () => {
const customOrigin = "https://portal.customer.example.test";
const setupUrl = `${customOrigin}/setup/${setupToken}`;
expect(() => derivePortalSetupJourneyContext(setupUrl, commonInput)).toThrow("outside the expected portal host contract");
expect(() =>
derivePortalSetupJourneyContext(setupUrl, {
...commonInput,
portalCustomDomainBaseUrl: "https://different.customer.example.test",
})
).toThrow("outside the expected portal host contract");
});
it("matches standard and custom journey paths while rejecting a foreign origin", () => {
const standard = derivePortalSetupJourneyContext(`${commonInput.portalBaseUrl}/${commonInput.tenantSlug}/setup/${setupToken}`, commonInput);
const customOrigin = "https://portal.customer.example.test";
const custom = derivePortalSetupJourneyContext(`${customOrigin}/setup/${setupToken}`, {
...commonInput,
portalCustomDomainBaseUrl: customOrigin,
});
expect(isExpectedPortalJourneyLocation(new URL(`${standard.origin}/${commonInput.tenantSlug}`), standard, standard.portalRootPath)).toBe(true);
expect(isExpectedPortalProjectDetailLocation(new URL(`${standard.origin}/${commonInput.tenantSlug}/projects/project-1`), standard)).toBe(true);
expect(isExpectedPortalJourneyLocation(new URL(customOrigin), custom, custom.portalRootPath)).toBe(true);
expect(isExpectedPortalProjectDetailLocation(new URL(`${customOrigin}/projects/project-1`), custom)).toBe(true);
expect(isExpectedPortalJourneyLocation(new URL("https://foreign.example.test/"), custom, custom.portalRootPath)).toBe(false);
expect(isExpectedPortalProjectDetailLocation(new URL("https://foreign.example.test/projects/project-1"), custom)).toBe(false);
});
it("rejects any setup main-document redirect without exposing its target", () => {
const secretTarget = `https://tracking.example.test/redirect/${setupToken}`;
const direct = { request: () => ({ redirectedFrom: () => null }) };
const redirected = { request: () => ({ redirectedFrom: () => ({ url: () => secretTarget }) }) };
expect(() => assertPortalSetupNavigationHasNoRedirect(direct)).not.toThrow();
const error = (() => {
try {
assertPortalSetupNavigationHasNoRedirect(redirected);
return null;
} catch (caught) {
return caught;
}
})();
expect(error).toBeInstanceOf(Error);
expect((error as Error).message).toContain("forbidden redirect chain");
expect((error as Error).message).not.toContain(secretTarget);
expect((error as Error).message).not.toContain(setupToken);
});
});
describe("portal invitation app-local paths", () => {
it("accepts only canonical same-origin route paths", () => {
expect(requireCanonicalE2eLocalPath("/demo-pro-crm/settings/customer-portal", "E2E_PATH")).toBe(
"/demo-pro-crm/settings/customer-portal",
);
for (const unsafe of [
"https://evil.example.test/path",
"//evil.example.test/path",
"/\\evil.example.test/path",
"/%5c%5cevil.example.test/path",
"/demo/../admin",
"/demo?next=//evil.example.test",
"/demo#fragment",
"/demo\u0000/path",
]) {
expect(() => requireCanonicalE2eLocalPath(unsafe, "E2E_PATH")).toThrow(
"E2E_PATH must be a canonical app-local absolute path",
);
}
});
});
function requestWith(post: ReturnType<typeof vi.fn>): APIRequestContext {
return { post } as unknown as APIRequestContext;
}
function response(status: number, payload?: unknown): APIResponse {
return {
status: () => status,
json: async () => payload,
} as unknown as APIResponse;
}