# @kody/aws

## Intent

Give agents a fork-ready AWS toolkit for STS identity, S3 list/metadata,
CloudWatch logs and metrics, and generic SigV4-signed REST. Auth is a saved
access key plus secret key (optional session token). Reads stay slim. S3 never
dumps object bodies. Writes support `dryRun` and require `confirm: true`.

This listing is meant to be forked. The live `@kody/aws` package does not talk
to a shared AWS account. After you fork, save your own credentials and call the
helpers in your account. No account ids or bucket names belong in this package.

Share this package as https://kody.codes/@kody/aws

## What it does

- Resolve STS caller identity (account / ARN / user id)
- List S3 buckets and objects; HEAD object metadata (no body dumps)
- Put or delete S3 objects with dry-run preview and explicit confirm
- Read CloudWatch log groups/events (redacted) and metric statistics
- Call uncommon AWS REST APIs through a SigV4-signed `./request` escape hatch
- Optionally store a fork-local default region via `./config`

## Prerequisites / setup

1. Create an IAM user or role session with least-privilege keys from the
   [IAM console](https://console.aws.amazon.com/iam/). Never paste secret values
   into chat.
2. Save the access key id:

https://kody.codes/account/secrets/new?name=awsAccessKeyId&description=AWS%20access%20key%20id%20(AKIA...)&allowedHosts=sts.amazonaws.com,sts.us-east-1.amazonaws.com,s3.amazonaws.com,s3.us-east-1.amazonaws.com,logs.us-east-1.amazonaws.com,monitoring.us-east-1.amazonaws.com&scope=user

3. Save the secret access key:

https://kody.codes/account/secrets/new?name=awsSecretAccessKey&description=AWS%20secret%20access%20key&allowedHosts=sts.amazonaws.com,sts.us-east-1.amazonaws.com,s3.amazonaws.com,s3.us-east-1.amazonaws.com,logs.us-east-1.amazonaws.com,monitoring.us-east-1.amazonaws.com&scope=user

4. Optional temporary session token:

https://kody.codes/account/secrets/new?name=awsSessionToken&description=Optional%20AWS%20session%20token%20for%20temporary%20credentials&allowedHosts=sts.amazonaws.com,sts.us-east-1.amazonaws.com,s3.amazonaws.com,s3.us-east-1.amazonaws.com,logs.us-east-1.amazonaws.com,monitoring.us-east-1.amazonaws.com&scope=user

5. Approve those amazonaws.com hosts. Add `{service}.{region}.amazonaws.com`
   when you call another region.
6. Default region is `us-east-1` unless you pass `region` or store a fork-local
   default with `./config`.
7. For additional accounts, pass `account: "work"` to use
   `awsAccessKeyId-work` / `awsSecretAccessKey-work`.

Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke, and dryRun.

## Done when

- `awsAccessKeyId` and `awsSecretAccessKey` are saved (optional
  `awsSessionToken`); needed amazonaws.com hosts are approved
- Smoke test returns `{ ok: true }` (live STS when secrets mount, or setup URLs
  when they do not) without printing secret values or S3 bodies
- S3 put/delete and other writes preview by default and only run live with
  `confirm: true`

## Branding

Official AWS smile wordmark (paths from [Amazon Web Services](https://aws.amazon.com))
in Squid Ink `#252F3E` and Amazon Orange `#FF9900`. Amazon Web Services® and the
AWS logo are trademarks of Amazon.com, Inc. or its affiliates. This package is
not affiliated with or endorsed by Amazon. `community-icon.svg` is unmodified
official artwork.

## Docs

- [IAM access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)
- [STS GetCallerIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html)
- [S3 API](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html)
- [CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/Welcome.html)
- [CloudWatch Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/Welcome.html)