@constructive-io/bucket-provisioner 0.25.1 → 0.26.0

package/README.md

@@ -152,7 +152,7 @@ The main class that orchestrates bucket creation and configuration.
 | `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']`) |
+| `allowedOrigins` | `string[]?` | Domains allowed for CORS (e.g., `['https://app.example.com']`). Empty or omitted means no browser origin may reach these buckets, and they are provisioned with no CORS rule set at all. |
 
 #### `provisioner.provision(options): Promise<ProvisionResult>`
 
@@ -161,7 +161,7 @@ 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
+4. Sets CORS rules for presigned URL uploads (skipped when no origins are allowed)
 5. Optionally enables versioning
 6. Adds lifecycle rules for temp buckets
 
@@ -172,6 +172,7 @@ Creates and configures a bucket. Steps:
 | `region` | `string?` | Override region for this bucket |
 | `versioning` | `boolean?` | Enable S3 versioning (default: `false`) |
 | `publicUrlPrefix` | `string?` | CDN/public URL for public buckets |
+| `allowedOrigins` | `string[]?` | Per-bucket CORS origins, overriding the constructor's |
 
 #### `provisioner.inspect(bucketName, accessType): Promise<ProvisionResult>`
 
@@ -185,6 +186,21 @@ Returns the underlying `@aws-sdk/client-s3` S3Client for advanced operations.
 
 Checks if a bucket exists and is accessible.
 
+### Naming
+
+#### `physicalBucketName({ scope, databaseId, bucketKey })`
+
+The physical name a platform-provisioned bucket gets from its own identity:
+`{scope}-{database label}-{bucketKey}-{digest}`. Takes no prefix — a bucket
+belongs to one database at one scope, and there is no global bucket namespace to
+prefix into. Each readable component has its own budget, so a long scope cannot
+crowd out the database label, and the digest covers the untruncated identity.
+
+#### `mintPhysicalBucketName(prefix, databaseId, bucketKey)`
+
+The prefixed policy — `{prefix}-{bucketKey}-{digest}` — for a deployment that
+names its own bucket namespace.
+
 ### Policy Builders
 
 Standalone functions for generating S3 policy documents.

package/esm/index.d.ts

@@ -28,7 +28,8 @@
  */
 export type { BucketProvisionerOptions } from './provisioner';
 export { BucketProvisioner } from './provisioner';
-export { mintPhysicalBucketName } from './naming';
+export type { PhysicalBucketIdentity } from './naming';
+export { mintPhysicalBucketName, physicalBucketName } from './naming';
 export { createS3Client } from './client';
 export type { BucketPolicyDocument, BucketPolicyStatement, PublicAccessBlockConfig, } from './policies';
 export { buildCloudFrontOacPolicy, buildPresignedUrlIamPolicy, buildPublicReadPolicy, getPublicAccessBlock, } from './policies';

package/esm/index.js

@@ -27,8 +27,7 @@
  * ```
  */
 export { BucketProvisioner } from './provisioner';
-// Physical naming policy
-export { mintPhysicalBucketName } from './naming';
+export { mintPhysicalBucketName, physicalBucketName } from './naming';
 // S3 client factory
 export { createS3Client } from './client';
 export { buildCloudFrontOacPolicy, buildPresignedUrlIamPolicy, buildPublicReadPolicy, getPublicAccessBlock, } from './policies';

package/esm/naming.d.ts

@@ -1,18 +1,37 @@
+/** What a physical bucket name is derived from: the bucket row's own identity. */
+export interface PhysicalBucketIdentity {
+    /** The scope the bucket row lives at (`platform`, `database`, an entity scope). */
+    scope: string;
+    /** The database that owns the bucket row. */
+    databaseId: string;
+    /** The bucket's logical key, as declared on the row. */
+    bucketKey: string;
+}
 /**
- * The single physical-bucket naming policy:
- * `{prefix}-{bucketKey}-{digest}` (e.g. `myapp-public-3f9c1a2b7e04`).
+ * The physical name a bucket gets from its own identity:
+ * `{scope}-{database label}-{bucketKey}-{digest}`
+ * (e.g. `database-028752cb-buildlogs-3f9c1a2b7e04`).
+ *
+ * This is the policy for a platform-provisioned bucket, and it takes no prefix
+ * because there is no global bucket namespace to prefix into: a bucket belongs
+ * to one database at one scope, and that is what its name should say. Callers
+ * derive names from here rather than composing a prefix of their own, so the
+ * policy can change in one place — and an already-provisioned bucket never
+ * consults it at all, since the row's recorded `physical_name` is authoritative.
  *
- * Both the presigned-upload (lazy) path and the bucket-provisioner (eager) path
- * derive names from this one function, so a bucket's physical name is identical
- * regardless of which path mints it.
+ * The scope is part of the digested identity untruncated, so two scopes of one
+ * database that declare the same bucket key stay distinct even when their
+ * readable labels truncate to the same thing.
+ */
+export declare function physicalBucketName(identity: PhysicalBucketIdentity): string;
+/**
+ * The prefixed physical-bucket naming policy:
+ * `{prefix}-{bucketKey}-{digest}` (e.g. `myapp-public-3f9c1a2b7e04`).
  *
- * The name is bounded and S3-legal by construction: the prefix and key are
- * sanitized to `[a-z0-9-]` and truncated to a readable budget, and the tail is
- * a digest of the *untruncated* identity — so two buckets whose keys agree only
- * past the truncation point, or the same key in two databases, still get distinct
- * names. Names remain stable for a given (prefix, databaseId, bucketKey) because
- * nothing here reads the clock or a counter; and an already-provisioned bucket
- * never consults this function at all, since `platform_buckets.physical_name` is
- * authoritative once recorded.
+ * For a deployment that names its own bucket namespace — a single-app
+ * installation, or the presigned-upload (lazy) path meeting a bucket an app
+ * configured. A platform-provisioned bucket uses {@link physicalBucketName}
+ * instead, whose components come from the bucket row rather than from
+ * deployment config.
  */
 export declare function mintPhysicalBucketName(prefix: string, databaseId: string, bucketKey: string): string;

package/esm/naming.js

@@ -8,6 +8,25 @@ const IDENTITY_DIGEST_LENGTH = 12;
 /** Readable budget: how much of the name the prefix and key may each occupy. */
 const PREFIX_BUDGET = 20;
 const BUCKET_KEY_BUDGET = 63 - IDENTITY_DIGEST_LENGTH - PREFIX_BUDGET - 3;
+/**
+ * Readable budgets for a name minted from a bucket's own identity.
+ *
+ * Each component gets its own budget rather than sharing one prefix budget, so
+ * a long scope cannot eat the database label (or the label the key) — every
+ * component keeps the room it was given, and the digest below covers whatever
+ * truncation drops.
+ */
+const SCOPE_BUDGET = 12;
+/**
+ * How many characters of the owning database's id the readable head carries:
+ * the first group of a UUID, enough to recognise a tenant in a bucket listing.
+ */
+const DATABASE_LABEL_LENGTH = 8;
+const IDENTITY_KEY_BUDGET = MAX_BUCKET_NAME_LENGTH -
+    IDENTITY_DIGEST_LENGTH -
+    SCOPE_BUDGET -
+    DATABASE_LABEL_LENGTH -
+    3;
 /**
  * Reduce a component to the S3 bucket-name alphabet: lowercase, `[a-z0-9-]`,
  * with runs of separators collapsed and no leading or trailing hyphen.
@@ -22,33 +41,69 @@ function sanitizeBucketNameComponent(value) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+/** A readable component: sanitized, truncated to its own budget, hyphen-free at the edges. */
+function readableComponent(value, budget) {
+    return sanitizeBucketNameComponent(value).slice(0, budget).replace(/-+$/, '');
+}
 /**
- * The single physical-bucket naming policy:
- * `{prefix}-{bucketKey}-{digest}` (e.g. `myapp-public-3f9c1a2b7e04`).
- *
- * Both the presigned-upload (lazy) path and the bucket-provisioner (eager) path
- * derive names from this one function, so a bucket's physical name is identical
- * regardless of which path mints it.
+ * Assemble a bounded, S3-legal name from readable components and the untruncated
+ * identity they were derived from.
  *
- * The name is bounded and S3-legal by construction: the prefix and key are
- * sanitized to `[a-z0-9-]` and truncated to a readable budget, and the tail is
- * a digest of the *untruncated* identity — so two buckets whose keys agree only
- * past the truncation point, or the same key in two databases, still get distinct
- * names. Names remain stable for a given (prefix, databaseId, bucketKey) because
- * nothing here reads the clock or a counter; and an already-provisioned bucket
- * never consults this function at all, since `platform_buckets.physical_name` is
- * authoritative once recorded.
+ * The digest is taken over the identity rather than over what survived
+ * truncation, so two buckets whose components agree only past their budgets
+ * still get distinct names. Nothing here reads the clock or a counter, so a
+ * given identity always mints the same name.
  */
-export function mintPhysicalBucketName(prefix, databaseId, bucketKey) {
-    const identity = `${prefix}/${databaseId}/${bucketKey}`;
-    const digest = createHash('sha256').update(identity).digest('hex').slice(0, IDENTITY_DIGEST_LENGTH);
-    const safePrefix = sanitizeBucketNameComponent(prefix).slice(0, PREFIX_BUDGET).replace(/-+$/, '');
-    const safeKey = sanitizeBucketNameComponent(bucketKey).slice(0, BUCKET_KEY_BUDGET).replace(/-+$/, '');
-    const name = [safePrefix, safeKey, digest].filter((part) => part.length > 0).join('-');
+function assembleBucketName(readable, identity, describeIdentity) {
+    const digest = createHash('sha256')
+        .update(identity)
+        .digest('hex')
+        .slice(0, IDENTITY_DIGEST_LENGTH);
+    const name = [...readable, digest].filter((part) => part.length > 0).join('-');
     // The digest alone already satisfies both bounds, so this is only reachable
-    // when both readable components sanitize away to nothing.
+    // when every readable component sanitizes away to nothing.
     if (name.length < MIN_BUCKET_NAME_LENGTH || name.length > MAX_BUCKET_NAME_LENGTH) {
-        throw new Error(`[bucket-provisioner] Cannot mint a legal S3 bucket name for key "${bucketKey}": got "${name}"`);
+        throw new Error(`[bucket-provisioner] Cannot mint a legal S3 bucket name for ${describeIdentity}: got "${name}"`);
     }
     return name;
 }
+/**
+ * The physical name a bucket gets from its own identity:
+ * `{scope}-{database label}-{bucketKey}-{digest}`
+ * (e.g. `database-028752cb-buildlogs-3f9c1a2b7e04`).
+ *
+ * This is the policy for a platform-provisioned bucket, and it takes no prefix
+ * because there is no global bucket namespace to prefix into: a bucket belongs
+ * to one database at one scope, and that is what its name should say. Callers
+ * derive names from here rather than composing a prefix of their own, so the
+ * policy can change in one place — and an already-provisioned bucket never
+ * consults it at all, since the row's recorded `physical_name` is authoritative.
+ *
+ * The scope is part of the digested identity untruncated, so two scopes of one
+ * database that declare the same bucket key stay distinct even when their
+ * readable labels truncate to the same thing.
+ */
+export function physicalBucketName(identity) {
+    const { scope, databaseId, bucketKey } = identity;
+    return assembleBucketName([
+        readableComponent(scope, SCOPE_BUDGET),
+        readableComponent(databaseId, DATABASE_LABEL_LENGTH),
+        readableComponent(bucketKey, IDENTITY_KEY_BUDGET),
+    ], `${scope}/${databaseId}/${bucketKey}`, `key "${bucketKey}" at scope "${scope}"`);
+}
+/**
+ * The prefixed physical-bucket naming policy:
+ * `{prefix}-{bucketKey}-{digest}` (e.g. `myapp-public-3f9c1a2b7e04`).
+ *
+ * For a deployment that names its own bucket namespace — a single-app
+ * installation, or the presigned-upload (lazy) path meeting a bucket an app
+ * configured. A platform-provisioned bucket uses {@link physicalBucketName}
+ * instead, whose components come from the bucket row rather than from
+ * deployment config.
+ */
+export function mintPhysicalBucketName(prefix, databaseId, bucketKey) {
+    return assembleBucketName([
+        readableComponent(prefix, PREFIX_BUDGET),
+        readableComponent(bucketKey, BUCKET_KEY_BUDGET),
+    ], `${prefix}/${databaseId}/${bucketKey}`, `key "${bucketKey}"`);
+}

package/esm/provisioner.d.ts

@@ -22,8 +22,13 @@ export interface BucketProvisionerOptions {
      * 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.
+     *
+     * Empty (or omitted) means no browser origin may reach these buckets — a
+     * build's log store, say, which only server-side code ever opens. Such a
+     * bucket is provisioned with no CORS rule set at all rather than with a
+     * fabricated origin.
      */
-    allowedOrigins: string[];
+    allowedOrigins?: string[];
 }
 /**
  * The BucketProvisioner handles creating and configuring S3-compatible

package/esm/provisioner.js

@@ -45,11 +45,8 @@ export class BucketProvisioner {
     config;
     allowedOrigins;
     constructor(options) {
-        if (!options.allowedOrigins || options.allowedOrigins.length === 0) {
-            throw new ProvisionerError('INVALID_CONFIG', 'allowedOrigins must contain at least one origin for CORS configuration');
-        }
         this.config = options.connection;
-        this.allowedOrigins = options.allowedOrigins;
+        this.allowedOrigins = options.allowedOrigins ?? [];
         this.client = createS3Client(options.connection);
     }
     /**
@@ -90,12 +87,19 @@ export class BucketProvisioner {
             // Ensure no leftover public policy on private/temp buckets
             await this.deleteBucketPolicy(bucketName);
         }
-        // 4. Set CORS rules (per-bucket override takes precedence over default)
+        // 4. Set CORS rules (per-bucket override takes precedence over default).
+        // A bucket no browser origin may reach gets no rule set: cross-origin
+        // access is the bucket's own recorded data, and "none recorded" is a
+        // legitimate answer, not a missing setting to invent an origin for.
         const effectiveOrigins = options.allowedOrigins ?? this.allowedOrigins;
-        const corsRules = accessType === 'private'
-            ? buildPrivateCorsRules(effectiveOrigins)
-            : buildUploadCorsRules(effectiveOrigins);
-        await this.setCors(bucketName, corsRules);
+        const corsRules = effectiveOrigins.length === 0
+            ? []
+            : accessType === 'private'
+                ? buildPrivateCorsRules(effectiveOrigins)
+                : buildUploadCorsRules(effectiveOrigins);
+        if (corsRules.length > 0) {
+            await this.setCors(bucketName, corsRules);
+        }
         // 5. Versioning
         if (versioning) {
             await this.enableVersioning(bucketName);

package/index.d.ts

@@ -28,7 +28,8 @@
  */
 export type { BucketProvisionerOptions } from './provisioner';
 export { BucketProvisioner } from './provisioner';
-export { mintPhysicalBucketName } from './naming';
+export type { PhysicalBucketIdentity } from './naming';
+export { mintPhysicalBucketName, physicalBucketName } from './naming';
 export { createS3Client } from './client';
 export type { BucketPolicyDocument, BucketPolicyStatement, PublicAccessBlockConfig, } from './policies';
 export { buildCloudFrontOacPolicy, buildPresignedUrlIamPolicy, buildPublicReadPolicy, getPublicAccessBlock, } from './policies';

package/index.js

@@ -28,12 +28,12 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProvisionerError = exports.buildTempCleanupRule = exports.buildAbortIncompleteMultipartRule = exports.buildUploadCorsRules = exports.buildPrivateCorsRules = exports.getPublicAccessBlock = exports.buildPublicReadPolicy = exports.buildPresignedUrlIamPolicy = exports.buildCloudFrontOacPolicy = exports.createS3Client = exports.mintPhysicalBucketName = exports.BucketProvisioner = void 0;
+exports.ProvisionerError = exports.buildTempCleanupRule = exports.buildAbortIncompleteMultipartRule = exports.buildUploadCorsRules = exports.buildPrivateCorsRules = exports.getPublicAccessBlock = exports.buildPublicReadPolicy = exports.buildPresignedUrlIamPolicy = exports.buildCloudFrontOacPolicy = exports.createS3Client = exports.physicalBucketName = exports.mintPhysicalBucketName = exports.BucketProvisioner = void 0;
 var provisioner_1 = require("./provisioner");
 Object.defineProperty(exports, "BucketProvisioner", { enumerable: true, get: function () { return provisioner_1.BucketProvisioner; } });
-// Physical naming policy
 var naming_1 = require("./naming");
 Object.defineProperty(exports, "mintPhysicalBucketName", { enumerable: true, get: function () { return naming_1.mintPhysicalBucketName; } });
+Object.defineProperty(exports, "physicalBucketName", { enumerable: true, get: function () { return naming_1.physicalBucketName; } });
 // S3 client factory
 var client_1 = require("./client");
 Object.defineProperty(exports, "createS3Client", { enumerable: true, get: function () { return client_1.createS3Client; } });

package/naming.d.ts

@@ -1,18 +1,37 @@
+/** What a physical bucket name is derived from: the bucket row's own identity. */
+export interface PhysicalBucketIdentity {
+    /** The scope the bucket row lives at (`platform`, `database`, an entity scope). */
+    scope: string;
+    /** The database that owns the bucket row. */
+    databaseId: string;
+    /** The bucket's logical key, as declared on the row. */
+    bucketKey: string;
+}
 /**
- * The single physical-bucket naming policy:
- * `{prefix}-{bucketKey}-{digest}` (e.g. `myapp-public-3f9c1a2b7e04`).
+ * The physical name a bucket gets from its own identity:
+ * `{scope}-{database label}-{bucketKey}-{digest}`
+ * (e.g. `database-028752cb-buildlogs-3f9c1a2b7e04`).
+ *
+ * This is the policy for a platform-provisioned bucket, and it takes no prefix
+ * because there is no global bucket namespace to prefix into: a bucket belongs
+ * to one database at one scope, and that is what its name should say. Callers
+ * derive names from here rather than composing a prefix of their own, so the
+ * policy can change in one place — and an already-provisioned bucket never
+ * consults it at all, since the row's recorded `physical_name` is authoritative.
  *
- * Both the presigned-upload (lazy) path and the bucket-provisioner (eager) path
- * derive names from this one function, so a bucket's physical name is identical
- * regardless of which path mints it.
+ * The scope is part of the digested identity untruncated, so two scopes of one
+ * database that declare the same bucket key stay distinct even when their
+ * readable labels truncate to the same thing.
+ */
+export declare function physicalBucketName(identity: PhysicalBucketIdentity): string;
+/**
+ * The prefixed physical-bucket naming policy:
+ * `{prefix}-{bucketKey}-{digest}` (e.g. `myapp-public-3f9c1a2b7e04`).
  *
- * The name is bounded and S3-legal by construction: the prefix and key are
- * sanitized to `[a-z0-9-]` and truncated to a readable budget, and the tail is
- * a digest of the *untruncated* identity — so two buckets whose keys agree only
- * past the truncation point, or the same key in two databases, still get distinct
- * names. Names remain stable for a given (prefix, databaseId, bucketKey) because
- * nothing here reads the clock or a counter; and an already-provisioned bucket
- * never consults this function at all, since `platform_buckets.physical_name` is
- * authoritative once recorded.
+ * For a deployment that names its own bucket namespace — a single-app
+ * installation, or the presigned-upload (lazy) path meeting a bucket an app
+ * configured. A platform-provisioned bucket uses {@link physicalBucketName}
+ * instead, whose components come from the bucket row rather than from
+ * deployment config.
  */
 export declare function mintPhysicalBucketName(prefix: string, databaseId: string, bucketKey: string): string;

package/naming.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.physicalBucketName = physicalBucketName;
 exports.mintPhysicalBucketName = mintPhysicalBucketName;
 const crypto_1 = require("crypto");
 /** S3's hard ceiling on a bucket name. */
@@ -11,6 +12,25 @@ const IDENTITY_DIGEST_LENGTH = 12;
 /** Readable budget: how much of the name the prefix and key may each occupy. */
 const PREFIX_BUDGET = 20;
 const BUCKET_KEY_BUDGET = 63 - IDENTITY_DIGEST_LENGTH - PREFIX_BUDGET - 3;
+/**
+ * Readable budgets for a name minted from a bucket's own identity.
+ *
+ * Each component gets its own budget rather than sharing one prefix budget, so
+ * a long scope cannot eat the database label (or the label the key) — every
+ * component keeps the room it was given, and the digest below covers whatever
+ * truncation drops.
+ */
+const SCOPE_BUDGET = 12;
+/**
+ * How many characters of the owning database's id the readable head carries:
+ * the first group of a UUID, enough to recognise a tenant in a bucket listing.
+ */
+const DATABASE_LABEL_LENGTH = 8;
+const IDENTITY_KEY_BUDGET = MAX_BUCKET_NAME_LENGTH -
+    IDENTITY_DIGEST_LENGTH -
+    SCOPE_BUDGET -
+    DATABASE_LABEL_LENGTH -
+    3;
 /**
  * Reduce a component to the S3 bucket-name alphabet: lowercase, `[a-z0-9-]`,
  * with runs of separators collapsed and no leading or trailing hyphen.
@@ -25,33 +45,69 @@ function sanitizeBucketNameComponent(value) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+/** A readable component: sanitized, truncated to its own budget, hyphen-free at the edges. */
+function readableComponent(value, budget) {
+    return sanitizeBucketNameComponent(value).slice(0, budget).replace(/-+$/, '');
+}
 /**
- * The single physical-bucket naming policy:
- * `{prefix}-{bucketKey}-{digest}` (e.g. `myapp-public-3f9c1a2b7e04`).
- *
- * Both the presigned-upload (lazy) path and the bucket-provisioner (eager) path
- * derive names from this one function, so a bucket's physical name is identical
- * regardless of which path mints it.
+ * Assemble a bounded, S3-legal name from readable components and the untruncated
+ * identity they were derived from.
  *
- * The name is bounded and S3-legal by construction: the prefix and key are
- * sanitized to `[a-z0-9-]` and truncated to a readable budget, and the tail is
- * a digest of the *untruncated* identity — so two buckets whose keys agree only
- * past the truncation point, or the same key in two databases, still get distinct
- * names. Names remain stable for a given (prefix, databaseId, bucketKey) because
- * nothing here reads the clock or a counter; and an already-provisioned bucket
- * never consults this function at all, since `platform_buckets.physical_name` is
- * authoritative once recorded.
+ * The digest is taken over the identity rather than over what survived
+ * truncation, so two buckets whose components agree only past their budgets
+ * still get distinct names. Nothing here reads the clock or a counter, so a
+ * given identity always mints the same name.
  */
-function mintPhysicalBucketName(prefix, databaseId, bucketKey) {
-    const identity = `${prefix}/${databaseId}/${bucketKey}`;
-    const digest = (0, crypto_1.createHash)('sha256').update(identity).digest('hex').slice(0, IDENTITY_DIGEST_LENGTH);
-    const safePrefix = sanitizeBucketNameComponent(prefix).slice(0, PREFIX_BUDGET).replace(/-+$/, '');
-    const safeKey = sanitizeBucketNameComponent(bucketKey).slice(0, BUCKET_KEY_BUDGET).replace(/-+$/, '');
-    const name = [safePrefix, safeKey, digest].filter((part) => part.length > 0).join('-');
+function assembleBucketName(readable, identity, describeIdentity) {
+    const digest = (0, crypto_1.createHash)('sha256')
+        .update(identity)
+        .digest('hex')
+        .slice(0, IDENTITY_DIGEST_LENGTH);
+    const name = [...readable, digest].filter((part) => part.length > 0).join('-');
     // The digest alone already satisfies both bounds, so this is only reachable
-    // when both readable components sanitize away to nothing.
+    // when every readable component sanitizes away to nothing.
     if (name.length < MIN_BUCKET_NAME_LENGTH || name.length > MAX_BUCKET_NAME_LENGTH) {
-        throw new Error(`[bucket-provisioner] Cannot mint a legal S3 bucket name for key "${bucketKey}": got "${name}"`);
+        throw new Error(`[bucket-provisioner] Cannot mint a legal S3 bucket name for ${describeIdentity}: got "${name}"`);
     }
     return name;
 }
+/**
+ * The physical name a bucket gets from its own identity:
+ * `{scope}-{database label}-{bucketKey}-{digest}`
+ * (e.g. `database-028752cb-buildlogs-3f9c1a2b7e04`).
+ *
+ * This is the policy for a platform-provisioned bucket, and it takes no prefix
+ * because there is no global bucket namespace to prefix into: a bucket belongs
+ * to one database at one scope, and that is what its name should say. Callers
+ * derive names from here rather than composing a prefix of their own, so the
+ * policy can change in one place — and an already-provisioned bucket never
+ * consults it at all, since the row's recorded `physical_name` is authoritative.
+ *
+ * The scope is part of the digested identity untruncated, so two scopes of one
+ * database that declare the same bucket key stay distinct even when their
+ * readable labels truncate to the same thing.
+ */
+function physicalBucketName(identity) {
+    const { scope, databaseId, bucketKey } = identity;
+    return assembleBucketName([
+        readableComponent(scope, SCOPE_BUDGET),
+        readableComponent(databaseId, DATABASE_LABEL_LENGTH),
+        readableComponent(bucketKey, IDENTITY_KEY_BUDGET),
+    ], `${scope}/${databaseId}/${bucketKey}`, `key "${bucketKey}" at scope "${scope}"`);
+}
+/**
+ * The prefixed physical-bucket naming policy:
+ * `{prefix}-{bucketKey}-{digest}` (e.g. `myapp-public-3f9c1a2b7e04`).
+ *
+ * For a deployment that names its own bucket namespace — a single-app
+ * installation, or the presigned-upload (lazy) path meeting a bucket an app
+ * configured. A platform-provisioned bucket uses {@link physicalBucketName}
+ * instead, whose components come from the bucket row rather than from
+ * deployment config.
+ */
+function mintPhysicalBucketName(prefix, databaseId, bucketKey) {
+    return assembleBucketName([
+        readableComponent(prefix, PREFIX_BUDGET),
+        readableComponent(bucketKey, BUCKET_KEY_BUDGET),
+    ], `${prefix}/${databaseId}/${bucketKey}`, `key "${bucketKey}"`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/bucket-provisioner",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "S3-compatible bucket provisioning library — create buckets, configure privacy policies, CORS, and access controls",
   "main": "index.js",
@@ -44,5 +44,5 @@
     "storage",
     "constructive"
   ],
-  "gitHead": "7e6cc68f5659d12ec852835a7d8fcca6b05a8f50"
+  "gitHead": "ec6638bb4a06080919cee7e9ebf48306a2535f2f"
 }

package/provisioner.d.ts

@@ -22,8 +22,13 @@ export interface BucketProvisionerOptions {
      * 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.
+     *
+     * Empty (or omitted) means no browser origin may reach these buckets — a
+     * build's log store, say, which only server-side code ever opens. Such a
+     * bucket is provisioned with no CORS rule set at all rather than with a
+     * fabricated origin.
      */
-    allowedOrigins: string[];
+    allowedOrigins?: string[];
 }
 /**
  * The BucketProvisioner handles creating and configuring S3-compatible

package/provisioner.js

@@ -48,11 +48,8 @@ class BucketProvisioner {
     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.allowedOrigins = options.allowedOrigins ?? [];
         this.client = (0, client_1.createS3Client)(options.connection);
     }
     /**
@@ -93,12 +90,19 @@ class BucketProvisioner {
             // Ensure no leftover public policy on private/temp buckets
             await this.deleteBucketPolicy(bucketName);
         }
-        // 4. Set CORS rules (per-bucket override takes precedence over default)
+        // 4. Set CORS rules (per-bucket override takes precedence over default).
+        // A bucket no browser origin may reach gets no rule set: cross-origin
+        // access is the bucket's own recorded data, and "none recorded" is a
+        // legitimate answer, not a missing setting to invent an origin for.
         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);
+        const corsRules = effectiveOrigins.length === 0
+            ? []
+            : accessType === 'private'
+                ? (0, cors_1.buildPrivateCorsRules)(effectiveOrigins)
+                : (0, cors_1.buildUploadCorsRules)(effectiveOrigins);
+        if (corsRules.length > 0) {
+            await this.setCors(bucketName, corsRules);
+        }
         // 5. Versioning
         if (versioning) {
             await this.enableVersioning(bucketName);