# @kody/aws — agent notes

Human setup and intent live in [`README.md`](./README.md). This file is for
agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by
**name** only (`awsAccessKeyId`, `awsSecretAccessKey`, optional
`awsSessionToken`) — never paste key values. Do not enable the optional
`identity-check` job unless the fork owner asked for it.

## Auth / secrets

| Secret | Purpose |
| --- | --- |
| `awsAccessKeyId` | Access key id (AKIA…) |
| `awsSecretAccessKey` | Secret access key |
| `awsSessionToken` | Optional temporary session token |

Pass `account: "work"` → `awsAccessKeyId-work` / `awsSecretAccessKey-work`
(and matching session token if used). Default region `us-east-1` unless
`region` is passed or `./config` stores a fork-local default.

Hosts to approve (extend per region): `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`.

## Import paths

| Export | Import |
| --- | --- |
| overview | `kody:@kody/aws` |
| guide | `kody:@kody/aws/guide` |
| smoke-test | `kody:@kody/aws/smoke-test` |
| identity | `kody:@kody/aws/identity` |
| s3 | `kody:@kody/aws/s3` |
| logs | `kody:@kody/aws/logs` |
| metrics | `kody:@kody/aws/metrics` |
| request | `kody:@kody/aws/request` |
| config | `kody:@kody/aws/config` |
| scheduled-identity-check | `kody:@kody/aws/scheduled-identity-check` |

Prefer static `kody:@kody/aws/...` imports from `execute`. Do not lead with
`packages.invoke`.

## Smoke test (read-only)

```js
import smokeTest from 'kody:@kody/aws/smoke-test'

export default async function main() {
	return await smokeTest()
	// without secrets => { ok: true, live: false, ...setup URLs }
	// with secrets => live STS identity summary — no secret values / S3 bodies
}
```

Read-only samples:

```js
import identity from 'kody:@kody/aws/identity'

export default async function main() {
	return await identity()
}
```

```js
import { listBuckets, listObjects, getObjectMetadata } from 'kody:@kody/aws/s3'

export default async function main() {
	const buckets = await listBuckets()
	const objects = await listObjects({ bucket: 'example-bucket' })
	const meta = await getObjectMetadata({
		bucket: 'example-bucket',
		key: 'notes.txt',
	})
	return { buckets, objects, meta }
}
```

## dryRun / confirm (writes)

S3 put/delete and other writes **default to dry-run**. They return a preview
unless `confirm: true` (and `dryRun` is not `true`).

```js
import { putObject } from 'kody:@kody/aws/s3'

export default async function main() {
	const preview = await putObject({
		bucket: 'example-bucket',
		key: 'notes.txt',
		body: 'hello',
	})
	// Only after explicit user approval of the exact bucket and key:
	const live = await putObject({
		bucket: 'example-bucket',
		key: 'notes.txt',
		body: 'hello',
		confirm: true,
	})
	return { preview, live }
}
```

## Edge cases / fork notes

- S3 `getObjectMetadata` is HEAD-only. This package will not dump object bodies.
- Log and generic REST helpers redact credential-shaped text.
- Live `@kody/aws` `packageStorage()` is the platform bucket — fork first; do
  not store caller account ids or bucket names in this listing.
- Optional `identity-check` job is **disabled by default** — leave it off
  unless the fork owner enables it.
- Never paste AWS secret keys or session tokens into chat or logs.