Tag S3 Objects With AWS SDK v3 (PutObjectTagging)

// put-object-with-tags.ts: upload an object and tag it in the same PutObject request.
// Usage: BUCKET=acme-reports npx tsx put-object-with-tags.ts
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({ region: process.env.AWS_REGION ?? "us-east-1" });
const tags: Record<string, string> = { project: "billing", classification: "internal", owner: "data team" };

// PutObject takes tags as one URL-query-encoded string: "project=billing&owner=data%20team"
const Tagging = Object.entries(tags)
  .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
  .join("&");

const out = await s3.send(new PutObjectCommand({
  Bucket: process.env.BUCKET ?? "acme-reports",
  Key: "2027/08/invoice-summary.csv",
  Body: "month,total\n2027-07,1834.20\n",
  ContentType: "text/csv",
  Tagging,
}));
console.log(`Uploaded with tags: ${Tagging}`);
console.log(`ETag ${out.ETag}${out.VersionId ? `, version ${out.VersionId}` : ""}`);

Uploaded with tags: project=billing&classification=internal&owner=data%20team
ETag "9b2cf535f27731c974343645a3985328", version 3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY

// object-tags.ts: read, replace, merge and remove S3 object tags with AWS SDK v3.
// Every function takes an optional versionId to work on a specific object version.
import {
  S3Client,
  DeleteObjectTaggingCommand,
  GetObjectTaggingCommand,
  PutObjectTaggingCommand,
  type Tag,
} from "@aws-sdk/client-s3";

export type Tags = Record<string, string>;
export interface ObjectRef { bucket: string; key: string; versionId?: string }

const MAX_TAGS = 10;

/** Throws before calling S3 when the set breaks the documented limits. */
export function validateTags(tags: Tags): void {
  const entries = Object.entries(tags);
  if (entries.length > MAX_TAGS) throw new Error(`${entries.length} tags: S3 allows at most ${MAX_TAGS} per object`);
  for (const [k, v] of entries) {
    // S3 measures tags in UTF-16 code units, which is what String.length counts
    if (k.length < 1 || k.length > 128) throw new Error(`tag key "${k}" must be 1 to 128 characters`);
    if (v.length > 256) throw new Error(`value of tag "${k}" is longer than 256 characters`);
  }
}

const toTagSet = (tags: Tags): Tag[] => Object.entries(tags).map(([Key, Value]) => ({ Key, Value }));

export async function getTags(s3: S3Client, o: ObjectRef): Promise<Tags> {
  const out = await s3.send(new GetObjectTaggingCommand({ Bucket: o.bucket, Key: o.key, VersionId: o.versionId }));
  return Object.fromEntries((out.TagSet ?? []).map((t) => [t.Key ?? "", t.Value ?? ""]));
}

/** Replaces the whole tag set: any tag not in `tags` is removed. */
export async function replaceTags(s3: S3Client, o: ObjectRef, tags: Tags): Promise<void> {
  validateTags(tags);
  await s3.send(new PutObjectTaggingCommand({
    Bucket: o.bucket, Key: o.key, VersionId: o.versionId, Tagging: { TagSet: toTagSet(tags) },
  }));
}

/** Adds or overwrites some tags and keeps the rest (read, merge, write). Returns the new set. */
export async function mergeTags(s3: S3Client, o: ObjectRef, changes: Tags): Promise<Tags> {
  const merged = { ...(await getTags(s3, o)), ...changes };
  await replaceTags(s3, o, merged);
  return merged;
}

/** Removes the named keys. Uses DeleteObjectTagging when nothing is left. */
export async function removeTags(s3: S3Client, o: ObjectRef, keys: string[]): Promise<Tags> {
  const remaining = await getTags(s3, o);
  for (const k of keys) delete remaining[k];
  if (Object.keys(remaining).length === 0) await clearTags(s3, o);
  else await replaceTags(s3, o, remaining);
  return remaining;
}

export async function clearTags(s3: S3Client, o: ObjectRef): Promise<void> {
  await s3.send(new DeleteObjectTaggingCommand({ Bucket: o.bucket, Key: o.key, VersionId: o.versionId }));
}

// use-object-tags.ts: merge a tag into an object, show the result, remove it again.
// Usage: BUCKET=acme-reports npx tsx use-object-tags.ts
import { S3Client } from "@aws-sdk/client-s3";
import { getTags, mergeTags, removeTags } from "./object-tags.js";

const s3 = new S3Client({ region: process.env.AWS_REGION ?? "us-east-1" });
const obj = { bucket: process.env.BUCKET ?? "acme-reports", key: "2027/08/invoice-summary.csv" };

console.log("before:", await getTags(s3, obj));
console.log("merged:", await mergeTags(s3, obj, { retention: "7y", classification: "confidential" }));
console.log("removed:", await removeTags(s3, obj, ["retention"]));

before: { project: 'billing', classification: 'internal', owner: 'data team' }
merged: {
  project: 'billing',
  classification: 'confidential',
  owner: 'data team',
  retention: '7y'
}
removed: {
  project: 'billing',
  classification: 'confidential',
  owner: 'data team'
}

// tag-prefix.ts: merge tags into every object under a prefix, with a fixed number of parallel requests.
// Dry run by default; --apply writes. Each object costs one GET and one PUT tagging request.
// Usage: BUCKET=acme-reports npx tsx tag-prefix.ts 2027/ project=billing retention=7y [--concurrency 16] [--apply]
import { S3Client, paginateListObjectsV2 } from "@aws-sdk/client-s3";
import { mergeTags, validateTags, type Tags } from "./object-tags.js";

const args = process.argv.slice(2);
const apply = args.includes("--apply");
const ci = args.indexOf("--concurrency");
const concurrency = ci >= 0 ? Number(args[ci + 1]) : 16;
const positional = args.filter((a, i) => !a.startsWith("--") && (ci < 0 || i !== ci + 1));
const [prefix = "", ...pairs] = positional;
const changes: Tags = Object.fromEntries(pairs.map((p) => {
  const eq = p.indexOf("=");
  if (eq < 1) throw new Error(`expected key=value, got "${p}"`);
  return [p.slice(0, eq), p.slice(eq + 1)];
}));
validateTags(changes);

const bucket = process.env.BUCKET ?? "acme-reports";
const s3 = new S3Client({ region: process.env.AWS_REGION ?? "us-east-1", maxAttempts: 5 });

async function* keys(): AsyncGenerator<string> {
  for await (const page of paginateListObjectsV2({ client: s3 }, { Bucket: bucket, Prefix: prefix })) {
    for (const o of page.Contents ?? []) if (o.Key && !o.Key.endsWith("/")) yield o.Key;
  }
}

let done = 0;
const failed: string[] = [];
const source = keys();

async function worker(): Promise<void> {
  for (let next = await source.next(); !next.done; next = await source.next()) {
    const key = next.value;
    try {
      if (apply) await mergeTags(s3, { bucket, key }, changes);
      done += 1;
      if (done % 1000 === 0) console.log(`${done} objects ${apply ? "tagged" : "matched"}`);
    } catch (err) {
      failed.push(`${key}: ${err instanceof Error ? err.name : String(err)}`);
    }
  }
}

await Promise.all(Array.from({ length: concurrency }, () => worker()));
console.log(`${apply ? "Tagged" : "Would tag"} ${done} objects under s3://${bucket}/${prefix} with ${JSON.stringify(changes)}`);
if (failed.length > 0) {
  console.log(`${failed.length} failed:`);
  for (const f of failed.slice(0, 20)) console.log(`  ${f}`);
  process.exitCode = 1;
}

1000 objects tagged
2000 objects tagged
Tagged 2339 objects under s3://acme-reports/2027/ with {"project":"billing","retention":"7y"}
1 failed:
  2027/events/part-0007.json: AccessDenied

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadOnlyPublicObjects",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:GetObjectVersion"],
      "Resource": "arn:aws:s3:::acme-reports/*",
      "Condition": { "StringEquals": { "s3:ExistingObjectTag/classification": "public" } }
    },
    {
      "Sid": "TagWithAgreedKeysOnly",
      "Effect": "Allow",
      "Action": ["s3:GetObjectTagging", "s3:PutObjectTagging", "s3:DeleteObjectTagging"],
      "Resource": "arn:aws:s3:::acme-reports/*",
      "Condition": {
        "ForAllValues:StringEquals": { "s3:RequestObjectTagKeys": ["project", "classification", "retention"] }
      }
    },
    {
      "Sid": "ListForBulkTagging",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::acme-reports"
    }
  ]
}

{
  "Rules": [
    {
      "ID": "expire-30-day-retention",
      "Status": "Enabled",
      "Filter": { "Tag": { "Key": "retention", "Value": "30d" } },
      "Expiration": { "Days": 30 }
    }
  ]
}