verify(P20): cross-account-role-automation-offline — 4-layer verify PASS + ship

VERIFY: structural — Terraform + docs + tests; behavioral — terraform validate + 3 tests + CI PASS; quality — offline-proven only (D-114), nova: ABAC tags. ---ci--- project: acdl phase: 20 milestone: v1.16 status: complete phase_role: execution requirements: covered: [REQ-184] partial: [] ---/ci---
2026-08-01 13:32:54 +00:00
parent fe312c6292
commit 9f9d971287
4 changed files with 287 additions and 0 deletions
@@ -0,0 +1,87 @@
+# Nova Onboarding — No-Humans Request Path (v1.16, REQ-182..184)
+
+The v1.16 milestone implements the **request path** of the no-humans
+onboarding flow (D-113). A consumer can submit an onboarding request
+without contacting the platform team; the platform generates an
+environment binding + (in a future milestone) provisions the AWS resources.
+
+## The 3-step request path
+
+### Step 1 — Submit an onboarding request (P18, REQ-182)
+
+A consumer submits an onboarding request to the Nova platform Lambda:
+
+```bash
+# Via the Lambda Function URL (IAM auth):
+curl -X POST "$NOVA_LAMBDA_URL" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "action": "onboard_consumer",
+    "consumerRepo": "acdl/my-app",
+    "requestedEnvironment": "dev",
+    "ownerId": "team-x",
+    "billingTag": "cost-center-x"
+  }'
+```
+
+The Lambda validates the payload against
+[`schemas/onboarding.schema.json`](../schemas/onboarding.schema.json),
+then writes a `pending` row to the `nova-contracts` DynamoDB table
+(D-119). No AWS resources are created by this action (D-113).
+
+### Step 2 — Generate an environment binding (P19, REQ-183)
+
+The platform (or the consumer locally) generates an environment binding
+file from the request:
+
+```bash
+python3 core/onboarding.py --request '{
+  "consumerRepo": "acdl/my-app",
+  "requestedEnvironment": "qa",
+  "ownerId": "team-x",
+  "billingTag": "cost-center-x"
+}' --out core/environments/qa.json
+```
+
+This produces a `<env>.json` from the `dev.json` template, filling in
+the `ownerId` + `billingTag` + a description. The `account_id` is a
+placeholder (`000000000000`) for the platform team to fill with the real
+account. The generated file validates against
+[`schemas/environment.schema.json`](../schemas/environment.schema.json).
+
+### Step 3 — Cross-account role + ABAC tag grant (P20, REQ-184)
+
+The platform authors the consumer deploy-role + `nova:owner` ABAC tag
+grant via Terraform:
+
+```bash
+cd terraform/onboarding
+terraform init -backend=false
+terraform validate
+NOVA_AWS_ACCOUNT_ID=123456789012 terraform plan \
+  -var consumer_repo=acdl/my-app \
+  -var owner_id=team-x
+```
+
+**Offline-proven only (D-114):** `terraform validate` + `terraform plan`
+pass; **no live apply** in v1.16. The live apply (creating the real
+cross-account role + OIDC trust) is deferred to a future feature
+milestone (D-113).
+
+## What is NOT automated (deferred)
+
+- **Real AWS account/network/state provisioning** — the request path
+  generates a binding file with a placeholder `account_id`; the actual
+  AWS account creation + VPC + state backend is a future feature (D-113).
+- **Live cross-account role apply** — the Terraform is offline-proven
+  only (D-114); live apply is deferred.
+- **OIDC trust policy** — the onboarding Terraform uses a placeholder
+  OIDC provider; real OIDC federation is blocked on
+  go-gitea/gitea#36988 (carries forward from v1.1).
+
+## See also
+
+- [`schemas/onboarding.schema.json`](../schemas/onboarding.schema.json) — the request schema
+- [`core/onboarding.py`](../core/onboarding.py) — the env-file generator
+- [`terraform/onboarding/`](../terraform/onboarding/) — the role-grant Terraform
+- [`core/environments/README.md`](../core/environments/README.md) — environment binding docs