@constructive-io/bucket-provisioner

@constructive-io/bucket-provisioner

S3-compatible bucket provisioning library for the Constructive storage module. Creates and configures buckets with the correct privacy policies, CORS rules, versioning, and lifecycle settings for private, public, and temporary file storage.

Features

• Privacy enforcement — Block All Public Access for private/temp buckets, public-read policy for public buckets
• CORS configuration — Browser-compatible rules for presigned URL uploads
• Lifecycle rules — Auto-cleanup for temp buckets (abandoned uploads)
• Versioning — Optional S3 versioning for durability
• Multi-provider — Works with AWS S3, MinIO, Cloudflare R2, Google Cloud Storage, and DigitalOcean Spaces
• Inspect/audit — Read back a bucket's current configuration for verification
• Typed errors — Structured ProvisionerError with error codes for programmatic handling

Installation

pnpm add @constructive-io/bucket-provisioner

Quick Start

import { BucketProvisioner } from '@constructive-io/bucket-provisioner';

const provisioner = new BucketProvisioner({
  connection: {
    provider: 'minio',
    region: 'us-east-1',
    endpoint: 'http://minio:9000',
    accessKeyId: 'minioadmin',
    secretAccessKey: 'minioadmin',
  },
  allowedOrigins: ['https://app.example.com'],
});

// Provision a private bucket (presigned URLs only)
const result = await provisioner.provision({
  bucketName: 'my-app-private',
  accessType: 'private',
  versioning: true,
});

console.log(result);
// {
//   bucketName: 'my-app-private',
//   accessType: 'private',
//   blockPublicAccess: true,
//   versioning: true,
//   corsRules: [...],
//   lifecycleRules: [],
//   ...
// }

Usage

Provision a Public Bucket

Public buckets serve files via direct URL or CDN. The provisioner applies a public-read bucket policy and configures CORS for browser uploads.

const result = await provisioner.provision({
  bucketName: 'my-app-public',
  accessType: 'public',
  publicUrlPrefix: 'https://cdn.example.com/public',
});
// result.blockPublicAccess === false
// result.publicUrlPrefix === 'https://cdn.example.com/public'

Provision a Temp Bucket

Temp buckets are staging areas for uploads. They behave like private buckets but include a lifecycle rule to auto-delete objects after a configurable period.

const result = await provisioner.provision({
  bucketName: 'my-app-temp',
  accessType: 'temp',
});
// result.lifecycleRules[0].id === 'temp-cleanup'
// result.lifecycleRules[0].expirationDays === 1

Inspect an Existing Bucket

Read back a bucket's current configuration to verify it matches expectations.

const config = await provisioner.inspect('my-app-private', 'private');
console.log(config.blockPublicAccess); // true
console.log(config.versioning);        // true
console.log(config.corsRules.length);  // 1

Use with AWS S3

For AWS S3, no endpoint is needed — just region and credentials.

const provisioner = new BucketProvisioner({
  connection: {
    provider: 's3',
    region: 'us-west-2',
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  allowedOrigins: ['https://app.example.com'],
});

Use with Cloudflare R2

const provisioner = new BucketProvisioner({
  connection: {
    provider: 'r2',
    region: 'auto',
    endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
    accessKeyId: R2_ACCESS_KEY,
    secretAccessKey: R2_SECRET_KEY,
  },
  allowedOrigins: ['https://app.example.com'],
});

API

BucketProvisioner

The main class that orchestrates bucket creation and configuration.

new BucketProvisioner(options)

Option	Type	Description
connection.provider	's3' | 'minio' | 'r2' | 'gcs' | 'spaces'	Storage provider type
connection.region	string	S3 region (e.g., 'us-east-1')
connection.endpoint	string?	S3-compatible endpoint URL. Required for non-AWS providers.
connection.accessKeyId	string	AWS access key ID
connection.secretAccessKey	string	AWS secret access key
connection.forcePathStyle	boolean?	Force path-style URLs (auto-detected per provider)
allowedOrigins	string[]	Domains allowed for CORS (e.g., ['https://app.example.com'])

provisioner.provision(options): Promise<ProvisionResult>

Creates and configures a bucket. Steps:

1. Creates the bucket (or verifies it exists)
2. Configures Block Public Access
3. Applies bucket policy (public-read or none)
4. Sets CORS rules for presigned URL uploads
5. Optionally enables versioning
6. Adds lifecycle rules for temp buckets

Option	Type	Description
bucketName	string	S3 bucket name
accessType	'public' | 'private' | 'temp'	Determines which policies are applied
region	string?	Override region for this bucket
versioning	boolean?	Enable S3 versioning (default: false)
publicUrlPrefix	string?	CDN/public URL for public buckets

provisioner.inspect(bucketName, accessType): Promise<ProvisionResult>

Reads back a bucket's current configuration (policy, CORS, versioning, lifecycle).

provisioner.getClient(): S3Client

Returns the underlying @aws-sdk/client-s3 S3Client for advanced operations.

provisioner.bucketExists(bucketName): Promise<boolean>

Checks if a bucket exists and is accessible.

Policy Builders

Standalone functions for generating S3 policy documents.

getPublicAccessBlock(accessType)

Returns the Block Public Access configuration for a given access type.

buildPublicReadPolicy(bucketName, keyPrefix?)

Builds a public-read bucket policy document.

buildCloudFrontOacPolicy(bucketName, distributionArn, keyPrefix?)

Builds a CloudFront Origin Access Control bucket policy.

buildPresignedUrlIamPolicy(bucketName)

Builds the minimum-permission IAM policy for the presigned URL plugin.

CORS Builders

buildUploadCorsRules(allowedOrigins, maxAgeSeconds?)

CORS rules for public/temp buckets (PUT, GET, HEAD).

buildPrivateCorsRules(allowedOrigins, maxAgeSeconds?)

CORS rules for private buckets (PUT, HEAD only — no GET).

Lifecycle Builders

buildTempCleanupRule(expirationDays?, prefix?)

Lifecycle rule for auto-expiring temp bucket objects.

buildAbortIncompleteMultipartRule(days?)

Lifecycle rule for cleaning up incomplete multipart uploads.

Error Handling

All errors thrown by the provisioner are instances of ProvisionerError:

import { ProvisionerError } from '@constructive-io/bucket-provisioner';

try {
  await provisioner.provision({ bucketName: 'test', accessType: 'private' });
} catch (err) {
  if (err instanceof ProvisionerError) {
    console.error(err.code);    // 'POLICY_FAILED', 'CORS_FAILED', etc.
    console.error(err.message); // Human-readable description
    console.error(err.cause);   // Original AWS SDK error
  }
}

Error codes:

Code	Description
CONNECTION_FAILED	Could not connect to the storage endpoint
BUCKET_ALREADY_EXISTS	Bucket exists and is owned by another account
BUCKET_NOT_FOUND	Bucket does not exist (for inspect/read operations)
INVALID_CONFIG	Invalid configuration (missing credentials, origins, etc.)
POLICY_FAILED	Failed to apply Block Public Access or bucket policy
CORS_FAILED	Failed to set CORS configuration
LIFECYCLE_FAILED	Failed to set lifecycle rules
VERSIONING_FAILED	Failed to enable versioning
ACCESS_DENIED	Credentials lack required permissions
PROVIDER_ERROR	Generic provider error (check cause for details)

Privacy Model

Access Type	Block Public Access	Bucket Policy	CORS Methods	Lifecycle
private	All blocked	None (deleted)	PUT, HEAD	None
public	Partially relaxed	Public-read	PUT, GET, HEAD	None
temp	All blocked	None (deleted)	PUT, GET, HEAD	Auto-expire (1 day)

Provider Notes

Provider	Endpoint Required	Path Style	Notes
s3	No	Virtual-hosted	AWS default
minio	Yes	Path-style	Local development, self-hosted
r2	Yes	Path-style	Cloudflare R2
gcs	Yes	Path-style	GCS S3-compatible API
spaces	Yes	Virtual-hosted	DigitalOcean Spaces

---

Education and Tutorials

1. Quickstart: Getting Up and Running Get started with modular databases in minutes. Install prerequisites and deploy your first module.

2. Modular PostgreSQL Development with Database Packages Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.

3. Authoring Database Changes Master the workflow for adding, organizing, and managing database changes with pgpm.

4. End-to-End PostgreSQL Testing with TypeScript Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.

5. Supabase Testing Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.

6. Drizzle ORM Testing Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.

7. Troubleshooting Common issues and solutions for pgpm, PostgreSQL, and testing.

Related Constructive Tooling

Package Management

• pgpm: PostgreSQL Package Manager for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.

Testing

• pgsql-test: Isolated testing environments with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
• pgsql-seed: PostgreSQL seeding utilities for CSV, JSON, SQL data loading, and pgpm deployment.
• supabase-test: Supabase-native test harness preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
• graphile-test: Authentication mocking for Graphile-focused test helpers and emulating row-level security contexts.
• pg-query-context: Session context injection to add session-local context (e.g., SET LOCAL) into queries—ideal for setting role, jwt.claims, and other session settings.

Parsing & AST

• pgsql-parser: SQL conversion engine that interprets and converts PostgreSQL syntax.
• libpg-query-node: Node.js bindings for libpg_query, converting SQL into parse trees.
• pg-proto-parser: Protobuf parser for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
• @pgsql/enums: TypeScript enums for PostgreSQL AST for safe and ergonomic parsing logic.
• @pgsql/types: Type definitions for PostgreSQL AST nodes in TypeScript.
• @pgsql/utils: AST utilities for constructing and transforming PostgreSQL syntax trees.

Documentation & Skills

• constructive-skills: Platform documentation and AI agent skills — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.

Install skills for AI coding agents:

# All platform skills (security, blueprints, codegen, billing, etc.)
npx skills add constructive-io/constructive-skills

# Individual repo skills (pgpm, testing, CLI, search, etc.)
npx skills add https://github.com/constructive-io/constructive --skill pgpm
npx skills add https://github.com/constructive-io/constructive --skill constructive-testing

Credits

Built by the Constructive team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on GitHub.

Disclaimer

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.