feat(samples): add customer handoff demo

[defangdevs]

Summary

• add a dependency-free, server-backed demo for Portal PR #1069's createInstallationHandoff action
• guide a developer through loading authorized workspaces/projects and creating an AWS, GCP, or Azure customer handoff
• preserve, display, copy, and open the exact handoffUrl returned by Portal
• add validation, safe upstream error handling, security headers, tests, and local/dev instructions

Depends on DefangLabs/portal#1069. This should remain a draft until that action is deployed to the target Portal environment.

Security

The developer supplies a short-lived bearer token with each request. The demo never persists or logs it, and deliberately has no shared server-configured credential mode.

Constitution gates

• DX First: Compose-based setup, guided UI, actionable errors, and documented end-to-end steps.
• Multi-Cloud: the same flow supports AWS, GCP, and Azure.
• Security: per-request credentials, HTTPS enforcement outside localhost, input limits/validation, timeouts, CSP, and safe error mapping.
• IaC: the runnable sample is fully declared in Compose; no manual cloud resource setup is introduced.
• Simplicity: Node's built-in APIs only, three small HTTP routes, and no runtime dependencies.

Testing

• npm test — 8 passing tests
• node --check portal-client.js server.js public/app.js
• docker compose config
• defang compose config
• bash scripts/check-sample-files.sh
• browser flow exercised with Chromium against intercepted GraphQL responses; verified that the UI used the literal returned URL:
  https://portal.dev.gnafed.click/clients/login?redirect=%2Finstallations%2F00000000-0000-4000-8000-000000000003%2Fsetup

A container image build was not run because the box's rootless Docker daemon is unavailable; both Compose configurations and the host-run application were validated.

Screenshot

Samples Checklist

✅ All good!

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}