Run Codex and Claude Code from a browser while the workspace stays on a private EC2 runtime—with no public IP and no inbound SSH.
+Run CLI agent harnesses from a browser while the workspace stays on a private EC2 runtime with no public IP and no inbound SSH.
Quick start · Architecture · Documentation · Security · Contributing
@@ -72,6 +72,7 @@ AWS IAM Identity Center --SAML--> Cognito bridge --OIDC--> App Runner - an App Runner web terminal - a restricted Step Functions job that can create only the fixed runtime stack - a DynamoDB identity-to-runtime registry +- a short-lived DynamoDB request-control table shared by every web instance - a short-lived, encrypted S3 upload staging area You need an organization instance of IAM Identity Center, permission to add a @@ -279,3 +280,5 @@ or uptime commitment. Bugs and improvements are welcome through GitHub issues an pull requests. Licensed under the [BSD 2-Clause License](LICENSE). + +_AgentFormation is still experimental—review the security model and try it in a non-production AWS account before depending on it._ diff --git a/docs/configuration.md b/docs/configuration.md index 4bd62f8..219c2d8 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -13,7 +13,7 @@ cp agentformation.example.json agentformation.local.json | Field | What to enter | When to change it | | ----------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `deploymentName` | A lowercase name using letters, numbers, and hyphens | Keep it stable for the life of one deployment. Changing it creates a separate set of AWS resources. | +| `deploymentName` | A lowercase name using letters, numbers, and hyphens; do not use the reserved `-runtime-` segment | Keep it stable for the life of one deployment. Changing it creates a separate set of AWS resources. | | `region` | The AWS Region for the deployment | Choose a Region supported by the required AWS services and configured Bedrock models. | | `publicUrl` | Empty, or the exact `https://` origin of an active App Runner custom domain | Leave empty for the generated App Runner address. Do not add a path or trailing slash. | | `networkMode` | `private-nat` or `private-endpoints` | `private-nat` is the normal starting point. The endpoint mode adds AWS service endpoints but still keeps internet access for developer tools. | diff --git a/docs/maintainer-release-checklist.md b/docs/maintainer-release-checklist.md index f57c009..1812bfd 100644 --- a/docs/maintainer-release-checklist.md +++ b/docs/maintainer-release-checklist.md @@ -76,8 +76,8 @@ account and complete this checklist. - Review findings in the account or organization IAM Access Analyzer. AgentFormation intentionally does not create this account-wide service; if no analyzer exists, record that operator gap instead of marking the review complete. -- Confirm the ECR scan for the exact web image tag completed, then review every - reported finding before release. +- Confirm the ECR scan for the exact web image digest deployed to App Runner + completed, then review every reported finding before release. - Run `./agentformation destroy --confirm DELETE` after the review window and verify no tagged EC2, EBS, NAT, App Runner, ECR, S3, DynamoDB, Cognito, Secrets Manager, Step Functions, Image Builder, AMI, or snapshot resources remain. diff --git a/docs/privacy.md b/docs/privacy.md index a1d0862..9a22971 100644 --- a/docs/privacy.md +++ b/docs/privacy.md @@ -8,10 +8,23 @@ The deployed system stores or processes: - assigned employees' email addresses and federated Cognito identifiers; - the mapping between an employee and an EC2 runtime; - environment-creation status and AWS Step Functions execution history; +- short-lived request counters and upload claims in DynamoDB; - encrypted runtime files on EBS; -- uploaded files in S3 until copied or expired; and +- uploaded files in S3 until copied or expired; +- terminal tab labels in that browser's local storage until app sign-out; and - normal AWS service, access, build, and application logs. +Each browser upload is limited to 50 MiB at the S3 write boundary, restricted to +one random key and declared content type, copied to a server-owned sealed key +before delivery, and deleted from staging after the runtime command finishes. +The one-day bucket rule is a backstop if immediate cleanup cannot be confirmed. + +Copying terminal text places it in the device's system clipboard. AgentFormation +clears its own selection state after a successful copy, but browsers do not offer +a safe, reliable way for a web app to erase the system clipboard later. Treat +copied secrets like any other clipboard secret and replace them before sharing or +leaving the device unattended. + The IAM Identity Center metadata address or downloaded XML contains organization-specific SAML endpoints and public signing certificates. The address belongs only in ignored `agentformation.local.json`; a fallback XML file diff --git a/docs/security-model.md b/docs/security-model.md index 9ed2568..5d9fb16 100644 --- a/docs/security-model.md +++ b/docs/security-model.md @@ -13,6 +13,12 @@ AgentFormation has three important trust levels: any runtime. AgentFormation does not claim to protect runtime data from the AWS account owner. +Permission to update an AgentFormation CloudFormation stack is administrative +access to that deployment. Stack parameters select trusted roles, tables, +secrets, images, and runtime resources, so operators should limit stack updates +to the same dedicated deployers they trust with the underlying AWS resources. +An optional `cloudFormationRoleArn` limits what CloudFormation can create; it +does not make an untrusted `UpdateStack` caller safe. ## Company sign-in @@ -53,13 +59,33 @@ For every terminal or upload request, the server: 5. targets only the instance in that record. The client never submits an instance ID. Runtime IDs are not returned by the -session-start API. Browser termination requests also carry an HMAC proof that -binds the Systems Manager session ID to the signed-in subject. +session-start API. Browser resume and termination requests carry an expiring +HMAC proof that binds the Systems Manager session ID to both the signed-in +subject and the currently assigned runtime instance. The server consistently +re-reads that assignment immediately before each privileged runtime action. + +Systems Manager returns a short-lived token and regional WebSocket address so a +Session Manager client can open the data channel. AgentFormation passes those +values to the signed-in browser, validates that the address is the expected +regional `ssmmessages` host and session path, and limits the Content Security +Policy to that AWS endpoint. The browser never receives the EC2 role credentials. State-changing environment, terminal, upload, and OAuth-relay routes accept only -same-origin JSON requests. Their success and error responses disable browser and -intermediary caching. The web app uses a new script nonce for every request instead -of allowing arbitrary inline scripts in its Content Security Policy. +same-origin JSON requests. They authenticate before parsing a body and stop +reading JSON after a small fixed limit. Their success and error responses disable +browser and intermediary caching. The web app uses a new script nonce for every +request instead of allowing arbitrary inline scripts in its Content Security +Policy. + +A second, short-lived DynamoDB table holds atomic request counters, in-flight +operation leases, termination deduplication records, and upload-completion +claims. Because all App Runner instances use the same table, switching instances +or restarting the service does not reset these controls. Limits are per federated +subject: environment creation is capped at four starts per hour; upload staging +is capped at 60 files and 2 GiB per hour; terminal and relay calls have narrower +minute or hourly limits. One privileged operation of the same kind is allowed in +flight for a subject and resource at a time. Expiring records are removed by +DynamoDB TTL. The OAuth relay exists for command-line tools that listen for a one-time callback inside the private runtime. It accepts only plain HTTP URLs whose host is exactly @@ -76,11 +102,31 @@ object with its own restricted role, stores it in a private temporary file, and removes that file after the request. The web service deletes the staging object after the command; the bucket lifecycle is a cleanup backstop. +The web role cannot use the general-purpose `AWS-RunShellScript` document. +Uploads and OAuth callbacks each use a separate, deployment-owned command +document whose parameters have strict character patterns and are exposed to the +script only as environment variables. The documents contain fixed commands, +and every callback and upload operation runs as the unprivileged +`agentformation` user. This keeps a web-service compromise from turning the +file-transfer path into an arbitrary root command. + +Browser file uploads use a one-key presigned POST whose policy enforces a 50 MiB +write limit. Before returning that policy, the server records the exact subject, +runtime, key, filename, content type, and size. Completion atomically claims that +record once, copies the matching object generation to a server-owned sealed key, +revalidates the runtime assignment, and only then asks the runtime to download +it. The runtime downloads to a private temporary filename, verifies the byte +count, and atomically renames the complete file into its visible destination. +If command completion cannot be confirmed, the upload claim stays in its +in-progress state until its TTL; that claim, rather than the shorter request +lease, prevents a duplicate delivery while the command may still be running. + ## Self-service environment creation A signed-in employee can ask the App Runner service to start one fixed Step -Functions job. The web role can start that exact job; it cannot call -CloudFormation itself. +Functions job. The web role can start that exact job and read the safe status +fields from events for the authenticated subject's deterministic runtime stack; +it cannot create, update, or delete CloudFormation stacks. The job: @@ -92,7 +138,17 @@ The job: hash; 5. supplies network, AMI, instance size, volume, model, and upload settings chosen by the operator during deployment; and -6. records the resulting tagged EC2 instance only after CloudFormation succeeds. +6. polls CloudFormation and instance discovery for bounded periods; +7. confirms the federated user is still enabled immediately before activation; +8. records the resulting tagged EC2 instance only after CloudFormation succeeds; + and +9. deletes a failed or superseded runtime stack before making a clean retry + available. + +The active runtime template remains stored under its content hash for as long as +the deployment uses it. After a successful update, older template hashes receive +a superseded tag and a fresh 30-day retirement window so both stable deployments +and already-running setup jobs keep a valid template. A separate CloudFormation service role can create only the named AgentFormation runtime IAM roles, the operator-selected AMI/network dependencies, and tagged @@ -100,8 +156,12 @@ runtime instances. The setup job cannot accept a browser-provided template URL, AMI, subnet, security group, IAM policy, model, or instance size. The DynamoDB conditional write makes repeated button presses idempotent: an active -or in-progress employee record is not replaced. A failed setup can be retried -using the same reviewed stack name. +or current in-progress employee record is not replaced. A failed setup is +eligible for immediate retry after cleanup. A setup still marked as provisioning +becomes retryable after 100 minutes, beyond the workflow's 90-minute hard timeout. +Every retry is reconciled against the deterministic stack before the same +reviewed stack name is reused, and activation/failure writes must still match the +exact reservation start time. ## Network and host controls @@ -112,10 +172,25 @@ using the same reviewed stack name. - Runtime EBS volumes and staged uploads are encrypted at rest. - The upload bucket rejects requests that do not use HTTPS. - Upload objects expire after one day and are deleted after they reach a runtime. +- Full teardown removes the web service first, stops and confirms every running + provisioning job, removes the setup state machine, and only then enumerates + runtime stacks. It also cancels active image builds and removes deployment-tagged + AMIs and snapshots before deleting the image pipeline. Teardown temporarily + blocks all writes to the staging bucket while every current object, version, + and delete marker is removed. If teardown stops before the foundation stack is + deleted, the sanitized original bucket policy is restored. - The default network uses one NAT gateway. Optional AWS service endpoints reduce some traffic through that gateway but do not remove the need for internet access to Git hosts, package registries, and similar developer services. +Runtime internet access is intentional: a general coding environment needs to +reach source hosts, package registries, and the APIs its owner chooses to use. +The runtime security group therefore allows outbound traffic while allowing no +inbound connections. Organizations that require destination filtering should add +their normal egress proxy, DNS policy, or network firewall and allow the developer +services they support; the reference template cannot guess a safe universal host +allowlist. + ## Credentials and model access The runtime uses its EC2 instance role. Long-lived AWS access keys are not placed @@ -137,35 +212,73 @@ broader AWS-managed policy. Bedrock access, provider terms, quotas, and regional model availability are controlled separately by AWS. -The runtime image pins the AWS CLI, Claude Code, and Codex versions. The AWS and -Codex installer scripts are checksum-checked before execution. AWS's installer +The runtime image pins the AWS CLI, Node.js, Bun, Claude Code, and Codex versions. +The AWS, Node.js, Bun, and Codex downloads are checksum-checked before execution. +AWS's installer then verifies the AWS CLI package signature with its embedded AWS CLI team key; the Codex installer verifies the selected release archive digest. +The App Runner image is pushed to the foundation stack's ECR repository, read +back from ECR by digest, and deployed with that immutable digest rather than a +mutable tag. The deploy command rejects a repository outside the current AWS +account and Region. + +The Image Builder parent identifier deliberately follows AWS's `x.x.x` form for +the selected Ubuntu LTS stream so a newly built image receives AWS's current +patched base. Every completed AMI is immutable, recorded by ID, and used only for +environments created from that reviewed build. Operators who need a frozen base +version can pin the parent identifier, but then take responsibility for advancing +it when AWS publishes security updates. + ## User lifecycle - Assigning an Identity Center group allows its members to sign in. Each member can create one runtime from the fixed setup job. -- `users disable` disables the federated Cognito profile, marks the registry record - disabled, and stops EC2 while preserving its encrypted disk. +- `users disable` disables the federated Cognito profile, requests Cognito's + global token revocation, moves any registry record to a non-active state, + terminates active Session Manager connections, and stops EC2 while preserving + its encrypted disk. - `users enable` starts the preserved instance, re-enables the profile, and restores the active registry record. -- `users purge --confirm DELETE` deletes the federated profile, CloudFormation - runtime, and persistent disk. +- `users purge --confirm DELETE` first revokes live access and stops matching + provisioning, then places a conditional purge lock on the exact disabled + registry record. Re-enable refuses that lock. Purge rechecks Cognito before it + deletes every runtime stack tagged for that deployment and subject, its + persistent disk, and the federated profile. Before any deletion, a re-enabled + profile aborts purge and releases the exact lock. After profile deletion, the + locked row is atomically replaced with a privacy-minimal `purged` marker that + contains only the subject, status, update time, and DynamoDB expiry time. The + marker remains for two hours. Every Auth.js token refresh checks that marker + and clears a revoked session; a browser that never refreshes expires within + one hour. Old browser sessions therefore cannot outlive the marker or create + another runtime before DynamoDB expires it. Remove the Identity Center application or group assignment as the source-of-truth offboarding step. If an assigned employee is purged but remains assigned, their next valid company sign-in can create a new federated profile and runtime. -An already-open Systems Manager terminal may remain usable briefly while disable -or group removal propagates. Use `users disable` and terminate active Systems -Manager sessions when immediate eviction is required. +Signing out of AgentFormation clears the app session and that browser's saved tab +metadata. It intentionally does not sign the person out of IAM Identity Center, +because that organization-wide session may also be serving other company apps. +As a result, signing back in can be immediate while the Identity Center session +is still valid. AgentFormation app sessions expire after one hour. + +Group removal prevents the next federation but cannot recall an already-issued +application session by itself. Use `users disable` for immediate app-side +revocation: it disables the Cognito profile, requests Cognito's global token +revocation, and changes the runtime registry so every new privileged request +fails even if an already-issued app session has not expired. It also stops an +in-progress setup and the EC2 instance. An already-open Systems Manager data +channel can remain usable only until the instance stop or session termination +reaches it. ## Compromise scope The App Runner role can start the fixed setup job for an enabled federated subject and can manage terminal sessions and staged uploads across all tagged runtimes in -this deployment. A compromise of the service role or server application can +this deployment. Its shared request-control table protects AWS capacity from an +abusive signed-in caller, but it is not a boundary against compromise of the web +role itself. A compromise of the service role or server application can therefore affect every managed runtime. It still cannot submit an arbitrary CloudFormation template or choose more privileged runtime settings. diff --git a/scripts/check.sh b/scripts/check.sh index d2b592d..661e96f 100755 --- a/scripts/check.sh +++ b/scripts/check.sh @@ -18,12 +18,16 @@ AUTH_COGNITO_ID=build-client \ AUTH_COGNITO_SECRET=build-secret \ AUTH_COGNITO_IDENTITY_PROVIDER=IdentityCenter \ AUTH_COGNITO_ISSUER=https://cognito-idp.us-east-1.amazonaws.com/us-east-1_build \ +AUTH_URL=https://localhost \ AGENTFORMATION_DEPLOYMENT=agentformation \ PROVISIONING_STATE_MACHINE_ARN=arn:aws:states:us-east-1:000000000000:stateMachine:build-only \ AWS_REGION=us-east-1 \ USER_REGISTRY_TABLE=build-users \ +CONTROL_TABLE=build-control \ UPLOAD_BUCKET=build-uploads \ SESSION_DOCUMENT_NAME=build-terminal \ +UPLOAD_DELIVERY_DOCUMENT_NAME=build-upload-delivery \ +OAUTH_RELAY_DOCUMENT_NAME=build-oauth-relay \ bun run build cd "$ROOT_DIR" diff --git a/scripts/deploy.sh b/scripts/deploy.sh index 92d5d34..24d04c9 100755 --- a/scripts/deploy.sh +++ b/scripts/deploy.sh @@ -14,22 +14,23 @@ DEPLOYMENT="$(deployment_name)" ACCOUNT_ID="$(aws_cli sts get-caller-identity --query Account --output text)" CALLER_ARN="$(aws_cli sts get-caller-identity --query Arn --output text)" AWS_PARTITION="$(cut -d: -f2 <<<"$CALLER_ARN")" -if [[ "$AWS_PARTITION" == "aws-cn" ]]; then - AWS_URL_SUFFIX="amazonaws.com.cn" -else - AWS_URL_SUFFIX="amazonaws.com" -fi DOMAIN_SUFFIX="$(hash_text "$ACCOUNT_ID:$DEPLOYMENT" | cut -c1-10)" DOMAIN_PREFIX="$DEPLOYMENT-$DOMAIN_SUFFIX" IDENTITY_CENTER_METADATA_URL="$(config '.identityCenter.metadataUrl // ""')" IDENTITY_CENTER_METADATA_FILE="$(config '.identityCenter.metadataFile // ""')" CONFIGURED_PUBLIC_URL="$(config '(.publicUrl // "") | rtrimstr("/")')" + +if [[ -n "$CONFIGURED_PUBLIC_URL" ]]; then + require_https_origin "publicUrl" "$CONFIGURED_PUBLIC_URL" +fi if [[ -n "$IDENTITY_CENTER_METADATA_FILE" && "$IDENTITY_CENTER_METADATA_FILE" != /* ]]; then IDENTITY_CENTER_METADATA_FILE="$ROOT_DIR/$IDENTITY_CENTER_METADATA_FILE" fi CONFIGURE_CASE_INSENSITIVE_USERNAMES=true -if aws_cli cloudformation describe-stacks --stack-name "$(foundation_stack)" >/dev/null 2>&1; then +FOUNDATION_EXISTS=false +if stack_exists "$(foundation_stack)"; then + FOUNDATION_EXISTS=true EXISTING_USER_POOL_ID="$(stack_output "$(foundation_stack)" UserPoolId)" EXISTING_USERNAME_CASE_SENSITIVE="$(aws_cli cognito-idp describe-user-pool \ --user-pool-id "$EXISTING_USER_POOL_ID" \ @@ -47,7 +48,10 @@ if aws_cli cloudformation describe-stacks --stack-name "$(foundation_stack)" >/d *) fail "Could not determine the existing Cognito username case-sensitivity setting" ;; - esac + esac +else + stack_status=$? + [[ "$stack_status" -eq 1 ]] || exit "$stack_status" fi print_identity_center_setup() { @@ -59,7 +63,8 @@ print_identity_center_setup() { acs_url="$(jq -r '[.[] | select(.OutputKey == "CognitoSamlAcsUrl") | .OutputValue][0] // ""' <<<"$outputs")" audience="$(jq -r '[.[] | select(.OutputKey == "CognitoSamlAudience") | .OutputValue][0] // ""' <<<"$outputs")" if [[ ! "$acs_url" =~ ^https:// ]] || [[ "$audience" != urn:amazon:cognito:sp:* ]]; then - user_pool_id="$(jq -er '[.[] | select(.OutputKey == "UserPoolId") | .OutputValue][0]' <<<"$outputs")" + user_pool_id="$(jq -r '[.[] | select(.OutputKey == "UserPoolId") | .OutputValue][0] // ""' <<<"$outputs")" + [[ -n "$user_pool_id" ]] || fail "The foundation stack did not return the Cognito user pool ID" if [[ "$AWS_PARTITION" == "aws-cn" ]]; then cognito_domain_suffix="amazoncognito.com.cn" else @@ -72,8 +77,7 @@ print_identity_center_setup() { say "SAML audience: $audience" } -if [[ -z "$IDENTITY_CENTER_METADATA_URL" && -z "$IDENTITY_CENTER_METADATA_FILE" ]] && \ - aws_cli cloudformation describe-stacks --stack-name "$(foundation_stack)" >/dev/null 2>&1; then +if [[ -z "$IDENTITY_CENTER_METADATA_URL" && -z "$IDENTITY_CENTER_METADATA_FILE" && "$FOUNDATION_EXISTS" == "true" ]]; then say "Identity Center setup is required before this existing deployment can be updated" print_identity_center_setup fail "Assign an IAM Identity Center group to a custom SAML application, then set identityCenter.metadataUrl (preferred) or identityCenter.metadataFile" @@ -83,10 +87,38 @@ deploy_stack "$(network_stack)" templates/network.yaml \ DeploymentName="$DEPLOYMENT" \ NetworkMode="$(config '.networkMode')" -deploy_stack "$(foundation_stack)" templates/foundation.yaml \ - DeploymentName="$DEPLOYMENT" \ - CognitoDomainPrefix="$DOMAIN_PREFIX" \ - ConfigureCaseInsensitiveUsernames="$CONFIGURE_CASE_INSENSITIVE_USERNAMES" +INITIAL_PUBLIC_URL="$CONFIGURED_PUBLIC_URL" +if [[ -z "$INITIAL_PUBLIC_URL" ]]; then + if stack_exists "$(web_stack)"; then + INITIAL_PUBLIC_URL="$(stack_output "$(web_stack)" ServiceUrl)" + require_https_origin "The existing web service URL" "$INITIAL_PUBLIC_URL" + else + stack_status=$? + [[ "$stack_status" -eq 1 ]] || exit "$stack_status" + # A localhost callback exists only long enough to bootstrap a genuinely new + # deployment. Read failures on an existing web stack must stop the deploy. + INITIAL_PUBLIC_URL="https://localhost" + fi +fi + +deploy_foundation_stack() { + local configure_identity_center="$1" + local public_url="$2" + deploy_stack "$(foundation_stack)" templates/foundation.yaml \ + DeploymentName="$DEPLOYMENT" \ + CognitoDomainPrefix="$DOMAIN_PREFIX" \ + ConfigureCaseInsensitiveUsernames="$CONFIGURE_CASE_INSENSITIVE_USERNAMES" \ + ConfigureIdentityCenterClient="$configure_identity_center" \ + InitialCallbackUrl="$public_url/api/auth/callback/cognito" \ + InitialLogoutUrl="$public_url/" \ + UploadAllowedOrigin="$public_url" +} + +if [[ "$FOUNDATION_EXISTS" == "false" ]]; then + # The user pool must exist before IAM Identity Center can be configured. The + # bootstrap stack has no app client, so local Cognito login is never exposed. + deploy_foundation_stack false "$INITIAL_PUBLIC_URL" +fi if [[ -z "$IDENTITY_CENTER_METADATA_URL" && -z "$IDENTITY_CENTER_METADATA_FILE" ]]; then say "The identity bootstrap is ready" @@ -96,41 +128,6 @@ if [[ -z "$IDENTITY_CENTER_METADATA_URL" && -z "$IDENTITY_CENTER_METADATA_FILE" fi USER_POOL_ID="$(stack_output "$(foundation_stack)" UserPoolId)" -CLIENT_ID="$(stack_output "$(foundation_stack)" UserPoolClientId)" -CLIENT_SECRET_ARN="$(stack_output "$(foundation_stack)" CognitoClientSecretArn)" - -configure_cognito_client() { - local callback_urls_json="$1" - local logout_urls_json="$2" - local url - local -a callback_urls=() - local -a logout_urls=() - while IFS= read -r url; do - [[ -n "$url" ]] && callback_urls+=("$url") - done < <(jq -r '.[]' <<<"$callback_urls_json") - while IFS= read -r url; do - [[ -n "$url" ]] && logout_urls+=("$url") - done < <(jq -r '.[]' <<<"$logout_urls_json") - [[ "${#callback_urls[@]}" -gt 0 && "${#logout_urls[@]}" -gt 0 ]] || \ - fail "Cognito callback and logout URLs cannot be empty" - - aws_cli cognito-idp update-user-pool-client \ - --user-pool-id "$USER_POOL_ID" \ - --client-id "$CLIENT_ID" \ - --supported-identity-providers IdentityCenter \ - --explicit-auth-flows ALLOW_REFRESH_TOKEN_AUTH \ - --allowed-o-auth-flows code \ - --allowed-o-auth-scopes openid email profile \ - --allowed-o-auth-flows-user-pool-client \ - --callback-urls "${callback_urls[@]}" \ - --logout-urls "${logout_urls[@]}" \ - --prevent-user-existence-errors ENABLED \ - --enable-token-revocation \ - --access-token-validity 60 \ - --id-token-validity 60 \ - --refresh-token-validity 1 \ - --token-validity-units AccessToken=minutes,IdToken=minutes,RefreshToken=days >/dev/null -} say "Connecting the Cognito bridge to IAM Identity Center" if [[ -n "$IDENTITY_CENTER_METADATA_URL" ]]; then @@ -161,14 +158,16 @@ else --idp-identifiers identity-center >/dev/null fi -CURRENT_CLIENT_URLS="$(aws_cli cognito-idp describe-user-pool-client \ - --user-pool-id "$USER_POOL_ID" \ - --client-id "$CLIENT_ID" \ - --query 'UserPoolClient.{callbacks:CallbackURLs,logouts:LogoutURLs}' \ - --output json)" -configure_cognito_client \ - "$(jq -c '.callbacks' <<<"$CURRENT_CLIENT_URLS")" \ - "$(jq -c '.logouts' <<<"$CURRENT_CLIENT_URLS")" +deploy_foundation_stack true "$INITIAL_PUBLIC_URL" +CLIENT_ID="$(stack_output "$(foundation_stack)" UserPoolClientId)" +CLIENT_SECRET_ARN="$(stack_output "$(foundation_stack)" CognitoClientSecretArn)" +AUTH_SECRET_ARN="$(stack_output "$(foundation_stack)" AuthSecretArn)" +USER_REGISTRY_TABLE_NAME="$(stack_output "$(foundation_stack)" UserRegistryTableName)" +CONTROL_TABLE_NAME="$(stack_output "$(foundation_stack)" ControlTableName)" +UPLOAD_BUCKET="$(stack_output "$(foundation_stack)" UploadBucketName)" +TERMINAL_SESSION_DOCUMENT_NAME="$(stack_output "$(foundation_stack)" TerminalSessionDocumentName)" +UPLOAD_DELIVERY_DOCUMENT_NAME="$(stack_output "$(foundation_stack)" UploadDeliveryDocumentName)" +OAUTH_RELAY_DOCUMENT_NAME="$(stack_output "$(foundation_stack)" OAuthRelayDocumentName)" say "Storing the generated Cognito client secret without printing it" aws_cli cognito-idp describe-user-pool-client \ @@ -244,26 +243,80 @@ else say "Reusing the latest tested AMI from the current image pipeline" fi -AMI_ID="$(aws_cli imagebuilder get-image \ - --image-build-version-arn "$IMAGE_ARN" \ - --query 'image.outputResources.amis[0].image' \ - --output text)" -[[ "$AMI_ID" =~ ^ami-[0-9a-f]+$ ]] || fail "Image Builder did not return an AMI ID" +BUILT_IMAGE="$(aws_cli imagebuilder get-image \ + --image-build-version-arn "$IMAGE_ARN" \ + --output json)" +jq -e --arg region "$(region)" --arg account "$ACCOUNT_ID" ' + (.image.outputResources.amis | type == "array" and length > 0) and + all(.image.outputResources.amis[]; + .region == $region and .accountId == $account and + (.image | test("^ami-([0-9a-f]{8}|[0-9a-f]{17})$"))) +' <<<"$BUILT_IMAGE" >/dev/null || fail "Image Builder returned an AMI outside this AWS account and region" +AMI_ID="$(jq -er --arg region "$(region)" ' + [.image.outputResources.amis[] | select(.region == $region) | .image] | first +' <<<"$BUILT_IMAGE")" +[[ "$AMI_ID" =~ ^ami-([0-9a-f]{8}|[0-9a-f]{17})$ ]] || fail "Image Builder did not return an AMI ID" +AMI_DESCRIPTION="$(aws_cli ec2 describe-images --image-ids "$AMI_ID" --output json)" +AMI_SNAPSHOT_ID_LINES="$(jq -er '[.Images[]?.BlockDeviceMappings[]?.Ebs.SnapshotId] | unique | join("\n")' \ + <<<"$AMI_DESCRIPTION")" +while IFS= read -r snapshot_id; do + [[ -n "$snapshot_id" ]] || continue + [[ "$snapshot_id" =~ ^snap-([0-9a-f]{8}|[0-9a-f]{17})$ ]] || \ + fail "The built AMI returned an invalid snapshot ID" +done <<<"$AMI_SNAPSHOT_ID_LINES" + +tag_image_resource() { + local resource_id="$1" + local attempt=1 tag_result tag_error + while [[ "$attempt" -le 30 ]]; do + if tag_error="$(aws_cli ec2 create-tags \ + --resources "$resource_id" \ + --tags "Key=AgentFormationDeployment,Value=$DEPLOYMENT" 2>&1)"; then + if tag_result="$(aws_cli ec2 describe-tags \ + --filters \ + "Name=resource-id,Values=$resource_id" \ + "Name=key,Values=AgentFormationDeployment" \ + --output json 2>&1)" && \ + jq -e --arg resource "$resource_id" --arg deployment "$DEPLOYMENT" ' + any(.Tags[]?; + .ResourceId == $resource and + .Key == "AgentFormationDeployment" and + .Value == $deployment) + ' <<<"$tag_result" >/dev/null; then + return 0 + fi + fi + [[ "$attempt" -lt 30 ]] || { + printf '%s\n' "${tag_error:-${tag_result:-EC2 did not confirm the resource tag}}" >&2 + fail "The built AMI or snapshot could not be tagged for teardown" + } + sleep 2 + attempt=$((attempt + 1)) + done +} + +say "Tagging the built AMI and snapshots for complete teardown" +tag_image_resource "$AMI_ID" +while IFS= read -r snapshot_id; do + [[ -n "$snapshot_id" ]] || continue + tag_image_resource "$snapshot_id" +done <<<"$AMI_SNAPSHOT_ID_LINES" aws_cli ssm put-parameter \ --name "$(ami_parameter_path)" \ --type String \ --value "$AMI_ID" \ --overwrite >/dev/null -UPLOAD_BUCKET="$(stack_output "$(foundation_stack)" UploadBucketName)" RUNTIME_TEMPLATE_HASH="$(hash_text "$(<"$ROOT_DIR/templates/runtime.yaml")")" RUNTIME_TEMPLATE_KEY="provisioning/runtime-$RUNTIME_TEMPLATE_HASH.yaml" -RUNTIME_TEMPLATE_URL="https://$UPLOAD_BUCKET.s3.$(region).$AWS_URL_SUFFIX/$RUNTIME_TEMPLATE_KEY" say "Publishing the reviewed runtime template under its content hash" -aws_cli s3 cp \ - "$ROOT_DIR/templates/runtime.yaml" \ - "s3://$UPLOAD_BUCKET/$RUNTIME_TEMPLATE_KEY" \ - --sse AES256 >/dev/null +aws_cli s3api put-object \ + --bucket "$UPLOAD_BUCKET" \ + --key "$RUNTIME_TEMPLATE_KEY" \ + --body "$ROOT_DIR/templates/runtime.yaml" \ + --server-side-encryption AES256 \ + --tagging 'agentformation-lifecycle=current' \ + --expected-bucket-owner "$ACCOUNT_ID" >/dev/null CLAUDE_MODEL="$(config '.models.claude')" CLAUDE_PROFILE="$(aws_cli bedrock get-inference-profile \ @@ -271,16 +324,17 @@ CLAUDE_PROFILE="$(aws_cli bedrock get-inference-profile \ --output json)" || fail "The configured Claude inference profile is unavailable" CLAUDE_PROFILE_ARN="$(jq -er '.inferenceProfileArn' <<<"$CLAUDE_PROFILE")" CLAUDE_MODEL_ARNS="$(jq -er '[.models[].modelArn] | select(length > 0) | join(",")' <<<"$CLAUDE_PROFILE")" +RUNTIME_SUBNET_ID="$(stack_output "$(network_stack)" PrivateSubnetId)" +RUNTIME_SECURITY_GROUP_ID="$(stack_output "$(network_stack)" RuntimeSecurityGroupId)" deploy_stack "$(provisioning_stack)" templates/provisioning.yaml \ DeploymentName="$DEPLOYMENT" \ UserPoolId="$USER_POOL_ID" \ - UserRegistryTableName="$(stack_output "$(foundation_stack)" UserRegistryTableName)" \ - RuntimeTemplateUrl="$RUNTIME_TEMPLATE_URL" \ + UserRegistryTableName="$USER_REGISTRY_TABLE_NAME" \ RuntimeTemplateBucket="$UPLOAD_BUCKET" \ RuntimeTemplateKey="$RUNTIME_TEMPLATE_KEY" \ - RuntimeSubnetId="$(stack_output "$(network_stack)" PrivateSubnetId)" \ - RuntimeSecurityGroupId="$(stack_output "$(network_stack)" RuntimeSecurityGroupId)" \ + RuntimeSubnetId="$RUNTIME_SUBNET_ID" \ + RuntimeSecurityGroupId="$RUNTIME_SECURITY_GROUP_ID" \ RuntimeAmiId="$AMI_ID" \ InstanceType="$(config '.runtime.instanceType')" \ Architecture="$ARCHITECTURE" \ @@ -290,8 +344,73 @@ deploy_stack "$(provisioning_stack)" templates/provisioning.yaml \ ClaudeFoundationModelArns="$CLAUDE_MODEL_ARNS" \ CodexModelId="$(config '.models.codex')" \ UploadBucketName="$UPLOAD_BUCKET" +PROVISIONING_STATE_MACHINE_ARN="$(stack_output "$(provisioning_stack)" StateMachineArn)" + +retire_superseded_runtime_templates() { + local provisioning_template_keys parsed_template_keys template_key template_tags + say "Retiring superseded runtime templates without touching the live template" + if ! provisioning_template_keys="$(aws_cli s3api list-objects-v2 \ + --bucket "$UPLOAD_BUCKET" \ + --prefix provisioning/ \ + --expected-bucket-owner "$ACCOUNT_ID" \ + --query 'Contents[].Key' \ + --output json)"; then + printf 'WARNING: Superseded runtime templates could not be listed; deployment remains ready.\n' >&2 + return 0 + fi + if ! parsed_template_keys="$(jq -er '(. // []) | map(select(type == "string")) | join("\n")' \ + <<<"$provisioning_template_keys")"; then + printf 'WARNING: Superseded runtime template results could not be read; deployment remains ready.\n' >&2 + return 0 + fi + + while IFS= read -r template_key; do + [[ -n "$template_key" ]] || continue + if [[ ! "$template_key" =~ ^provisioning/runtime-[0-9a-f]{64}\.yaml$ ]]; then + printf 'WARNING: Skipping an unexpected object under the provisioning prefix.\n' >&2 + continue + fi + [[ "$template_key" == "$RUNTIME_TEMPLATE_KEY" ]] && continue + if ! template_tags="$(aws_cli s3api get-object-tagging \ + --bucket "$UPLOAD_BUCKET" \ + --key "$template_key" \ + --expected-bucket-owner "$ACCOUNT_ID" \ + --query TagSet \ + --output json)"; then + printf 'WARNING: A superseded runtime template could not be inspected; continuing.\n' >&2 + continue + fi + if jq -e 'any(.[]; .Key == "agentformation-lifecycle" and .Value == "superseded")' \ + <<<"$template_tags" >/dev/null; then + continue + fi + # The self-copy applies the retirement tag, resets its expiry window, and + # deliberately replaces irrelevant object metadata on this YAML object. + if ! aws_cli s3api copy-object \ + --bucket "$UPLOAD_BUCKET" \ + --key "$template_key" \ + --copy-source "$UPLOAD_BUCKET/$template_key" \ + --metadata-directive REPLACE \ + --tagging-directive REPLACE \ + --tagging 'agentformation-lifecycle=superseded' \ + --server-side-encryption AES256 \ + --expected-bucket-owner "$ACCOUNT_ID" \ + --expected-source-bucket-owner "$ACCOUNT_ID" >/dev/null; then + printf 'WARNING: A superseded runtime template could not be retired; continuing.\n' >&2 + fi + done <<<"$parsed_template_keys" +} REPOSITORY_URI="$(stack_output "$(foundation_stack)" WebRepositoryUri)" +REPOSITORY_NAME="$(stack_output "$(foundation_stack)" WebRepositoryName)" +if [[ "$AWS_PARTITION" == "aws-cn" ]]; then + ECR_URL_SUFFIX="amazonaws.com.cn" +else + ECR_URL_SUFFIX="amazonaws.com" +fi +EXPECTED_REPOSITORY_URI="$ACCOUNT_ID.dkr.ecr.$(region).$ECR_URL_SUFFIX/$REPOSITORY_NAME" +[[ "$REPOSITORY_URI" == "$EXPECTED_REPOSITORY_URI" ]] || \ + fail "The foundation stack returned a web repository outside this account or region" IMAGE_TAG="$(date -u +%Y%m%d%H%M%S)" REGISTRY_HOST="${REPOSITORY_URI%%/*}" DOCKER_CONFIG_DIR="$STATE_DIR/docker" @@ -346,59 +465,51 @@ DOCKER_HOST="$DOCKER_ENDPOINT" docker --config "$DOCKER_CONFIG_DIR" buildx build cleanup_docker_auth trap - EXIT +WEB_IMAGE_DIGEST="$(aws_cli ecr describe-images \ + --repository-name "$REPOSITORY_NAME" \ + --image-ids "imageTag=$IMAGE_TAG" \ + --query 'imageDetails[0].imageDigest' \ + --output text)" +[[ "$WEB_IMAGE_DIGEST" =~ ^sha256:[a-f0-9]{64}$ ]] || \ + fail "ECR did not return a valid digest for the web image" +WEB_IMAGE_IDENTIFIER="$REPOSITORY_URI@$WEB_IMAGE_DIGEST" + deploy_web_stack() { local public_url="$1" deploy_stack "$(web_stack)" templates/web.yaml \ DeploymentName="$DEPLOYMENT" \ - ImageIdentifier="$REPOSITORY_URI:$IMAGE_TAG" \ + ImageIdentifier="$WEB_IMAGE_IDENTIFIER" \ PublicUrl="$public_url" \ UserPoolClientId="$CLIENT_ID" \ - CognitoIssuer="$(stack_output "$(foundation_stack)" CognitoIssuer)" \ + UserPoolId="$USER_POOL_ID" \ CognitoClientSecretArn="$CLIENT_SECRET_ARN" \ - AuthSecretArn="$(stack_output "$(foundation_stack)" AuthSecretArn)" \ - UserRegistryTableName="$(stack_output "$(foundation_stack)" UserRegistryTableName)" \ - UploadBucketName="$(stack_output "$(foundation_stack)" UploadBucketName)" \ - TerminalSessionDocumentName="$(stack_output "$(foundation_stack)" TerminalSessionDocumentName)" \ - ProvisioningStateMachineArn="$(stack_output "$(provisioning_stack)" StateMachineArn)" + AuthSecretArn="$AUTH_SECRET_ARN" \ + UserRegistryTableName="$USER_REGISTRY_TABLE_NAME" \ + ControlTableName="$CONTROL_TABLE_NAME" \ + UploadBucketName="$UPLOAD_BUCKET" \ + TerminalSessionDocumentName="$TERMINAL_SESSION_DOCUMENT_NAME" \ + UploadDeliveryDocumentName="$UPLOAD_DELIVERY_DOCUMENT_NAME" \ + OAuthRelayDocumentName="$OAUTH_RELAY_DOCUMENT_NAME" \ + ProvisioningStateMachineArn="$PROVISIONING_STATE_MACHINE_ARN" } -INITIAL_PUBLIC_URL="$CONFIGURED_PUBLIC_URL" -if [[ -z "$INITIAL_PUBLIC_URL" ]]; then - INITIAL_PUBLIC_URL="$(stack_output "$(web_stack)" ServiceUrl 2>/dev/null || true)" -fi -if [[ ! "$INITIAL_PUBLIC_URL" =~ ^https?:// ]]; then - INITIAL_PUBLIC_URL='http://localhost:3000' -fi deploy_web_stack "$INITIAL_PUBLIC_URL" SERVICE_URL="$(stack_output "$(web_stack)" ServiceUrl)" +require_https_origin "The deployed web service URL" "$SERVICE_URL" PUBLIC_URL="${CONFIGURED_PUBLIC_URL:-$SERVICE_URL}" +require_https_origin "The final public URL" "$PUBLIC_URL" if [[ "$INITIAL_PUBLIC_URL" != "$PUBLIC_URL" ]]; then say "Applying the final public address to Auth.js" deploy_web_stack "$PUBLIC_URL" fi say "Updating Cognito callback URLs for the public web address" -configure_cognito_client \ - "$(jq -cn --arg publicUrl "$PUBLIC_URL" '[($publicUrl + "/api/auth/callback/cognito")]')" \ - "$(jq -cn --arg publicUrl "$PUBLIC_URL" '[($publicUrl + "/")]')" - -say "Restricting browser uploads to the deployed web address" -UPLOAD_CORS_CONFIGURATION="$(jq -cn --arg publicUrl "$PUBLIC_URL" '{ - CORSRules: [{ - AllowedHeaders: ["content-type"], - AllowedMethods: ["PUT"], - AllowedOrigins: [$publicUrl], - ExposeHeaders: ["ETag"], - MaxAgeSeconds: 300 - }] -}')" -aws_cli s3api put-bucket-cors \ - --bucket "$(stack_output "$(foundation_stack)" UploadBucketName)" \ - --cors-configuration "$UPLOAD_CORS_CONFIGURATION" +deploy_foundation_stack true "$PUBLIC_URL" cat >"$STATE_DIR/deployment.json" <@@ -70,23 +71,12 @@ export default async function Home() {
- Create a fresh tmux session, or reopen one of your 20 most - recently closed tabs. + Create a fresh tmux session, or reopen a recently closed tab. Up + to {MAX_TERMINAL_TABS} tabs can be open at once.
- Seeing 127.0.0.1 refused to connect is - expected: the login listener is inside your private runtime, not - on this device. -
-