@constructive-io/bucket-provisioner 0.2.0

package/provisioner.js

@@ -0,0 +1,401 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BucketProvisioner = void 0;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const types_1 = require("./types");
+const client_1 = require("./client");
+const policies_1 = require("./policies");
+const cors_1 = require("./cors");
+const lifecycle_1 = require("./lifecycle");
+/**
+ * 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',
+ * });
+ * ```
+ */
+class BucketProvisioner {
+    client;
+    config;
+    allowedOrigins;
+    constructor(options) {
+        if (!options.allowedOrigins || options.allowedOrigins.length === 0) {
+            throw new types_1.ProvisionerError('INVALID_CONFIG', 'allowedOrigins must contain at least one origin for CORS configuration');
+        }
+        this.config = options.connection;
+        this.allowedOrigins = options.allowedOrigins;
+        this.client = (0, client_1.createS3Client)(options.connection);
+    }
+    /**
+     * Get the underlying S3Client instance.
+     * Useful for advanced operations not covered by the provisioner.
+     */
+    getClient() {
+        return this.client;
+    }
+    /**
+     * 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
+     */
+    async provision(options) {
+        const { bucketName, accessType, versioning = false } = options;
+        const region = options.region ?? this.config.region;
+        // 1. Create the bucket
+        await this.createBucket(bucketName, region);
+        // 2. Configure Block Public Access
+        const publicAccessBlock = (0, policies_1.getPublicAccessBlock)(accessType);
+        await this.setPublicAccessBlock(bucketName, publicAccessBlock);
+        // 3. Apply bucket policy
+        if (accessType === 'public') {
+            const policy = (0, policies_1.buildPublicReadPolicy)(bucketName);
+            await this.setBucketPolicy(bucketName, policy);
+        }
+        else {
+            // Ensure no leftover public policy on private/temp buckets
+            await this.deleteBucketPolicy(bucketName);
+        }
+        // 4. Set CORS rules (per-bucket override takes precedence over default)
+        const effectiveOrigins = options.allowedOrigins ?? this.allowedOrigins;
+        const corsRules = accessType === 'private'
+            ? (0, cors_1.buildPrivateCorsRules)(effectiveOrigins)
+            : (0, cors_1.buildUploadCorsRules)(effectiveOrigins);
+        await this.setCors(bucketName, corsRules);
+        // 5. Versioning
+        if (versioning) {
+            await this.enableVersioning(bucketName);
+        }
+        // 6. Lifecycle rules for temp buckets
+        const lifecycleRules = [];
+        if (accessType === 'temp') {
+            const tempRule = (0, lifecycle_1.buildTempCleanupRule)(1);
+            lifecycleRules.push(tempRule);
+            await this.setLifecycleRules(bucketName, lifecycleRules);
+        }
+        // Build result
+        const publicUrlPrefix = accessType === 'public'
+            ? (options.publicUrlPrefix ?? null)
+            : null;
+        return {
+            bucketName,
+            accessType,
+            endpoint: this.config.endpoint ?? null,
+            provider: this.config.provider,
+            region,
+            publicUrlPrefix,
+            blockPublicAccess: accessType !== 'public',
+            versioning,
+            corsRules,
+            lifecycleRules,
+        };
+    }
+    /**
+     * Create an S3 bucket. Handles the "bucket already exists" case gracefully.
+     */
+    async createBucket(bucketName, region) {
+        try {
+            const command = new client_s3_1.CreateBucketCommand({
+                Bucket: bucketName,
+                ...(region && region !== 'us-east-1'
+                    ? { CreateBucketConfiguration: { LocationConstraint: region } }
+                    : {}),
+            });
+            await this.client.send(command);
+        }
+        catch (err) {
+            // Bucket already exists and we own it — that's fine
+            if (err.name === 'BucketAlreadyOwnedByYou' ||
+                err.name === 'BucketAlreadyExists' ||
+                err.Code === 'BucketAlreadyOwnedByYou' ||
+                err.Code === 'BucketAlreadyExists') {
+                return;
+            }
+            throw new types_1.ProvisionerError('PROVIDER_ERROR', `Failed to create bucket '${bucketName}': ${err.message}`, err);
+        }
+    }
+    /**
+     * Check if a bucket exists and is accessible.
+     */
+    async bucketExists(bucketName) {
+        try {
+            await this.client.send(new client_s3_1.HeadBucketCommand({ Bucket: bucketName }));
+            return true;
+        }
+        catch (err) {
+            if (err.name === 'NotFound' || err.$metadata?.httpStatusCode === 404) {
+                return false;
+            }
+            if (err.$metadata?.httpStatusCode === 403) {
+                throw new types_1.ProvisionerError('ACCESS_DENIED', `Access denied to bucket '${bucketName}'`, err);
+            }
+            throw new types_1.ProvisionerError('PROVIDER_ERROR', `Failed to check bucket '${bucketName}': ${err.message}`, err);
+        }
+    }
+    /**
+     * Configure S3 Block Public Access settings.
+     */
+    async setPublicAccessBlock(bucketName, config) {
+        try {
+            await this.client.send(new client_s3_1.PutPublicAccessBlockCommand({
+                Bucket: bucketName,
+                PublicAccessBlockConfiguration: config,
+            }));
+        }
+        catch (err) {
+            throw new types_1.ProvisionerError('POLICY_FAILED', `Failed to set public access block on '${bucketName}': ${err.message}`, err);
+        }
+    }
+    /**
+     * Apply an S3 bucket policy.
+     */
+    async setBucketPolicy(bucketName, policy) {
+        try {
+            await this.client.send(new client_s3_1.PutBucketPolicyCommand({
+                Bucket: bucketName,
+                Policy: JSON.stringify(policy),
+            }));
+        }
+        catch (err) {
+            throw new types_1.ProvisionerError('POLICY_FAILED', `Failed to set bucket policy on '${bucketName}': ${err.message}`, err);
+        }
+    }
+    /**
+     * Delete an S3 bucket policy (used to clear leftover public policies).
+     */
+    async deleteBucketPolicy(bucketName) {
+        try {
+            await this.client.send(new client_s3_1.DeleteBucketPolicyCommand({ Bucket: bucketName }));
+        }
+        catch (err) {
+            // No policy to delete — that's fine
+            if (err.name === 'NoSuchBucketPolicy' || err.$metadata?.httpStatusCode === 404) {
+                return;
+            }
+            throw new types_1.ProvisionerError('POLICY_FAILED', `Failed to delete bucket policy on '${bucketName}': ${err.message}`, err);
+        }
+    }
+    /**
+     * Set CORS configuration on an S3 bucket.
+     */
+    async setCors(bucketName, rules) {
+        try {
+            await this.client.send(new client_s3_1.PutBucketCorsCommand({
+                Bucket: bucketName,
+                CORSConfiguration: {
+                    CORSRules: rules.map((rule) => ({
+                        AllowedOrigins: rule.allowedOrigins,
+                        AllowedMethods: rule.allowedMethods,
+                        AllowedHeaders: rule.allowedHeaders,
+                        ExposeHeaders: rule.exposedHeaders,
+                        MaxAgeSeconds: rule.maxAgeSeconds,
+                    })),
+                },
+            }));
+        }
+        catch (err) {
+            throw new types_1.ProvisionerError('CORS_FAILED', `Failed to set CORS on '${bucketName}': ${err.message}`, err);
+        }
+    }
+    /**
+     * Enable versioning on an S3 bucket.
+     */
+    async enableVersioning(bucketName) {
+        try {
+            await this.client.send(new client_s3_1.PutBucketVersioningCommand({
+                Bucket: bucketName,
+                VersioningConfiguration: { Status: 'Enabled' },
+            }));
+        }
+        catch (err) {
+            throw new types_1.ProvisionerError('VERSIONING_FAILED', `Failed to enable versioning on '${bucketName}': ${err.message}`, err);
+        }
+    }
+    /**
+     * Set lifecycle rules on an S3 bucket.
+     */
+    async setLifecycleRules(bucketName, rules) {
+        try {
+            await this.client.send(new client_s3_1.PutBucketLifecycleConfigurationCommand({
+                Bucket: bucketName,
+                LifecycleConfiguration: {
+                    Rules: rules.map((rule) => ({
+                        ID: rule.id,
+                        Filter: { Prefix: rule.prefix },
+                        Status: rule.enabled ? 'Enabled' : 'Disabled',
+                        Expiration: { Days: rule.expirationDays },
+                    })),
+                },
+            }));
+        }
+        catch (err) {
+            throw new types_1.ProvisionerError('LIFECYCLE_FAILED', `Failed to set lifecycle rules on '${bucketName}': ${err.message}`, err);
+        }
+    }
+    /**
+     * 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
+     */
+    async updateCors(options) {
+        const { bucketName, accessType, allowedOrigins } = options;
+        if (!allowedOrigins || allowedOrigins.length === 0) {
+            throw new types_1.ProvisionerError('INVALID_CONFIG', 'allowedOrigins must contain at least one origin for CORS configuration');
+        }
+        const corsRules = accessType === 'private'
+            ? (0, cors_1.buildPrivateCorsRules)(allowedOrigins)
+            : (0, cors_1.buildUploadCorsRules)(allowedOrigins);
+        await this.setCors(bucketName, corsRules);
+        return corsRules;
+    }
+    /**
+     * 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)
+     */
+    async inspect(bucketName, accessType) {
+        const exists = await this.bucketExists(bucketName);
+        if (!exists) {
+            throw new types_1.ProvisionerError('BUCKET_NOT_FOUND', `Bucket '${bucketName}' does not exist`);
+        }
+        // Read all configurations in parallel
+        const [publicAccessBlock, policy, cors, versioning, lifecycle] = await Promise.all([
+            this.getPublicAccessBlock(bucketName),
+            this.getBucketPolicy(bucketName),
+            this.getBucketCors(bucketName),
+            this.getBucketVersioning(bucketName),
+            this.getBucketLifecycle(bucketName),
+        ]);
+        const isFullyBlocked = publicAccessBlock
+            ? publicAccessBlock.BlockPublicAcls === true &&
+                publicAccessBlock.IgnorePublicAcls === true &&
+                publicAccessBlock.BlockPublicPolicy === true &&
+                publicAccessBlock.RestrictPublicBuckets === true
+            : false;
+        return {
+            bucketName,
+            accessType,
+            endpoint: this.config.endpoint ?? null,
+            provider: this.config.provider,
+            region: this.config.region,
+            publicUrlPrefix: null,
+            blockPublicAccess: isFullyBlocked,
+            versioning: versioning === 'Enabled',
+            corsRules: cors,
+            lifecycleRules: lifecycle,
+        };
+    }
+    // --- Private read methods for inspect ---
+    async getPublicAccessBlock(bucketName) {
+        try {
+            const result = await this.client.send(new client_s3_1.GetPublicAccessBlockCommand({ Bucket: bucketName }));
+            const config = result.PublicAccessBlockConfiguration;
+            if (!config)
+                return null;
+            return {
+                BlockPublicAcls: config.BlockPublicAcls ?? false,
+                IgnorePublicAcls: config.IgnorePublicAcls ?? false,
+                BlockPublicPolicy: config.BlockPublicPolicy ?? false,
+                RestrictPublicBuckets: config.RestrictPublicBuckets ?? false,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    async getBucketPolicy(bucketName) {
+        try {
+            const result = await this.client.send(new client_s3_1.GetBucketPolicyCommand({ Bucket: bucketName }));
+            return result.Policy ? JSON.parse(result.Policy) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async getBucketCors(bucketName) {
+        try {
+            const result = await this.client.send(new client_s3_1.GetBucketCorsCommand({ Bucket: bucketName }));
+            return (result.CORSRules ?? []).map((rule) => ({
+                allowedOrigins: rule.AllowedOrigins ?? [],
+                allowedMethods: (rule.AllowedMethods ?? []),
+                allowedHeaders: rule.AllowedHeaders ?? [],
+                exposedHeaders: rule.ExposeHeaders ?? [],
+                maxAgeSeconds: rule.MaxAgeSeconds ?? 0,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    async getBucketVersioning(bucketName) {
+        try {
+            const result = await this.client.send(new client_s3_1.GetBucketVersioningCommand({ Bucket: bucketName }));
+            return result.Status ?? 'Disabled';
+        }
+        catch {
+            return 'Disabled';
+        }
+    }
+    async getBucketLifecycle(bucketName) {
+        try {
+            const result = await this.client.send(new client_s3_1.GetBucketLifecycleConfigurationCommand({ Bucket: bucketName }));
+            return (result.Rules ?? []).map((rule) => ({
+                id: rule.ID ?? '',
+                prefix: rule.Filter?.Prefix ?? '',
+                expirationDays: rule.Expiration?.Days ?? 0,
+                enabled: rule.Status === 'Enabled',
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+}
+exports.BucketProvisioner = BucketProvisioner;

package/types.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Types for the bucket provisioner library.
+ *
+ * Defines the configuration interfaces for S3-compatible storage providers,
+ * bucket creation options, privacy policies, and CORS rules.
+ */
+/**
+ * Supported storage provider identifiers.
+ *
+ * Used to select provider-specific behavior (e.g., path-style URLs for MinIO,
+ * jurisdiction headers for R2).
+ */
+export type StorageProvider = 's3' | 'minio' | 'r2' | 'gcs' | 'spaces';
+/**
+ * Connection configuration for an S3-compatible storage backend.
+ *
+ * This is the input you provide to connect to your storage provider.
+ * For AWS S3, only `region` and credentials are needed.
+ * For MinIO/R2/etc., also provide `endpoint`.
+ */
+export interface StorageConnectionConfig {
+    /** Storage provider type */
+    provider: StorageProvider;
+    /** S3 region (e.g., "us-east-1"). Required for AWS S3. */
+    region: string;
+    /** S3-compatible endpoint URL (e.g., "http://minio:9000"). Required for non-AWS providers. */
+    endpoint?: string;
+    /** AWS access key ID */
+    accessKeyId: string;
+    /** AWS secret access key */
+    secretAccessKey: string;
+    /** Use path-style URLs (required for MinIO, optional for others) */
+    forcePathStyle?: boolean;
+}
+/**
+ * Bucket access type, matching the database bucket `type` column.
+ *
+ * - `public`: Files served via CDN/public URL. Bucket policy allows public reads.
+ * - `private`: Files served via presigned GET URLs only. No public access.
+ * - `temp`: Staging area for uploads. Treated as private. Lifecycle rules may apply.
+ */
+export type BucketAccessType = 'public' | 'private' | 'temp';
+/**
+ * Options for creating or configuring an S3 bucket.
+ */
+export interface CreateBucketOptions {
+    /** The S3 bucket name (globally unique for AWS, locally unique for MinIO) */
+    bucketName: string;
+    /** Bucket access type — determines which policies are applied */
+    accessType: BucketAccessType;
+    /** S3 region for bucket creation (defaults to connection config region) */
+    region?: string;
+    /** Whether to enable versioning (recommended for durability) */
+    versioning?: boolean;
+    /**
+     * Public URL prefix for public buckets.
+     * This is the CDN or public endpoint URL that serves files from the bucket.
+     * Only meaningful for `accessType: 'public'`.
+     * Example: "https://cdn.example.com/public"
+     */
+    publicUrlPrefix?: string;
+    /**
+     * Per-bucket CORS allowed origins override.
+     * When provided, these origins are used instead of the provisioner's default allowedOrigins.
+     * Use ['*'] for open/CDN mode (wildcard CORS, any origin can fetch).
+     * NULL/undefined = use the provisioner's default allowedOrigins.
+     */
+    allowedOrigins?: string[];
+}
+/**
+ * Options for updating CORS on an existing S3 bucket.
+ */
+export interface UpdateCorsOptions {
+    /** The S3 bucket name */
+    bucketName: string;
+    /** Bucket access type — determines which CORS rule set to apply */
+    accessType: BucketAccessType;
+    /** The allowed origins to set. Use ['*'] for open/CDN mode. */
+    allowedOrigins: string[];
+}
+/**
+ * CORS rule for S3 bucket configuration.
+ *
+ * Required for browser-based presigned URL uploads.
+ * The presigned PUT request is a cross-origin request from the client
+ * to the S3 endpoint, so CORS must be configured on the bucket.
+ */
+export interface CorsRule {
+    /** Allowed origin domains (e.g., ["https://app.example.com"]) */
+    allowedOrigins: string[];
+    /** Allowed HTTP methods */
+    allowedMethods: ('GET' | 'PUT' | 'HEAD' | 'POST' | 'DELETE')[];
+    /** Allowed request headers */
+    allowedHeaders: string[];
+    /** Headers exposed to the browser */
+    exposedHeaders: string[];
+    /** Preflight cache duration in seconds */
+    maxAgeSeconds: number;
+}
+/**
+ * Lifecycle rule for automatic object expiration.
+ *
+ * Useful for temp buckets where uploads expire after a set period.
+ */
+export interface LifecycleRule {
+    /** Rule ID (descriptive name) */
+    id: string;
+    /** S3 key prefix to apply the rule to (empty string = entire bucket) */
+    prefix: string;
+    /** Number of days after which objects expire */
+    expirationDays: number;
+    /** Whether the rule is enabled */
+    enabled: boolean;
+}
+/**
+ * Result of a bucket provisioning operation.
+ *
+ * Contains all the information needed to configure the `storage_module`
+ * table and the presigned URL plugin.
+ */
+export interface ProvisionResult {
+    /** The S3 bucket name */
+    bucketName: string;
+    /** Bucket access type */
+    accessType: BucketAccessType;
+    /** S3 endpoint URL (null for AWS S3 default) */
+    endpoint: string | null;
+    /** Storage provider type */
+    provider: StorageProvider;
+    /** S3 region */
+    region: string;
+    /**
+     * Public URL prefix for download URLs.
+     * For public buckets: the CDN/public endpoint.
+     * For private buckets: null (presigned URLs only).
+     */
+    publicUrlPrefix: string | null;
+    /** Whether Block Public Access is enabled */
+    blockPublicAccess: boolean;
+    /** Whether versioning is enabled */
+    versioning: boolean;
+    /** CORS rules applied */
+    corsRules: CorsRule[];
+    /** Lifecycle rules applied */
+    lifecycleRules: LifecycleRule[];
+}
+export type ProvisionerErrorCode = 'CONNECTION_FAILED' | 'BUCKET_ALREADY_EXISTS' | 'BUCKET_NOT_FOUND' | 'INVALID_CONFIG' | 'POLICY_FAILED' | 'CORS_FAILED' | 'LIFECYCLE_FAILED' | 'VERSIONING_FAILED' | 'ACCESS_DENIED' | 'PROVIDER_ERROR';
+/**
+ * Structured error thrown by the bucket provisioner.
+ */
+export declare class ProvisionerError extends Error {
+    readonly code: ProvisionerErrorCode;
+    readonly cause?: unknown;
+    constructor(code: ProvisionerErrorCode, message: string, cause?: unknown);
+}

package/types.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Types for the bucket provisioner library.
+ *
+ * Defines the configuration interfaces for S3-compatible storage providers,
+ * bucket creation options, privacy policies, and CORS rules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProvisionerError = void 0;
+/**
+ * Structured error thrown by the bucket provisioner.
+ */
+class ProvisionerError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.name = 'ProvisionerError';
+        this.code = code;
+        this.cause = cause;
+    }
+}
+exports.ProvisionerError = ProvisionerError;