refactor(SDK-1127): extract sub flows from PaymentFlow

[mariechatfield]

Summary

• Carves the create-payment and view-history steps out of PaymentFlow into their own hub+spoke flows, mirroring the PayrollFlow/PayrollExecutionFlow pattern: each spoke owns its own robot3 machine and breadcrumb trail, prefixed with the hub's landing breadcrumb, and bubbles terminal events (exit, cancel, landing navigation) back up to the hub. Pure refactor — no behavior change, all six original events unchanged.
• Marks the two new standalone flows @alpha (not yet promoted to the public surface) — PaymentFlow still composes them internally, but its @components list and GUIDE.md step-flow diagram point at the underlying public blocks (CreatePayment, PaymentSummary, PaymentHistory, PaymentStatement) they wrap, matching what a partner using the public surface actually sees.

http://localhost:5200/contractormanagement/PaymentFlow behaves the same locally as it does on main

http://localhost:5200/contractormanagement/CreatePaymentFlow works to create a payment (same as the PaymentFlow starting from the New payment button)

http://localhost:5200/contractormanagement/ViewHistoryView lets you view payment details (same as the PaymentFlow starting with the eye icon on an existing payment)

Test plan

• paymentStateMachine.test.ts characterization test for the prior flat machine, plus new createPaymentMachine.test.ts / viewHistoryMachine.test.ts covering each extracted spoke
• npm run derive regenerates cleanly with 0 errors; CreatePaymentFlow/ViewHistoryFlow correctly excluded from the generated reference while @alpha
• Pre-existing, unrelated failure in docs-site/plugins/typedoc-custom/sdk-router.test.ts reproduces on main too — not introduced by this branch

🤖 Generated with Claude Code

[boostsecurity-io-ai]

⚠️  2 New Security Findings

The latest commit contains 2 new security findings.

Findings Note: 2 findings are displayed as inline comments.

Not a finding? Ignore it by adding a comment on the line with just the word noboost.

Scanner: boostsecurity - Semgrep

[boostsecurity-io-ai]

CWE-918: Server-Side Request Forgery (SSRF)
Original Rule ID: rules_lgpl_javascript_ssrf_rule-node-ssrf

Details

The web server receives a URL or similar request from an upstream component and retrieves the contents of this URL, but it does not sufficiently ensure that the request is being sent to the expected destination.

This rule detected user-controlled URLs being passed to Node.js HTTP client
libraries including axios.get(), axios.post(), fetch(), http.get(),
http.request(), needle(), request(), urllib.request(),
superagent.get(), bent(), got.get(), net.connect(), and
socket.io-client.io(). When user input controls the destination URL of HTTP
requests without validation, Server-Side Request Forgery (SSRF) vulnerabilities
arise. SSRF allows attackers to force the server to make requests to internal
systems, cloud metadata endpoints (such as 169.254.169.254), or other
unauthorized destinations. This can expose internal APIs, databases,
administrative panels, or enable network scanning and pivoting attacks that
bypass firewall rules and network segmentation.
 📘 Learn More

AI Remediation

The fix adds an origin-allowlist re-validation (validateHost) at the start of seedHistoricalContractorPayment before any fetch calls, ensuring the request destination is confined to the pre-approved gws-flows origins and cannot be redirected toward internal systems or cloud metadata endpoints. This closes the SSRF (CWE-918) gap where proxyBase was consumed as an HTTP client URL without validation at the request site.

Suggested change

	const contractorRes = await fetch(`${proxyBase}/v1/contractors/${contractorId}`, {
	// Re-validate the origin of the proxy base against the allowlist before
	// issuing requests to guard against SSRF (CWE-918). proxyBase is derived
	// from a validated host plus a flow token, but validating here ensures the
	// request destination cannot be redirected to an internal/metadata endpoint.
	validateHost(proxyBase)

[boostsecurity-io-ai]

CWE-918: Server-Side Request Forgery (SSRF)
Original Rule ID: rules_lgpl_javascript_ssrf_rule-node-ssrf

Details

The web server receives a URL or similar request from an upstream component and retrieves the contents of this URL, but it does not sufficiently ensure that the request is being sent to the expected destination.

This rule detected user-controlled URLs being passed to Node.js HTTP client
libraries including axios.get(), axios.post(), fetch(), http.get(),
http.request(), needle(), request(), urllib.request(),
superagent.get(), bent(), got.get(), net.connect(), and
socket.io-client.io(). When user input controls the destination URL of HTTP
requests without validation, Server-Side Request Forgery (SSRF) vulnerabilities
arise. SSRF allows attackers to force the server to make requests to internal
systems, cloud metadata endpoints (such as 169.254.169.254), or other
unauthorized destinations. This can expose internal APIs, databases,
administrative panels, or enable network scanning and pivoting attacks that
bypass firewall rules and network segmentation.
 📘 Learn More

AI Remediation

The base host of each fetch URL (proxyBase) already flows from the allowlist-validated safeHost, but the interpolated companyId/contractorId path segments were unvalidated, allowing potential URL/path manipulation that could redirect requests to unintended destinations (SSRF). The fix enforces a strict identifier allowlist (^[a-zA-Z0-9_-]+$) and applies encodeURIComponent so these values cannot alter the request target. This constrains the outbound request destination to the validated proxy base with well-formed path segments.

At line 69, do the following changes:

   companyId: string,
   contractorId: string,
 ): Promise<string> {
-  const contractorRes = await fetch(`${proxyBase}/v1/contractors/${contractorId}`, {
-    signal: AbortSignal.timeout(10000),
-  })
+  // Guard against path/URL injection: IDs are interpolated into request URLs,
+  // so restrict them to opaque identifier characters before use.
+  const ID_PATTERN = /^[a-zA-Z0-9_-]+$/
+  if (!ID_PATTERN.test(companyId) || !ID_PATTERN.test(contractorId)) {
+    throw new Error('Invalid company or contractor ID')
+  }
+
+  const contractorRes = await fetch(
+    `${proxyBase}/v1/contractors/${encodeURIComponent(contractorId)}`,
+    {
+      signal: AbortSignal.timeout(10000),
+    },
+  )
   if (!contractorRes.ok) return ''
   const contractor = (await contractorRes.json()) as { wage_type?: string }
 

At line 79, do the following changes:

   checkDate.setDate(checkDate.getDate() - 14)
 
   const paymentRes = await fetch(
-    `${proxyBase}/v1/companies/${companyId}/contractor_payment_groups`,
+    `${proxyBase}/v1/companies/${encodeURIComponent(companyId)}/contractor_payment_groups`,
     {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },

[mariechatfield]

closed in favor of #2463 once I realized that this introduced new bugs due to missing tests