@constructive-io/bucket-provisioner 0.25.0 → 0.25.1

package/esm/index.d.ts

@@ -28,6 +28,7 @@
  */
 export type { BucketProvisionerOptions } from './provisioner';
 export { BucketProvisioner } from './provisioner';
+export { mintPhysicalBucketName } 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,6 +27,8 @@
  * ```
  */
 export { BucketProvisioner } from './provisioner';
+// Physical naming policy
+export { mintPhysicalBucketName } from './naming';
 // S3 client factory
 export { createS3Client } from './client';
 export { buildCloudFrontOacPolicy, buildPresignedUrlIamPolicy, buildPublicReadPolicy, getPublicAccessBlock, } from './policies';

package/esm/naming.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function mintPhysicalBucketName(prefix: string, databaseId: string, bucketKey: string): string;

package/esm/naming.js

@@ -0,0 +1,54 @@
+import { createHash } from 'crypto';
+/** S3's hard ceiling on a bucket name. */
+const MAX_BUCKET_NAME_LENGTH = 63;
+/** S3's floor, which a degenerate prefix/key could otherwise fall under. */
+const MIN_BUCKET_NAME_LENGTH = 3;
+/** Hex characters of the identity digest kept as the uniqueness tail. */
+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;
+/**
+ * Reduce a component to the S3 bucket-name alphabet: lowercase, `[a-z0-9-]`,
+ * with runs of separators collapsed and no leading or trailing hyphen.
+ *
+ * Dots are legal in a bucket name but deliberately dropped — a dotted name
+ * cannot be used with virtual-hosted-style HTTPS, because the wildcard
+ * certificate does not match a further label.
+ */
+function sanitizeBucketNameComponent(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+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('-');
+    // The digest alone already satisfies both bounds, so this is only reachable
+    // when both readable components sanitize 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}"`);
+    }
+    return name;
+}

package/index.d.ts

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

package/index.js

@@ -28,9 +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.BucketProvisioner = void 0;
+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;
 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; } });
 // S3 client factory
 var client_1 = require("./client");
 Object.defineProperty(exports, "createS3Client", { enumerable: true, get: function () { return client_1.createS3Client; } });

package/naming.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function mintPhysicalBucketName(prefix: string, databaseId: string, bucketKey: string): string;

package/naming.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mintPhysicalBucketName = mintPhysicalBucketName;
+const crypto_1 = require("crypto");
+/** S3's hard ceiling on a bucket name. */
+const MAX_BUCKET_NAME_LENGTH = 63;
+/** S3's floor, which a degenerate prefix/key could otherwise fall under. */
+const MIN_BUCKET_NAME_LENGTH = 3;
+/** Hex characters of the identity digest kept as the uniqueness tail. */
+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;
+/**
+ * Reduce a component to the S3 bucket-name alphabet: lowercase, `[a-z0-9-]`,
+ * with runs of separators collapsed and no leading or trailing hyphen.
+ *
+ * Dots are legal in a bucket name but deliberately dropped — a dotted name
+ * cannot be used with virtual-hosted-style HTTPS, because the wildcard
+ * certificate does not match a further label.
+ */
+function sanitizeBucketNameComponent(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+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('-');
+    // The digest alone already satisfies both bounds, so this is only reachable
+    // when both readable components sanitize 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}"`);
+    }
+    return name;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/bucket-provisioner",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "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": "b5b6b9f05276b7e9cbd3d1f4acd31dd315c353ea"
+  "gitHead": "7e6cc68f5659d12ec852835a7d8fcca6b05a8f50"
 }