Harden runtime boundaries and failure handling

.github/workflows/checks.yml

@@ -45,38 +45,50 @@ jobs:
       - run: bun run test
       - run: bun run build
         env:
+          AGENTFORMATION_DEPLOYMENT: agentformation
+          AUTH_URL: https://localhost
           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_SECRET: build-only-secret-with-at-least-32-characters
           AWS_REGION: us-east-1
+          CONTROL_TABLE: build-control
+          PROVISIONING_STATE_MACHINE_ARN: arn:aws:states:us-east-1:000000000000:stateMachine:build-only
           USER_REGISTRY_TABLE: build-users
           UPLOAD_BUCKET: build-uploads
           SESSION_DOCUMENT_NAME: build-terminal
+          UPLOAD_DELIVERY_DOCUMENT_NAME: build-upload-delivery
+          OAUTH_RELAY_DOCUMENT_NAME: build-oauth-relay
       - name: Build and smoke-test the production container
         run: |
           docker build --tag agentformation-web:test .
           docker run --detach --rm \
             --name agentformation-web-test \
             --publish 127.0.0.1:3000:3000 \
             --env HOSTNAME=container-internal \
-            --env AUTH_URL=http://localhost:3000 \
+            --env AGENTFORMATION_DEPLOYMENT=agentformation \
+            --env AUTH_URL=https://localhost \
             --env AUTH_TRUST_HOST=true \
             --env AUTH_COGNITO_ID=container-client \
             --env AUTH_COGNITO_SECRET=container-secret \
             --env AUTH_COGNITO_IDENTITY_PROVIDER=IdentityCenter \
             --env AUTH_COGNITO_ISSUER=https://cognito-idp.us-east-1.amazonaws.com/us-east-1_container \
             --env AUTH_SECRET=container-only-secret-with-at-least-32-characters \
             --env AWS_REGION=us-east-1 \
+            --env CONTROL_TABLE=container-control \
+            --env PROVISIONING_STATE_MACHINE_ARN=arn:aws:states:us-east-1:000000000000:stateMachine:container-only \
             --env USER_REGISTRY_TABLE=container-users \
             --env UPLOAD_BUCKET=container-uploads \
             --env SESSION_DOCUMENT_NAME=container-terminal \
+            --env UPLOAD_DELIVERY_DOCUMENT_NAME=container-upload-delivery \
+            --env OAUTH_RELAY_DOCUMENT_NAME=container-oauth-relay \
             agentformation-web:test
           trap 'docker stop agentformation-web-test >/dev/null 2>&1 || true' EXIT
           for _ in {1..30}; do
             if curl --fail --silent --show-error http://127.0.0.1:3000/api/health | grep -F '"status":"ok"' && \
-              curl --fail --silent --show-error http://127.0.0.1:3000/ | grep -F AgentFormation; then
+              curl --fail --silent --show-error http://127.0.0.1:3000/ | grep -F AgentFormation && \
+              docker exec agentformation-web-test id -u | grep -Fx 1001; then
               exit 0
             fi
             sleep 2

README.md

@@ -2,14 +2,14 @@
 
 # AgentFormation
 
-**Spin up private, persistent EC2 workspaces for coding agents in your own AWS account.**
+**Spin up private, persistent EC2 workspaces for coding agents in your AWS org**
 
 <p>
   <a href="LICENSE"><img alt="License: BSD 2-Clause" src="https://img.shields.io/badge/license-BSD%202--Clause-3f3f46?style=flat-square"></a>
   <a href="SECURITY.md"><img alt="Security policy" src="https://img.shields.io/badge/security-policy-2f855a?style=flat-square"></a>
 </p>
 
-<p>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.</p>
+<p>Run CLI agent harnesses from a browser while the workspace stays on a private EC2 runtime with no public IP and no inbound SSH.</p>
 
 <p><a href="#quick-start">Quick start</a> · <a href="#architecture">Architecture</a> · <a href="#documentation">Documentation</a> · <a href="#security-model">Security</a> · <a href="CONTRIBUTING.md">Contributing</a></p>
 
@@ -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._

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

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.

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