[defangdevs]

Summary

• add a server-backed customer-handoff sample for the merged Portal create-handoff contract
• derive a stable opaque installation name for compatible retries, preserve the exact Portal redirect, and allowlist its origin
• keep the developer bearer token in environment configuration, redact logs, and test request, replay, redirect, status, and error behavior at the HTTP boundary
• mark the older AWS-only provider handoff as a legacy prototype

This is intentionally a draft current-contract foundation. It does not present the active machine-auth/callback work in portal#1086 or lifecycle/revocation work in portal#1087 as shipped. Automatic deployment is current behavior from merged portal#1093.

Refs DefangLabs/portal#1091 and pairs with DefangLabs/defang-docs#436. Supersedes the unsafe browser-token prototype in #717.

Current contract demonstrated

• trusted backend trigger after the developer verifies signup/payment/entitlement
• exact createInstallationHandoff GraphQL request and initial pending/ready response handling
• compatible replay using customer identity plus a hash-derived installationName
• 303 See Other to the exact returned handoffUrl
• explicit lack of machine credentials, callbacks, supported partner polling, expiry/cancellation, and verified revocation

Security

• no long-lived credential is pasted into browser code or committed files
• the Portal token is server-only environment configuration
• logs exclude the token, customer email, external reference, and handoff URL
• the redirect is accepted only from the configured Portal origin
• upstream error details are mapped to safe operator-facing messages

Screenshot

Constitution gates

• II.1 DX First: PASS — Compose interface, actionable errors, focused sample and tests
• II.2 Multi-Cloud: PASS — one request path for AWS, Google Cloud, and Azure; current provider constraints are documented
• II.3 Security: PASS for this sample — server-only credential, OIDC handoff, origin validation, and redacted logs; existing broad cloud roles are documented rather than hidden
• II.4 IaC: PASS — repeat-safe handoff feeds the versioned deployment workflow; no sample-side console automation
• II.5 Simplicity: PASS — small dependency-free Node server with explicit current-contract behavior

Testing

• npm test — 10 passed
• npx prettier --check portal-client.js portal-client.test.js server.js server.test.js
• node --check portal-client.js && node --check server.js
• docker compose config
• defang compose config
• repository-wide scripts/check-sample-files.sh
• docker compose build
• built-container /health and rendered UI smoke test

Repository-level npx eslint cannot start because this repository has no eslint.config.*; this branch adds no lint suppression. The JavaScript syntax and formatter checks above pass.

Dependency before production use

Keep this PR in draft while the desired unattended integration is blocked on #1086 and #1087. The sample itself is mergeable as an honest evaluation foundation and can be updated to machine credentials/status/callbacks once those contracts merge.

[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.}