S3 Storage

Alpha

DSAR is currently in alpha. APIs, package surfaces, configuration, and documentation may change as the project evolves.

@dsar/storage-s3 connects DSAR to any S3-compatible object store — AWS S3, MinIO, Cloudflare R2, DigitalOcean Spaces, and more.

Installation

Package manager	Command
npm	`npm install @dsar/storage-s3`
pnpm	`pnpm add @dsar/storage-s3`
yarn	`yarn add @dsar/storage-s3`
bun	`bun add @dsar/storage-s3`

Setup

import { dsarInstance } from "@dsar/backend";
import { makeS3StorageAdapter } from "@dsar/storage-s3";

const runtime = dsarInstance({
	adapters: {
		inbound: "stub",
		notifications: "stub",
		storage: makeS3StorageAdapter({
			bucket: "dsar-artifacts",
			region: "us-east-1",
			prefix: "artifacts",
			retryMaxAttempts: 3,
			timeoutMs: 3000,
		}),
	},
});

Configuration

Option	Default	Description
`bucket`	—	S3 bucket name (required)
`region`	—	AWS region (required)
`endpoint`	—	Custom endpoint for S3-compatible providers
`accessKeyId`	—	Explicit AWS access key
`secretAccessKey`	—	Explicit AWS secret key
`sessionToken`	—	Temporary session token
`forcePathStyle`	`false`	Use path-style URLs (for MinIO, etc.)
`prefix`	`artifacts`	Key prefix for all stored objects
`timeoutMs`	`3000`	Request timeout in milliseconds
`retryMaxAttempts`	`3`	Retry count for retriable failures

Key Layout

Default deterministic key format:

<prefix>/<requestId>/<manifestId>/<category>/<redaction>/<thirdParty>/<artifactName>

Fallback values:

missing requestId → request-unknown
missing manifestId → manifest-unknown
missing category → uncategorized
missing name/id → artifact.bin

Error and Retry Behaviour

Category	Retriable	Examples
`timeout`	yes	timeout, aborted request
`rate_limit`	yes	throttling, 429
`network`	yes	socket/connection failures
`auth`	no	unauthorised, access denied
`validation`	no	malformed key/input
`config`	no	invalid adapter config
`unknown`	no	unmatched provider errors

Manifest Linkage

Storage operations preserve manifest-linked metadata on artifact references:

requestId
manifestId
manifestHash
manifestSignature

This metadata is available via putObject results and headObject/getObject metadata for review and audit correlation.