feat: dynamic assume-role support, configurable placeholder image & install tofu consolidation

README.md

@@ -288,6 +288,67 @@ LOG_RETENTION_DAYS: 30
 PARAMETERS_STRATEGY: "env"              # or "secretsmanager"
 ```
 
+### Placeholder Image (Scope Bootstrap)
+
+When a scope is created, the Lambda function and its IAM role must exist **before**
+the first real deployment — otherwise aliases, networking, and IAM have nothing to
+attach to. To bootstrap this, `create-scope` provisions a throwaway **placeholder**
+function that the first deployment then overwrites with the real code.
+
+How the placeholder is sourced depends on the scope's **package type**:
+
+- **Zip** — fully self-contained. A minimal handler ships pre-built and
+  base64-encoded in the repo (`scope/placeholder/placeholder_lambda.zip.b64`) and is
+  used automatically. **No configuration needed.**
+- **Image** — the placeholder must be a container image, and this is where
+  `PLACEHOLDER_IMAGE_URI_DEFAULT` comes in.
+
+#### Why `PLACEHOLDER_IMAGE_URI_DEFAULT` is needed for Image scopes
+
+A Lambda function with `PackageType=Image` can only pull from a **private ECR
+repository in the same account and region** — Lambda rejects `public.ecr.aws`
+images at function-creation time. The built-in default in
+`scope/scripts/resolve_placeholder_image` points at a public image
+(`public.ecr.aws/nullplatform/aws-lambda/nullplatform-lambda-placeholder:latest`),
+which is fine to *validate* but cannot actually back a real Lambda function.
+
+So for Image-based scopes you **must** mirror a placeholder into your own private
+ECR and point the scope at it. The image must also be **single-arch matching the
+scope architecture** (`-amd64` for `x86_64`, `-arm64` for `arm64`) — Lambda does
+not accept multi-arch manifest lists.
+
+#### Resolution precedence
+
+The placeholder image URI is resolved in this order (first match wins):
+
+1. scope-configurations provider key `deployment.placeholder_image_uri` — per-scope,
+   managed without code
+2. `PLACEHOLDER_IMAGE_URI_DEFAULT` env var — the **account-wide** knob, set in
+   `values.yaml` or via the agent's `extra_envs` (Helm)
+3. the public default in `scope/scripts/resolve_placeholder_image` (validation-only
+   fallback; not usable for real Image functions)
+
+Because the URI is account-specific, `values.yaml` ships it commented out — set it
+once per installation and every Image scope in that account uses it, unless a
+specific scope overrides it via the provider key.
+
+#### Publishing a placeholder image
+
+Use the helper script to build and push the single-arch placeholders to your private
+ECR (it creates the repository if it does not exist):
+
+```bash
+export PLACEHOLDER_IMAGE_REPO=123456789012.dkr.ecr.us-east-1.amazonaws.com/aws-lambda/nullplatform-lambda-placeholder
+lambda/scope/placeholder/publish        # pushes <repo>:latest-arm64 and <repo>:latest-amd64
+```
+
+Then set the URI (matching your scope architecture) in `values.yaml` or the agent's
+`extra_envs`:
+
+```yaml
+PLACEHOLDER_IMAGE_URI_DEFAULT: "123456789012.dkr.ecr.us-east-1.amazonaws.com/aws-lambda/nullplatform-lambda-placeholder:latest-arm64"
+```
+
 ### Resource Naming
 
 | Resource | Format | Example |
@@ -507,6 +568,7 @@ export TOFU_LOCK_TABLE=my-lock-table
 | Issue | Cause | Solution |
 |-------|-------|----------|
 | "Function name too long" | Name exceeds 64 chars | Shorten namespace/application/scope slugs |
+| "Placeholder image not found" | Image scope with no private placeholder published | Run `lambda/scope/placeholder/publish` and set `PLACEHOLDER_IMAGE_URI_DEFAULT` (see [Placeholder Image](#placeholder-image-scope-bootstrap)) |
 | "Provisioned concurrency timeout" | Warmup taking too long | Increase `PROVISIONED_CONCURRENCY_MAX_WAIT_SECONDS` |
 | "ALB listener rule capacity" | Too many rules on ALB | Increase `ALB_LISTENER_RULE_CAPACITY` in values.yaml |
 | "Module not composed" | `MODULES_TO_USE` not updated | Verify setup script appends to `MODULES_TO_USE` |

lambda/deployment/scripts/update_function_code

@@ -34,6 +34,22 @@ if [ "$package_type" = "Image" ]; then
   fi
   log debug "   ✅ image_uri=$IMAGE_URI"
 
+  # Ensure the image's ECR repo lets the Lambda service pull it. Container-image
+  # Lambdas require a repository policy granting lambda.amazonaws.com; without it
+  # update-function-code fails with "Lambda does not have permission to access
+  # the ECR image". Idempotent and best-effort (cross-account repos may not be
+  # writable from here — Lambda would then need the policy set on the source side).
+  if [[ "$IMAGE_URI" == *.dkr.ecr.*.amazonaws.com/* ]]; then
+    ecr_region=$(echo "${IMAGE_URI%%/*}" | cut -d. -f4)
+    ecr_repo="${IMAGE_URI#*/}"; ecr_repo="${ecr_repo%%:*}"; ecr_repo="${ecr_repo%%@*}"
+    lambda_pull_policy='{"Version":"2008-10-17","Statement":[{"Sid":"LambdaECRImageRetrievalPolicy","Effect":"Allow","Principal":{"Service":"lambda.amazonaws.com"},"Action":["ecr:BatchGetImage","ecr:GetDownloadUrlForLayer"]}]}'
+    if aws ecr set-repository-policy --repository-name "$ecr_repo" --region "$ecr_region" --policy-text "$lambda_pull_policy" >/dev/null 2>&1; then
+      log debug "   ✅ ensured Lambda pull policy on ECR repo $ecr_repo"
+    else
+      log warn "   ⚠️  could not set Lambda pull policy on ECR repo $ecr_repo (continuing; pull may fail if not already allowed)"
+    fi
+  fi
+
   update_output=$(aws lambda update-function-code \
     --function-name "$LAMBDA_FUNCTION_NAME" \
     --image-uri "$IMAGE_URI" \

lambda/deployment/workflows/blue_green.yaml

@@ -3,6 +3,16 @@ include:
 configuration:
   DEPLOYMENT_STRATEGY: "blue_green"
 steps:
+  - name: assume_role
+    type: script
+    file: "$SERVICE_PATH/utils/assume_role_step"
+    output:
+      - name: AWS_ACCESS_KEY_ID
+        type: environment
+      - name: AWS_SECRET_ACCESS_KEY
+        type: environment
+      - name: AWS_SESSION_TOKEN
+        type: environment
   - name: build_context
     type: script
     file: "$SERVICE_PATH/deployment/build_context"

lambda/deployment/workflows/delete.yaml

@@ -1,6 +1,16 @@
 include:
   - "$SERVICE_PATH/values.yaml"
 steps:
+  - name: assume_role
+    type: script
+    file: "$SERVICE_PATH/utils/assume_role_step"
+    output:
+      - name: AWS_ACCESS_KEY_ID
+        type: environment
+      - name: AWS_SECRET_ACCESS_KEY
+        type: environment
+      - name: AWS_SESSION_TOKEN
+        type: environment
   - name: build_context
     type: script
     file: "$SERVICE_PATH/deployment/build_context"

lambda/deployment/workflows/diagnose.yaml

@@ -0,0 +1,41 @@
+include:
+  - "$SERVICE_PATH/values.yaml"
+steps:
+  - name: assume_role
+    type: script
+    file: "$SERVICE_PATH/utils/assume_role_step"
+    output:
+      - name: AWS_ACCESS_KEY_ID
+        type: environment
+      - name: AWS_SECRET_ACCESS_KEY
+        type: environment
+      - name: AWS_SESSION_TOKEN
+        type: environment
+  - name: build_context
+    type: script
+    file: "$SERVICE_PATH/diagnose/build_context"
+    output:
+      - name: SCOPE_ID
+        type: environment
+      - name: SCOPE_NRN
+        type: environment
+      - name: LAMBDA_FUNCTION_NAME
+        type: environment
+      - name: LAMBDA_FUNCTION_ARN
+        type: environment
+      - name: LAMBDA_ROLE_ARN
+        type: environment
+      - name: SCOPE_DOMAIN
+        type: environment
+  - name: diagnose
+    type: executor
+    before_each:
+      name: notify_check_running
+      type: script
+      file: "$SERVICE_PATH/diagnose/notify_check_running"
+    after_each:
+      name: notify_check_results
+      type: script
+      file: "$SERVICE_PATH/diagnose/notify_results"
+    folders:
+      - "$SERVICE_PATH/diagnose/checks"

lambda/deployment/workflows/finalize.yaml

@@ -1,6 +1,16 @@
 include:
   - "$SERVICE_PATH/values.yaml"
 steps:
+  - name: assume_role
+    type: script
+    file: "$SERVICE_PATH/utils/assume_role_step"
+    output:
+      - name: AWS_ACCESS_KEY_ID
+        type: environment
+      - name: AWS_SECRET_ACCESS_KEY
+        type: environment
+      - name: AWS_SESSION_TOKEN
+        type: environment
   - name: build_context
     type: script
     file: "$SERVICE_PATH/deployment/build_context"

lambda/deployment/workflows/initial.yaml

@@ -1,6 +1,16 @@
 include:
   - "$SERVICE_PATH/values.yaml"
 steps:
+  - name: assume_role
+    type: script
+    file: "$SERVICE_PATH/utils/assume_role_step"
+    output:
+      - name: AWS_ACCESS_KEY_ID
+        type: environment
+      - name: AWS_SECRET_ACCESS_KEY
+        type: environment
+      - name: AWS_SESSION_TOKEN
+        type: environment
   - name: build_context
     type: script
     file: "$SERVICE_PATH/deployment/build_context"

lambda/deployment/workflows/rollback.yaml

@@ -1,6 +1,16 @@
 include:
   - "$SERVICE_PATH/values.yaml"
 steps:
+  - name: assume_role
+    type: script
+    file: "$SERVICE_PATH/utils/assume_role_step"
+    output:
+      - name: AWS_ACCESS_KEY_ID
+        type: environment
+      - name: AWS_SECRET_ACCESS_KEY
+        type: environment
+      - name: AWS_SESSION_TOKEN
+        type: environment
   - name: build_context
     type: script
     file: "$SERVICE_PATH/deployment/build_context"

lambda/deployment/workflows/switch_traffic.yaml

@@ -1,6 +1,16 @@
 include:
   - "$SERVICE_PATH/values.yaml"
 steps:
+  - name: assume_role
+    type: script
+    file: "$SERVICE_PATH/utils/assume_role_step"
+    output:
+      - name: AWS_ACCESS_KEY_ID
+        type: environment
+      - name: AWS_SECRET_ACCESS_KEY
+        type: environment
+      - name: AWS_SESSION_TOKEN
+        type: environment
   - name: build_context
     type: script
     file: "$SERVICE_PATH/deployment/build_context"

lambda/diagnose/build_context

@@ -16,6 +16,10 @@ fi
 
 source "$SERVICE_PATH/utils/lambda_function_name"
 
+# NOTE: The IAM role is assumed by the dedicated `assume_role` step that runs
+# first in the workflow (see utils/assume_role_step); credentials are already in
+# the environment here.
+
 lambda_info=$(aws lambda get-function --function-name "$LAMBDA_FUNCTION_NAME" --output json 2>/dev/null || echo "{}")
 LAMBDA_FUNCTION_ARN=$(echo "$lambda_info" | jq -r '.Configuration.FunctionArn // ""')
 LAMBDA_ROLE_ARN=$(echo "$lambda_info" | jq -r '.Configuration.Role // ""')

lambda/installation.md

@@ -29,17 +29,24 @@ git clone https://github.com/nullplatform/tofu-modules /root/.np/nullplatform/to
 ### 2. Configure variables
 
 ```bash
-cd lambda/tofu
+cd lambda/specs/tofu
 cp terraform.tfvars.example terraform.tfvars
 ```
 
-Edit `terraform.tfvars` with your values:
+This module registers the scope type **and** provisions the IAM policies the
+agent needs to operate Lambda scopes (formerly the separate `requirements`
+module — now consolidated here). Edit `terraform.tfvars` with your values:
 
 | Variable | Required | Description |
 |---|---|---|
 | `nrn` | ✅ | Nullplatform Resource Name (`organization:account`) |
 | `np_api_key` | ✅ | Nullplatform API key |
 | `tags_selectors` | ✅ | Tags to select the agent (e.g. `{ environment = "production" }`) |
+| `name` | ✅ | Unique identifier for IAM policy naming (account-global, e.g. `prod-us-east-1`) |
+| `aws_region` | — | AWS provider region. IAM is global; leave unset to resolve from the environment |
+| `create_role` | — | `true` to create a new IAM role and attach the Lambda policies to it |
+| `trusted_arns` | — | Principal ARNs allowed to assume the created role (with `create_role = true`) |
+| `role_name` | — | Existing IAM role to attach the Lambda policies to (instead of `create_role`) |
 | `github_branch` | — | Branch to fetch specs from (default: `main`) |
 | `repo_path` | — | Path where scopes-lambda is cloned on the agent |
 | `overrides_enabled` | — | Set `true` to enable config overrides from scopes-networking |

lambda/instance/workflows/list.yaml

@@ -1,6 +1,16 @@
 include:
   - "$SERVICE_PATH/values.yaml"
 steps:
+  - name: assume_role
+    type: script
+    file: "$SERVICE_PATH/utils/assume_role_step"
+    output:
+      - name: AWS_ACCESS_KEY_ID
+        type: environment
+      - name: AWS_SECRET_ACCESS_KEY
+        type: environment
+      - name: AWS_SESSION_TOKEN
+        type: environment
   - name: build_context
     type: script
     file: "$SERVICE_PATH/instance/build_context"

lambda/log/workflows/log.yaml

@@ -1,6 +1,16 @@
 include:
   - "$SERVICE_PATH/values.yaml"
 steps:
+  - name: assume_role
+    type: script
+    file: "$SERVICE_PATH/utils/assume_role_step"
+    output:
+      - name: AWS_ACCESS_KEY_ID
+        type: environment
+      - name: AWS_SECRET_ACCESS_KEY
+        type: environment
+      - name: AWS_SESSION_TOKEN
+        type: environment
   - name: build_context
     type: script
     file: "$SERVICE_PATH/log/build_context"

lambda/metric/workflows/list.yaml

@@ -1,6 +1,16 @@
 include:
   - "$SERVICE_PATH/values.yaml"
 steps:
+  - name: assume_role
+    type: script
+    file: "$SERVICE_PATH/utils/assume_role_step"
+    output:
+      - name: AWS_ACCESS_KEY_ID
+        type: environment
+      - name: AWS_SECRET_ACCESS_KEY
+        type: environment
+      - name: AWS_SESSION_TOKEN
+        type: environment
   - name: list_metrics
     type: script
     file: "$SERVICE_PATH/metric/list_metrics"

lambda/metric/workflows/metric.yaml

@@ -1,6 +1,16 @@
 include:
   - "$SERVICE_PATH/values.yaml"
 steps:
+  - name: assume_role
+    type: script
+    file: "$SERVICE_PATH/utils/assume_role_step"
+    output:
+      - name: AWS_ACCESS_KEY_ID
+        type: environment
+      - name: AWS_SECRET_ACCESS_KEY
+        type: environment
+      - name: AWS_SESSION_TOKEN
+        type: environment
   - name: build_context
     type: script
     file: "$SERVICE_PATH/metric/build_context"

lambda/prerequisites.md

@@ -229,7 +229,7 @@ Agents run in a Kubernetes pod and authenticate to AWS via a **Service Account**
 The IAM policies above let the agent CREATE Lambda functions and target
 groups, but the `create-scope` workflow ALSO depends on three runtime
 artifacts that must exist BEFORE the first scope is created. None are
-auto-created by the bundled `install/tofu/main.tf` today — the operator
+auto-created by the bundled `specs/tofu/main.tf` today — the operator
 must provision them.
 
 ### 1. Placeholder image (private ECR)
@@ -383,7 +383,7 @@ This applies to **every** ECR repository that ever stores a Lambda
 image:
 
 1. The placeholder ECR (created during installation, addressed by
-   `lambda/tofu/main.tf` if you use the bundled module — the policy is
+   `lambda/specs/tofu/main.tf` if you use the bundled module — the policy is
    already applied there).
 2. **The per-application ECR repositories** that `np asset push`
    creates dynamically when each app does its first build, named

lambda/scope/placeholder/publish

@@ -51,7 +51,7 @@ if ! docker buildx version &>/dev/null; then
 fi
 
 # Extract registry host and region from IMAGE_REPO
-ECR_REGISTRY=$(echo "$IMAGE_REPO" | cut -d/ -f1)       # 688720756067.dkr.ecr.us-east-1.amazonaws.com
+ECR_REGISTRY=$(echo "$IMAGE_REPO" | cut -d/ -f1)       # 123456789012.dkr.ecr.us-east-1.amazonaws.com
 ECR_REGION=$(echo "$ECR_REGISTRY" | cut -d. -f4)        # us-east-1
 ECR_REPO_NAME=$(echo "$IMAGE_REPO" | cut -d/ -f2-)      # aws-lambda/nullplatform-lambda-placeholder
 

lambda/scope/scripts/resolve_placeholder_image

@@ -38,14 +38,15 @@ log info "🔍 Resolving placeholder image URI..."
 placeholder_image_base="${PLACEHOLDER_IMAGE_URI:-public.ecr.aws/nullplatform/aws-lambda/nullplatform-lambda-placeholder:latest}"
 architecture="${ARCHITECTURE:-arm64}"
 
-# Lambda uses "x86_64" but images are tagged with Docker convention "amd64"
-arch_tag="${architecture}"
-[ "$architecture" = "x86_64" ] && arch_tag="amd64"
+log debug "   📋 architecture=$architecture"
 
+# Use the image URI as-is. If PLACEHOLDER_IMAGE_URI is not set, the default
+# :latest tag is used without any architecture suffix — publish arch-specific
+# tags and set PLACEHOLDER_IMAGE_URI explicitly if needed.
 if [[ "$placeholder_image_base" == *":"* ]]; then
-  placeholder_image_uri="${placeholder_image_base}-${arch_tag}"
+  placeholder_image_uri="$placeholder_image_base"
 else
-  placeholder_image_uri="${placeholder_image_base}:latest-${arch_tag}"
+  placeholder_image_uri="${placeholder_image_base}:latest"
 fi
 
 log debug "   📋 architecture=$architecture"