or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

access-control-security.mdbucket-configuration.mdbucket-operations.mdclient-configuration.mdindex.mdlisting-pagination.mdmultipart-upload.mdobject-operations.mdwaiters-utilities.md
tile.json

access-control-security.mddocs/

Access Control & Security

Comprehensive access control management through Access Control Lists (ACLs), bucket policies, and AWS Identity and Access Management (IAM) integration for securing S3 resources.

Capabilities

Bucket Access Control Lists

Manage bucket-level permissions using Access Control Lists.

/**
 * Get bucket ACL permissions
 */
class GetBucketAclCommand {
  constructor(input: GetBucketAclCommandInput);
}

interface GetBucketAclCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

interface GetBucketAclCommandOutput {
  /** Bucket owner information */
  Owner?: Owner;
  
  /** List of permission grants */
  Grants?: Grant[];
}

/**
 * Set bucket ACL permissions
 */
class PutBucketAclCommand {
  constructor(input: PutBucketAclCommandInput);
}

interface PutBucketAclCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Canned ACL to apply */
  ACL?: BucketCannedACL;
  
  /** Complete access control policy */
  AccessControlPolicy?: AccessControlPolicy;
  
  /** Grant full control permission */
  GrantFullControl?: string;
  
  /** Grant read permission */
  GrantRead?: string;
  
  /** Grant read ACP permission */
  GrantReadACP?: string;
  
  /** Grant write permission */
  GrantWrite?: string;
  
  /** Grant write ACP permission */
  GrantWriteACP?: string;
  
  /** Checksum algorithm */
  ChecksumAlgorithm?: ChecksumAlgorithm;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

interface AccessControlPolicy {
  /** List of permission grants */
  Grants?: Grant[];
  
  /** Resource owner */
  Owner?: Owner;
}

interface Grant {
  /** Grantee information */
  Grantee?: Grantee;
  
  /** Permission granted */
  Permission?: Permission;
}

interface Grantee {
  /** Display name */
  DisplayName?: string;
  
  /** Email address (legacy) */
  EmailAddress?: string;
  
  /** Canonical user ID */
  ID?: string;
  
  /** Grantee type */
  Type?: Type;
  
  /** Predefined group URI */
  URI?: string;
}

Usage Examples:

import { S3Client, GetBucketAclCommand, PutBucketAclCommand } from "@aws-sdk/client-s3";

const client = new S3Client({ region: "us-east-1" });

// Get current bucket ACL
const getBucketAcl = new GetBucketAclCommand({
  Bucket: "my-bucket"
});
const aclResponse = await client.send(getBucketAcl);
console.log("Current grants:", aclResponse.Grants);

// Set bucket to public read
const publicReadAcl = new PutBucketAclCommand({
  Bucket: "public-assets",
  ACL: "public-read"
});
await client.send(publicReadAcl);

// Set custom ACL with specific grants
const customAcl = new PutBucketAclCommand({
  Bucket: "shared-bucket",
  AccessControlPolicy: {
    Owner: {
      ID: "canonical-user-id-of-owner"
    },
    Grants: [
      {
        Grantee: {
          Type: "CanonicalUser",
          ID: "canonical-user-id-of-grantee"
        },
        Permission: "READ"
      },
      {
        Grantee: {
          Type: "Group",
          URI: "http://acs.amazonaws.com/groups/global/AuthenticatedUsers"
        },
        Permission: "READ"
      }
    ]
  }
});
await client.send(customAcl);

Object Access Control Lists

Manage object-level permissions using Access Control Lists.

/**
 * Get object ACL permissions
 */
class GetObjectAclCommand {
  constructor(input: GetObjectAclCommandInput);
}

interface GetObjectAclCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Object key */
  Key: string;
  
  /** Object version ID */
  VersionId?: string;
  
  /** Request payer setting */
  RequestPayer?: RequestPayer;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

interface GetObjectAclCommandOutput {
  /** Object owner */
  Owner?: Owner;
  
  /** List of permission grants */
  Grants?: Grant[];
  
  /** Request charged information */
  RequestCharged?: RequestCharged;
}

/**
 * Set object ACL permissions
 */
class PutObjectAclCommand {
  constructor(input: PutObjectAclCommandInput);
}

interface PutObjectAclCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Object key */
  Key: string;
  
  /** Canned ACL to apply */
  ACL?: ObjectCannedACL;
  
  /** Complete access control policy */
  AccessControlPolicy?: AccessControlPolicy;
  
  /** Grant full control permission */
  GrantFullControl?: string;
  
  /** Grant read permission */
  GrantRead?: string;
  
  /** Grant read ACP permission */
  GrantReadACP?: string;
  
  /** Grant write ACP permission */
  GrantWriteACP?: string;
  
  /** Object version ID */
  VersionId?: string;
  
  /** Request payer setting */
  RequestPayer?: RequestPayer;
  
  /** Checksum algorithm */
  ChecksumAlgorithm?: ChecksumAlgorithm;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

Usage Example:

import { S3Client, PutObjectAclCommand } from "@aws-sdk/client-s3";

const client = new S3Client({ region: "us-east-1" });

// Make object publicly readable
const publicObjectAcl = new PutObjectAclCommand({
  Bucket: "my-bucket",
  Key: "public/image.jpg",
  ACL: "public-read"
});
await client.send(publicObjectAcl);

Bucket Policies

Manage bucket policies for fine-grained access control using JSON policy documents.

/**
 * Get bucket policy
 */
class GetBucketPolicyCommand {
  constructor(input: GetBucketPolicyCommandInput);
}

interface GetBucketPolicyCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

interface GetBucketPolicyCommandOutput {
  /** Policy document as JSON string */
  Policy?: string;
}

/**
 * Set bucket policy
 */
class PutBucketPolicyCommand {
  constructor(input: PutBucketPolicyCommandInput);
}

interface PutBucketPolicyCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Policy document as JSON string */
  Policy: string;
  
  /** Confirm removal of public access */
  ConfirmRemoveSelfBucketAccess?: boolean;
  
  /** Checksum algorithm */
  ChecksumAlgorithm?: ChecksumAlgorithm;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

/**
 * Delete bucket policy
 */
class DeleteBucketPolicyCommand {
  constructor(input: DeleteBucketPolicyCommandInput);
}

interface DeleteBucketPolicyCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

/**
 * Get bucket policy status
 */
class GetBucketPolicyStatusCommand {
  constructor(input: GetBucketPolicyStatusCommandInput);
}

interface GetBucketPolicyStatusCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

interface GetBucketPolicyStatusCommandOutput {
  /** Policy status information */
  PolicyStatus?: PolicyStatus;
}

interface PolicyStatus {
  /** Whether the policy allows public access */
  IsPublic?: boolean;
}

Usage Examples:

import { 
  S3Client, 
  PutBucketPolicyCommand, 
  GetBucketPolicyCommand,
  GetBucketPolicyStatusCommand 
} from "@aws-sdk/client-s3";

const client = new S3Client({ region: "us-east-1" });

// Set a bucket policy for public read access to specific prefix
const policy = {
  Version: "2012-10-17",
  Statement: [
    {
      Sid: "PublicReadGetObject",
      Effect: "Allow",
      Principal: "*",
      Action: "s3:GetObject",
      Resource: "arn:aws:s3:::my-bucket/public/*"
    }
  ]
};

const putPolicy = new PutBucketPolicyCommand({
  Bucket: "my-bucket",
  Policy: JSON.stringify(policy)
});
await client.send(putPolicy);

// Check if bucket policy allows public access
const getPolicyStatus = new GetBucketPolicyStatusCommand({
  Bucket: "my-bucket"
});
const status = await client.send(getPolicyStatus);
console.log(`Bucket is public: ${status.PolicyStatus?.IsPublic}`);

Public Access Block

Control public access to buckets and objects at the account or bucket level.

/**
 * Get public access block configuration
 */
class GetPublicAccessBlockCommand {
  constructor(input: GetPublicAccessBlockCommandInput);
}

interface GetPublicAccessBlockCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

interface GetPublicAccessBlockCommandOutput {
  /** Public access block configuration */
  PublicAccessBlockConfiguration?: PublicAccessBlockConfiguration;
}

/**
 * Set public access block configuration
 */
class PutPublicAccessBlockCommand {
  constructor(input: PutPublicAccessBlockCommandInput);
}

interface PutPublicAccessBlockCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Public access block configuration */
  PublicAccessBlockConfiguration: PublicAccessBlockConfiguration;
  
  /** Checksum algorithm */
  ChecksumAlgorithm?: ChecksumAlgorithm;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

/**
 * Delete public access block configuration
 */
class DeletePublicAccessBlockCommand {
  constructor(input: DeletePublicAccessBlockCommandInput);
}

interface DeletePublicAccessBlockCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

interface PublicAccessBlockConfiguration {
  /** Block public ACLs */
  BlockPublicAcls?: boolean;
  
  /** Ignore public ACLs */
  IgnorePublicAcls?: boolean;
  
  /** Block public bucket policies */
  BlockPublicPolicy?: boolean;
  
  /** Restrict public bucket policies */
  RestrictPublicBuckets?: boolean;
}

Usage Example:

import { S3Client, PutPublicAccessBlockCommand } from "@aws-sdk/client-s3";

const client = new S3Client({ region: "us-east-1" });

// Block all public access
const blockPublicAccess = new PutPublicAccessBlockCommand({
  Bucket: "secure-bucket",
  PublicAccessBlockConfiguration: {
    BlockPublicAcls: true,
    IgnorePublicAcls: true,
    BlockPublicPolicy: true,
    RestrictPublicBuckets: true
  }
});
await client.send(blockPublicAccess);

Object Ownership Controls

Configure object ownership for objects uploaded to the bucket.

/**
 * Get bucket ownership controls
 */
class GetBucketOwnershipControlsCommand {
  constructor(input: GetBucketOwnershipControlsCommandInput);
}

interface GetBucketOwnershipControlsCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

interface GetBucketOwnershipControlsCommandOutput {
  /** Ownership controls configuration */
  OwnershipControls?: OwnershipControls;
}

/**
 * Set bucket ownership controls
 */
class PutBucketOwnershipControlsCommand {
  constructor(input: PutBucketOwnershipControlsCommandInput);
}

interface PutBucketOwnershipControlsCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Ownership controls configuration */
  OwnershipControls: OwnershipControls;
  
  /** Content MD5 */
  ContentMD5?: string;
  
  /** Checksum algorithm */
  ChecksumAlgorithm?: ChecksumAlgorithm;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

/**
 * Delete bucket ownership controls
 */
class DeleteBucketOwnershipControlsCommand {
  constructor(input: DeleteBucketOwnershipControlsCommandInput);
}

interface DeleteBucketOwnershipControlsCommandInput {
  /** Bucket name */
  Bucket: string;
  
  /** Expected bucket owner account ID */
  ExpectedBucketOwner?: string;
}

interface OwnershipControls {
  /** List of ownership rules */
  Rules: OwnershipControlsRule[];
}

interface OwnershipControlsRule {
  /** Object ownership setting */
  ObjectOwnership: ObjectOwnership;
}

Usage Example:

import { S3Client, PutBucketOwnershipControlsCommand } from "@aws-sdk/client-s3";

const client = new S3Client({ region: "us-east-1" });

// Set bucket owner as preferred owner for all objects
const ownershipControls = new PutBucketOwnershipControlsCommand({
  Bucket: "my-bucket",
  OwnershipControls: {
    Rules: [
      {
        ObjectOwnership: "BucketOwnerPreferred"
      }
    ]
  }
});
await client.send(ownershipControls);

Common Types

// Permission types
type Permission = 
  | "FULL_CONTROL"
  | "READ" 
  | "READ_ACP"
  | "WRITE"
  | "WRITE_ACP";

// Grantee types
type Type = 
  | "CanonicalUser"
  | "AmazonCustomerByEmail"
  | "Group";

// Bucket canned ACL options
type BucketCannedACL = 
  | "private"
  | "public-read"
  | "public-read-write"
  | "authenticated-read";

// Object canned ACL options  
type ObjectCannedACL =
  | "private"
  | "public-read"
  | "public-read-write"
  | "authenticated-read"
  | "aws-exec-read"
  | "bucket-owner-read"
  | "bucket-owner-full-control";

// Object ownership options
type ObjectOwnership =
  | "BucketOwnerPreferred"
  | "ObjectWriter"
  | "BucketOwnerEnforced";

// Core types
interface Owner {
  /** Display name */
  DisplayName?: string;
  
  /** Canonical user ID */
  ID?: string;
}

// Well-known predefined groups
const PredefinedGroups = {
  /** All authenticated AWS users */
  AuthenticatedUsers: "http://acs.amazonaws.com/groups/global/AuthenticatedUsers",
  
  /** All users (public access) */
  AllUsers: "http://acs.amazonaws.com/groups/global/AllUsers",
  
  /** S3 log delivery group */
  LogDelivery: "http://acs.amazonaws.com/groups/s3/LogDelivery"
} as const;

Complete Access Control Example:

import { 
  S3Client, 
  PutBucketAclCommand,
  PutObjectAclCommand,
  PutBucketPolicyCommand,
  PutPublicAccessBlockCommand
} from "@aws-sdk/client-s3";

const client = new S3Client({ region: "us-east-1" });

async function setupSecureBucket(bucketName: string) {
  // 1. Block all public access by default
  const blockPublicAccess = new PutPublicAccessBlockCommand({
    Bucket: bucketName,
    PublicAccessBlockConfiguration: {
      BlockPublicAcls: true,
      IgnorePublicAcls: true,
      BlockPublicPolicy: true,
      RestrictPublicBuckets: true
    }
  });
  await client.send(blockPublicAccess);

  // 2. Set private ACL
  const privateBucketAcl = new PutBucketAclCommand({
    Bucket: bucketName,
    ACL: "private"
  });
  await client.send(privateBucketAcl);

  // 3. Set restrictive bucket policy
  const restrictivePolicy = {
    Version: "2012-10-17",
    Statement: [
      {
        Sid: "DenyInsecureConnections",
        Effect: "Deny",
        Principal: "*",
        Action: "s3:*",
        Resource: [
          `arn:aws:s3:::${bucketName}`,
          `arn:aws:s3:::${bucketName}/*`
        ],
        Condition: {
          Bool: {
            "aws:SecureTransport": "false"
          }
        }
      }
    ]
  };

  const putPolicy = new PutBucketPolicyCommand({
    Bucket: bucketName,
    Policy: JSON.stringify(restrictivePolicy)
  });
  await client.send(putPolicy);

  console.log(`Secure bucket ${bucketName} configured`);
}

// Usage
await setupSecureBucket("my-secure-bucket");