Claude Code × AWS S3: sync, images, sauvegardes et URL présignées avec le moindre privilège

S3 donne l’impression d’être un simple stockage de fichiers, mais une application réelle ajoute vite des sujets de droits, exposition publique, synchronisation, cache, suppression et coûts. Claude Code peut générer scripts et helpers rapidement, mais un prompt vague peut produire une policy trop large.

Ce guide s’adresse aux débutants qui veulent utiliser S3 sérieusement sans créer un problème de sécurité. Nous couvrons site statique, images, sauvegardes et URL présignées. Le fil conducteur est le moindre privilège: chaque script ne reçoit que l’action et le prefix nécessaires.

Les exemples suivent les documentations officielles: AWS CLI S3 reference, aws s3 sync reference, Boto3 presigned URL guide, Claude Code common workflows.

Pour compléter, consultez aussi: IAM, security, context.

Séparer les usages S3 avant le code

use case 1: site statique. dist est synchronisé vers site/ puis servi par CloudFront. use case 2: images. L’admin envoie vers uploads/ ou assets/images/. use case 3: sauvegarde. Les dumps et PDFs sont placés sous un prefix daté, sans —delete. use case 4: téléchargement privé. Le bucket reste privé et l’application donne une URL présignée courte.

Si tout est mélangé, s3:* semble tentant. Définissez plutôt site/, assets/images/, uploads/, backups/ et assets/private-reports/. Claude Code produira alors des policies et scripts plus simples à relire.

Identité et IAM au moindre privilège

Placez d’abord le bucket et la région dans des variables afin que vous et Claude Code vérifiiez la même cible.

export AWS_REGION=ap-northeast-1
export S3_BUCKET=claudecode-lab-assets-prod
aws sts get-caller-identity
aws s3 ls "s3://${S3_BUCKET}/" --region "${AWS_REGION}"

Cette policy lit seulement assets, écrit seulement uploads et évite les droits larges de suppression.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadPublicAssetsOnly",
      "Effect": "Allow",
      "Action": ["s3:GetObject"],
      "Resource": "arn:aws:s3:::claudecode-lab-assets-prod/assets/*"
    },
    {
      "Sid": "WriteUploadsOnly",
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:AbortMultipartUpload"],
      "Resource": "arn:aws:s3:::claudecode-lab-assets-prod/uploads/*"
    },
    {
      "Sid": "ListLimitedPrefixes",
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": "arn:aws:s3:::claudecode-lab-assets-prod",
      "Condition": {
        "StringLike": {
          "s3:prefix": ["assets/*", "uploads/*", "backups/*"]
        }
      }
    }
  ]
}

C’est la forme de base pour un site statique ou un dossier d’images. Commencez toujours par dryrun.

# 1. Preview changes first. This should become a habit.
aws s3 sync ./dist "s3://${S3_BUCKET}/site/" \
  --region "${AWS_REGION}" \
  --delete \
  --cache-control "public,max-age=300" \
  --dryrun

# 2. Deploy only after the preview looks right.
aws s3 sync ./dist "s3://${S3_BUCKET}/site/" \
  --region "${AWS_REGION}" \
  --delete \
  --cache-control "public,max-age=300"

# 3. Upload long-lived images with a different cache policy.
aws s3 sync ./public/images "s3://${S3_BUCKET}/assets/images/" \
  --region "${AWS_REGION}" \
  --exclude "*.psd" \
  --cache-control "public,max-age=31536000,immutable"

Une URL présignée garde le bucket privé tout en autorisant un téléchargement temporaire.

import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const s3 = new S3Client({ region: process.env.AWS_REGION ?? "ap-northeast-1" });

export async function createDownloadUrl(key: string, filename: string) {
  if (!key.startsWith("assets/private-reports/")) {
    throw new Error(`Unexpected S3 key prefix: ${key}`);
  }

  const command = new GetObjectCommand({
    Bucket: process.env.S3_BUCKET_NAME,
    Key: key,
    ResponseContentDisposition: `attachment; filename="${filename}"`,
  });

  return getSignedUrl(s3, command, { expiresIn: 900 });
}

Dans la demande à Claude Code, ajoutez le besoin, les interdictions et les commandes de contrôle.

このリポジトリに AWS S3 連携を追加してください。
目的: public/images を S3 の assets/images/ に同期し、private-reports/ のPDFだけ署名付きURLで配布する。
制約: バケット全体公開は禁止。s3:DeleteObject は付けない。aws s3 sync は必ず --dryrun を先に出す。
成果物: scripts/s3-sync-assets.mjs、lib/s3-presigned-url.ts、READMEの手順、確認コマンド。
確認: npm test、aws s3 ls、aws s3 sync --dryrun の出力で説明してください。
参照: AWS CLI s3/sync docs と Anthropic Claude Code common workflows。

La policy est volontairement étroite: GetObject sur assets, PutObject sur uploads, ListBucket limité par prefix. Les erreurs fréquentes sont ListBucket sur un ARN d’objet et s3:* sur tout le bucket.

Le droit DeleteObject est un autre pitfall. Beaucoup de flux n’en ont pas besoin. S’il faut supprimer, isolez le rôle ou le script avec dryrun, comptage des suppressions et validation humaine. Claude Code écrit vite le JSON; l’étendue finale reste à relire.

Utiliser aws s3 sync sans se piéger

aws s3 sync compare un dossier local et un prefix S3. Avec —delete, il supprime côté S3 ce qui n’existe plus localement. C’est utile pour un déploiement statique, dangereux pour des sauvegardes ou des images partagées.

# Backup use case: append-only, no --delete.
BACKUP_DATE=$(date +%Y-%m-%d)
aws s3 sync ./backups "s3://${S3_BUCKET}/backups/${BACKUP_DATE}/" \
  --region "${AWS_REGION}" \
  --storage-class STANDARD_IA \
  --exclude "*.tmp"

aws s3 ls "s3://${S3_BUCKET}/backups/${BACKUP_DATE}/" --recursive --summarize

Mon modèle: dryrun d’abord, exécution ensuite. Le script doit afficher bucket, région, prefix et diff. Si trop de deletes apparaissent, il s’arrête. Ce garde-fou simple évite le mauvais dossier avec —delete.

Une URL présignée est une permission temporaire

Une presigned URL autorise une action S3 pendant une durée limitée. Le bucket ne devient pas public. C’est adapté aux factures, rapports privés, exports PDF ou téléchargements par utilisateur après authentification.

Trois détails comptent: expiresIn est en secondes, le prefix du key doit être validé, et le nom de fichier navigateur ne doit pas devenir directement la key. Générez plutôt uploads/yyyy/mm/dd/uuid.ext côté serveur. Les URLs trop longues sont une failure classique.

Coûts, cache et exposition publique

Le coût S3 n’est pas seulement le stockage. Requests, transfert, CloudFront, versioning et lifecycle comptent aussi. Pour des assets publics, placez CloudFront devant S3 et définissez cache-control. Pour des fichiers privés, n’ouvrez pas le bucket par facilité.

DRYRUN_OUTPUT=$(aws s3 sync ./dist "s3://${S3_BUCKET}/site/" --delete --dryrun)
echo "$DRYRUN_OUTPUT"
DELETE_COUNT=$(echo "$DRYRUN_OUTPUT" | grep -c "delete:" || true)
if [ "$DELETE_COUNT" -gt 20 ]; then
  echo "Too many deletes: ${DELETE_COUNT}. Stop and review."
  exit 1
fi

Beaucoup de tutoriels anciens activent S3 static website hosting avec un bucket public. En production, private S3 + CloudFront est souvent plus facile à sécuriser et à expliquer lors d’un audit.

Ce que Claude Code fait, ce que l’humain valide

Claude Code peut produire scripts, helpers TypeScript, README, tests et messages d’erreur. L’humain valide compte AWS, bucket, prefix, DeleteObject, public access et CloudFront. Avant exécution, lancez aws sts get-caller-identity et aws s3 ls.

Note de vérification Masa: la séparation des prefixes a été le levier le plus utile. Avec site, assets, uploads, backups et private-reports séparés, la revue IAM devient beaucoup plus claire. Demander les verification steps à Claude Code améliore aussi la confiance.

Résumé

Claude Code × AWS S3 est efficace si les permissions restent ennuyeuses. Séparez les use cases, utilisez dryrun, évitez DeleteObject large, gardez S3 privé et donnez des URL présignées courtes.

Pour appliquer ce modèle à un vrai dépôt, utilisez training / consultation.