s3

Amazon S3 access from Agency code — get and put objects (text or binary) and create buckets — with no AWS SDK dependency. Requests are signed with AWS Signature Version 4 using only Node's built-in crypto.

Credentials come from the standard AWS environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_SESSION_TOKEN). The region defaults to AWS_REGION, then us-east-1, and can be overridden per call.

import { s3Put, s3Get } from "std::aws/s3"

node main() {
  s3Put("my-bucket", "notes.txt", "hello") with approve
  const text = s3Get("my-bucket", "notes.txt") with approve
  print(text)
}

Every operation raises an interrupt before it runs, so an S3 function handed to an LLM as a tool cannot read or write a bucket without going through a handler. Lock the bucket parameter with .partial(bucket: ...) to scope an agent to a single bucket.

Scope: plain SigV4; virtual-hosted and path-style endpoints across the commercial, GovCloud, China, and ISO partitions. Binary is base64 in and out.

Types

S3PutResult

The result of a successful s3Put / s3PutBinary.

/** The result of a successful `s3Put` / `s3PutBinary`. */
export type S3PutResult = {
  bucket: string;
  key: string;
  url: string;
  etag: string
}

(source)

S3CreateBucketResult

The result of a successful createBucket.

/** The result of a successful `createBucket`. */
export type S3CreateBucketResult = {
  bucket: string;
  region: string;
  location: string
}

(source)

Effects

std::aws::s3::get

effect std::aws::s3::get {
  bucket: string;
  key: string;
  region: string
}

(source)

std::aws::s3::getBinary

effect std::aws::s3::getBinary {
  bucket: string;
  key: string;
  region: string
}

(source)

std::aws::s3::put

effect std::aws::s3::put {
  bucket: string;
  key: string;
  region: string
}

(source)

std::aws::s3::putBinary

effect std::aws::s3::putBinary {
  bucket: string;
  key: string;
  region: string
}

(source)

std::aws::s3::createBucket

effect std::aws::s3::createBucket {
  bucket: string;
  region: string
}

(source)

std::aws::s3::presignGet

effect std::aws::s3::presignGet {
  bucket: string;
  key: string;
  expiresIn: number;
  region: string
}

(source)

Functions

s3Get

s3Get(bucket: string, key: string, region: string = ""): Result<string>

Download an S3 object as UTF-8 text. Complete . and .. key segments are rejected.

@param bucket - The S3 bucket name @param key - The object key (path within the bucket) @param region - AWS region; defaults to AWS_REGION, then us-east-1

Parameters:

Name	Type	Default
bucket	string
key	string
region	string	""

Returns: Result<string>

Throws: std::aws::s3::get

(source)

s3GetBinary

s3GetBinary(bucket: string, key: string, region: string = ""): Result<string>

Download an S3 object as base64, not readable text. Complete . and .. key segments are rejected.

@param bucket - The S3 bucket name @param key - The object key (path within the bucket) @param region - AWS region; defaults to AWS_REGION, then us-east-1

Parameters:

Name	Type	Default
bucket	string
key	string
region	string	""

Returns: Result<string>

Throws: std::aws::s3::getBinary

(source)

s3Put

s3Put(
  bucket: string,
  key: string,
  content: string,
  region: string = "",
  contentType: string = "text/plain",
): Result<S3PutResult>

Upload UTF-8 text to S3. Returns the bucket, key, URL, and ETag. Complete . and .. key segments are rejected.

@param bucket - The S3 bucket name @param key - The object key (path within the bucket) @param content - The text to write @param region - AWS region; defaults to AWS_REGION, then us-east-1 @param contentType - The Content-Type for the object

Parameters:

Name	Type	Default
bucket	string
key	string
content	string
region	string	""
contentType	string	"text/plain"

Returns: Result<S3PutResult>

Throws: std::aws::s3::put

(source)

s3PutBinary

s3PutBinary(
  bucket: string,
  key: string,
  base64: string,
  region: string = "",
  contentType: string = "application/octet-stream",
): Result<S3PutResult>

Upload strict base64-decoded binary to S3. Returns the bucket, key, URL, and ETag. Complete . and .. key segments are rejected.

@param bucket - The S3 bucket name @param key - The object key (path within the bucket) @param base64 - The binary content, base64-encoded @param region - AWS region; defaults to AWS_REGION, then us-east-1 @param contentType - The Content-Type for the object

Parameters:

Name	Type	Default
bucket	string
key	string
base64	string
region	string	""
contentType	string	"application/octet-stream"

Returns: Result<S3PutResult>

Throws: std::aws::s3::putBinary

(source)

s3PresignGet

s3PresignGet(
  bucket: string,
  key: string,
  expiresIn: number = 1h,
  region: string = "",
): Result<string>

Create a presigned download URL for a private S3 object. Anyone holding the URL can download that object until it expires, so treat the URL like the object's contents. The URL is computed locally; no request is sent. With temporary credentials (AWS_SESSION_TOKEN), the URL stops working when the session expires, whatever expiry was requested.

@param bucket - The S3 bucket name @param key - The object key (path within the bucket) @param expiresIn - How long the URL works for, in milliseconds, 1 to 604800000 (7 days); default one hour @param region - AWS region; defaults to AWS_REGION, then us-east-1

Parameters:

Name	Type	Default
bucket	string
key	string
expiresIn	number	1h
region	string	""

Returns: Result<string>

Throws: std::aws::s3::presignGet

(source)

createBucket

createBucket(bucket: string, region: string = ""): Result<S3CreateBucketResult>

Create an S3 bucket and return its bucket, region, and location.

@param bucket - The globally-unique bucket name to create @param region - AWS region; defaults to AWS_REGION, then us-east-1

Parameters:

Name	Type	Default
bucket	string
region	string	""

Returns: Result<S3CreateBucketResult>

Throws: std::aws::s3::createBucket

(source)