@kody/aws

import {
	COMMON_AWS_HOSTS,
	DEFAULT_ACCESS_KEY_SECRET,
	DEFAULT_SECRET_KEY_SECRET,
	DEFAULT_SESSION_TOKEN_SECRET,
	accessKeySetupUrl,
	resolveAccessKeySecretName,
	resolveSecretKeySecretName,
	resolveSessionTokenSecretName,
	secretKeySetupUrl,
	sessionTokenSetupUrl,
	type AwsAuthOptions,
} from './validation.ts'

/** Agent-usable setup URLs and AWS console steps for this package. */
export default async function guide(params: AwsAuthOptions = {}) {
	const accessKeySecret = resolveAccessKeySecretName(params)
	const secretKeySecret = resolveSecretKeySecretName(params)
	const sessionTokenSecret = resolveSessionTokenSecretName(params)
	return {
		auth: 'access-key-secret-key',
		oauth: false,
		requiredHosts: [...COMMON_AWS_HOSTS],
		secrets: {
			accessKeyId: accessKeySecret,
			secretAccessKey: secretKeySecret,
			sessionToken: sessionTokenSecret,
		},
		secretUrls: {
			accessKeyId: accessKeySetupUrl(accessKeySecret),
			secretAccessKey: secretKeySetupUrl(secretKeySecret),
			sessionToken: sessionTokenSetupUrl(sessionTokenSecret),
		},
		docs: 'https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html',
		console: 'https://console.aws.amazon.com/iam/',
		steps: [
			'Open the IAM console and create an access key for a least-privilege user or role session.',
			'Never paste the secret access key or session token into chat.',
			'Save the access key id at the accessKeyId secret URL and approve the listed amazonaws.com hosts.',
			'Save the secret access key at the secretAccessKey secret URL and approve the same hosts.',
			'If you use temporary credentials, also save awsSessionToken and approve the same hosts.',
			'Add more regional hosts such as logs.eu-west-1.amazonaws.com when you call those regions.',
			'Import kody:@kody/aws/smoke-test to verify local helpers. Live STS needs mounted secrets.',
			'S3 put/delete and other writes default to dryRun. A live mutation requires confirm: true.',
		],
		multiAccount:
			'Default secrets are awsAccessKeyId and awsSecretAccessKey. Additional accounts use account: "work" (secrets awsAccessKeyId-work / awsSecretAccessKey-work).',
		defaultSecretNames: {
			accessKeyId: DEFAULT_ACCESS_KEY_SECRET,
			secretAccessKey: DEFAULT_SECRET_KEY_SECRET,
			sessionToken: DEFAULT_SESSION_TOKEN_SECRET,
		},
	}
}