AWS authentication

Chatticus does not create IAM users or mint long-lived IAM access keys. This is a hard control, not a preference. The organization is transitioning to AWS IAM Identity Center; every new path must use short-lived credentials from OIDC, sts:AssumeRole, or an Identity Center–compatible session.

Temporary access keys copied out of an AssumeRole or OIDC session response are allowed only as in-process forwarding (for example, SAM docker bundling or a one-shot shell script). Storing those values in GitHub Secrets, SSM, or Secrets Manager as a standing credential is forbidden. Creating new long-lived keys — including "temporary" keys left in place as a workaround — is forbidden.

Allowed patterns

Forbidden patterns

Do not add any of the following to this repository or to templates it publishes for Chatticus or customer accounts:

• iam:CreateAccessKey, CreateAccessKey, create_access_key, create-access-key
• CDK iam.AccessKey, CfnAccessKey, CloudFormation AWS::IAM::AccessKey
• Terraform aws_iam_access_key
• aws iam create-access-key (or create-user for standing operator access)
• GitHub Actions secrets AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY for deploy
• Scripts that mint keys and write them to disk, SSM, or Secrets Manager

Verify no minting remains

From the repository root:

rg -n 'CreateAccessKey|create_access_key|create-access-key|iam\.AccessKey|CfnAccessKey|aws_iam_access_key|AWS::IAM::AccessKey|iam:CreateAccessKey' \
  --glob '!**/node_modules/**' --glob '!**/.git/**' \
  --glob '!docs/AWS_AUTH.md' --glob '!infra/test/**'

rg -n 'secrets\.AWS_ACCESS_KEY_ID|secrets\.AWS_SECRET_ACCESS_KEY' .github/workflows/

Production paths must return no matches (exclude this policy doc and guard tests). CI enforces the same rules in infra/test/no-iam-access-keys.test.ts and infra/test/deploy-workflows.test.ts.

Legitimate AccessKeyId / AWS_ACCESS_KEY_ID references are limited to:

• STS AssumeRole response handling (conversation/src/computer/provisioning.ts, push-customer-computer-image.sh)
• Forwarding an existing OIDC session into docker (web-build-env.ts)
• Test fixtures and mocks (conversation/features-support/, conversation/test/)

Rotating the invoke key

The invoke key is one shared value: CloudFront presents it as the X-Chatticus-Invoke-Key origin header and the Front Door refuses every route but /health without it (the owner host token and the model gateway excepted). It is a Secrets Manager secret, not an AWS access key, and it is rotated by infra/rotate-invoke-key.sh.

Who holds the key and how they get it

Development has no customer-account host workers. In staging and production every running customer host worker is refused after the previous value is retired and must be restarted (end the computer and let the next turn start it, or re-provision); rotate during a quiet period and expect an interrupted computer turn for those organizations.

Runbook

Precondition: the Front Door and ComputerStarter that read AWSPREVIOUS are deployed (the Deploy Web (development) workflow deploys the control plane first), and aws login / aws sso login for the environment is current.

cd infra
sh rotate-invoke-key.sh development --dry-run      # read-only: steps and checks
sh rotate-invoke-key.sh development --yes          # rotate

What it does, in this order:

1. Refuses without an explicit environment and --yes; uses the profile chatticus-<environment> (CHATTICUS_AWS_PROFILE overrides); refuses a secret that is not in the session's account.
2. Read-only checks: CloudFront and Function URL /health answer 200, the Function URL refuses a keyless request with the invoke key gate, CloudFront passes the gate.
3. get-random-password (40 characters, no punctuation) held in memory, then put-secret-value through stdin. The old value becomes AWSPREVIOUS. The Front Door accepts both values from here on.
4. Waits 65 seconds so every warm Front Door has read the pair.
5. Redeploys the Web stack (development: gh workflow run "Deploy Web (development)" --ref develop and watches it; staging and production: deploy-chatticus-dedicated-account.sh <environment> web from the operator session), then waits for the distribution to be Deployed.
6. Compares the distribution's origin header with the AWSCURRENT value in memory (never printed). Only if equal does it go on.
7. Retires AWSPREVIOUS (update-secret-version-stage), waits 65 seconds and re-verifies the open and the protected routes.

If any step fails the script exits non-zero with the reason. Before step 7 nothing is down, because both values are still accepted. Fix the cause and run --resume --yes, which finishes steps 4 to 7 without a new value; a normal run refuses while a previous value is staged. If gh is missing or not logged in the script prints the exact gh workflow run command and exits 3; run it, wait, then --resume --yes. Afterwards run the acceptance runner (cd conversation && npx tsx bin/acceptance.ts --environment development).

The window

There is no refusal window for web users: for the whole time CloudFront still carries the old key the Front Door accepts it as AWSPREVIOUS, and the first wait keeps the deploy from beating the Lambda cache. The only exposure is the old key staying valid until step 7; if it is suspected leaked, do not stop between steps 3 and 7. If the Web deploy is done by hand with a CloudFront that takes long to propagate, nothing is lost: both values work. After retirement the old key is dead everywhere within 60 seconds.

Cadence

Rotate every 90 days, after anyone with cloudfront:GetDistributionConfig, secretsmanager:GetSecretValue on the secret or ecs:DescribeTasks on the host cluster leaves the operator set, and at once on any suspected exposure.

Proposed, not built: take the key out of the CloudFront configuration

Today the key is plain text in the distribution configuration. The fix is an origin access control for the Function URL: set the Function URL authType to AWS_IAM and let CloudFront sign the origin request (SigV4) with an OAC, so no shared header exists. Known obstacles from this repo: the STS authorization relay (integration-test and caller-identity proof, buildStsGetCallerIdentityHeaders) and the worker bearer travel in the Authorization header, which the OAC SigV4 signature would overwrite; direct Function URL callers (customer-account host workers, the acceptance runner) would need to sign requests themselves or use a second, separately protected URL; and the Function URL would need a resource policy for cloudfront.amazonaws.com scoped to the distribution ARN. Until then the rotation above is the control.

Ops cleanup after cutover

This repository does not mint keys, but historical operator practice and sibling repos may have left standing credentials. After this control lands, deactivate and delete any long-lived keys that are not tied to an active break-glass exception:

Use aws iam list-users and aws iam list-access-keys --user-name <user> (or Identity Center permission sets) in each account. Do not create replacement keys while cleaning up — use aws login / Identity Center and existing AssumeRole paths instead.

Related docs

• infra/README.md — GitHub Actions OIDC one-time setup
• AGENTS.md — agent hard control (summary)
• infra/customer-role.yml — customer cross-account role (roles only, no users/keys)