@constructive-io/bucket-provisioner 0.2.0

package/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/lifecycle.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTempCleanupRule = buildTempCleanupRule;
+exports.buildAbortIncompleteMultipartRule = buildAbortIncompleteMultipartRule;
+/**
+ * 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)
+ */
+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)
+ */
+function buildAbortIncompleteMultipartRule(expirationDays = 1) {
+    return {
+        id: 'abort-incomplete-multipart',
+        prefix: '',
+        expirationDays,
+        enabled: true,
+    };
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@constructive-io/bucket-provisioner",
+  "version": "0.2.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "S3-compatible bucket provisioning library — create buckets, configure privacy policies, CORS, and access controls",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1009.0"
+  },
+  "devDependencies": {
+    "makage": "^0.3.0"
+  },
+  "keywords": [
+    "s3",
+    "bucket",
+    "provisioner",
+    "minio",
+    "cloudflare-r2",
+    "storage",
+    "constructive"
+  ],
+  "gitHead": "fe60f7b81252eea53dce227bb581d5ae2ef0ec36"
+}

package/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/policies.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPublicAccessBlock = getPublicAccessBlock;
+exports.buildPublicReadPolicy = buildPublicReadPolicy;
+exports.buildCloudFrontOacPolicy = buildCloudFrontOacPolicy;
+exports.buildPresignedUrlIamPolicy = buildPresignedUrlIamPolicy;
+/**
+ * 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
+ */
+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.
+ */
+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
+ */
+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
+ */
+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/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;
+}