@constructive-io/bucket-provisioner 0.2.0

package/esm/cors.js

@@ -0,0 +1,84 @@
+/**
+ * CORS configuration builders.
+ *
+ * Generates CORS rules for S3 buckets to allow browser-based
+ * presigned URL uploads. Without CORS, the browser will block
+ * the cross-origin PUT request to the S3 endpoint.
+ */
+/**
+ * Build the default CORS rules for presigned URL uploads.
+ *
+ * This allows:
+ * - PUT: for presigned uploads from the browser
+ * - GET: for presigned downloads and public file access
+ * - HEAD: for confirmUpload verification and cache headers
+ *
+ * @param allowedOrigins - Domains allowed to make cross-origin requests.
+ *                          Use specific domains in production (e.g., ["https://app.example.com"]).
+ *                          Never use ["*"] in production.
+ * @param maxAgeSeconds - Preflight cache duration (default: 3600 = 1 hour)
+ */
+export function buildUploadCorsRules(allowedOrigins, maxAgeSeconds = 3600) {
+    if (allowedOrigins.length === 0) {
+        throw new Error('allowedOrigins must contain at least one origin');
+    }
+    return [
+        {
+            allowedOrigins,
+            allowedMethods: ['PUT', 'GET', 'HEAD'],
+            allowedHeaders: [
+                'Content-Type',
+                'Content-Length',
+                'Content-MD5',
+                'x-amz-content-sha256',
+                'x-amz-date',
+                'x-amz-security-token',
+                'Authorization',
+            ],
+            exposedHeaders: [
+                'ETag',
+                'Content-Length',
+                'Content-Type',
+                'x-amz-request-id',
+                'x-amz-id-2',
+            ],
+            maxAgeSeconds,
+        },
+    ];
+}
+/**
+ * Build restrictive CORS rules for private-only buckets.
+ *
+ * Similar to upload CORS but without GET (private files use
+ * presigned URLs which include auth in the query string,
+ * so CORS is less of a concern for downloads).
+ *
+ * @param allowedOrigins - Domains allowed to make cross-origin requests.
+ * @param maxAgeSeconds - Preflight cache duration (default: 3600 = 1 hour)
+ */
+export function buildPrivateCorsRules(allowedOrigins, maxAgeSeconds = 3600) {
+    if (allowedOrigins.length === 0) {
+        throw new Error('allowedOrigins must contain at least one origin');
+    }
+    return [
+        {
+            allowedOrigins,
+            allowedMethods: ['PUT', 'HEAD'],
+            allowedHeaders: [
+                'Content-Type',
+                'Content-Length',
+                'Content-MD5',
+                'x-amz-content-sha256',
+                'x-amz-date',
+                'x-amz-security-token',
+                'Authorization',
+            ],
+            exposedHeaders: [
+                'ETag',
+                'Content-Length',
+                'x-amz-request-id',
+            ],
+            maxAgeSeconds,
+        },
+    ];
+}

package/esm/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @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 and public file storage.
+ *
+ * @example
+ * ```typescript
+ * 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'],
+ * });
+ *
+ * const result = await provisioner.provision({
+ *   bucketName: 'my-app-storage',
+ *   accessType: 'private',
+ * });
+ * ```
+ */
+export { BucketProvisioner } from './provisioner';
+export type { BucketProvisionerOptions } from './provisioner';
+export { createS3Client } from './client';
+export { getPublicAccessBlock, buildPublicReadPolicy, buildCloudFrontOacPolicy, buildPresignedUrlIamPolicy, } from './policies';
+export type { PublicAccessBlockConfig, BucketPolicyDocument, BucketPolicyStatement, } from './policies';
+export { buildUploadCorsRules, buildPrivateCorsRules } from './cors';
+export { buildTempCleanupRule, buildAbortIncompleteMultipartRule } from './lifecycle';
+export type { StorageProvider, StorageConnectionConfig, BucketAccessType, CreateBucketOptions, UpdateCorsOptions, CorsRule, LifecycleRule, ProvisionResult, ProvisionerErrorCode, } from './types';
+export { ProvisionerError } from './types';

package/esm/index.js

@@ -0,0 +1,39 @@
+/**
+ * @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 and public file storage.
+ *
+ * @example
+ * ```typescript
+ * 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'],
+ * });
+ *
+ * const result = await provisioner.provision({
+ *   bucketName: 'my-app-storage',
+ *   accessType: 'private',
+ * });
+ * ```
+ */
+// Core provisioner
+export { BucketProvisioner } from './provisioner';
+// S3 client factory
+export { createS3Client } from './client';
+// Policy builders
+export { getPublicAccessBlock, buildPublicReadPolicy, buildCloudFrontOacPolicy, buildPresignedUrlIamPolicy, } from './policies';
+// CORS builders
+export { buildUploadCorsRules, buildPrivateCorsRules } from './cors';
+// Lifecycle builders
+export { buildTempCleanupRule, buildAbortIncompleteMultipartRule } from './lifecycle';
+export { ProvisionerError } from './types';

package/esm/lifecycle.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Lifecycle rule builders.
+ *
+ * Generates S3 lifecycle configurations for automatic object expiration.
+ * Primarily used for temp buckets where uploads should be cleaned up
+ * after a configurable period.
+ */
+import type { LifecycleRule } from './types';
+/**
+ * Build a lifecycle rule for temp bucket cleanup.
+ *
+ * Temp buckets hold staging uploads (files with status='pending' that
+ * were never confirmed). This rule automatically deletes objects after
+ * a set number of days, preventing storage cost accumulation from
+ * abandoned uploads.
+ *
+ * @param expirationDays - Days after which objects expire (default: 1)
+ * @param prefix - Key prefix to target (default: "" = entire bucket)
+ */
+export declare function buildTempCleanupRule(expirationDays?: number, prefix?: string): LifecycleRule;
+/**
+ * Build a lifecycle rule for incomplete multipart upload cleanup.
+ *
+ * Incomplete multipart uploads consume storage but serve no purpose.
+ * This rule aborts them after a set number of days.
+ *
+ * @param expirationDays - Days after which incomplete uploads are aborted (default: 1)
+ */
+export declare function buildAbortIncompleteMultipartRule(expirationDays?: number): LifecycleRule;

package/esm/lifecycle.js

@@ -0,0 +1,42 @@
+/**
+ * Lifecycle rule builders.
+ *
+ * Generates S3 lifecycle configurations for automatic object expiration.
+ * Primarily used for temp buckets where uploads should be cleaned up
+ * after a configurable period.
+ */
+/**
+ * Build a lifecycle rule for temp bucket cleanup.
+ *
+ * Temp buckets hold staging uploads (files with status='pending' that
+ * were never confirmed). This rule automatically deletes objects after
+ * a set number of days, preventing storage cost accumulation from
+ * abandoned uploads.
+ *
+ * @param expirationDays - Days after which objects expire (default: 1)
+ * @param prefix - Key prefix to target (default: "" = entire bucket)
+ */
+export function buildTempCleanupRule(expirationDays = 1, prefix = '') {
+    return {
+        id: 'temp-cleanup',
+        prefix,
+        expirationDays,
+        enabled: true,
+    };
+}
+/**
+ * Build a lifecycle rule for incomplete multipart upload cleanup.
+ *
+ * Incomplete multipart uploads consume storage but serve no purpose.
+ * This rule aborts them after a set number of days.
+ *
+ * @param expirationDays - Days after which incomplete uploads are aborted (default: 1)
+ */
+export function buildAbortIncompleteMultipartRule(expirationDays = 1) {
+    return {
+        id: 'abort-incomplete-multipart',
+        prefix: '',
+        expirationDays,
+        enabled: true,
+    };
+}

package/esm/policies.d.ts

@@ -0,0 +1,88 @@
+/**
+ * S3 bucket policy builders.
+ *
+ * Generates the JSON policy documents for private and public bucket
+ * configurations. These are the actual S3 bucket policies that control
+ * who can access objects in the bucket.
+ *
+ * Privacy model:
+ * - Private buckets: Block All Public Access enabled, no bucket policy needed.
+ *   All access goes through presigned URLs generated server-side.
+ * - Public buckets: Block Public Access disabled for GetObject only.
+ *   A bucket policy grants public read access (optionally restricted to a key prefix).
+ */
+import type { BucketAccessType } from './types';
+/**
+ * S3 Block Public Access configuration.
+ *
+ * For private/temp buckets: all four flags are true (maximum lockdown).
+ * For public buckets: BlockPublicPolicy and RestrictPublicBuckets are false
+ * so that a public-read bucket policy can be applied.
+ */
+export interface PublicAccessBlockConfig {
+    BlockPublicAcls: boolean;
+    IgnorePublicAcls: boolean;
+    BlockPublicPolicy: boolean;
+    RestrictPublicBuckets: boolean;
+}
+/**
+ * Get the Block Public Access configuration for a bucket access type.
+ *
+ * - private/temp: all blocks enabled (maximum security)
+ * - public: ACL blocks enabled (ACLs are deprecated), but policy blocks
+ *   disabled so a public-read bucket policy can be attached
+ */
+export declare function getPublicAccessBlock(accessType: BucketAccessType): PublicAccessBlockConfig;
+/**
+ * AWS IAM-style policy document for S3 bucket policies.
+ */
+export interface BucketPolicyDocument {
+    Version: string;
+    Statement: BucketPolicyStatement[];
+}
+export interface BucketPolicyStatement {
+    Sid: string;
+    Effect: 'Allow' | 'Deny';
+    Principal: string | {
+        AWS: string;
+    } | {
+        Service: string;
+    };
+    Action: string | string[];
+    Resource: string | string[];
+    Condition?: Record<string, Record<string, string>>;
+}
+/**
+ * Build a public-read bucket policy.
+ *
+ * Grants anonymous GetObject access to the entire bucket or a specific prefix.
+ * This is the standard way to serve public files via direct URL or CDN.
+ *
+ * @param bucketName - S3 bucket name
+ * @param keyPrefix - Optional key prefix to restrict public reads (e.g., "public/").
+ *                     If provided, only objects under this prefix are publicly readable.
+ *                     If omitted, the entire bucket is publicly readable.
+ */
+export declare function buildPublicReadPolicy(bucketName: string, keyPrefix?: string): BucketPolicyDocument;
+/**
+ * Build a CloudFront Origin Access Control (OAC) bucket policy.
+ *
+ * This is the recommended way to serve public files through CloudFront
+ * without making the S3 bucket itself public. CloudFront authenticates
+ * to S3 using the OAC, and the bucket policy only allows CloudFront.
+ *
+ * @param bucketName - S3 bucket name
+ * @param cloudFrontDistributionArn - The CloudFront distribution ARN
+ * @param keyPrefix - Optional key prefix to restrict access
+ */
+export declare function buildCloudFrontOacPolicy(bucketName: string, cloudFrontDistributionArn: string, keyPrefix?: string): BucketPolicyDocument;
+/**
+ * Build the IAM policy for the presigned URL plugin's S3 credentials.
+ *
+ * This is the minimum-permission policy that the GraphQL server's
+ * S3 access key should have. It only allows PutObject, GetObject,
+ * and HeadObject — no delete, no list, no bucket management.
+ *
+ * @param bucketName - S3 bucket name
+ */
+export declare function buildPresignedUrlIamPolicy(bucketName: string): BucketPolicyDocument;

package/esm/policies.js

@@ -0,0 +1,121 @@
+/**
+ * S3 bucket policy builders.
+ *
+ * Generates the JSON policy documents for private and public bucket
+ * configurations. These are the actual S3 bucket policies that control
+ * who can access objects in the bucket.
+ *
+ * Privacy model:
+ * - Private buckets: Block All Public Access enabled, no bucket policy needed.
+ *   All access goes through presigned URLs generated server-side.
+ * - Public buckets: Block Public Access disabled for GetObject only.
+ *   A bucket policy grants public read access (optionally restricted to a key prefix).
+ */
+/**
+ * Get the Block Public Access configuration for a bucket access type.
+ *
+ * - private/temp: all blocks enabled (maximum security)
+ * - public: ACL blocks enabled (ACLs are deprecated), but policy blocks
+ *   disabled so a public-read bucket policy can be attached
+ */
+export function getPublicAccessBlock(accessType) {
+    if (accessType === 'public') {
+        return {
+            BlockPublicAcls: true,
+            IgnorePublicAcls: true,
+            BlockPublicPolicy: false,
+            RestrictPublicBuckets: false,
+        };
+    }
+    // private and temp: full lockdown
+    return {
+        BlockPublicAcls: true,
+        IgnorePublicAcls: true,
+        BlockPublicPolicy: true,
+        RestrictPublicBuckets: true,
+    };
+}
+/**
+ * Build a public-read bucket policy.
+ *
+ * Grants anonymous GetObject access to the entire bucket or a specific prefix.
+ * This is the standard way to serve public files via direct URL or CDN.
+ *
+ * @param bucketName - S3 bucket name
+ * @param keyPrefix - Optional key prefix to restrict public reads (e.g., "public/").
+ *                     If provided, only objects under this prefix are publicly readable.
+ *                     If omitted, the entire bucket is publicly readable.
+ */
+export function buildPublicReadPolicy(bucketName, keyPrefix) {
+    const resource = keyPrefix
+        ? `arn:aws:s3:::${bucketName}/${keyPrefix}*`
+        : `arn:aws:s3:::${bucketName}/*`;
+    return {
+        Version: '2012-10-17',
+        Statement: [
+            {
+                Sid: 'PublicReadAccess',
+                Effect: 'Allow',
+                Principal: '*',
+                Action: 's3:GetObject',
+                Resource: resource,
+            },
+        ],
+    };
+}
+/**
+ * Build a CloudFront Origin Access Control (OAC) bucket policy.
+ *
+ * This is the recommended way to serve public files through CloudFront
+ * without making the S3 bucket itself public. CloudFront authenticates
+ * to S3 using the OAC, and the bucket policy only allows CloudFront.
+ *
+ * @param bucketName - S3 bucket name
+ * @param cloudFrontDistributionArn - The CloudFront distribution ARN
+ * @param keyPrefix - Optional key prefix to restrict access
+ */
+export function buildCloudFrontOacPolicy(bucketName, cloudFrontDistributionArn, keyPrefix) {
+    const resource = keyPrefix
+        ? `arn:aws:s3:::${bucketName}/${keyPrefix}*`
+        : `arn:aws:s3:::${bucketName}/*`;
+    return {
+        Version: '2012-10-17',
+        Statement: [
+            {
+                Sid: 'AllowCloudFrontOACRead',
+                Effect: 'Allow',
+                Principal: { Service: 'cloudfront.amazonaws.com' },
+                Action: 's3:GetObject',
+                Resource: resource,
+                Condition: {
+                    StringEquals: {
+                        'AWS:SourceArn': cloudFrontDistributionArn,
+                    },
+                },
+            },
+        ],
+    };
+}
+/**
+ * Build the IAM policy for the presigned URL plugin's S3 credentials.
+ *
+ * This is the minimum-permission policy that the GraphQL server's
+ * S3 access key should have. It only allows PutObject, GetObject,
+ * and HeadObject — no delete, no list, no bucket management.
+ *
+ * @param bucketName - S3 bucket name
+ */
+export function buildPresignedUrlIamPolicy(bucketName) {
+    return {
+        Version: '2012-10-17',
+        Statement: [
+            {
+                Sid: 'PresignedUrlPluginAccess',
+                Effect: 'Allow',
+                Principal: '*',
+                Action: ['s3:PutObject', 's3:GetObject', 's3:HeadObject'],
+                Resource: `arn:aws:s3:::${bucketName}/*`,
+            },
+        ],
+    };
+}

package/esm/provisioner.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Bucket Provisioner — core provisioning logic.
+ *
+ * Orchestrates S3 bucket creation, privacy configuration, CORS setup,
+ * versioning, and lifecycle rules. Uses the AWS SDK S3 client for all
+ * operations, which works with any S3-compatible backend (MinIO, R2, etc.).
+ *
+ * Privacy model:
+ * - Private/temp buckets: Block All Public Access, no bucket policy, presigned URLs only
+ * - Public buckets: Block Public Access partially relaxed, public-read bucket policy applied
+ */
+import type { S3Client } from '@aws-sdk/client-s3';
+import type { StorageConnectionConfig, CreateBucketOptions, UpdateCorsOptions, CorsRule, LifecycleRule, ProvisionResult, BucketAccessType } from './types';
+import type { BucketPolicyDocument, PublicAccessBlockConfig } from './policies';
+/**
+ * Options for the BucketProvisioner constructor.
+ */
+export interface BucketProvisionerOptions {
+    /** Storage connection config — credentials, endpoint, provider */
+    connection: StorageConnectionConfig;
+    /**
+     * Default allowed origins for CORS rules.
+     * These are the domains where your app runs (e.g., ["https://app.example.com"]).
+     * Required for browser-based presigned URL uploads.
+     */
+    allowedOrigins: string[];
+}
+/**
+ * The BucketProvisioner handles creating and configuring S3-compatible
+ * buckets with the correct privacy settings, CORS rules, and policies
+ * for the Constructive storage module.
+ *
+ * @example
+ * ```typescript
+ * 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
+ * const result = await provisioner.provision({
+ *   bucketName: 'my-app-storage',
+ *   accessType: 'private',
+ * });
+ * ```
+ */
+export declare class BucketProvisioner {
+    private readonly client;
+    private readonly config;
+    private readonly allowedOrigins;
+    constructor(options: BucketProvisionerOptions);
+    /**
+     * Get the underlying S3Client instance.
+     * Useful for advanced operations not covered by the provisioner.
+     */
+    getClient(): S3Client;
+    /**
+     * Provision a fully configured S3 bucket.
+     *
+     * This is the main entry point. It:
+     * 1. Creates the bucket (or verifies it exists)
+     * 2. Configures Block Public Access based on access type
+     * 3. Applies the appropriate bucket policy (public-read or none)
+     * 4. Sets CORS rules for presigned URL uploads
+     * 5. Optionally enables versioning
+     * 6. Optionally adds lifecycle rules (auto-enabled for temp buckets)
+     *
+     * @param options - Bucket creation options
+     * @returns ProvisionResult with all configuration details
+     */
+    provision(options: CreateBucketOptions): Promise<ProvisionResult>;
+    /**
+     * Create an S3 bucket. Handles the "bucket already exists" case gracefully.
+     */
+    createBucket(bucketName: string, region?: string): Promise<void>;
+    /**
+     * Check if a bucket exists and is accessible.
+     */
+    bucketExists(bucketName: string): Promise<boolean>;
+    /**
+     * Configure S3 Block Public Access settings.
+     */
+    setPublicAccessBlock(bucketName: string, config: PublicAccessBlockConfig): Promise<void>;
+    /**
+     * Apply an S3 bucket policy.
+     */
+    setBucketPolicy(bucketName: string, policy: BucketPolicyDocument): Promise<void>;
+    /**
+     * Delete an S3 bucket policy (used to clear leftover public policies).
+     */
+    deleteBucketPolicy(bucketName: string): Promise<void>;
+    /**
+     * Set CORS configuration on an S3 bucket.
+     */
+    setCors(bucketName: string, rules: CorsRule[]): Promise<void>;
+    /**
+     * Enable versioning on an S3 bucket.
+     */
+    enableVersioning(bucketName: string): Promise<void>;
+    /**
+     * Set lifecycle rules on an S3 bucket.
+     */
+    setLifecycleRules(bucketName: string, rules: LifecycleRule[]): Promise<void>;
+    /**
+     * Update CORS configuration on an existing S3 bucket.
+     *
+     * Call this when the `allowed_origins` column changes on a bucket row.
+     * Builds the appropriate CORS rule set for the bucket's access type
+     * and applies it to the S3 bucket.
+     *
+     * @param options - Bucket name, access type, and new allowed origins
+     * @returns The CORS rules that were applied
+     */
+    updateCors(options: UpdateCorsOptions): Promise<CorsRule[]>;
+    /**
+     * Inspect the current configuration of an existing bucket.
+     *
+     * Reads the bucket's policy, CORS, versioning, lifecycle, and public access
+     * settings and returns them in a structured format. Useful for auditing
+     * or verifying that a bucket is correctly configured.
+     *
+     * @param bucketName - S3 bucket name
+     * @param accessType - Expected access type (used in the result)
+     */
+    inspect(bucketName: string, accessType: BucketAccessType): Promise<ProvisionResult>;
+    private getPublicAccessBlock;
+    private getBucketPolicy;
+    private getBucketCors;
+    private getBucketVersioning;
+    private getBucketLifecycle;
+}