@nestm/storage 0.1.0-alpha.7 → 0.1.0-alpha.9

package/dist/files-sdk/provider/index.d.ts

@@ -2,6 +2,7 @@ import type { Adapter } from 'files-sdk';
 import { type LoadFilesOptions } from 'files-sdk/loader';
 import { type EnvVar, type Provider, type ProviderSlug } from 'files-sdk/providers';
 import { type FilesSdkDriverOptions, type FilesSdkStorageDriver } from '../files-sdk.driver.js';
+import type { S3ProviderProfile } from '../s3/index.js';
 /** Slug of a storage provider this package can build a driver for. */
 export type StorageProviderName = ProviderSlug;
 /**
@@ -18,6 +19,8 @@ export interface ProviderStorageDriverOptions extends Omit<FilesSdkDriverOptions
     /** Which provider to build. Validate untrusted input with {@link isStorageProvider}. */
     provider: StorageProviderName;
     config?: StorageProviderConfig;
+    /** Verified operation profile for the `s3` slug, especially custom endpoints. */
+    s3ProviderProfile?: S3ProviderProfile;
 }
 /**
  * Builds a {@link FilesSdkStorageDriver} for a provider named at runtime,
@@ -26,11 +29,12 @@ export interface ProviderStorageDriverOptions extends Omit<FilesSdkDriverOptions
  * `'r2'`, `'fs'`, …) and installs one native SDK, instead of the application
  * hard-coding a driver per backend.
  *
- * The `s3` slug additionally gets the conditional-promotion and signed-policy
- * capabilities {@link createS3StorageDriver} attaches; every other provider
- * exposes exactly what its adapter declares. Import
- * `@nestm/storage/files-sdk/s3` directly when the provider is known at build
- * time and the extra indirection buys nothing.
+ * The `s3` slug additionally gets the exact verified provider profile and
+ * signed-policy capabilities {@link createS3StorageDriver} attaches. Providers
+ * not backed by the AWS S3 SDK expose what their adapter declares;
+ * noncanonical S3-backed providers default to an unverified, read-only profile.
+ * Import `@nestm/storage/files-sdk/s3` directly when the provider is known at
+ * build time and the extra indirection buys nothing.
  *
  * @throws StorageError `INVALID_ARGUMENT` for an unknown slug, and whatever the
  * adapter reports (mapped) when required config or credentials are missing.

package/dist/files-sdk/provider/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/files-sdk/provider/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAKL,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC3B,MAAM,wBAAwB,CAAC;AAEhC,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC;AAEvE,MAAM,WAAW,4BAA6B,SAAQ,IAAI,CACxD,qBAAqB,CAAC,OAAO,CAAC,EAC9B,SAAS,CACV;IACC,wFAAwF;IACxF,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,qBAAqB,CAAC,CAWhC;AA6CD,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,mBAAmB,CAE7E;AAED,wDAAwD;AACxD,wBAAgB,oBAAoB,IAAI,SAAS,QAAQ,EAAE,CAE1D;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAErE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEjE;AAED,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEvE;AAED,YAAY,EACV,MAAM,IAAI,qBAAqB,EAC/B,QAAQ,IAAI,mBAAmB,GAChC,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/files-sdk/provider/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAKL,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC3B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAa,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGnE,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC;AAEvE,MAAM,WAAW,4BAA6B,SAAQ,IAAI,CACxD,qBAAqB,CAAC,OAAO,CAAC,EAC9B,SAAS,CACV;IACC,wFAAwF;IACxF,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,iFAAiF;IACjF,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,qBAAqB,CAAC,CAoBhC;AA+ED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,mBAAmB,CAE7E;AAED,wDAAwD;AACxD,wBAAgB,oBAAoB,IAAI,SAAS,QAAQ,EAAE,CAE1D;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAErE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEjE;AAED,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEvE;AAED,YAAY,EACV,MAAM,IAAI,qBAAqB,EAC/B,QAAQ,IAAI,mBAAmB,GAChC,MAAM,qBAAqB,CAAC"}

package/dist/files-sdk/provider/index.js

@@ -2,6 +2,7 @@ import { loadFiles } from 'files-sdk/loader';
 import { PROVIDER_NAMES, getProvider, getSecretEnvVars, listEnvVars, } from 'files-sdk/providers';
 import { StorageError, StorageErrorCode } from '../../storage.error.js';
 import { createFilesSdkDriver, mapFilesSdkError, } from '../files-sdk.driver.js';
+import { recordS3ConstructionMetadata } from '../s3/construction-metadata.js';
 /**
  * Builds a {@link FilesSdkStorageDriver} for a provider named at runtime,
  * importing that provider's adapter — and only that one — on demand. A
@@ -9,27 +10,49 @@ import { createFilesSdkDriver, mapFilesSdkError, } from '../files-sdk.driver.js'
  * `'r2'`, `'fs'`, …) and installs one native SDK, instead of the application
  * hard-coding a driver per backend.
  *
- * The `s3` slug additionally gets the conditional-promotion and signed-policy
- * capabilities {@link createS3StorageDriver} attaches; every other provider
- * exposes exactly what its adapter declares. Import
- * `@nestm/storage/files-sdk/s3` directly when the provider is known at build
- * time and the extra indirection buys nothing.
+ * The `s3` slug additionally gets the exact verified provider profile and
+ * signed-policy capabilities {@link createS3StorageDriver} attaches. Providers
+ * not backed by the AWS S3 SDK expose what their adapter declares;
+ * noncanonical S3-backed providers default to an unverified, read-only profile.
+ * Import `@nestm/storage/files-sdk/s3` directly when the provider is known at
+ * build time and the extra indirection buys nothing.
  *
  * @throws StorageError `INVALID_ARGUMENT` for an unknown slug, and whatever the
  * adapter reports (mapped) when required config or credentials are missing.
  */
 export async function createProviderStorageDriver(options) {
-    const { provider, config, ...filesOptions } = options;
+    const { provider, config, s3ProviderProfile, ...filesOptions } = options;
     if (!isStorageProvider(provider)) {
         throw unknownProvider(provider);
     }
     // `loadFiles` owns the slug → adapter mapping and keeps the import lazy; the
     // client it returns is discarded so the caller's own driver options (prefix,
     // hooks, plugins, readonly, retries) apply to the instance the bridge builds.
-    const adapter = await resolveAdapter(provider, config);
-    return createFilesSdkDriver({ ...filesOptions, adapter });
+    if (s3ProviderProfile !== undefined && provider !== 's3') {
+        throw new StorageError('s3ProviderProfile can only be used with the "s3" provider.', { code: StorageErrorCode.INVALID_ARGUMENT, permanent: true });
+    }
+    const adapter = await resolveAdapter(provider, config, s3ProviderProfile);
+    return createFilesSdkDriver({
+        ...filesOptions,
+        adapter,
+    });
+}
+function isS3BackedAdapter(adapter) {
+    try {
+        const raw = adapter.raw;
+        if (typeof raw !== 'object' || raw === null)
+            return false;
+        const candidate = raw;
+        return (typeof candidate.send === 'function' &&
+            typeof candidate.config === 'object' &&
+            candidate.config !== null &&
+            candidate.config.serviceId === 'S3');
+    }
+    catch {
+        return false;
+    }
 }
-async function resolveAdapter(provider, config) {
+async function resolveAdapter(provider, config, s3ProviderProfile) {
     let resolved;
     try {
         resolved = await loadFiles({ ...config, provider });
@@ -42,18 +65,33 @@ async function resolveAdapter(provider, config) {
         const { withFsConditionalMutation } = await import('../fs/index.js');
         return withFsConditionalMutation(adapter);
     }
-    if (provider !== 's3') {
+    if (!isS3BackedAdapter(adapter)) {
         return adapter;
     }
-    // Built by `s3(...)`, so its `raw` is an S3Client and the promotion path
-    // holds. The S3-compatible wrappers keep only what they declare themselves.
+    // Every AWS-SDK-backed wrapper gets fail-closed S3 provenance and endpoint
+    // hardening. Only the canonical `s3` slug may infer native AWS or accept an
+    // explicit verified profile; named compatibles remain unverified/read-only.
     const { withS3Capabilities } = await import('../s3/index.js');
-    return withS3Capabilities(adapter, {
+    const configJsonPublicBaseUrl = config?.configJson?.publicBaseUrl;
+    const publicBaseUrl = config?.publicBaseUrl ??
+        (typeof configJsonPublicBaseUrl === 'string'
+            ? configJsonPublicBaseUrl
+            : undefined);
+    const s3Adapter = adapter;
+    recordS3ConstructionMetadata(s3Adapter.raw, {
+        publicBaseUrlConfigured: provider !== 's3' ||
+            config?.publicBaseUrl !== undefined ||
+            configJsonPublicBaseUrl !== undefined,
+    });
+    return withS3Capabilities(s3Adapter, {
         ...(typeof config?.endpoint === 'string' && {
             endpoint: config.endpoint,
         }),
-        ...(config?.publicBaseUrl !== undefined && {
-            publicBaseUrl: config.publicBaseUrl,
+        ...(publicBaseUrl !== undefined && {
+            publicBaseUrl,
+        }),
+        ...(s3ProviderProfile !== undefined && {
+            providerProfile: s3ProviderProfile,
         }),
     });
 }

package/dist/files-sdk/provider/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/files-sdk/provider/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Adapter } from 'files-sdk';\nimport { loadFiles, type LoadFilesOptions } from 'files-sdk/loader';\nimport {\n  PROVIDER_NAMES,\n  getProvider,\n  getSecretEnvVars,\n  listEnvVars,\n  type EnvVar,\n  type Provider,\n  type ProviderSlug,\n} from 'files-sdk/providers';\n\nimport { StorageError, StorageErrorCode } from '../../storage.error.js';\nimport {\n  createFilesSdkDriver,\n  mapFilesSdkError,\n  type FilesSdkDriverOptions,\n  type FilesSdkStorageDriver,\n} from '../files-sdk.driver.js';\n\n/** Slug of a storage provider this package can build a driver for. */\nexport type StorageProviderName = ProviderSlug;\n\n/**\n * Flat, provider-specific settings — `bucket` and `region` for an object store,\n * `root` for the filesystem, `accountName` and `container` for Azure, and so\n * on. Every provider reads what it needs and ignores the rest, so one config\n * shape serves a deployment that switches providers by name.\n *\n * Credentials may be omitted for any provider whose SDK resolves its own chain\n * (an IAM role, Application Default Credentials, a shared profile).\n */\nexport type StorageProviderConfig = Omit<LoadFilesOptions, 'provider'>;\n\nexport interface ProviderStorageDriverOptions extends Omit<\n  FilesSdkDriverOptions<Adapter>,\n  'adapter'\n> {\n  /** Which provider to build. Validate untrusted input with {@link isStorageProvider}. */\n  provider: StorageProviderName;\n  config?: StorageProviderConfig;\n}\n\n/**\n * Builds a {@link FilesSdkStorageDriver} for a provider named at runtime,\n * importing that provider's adapter — and only that one — on demand. A\n * deployment selects its store with a string (`'s3'`, `'gcs'`, `'azure'`,\n * `'r2'`, `'fs'`, …) and installs one native SDK, instead of the application\n * hard-coding a driver per backend.\n *\n * The `s3` slug additionally gets the conditional-promotion and signed-policy\n * capabilities {@link createS3StorageDriver} attaches; every other provider\n * exposes exactly what its adapter declares. Import\n * `@nestm/storage/files-sdk/s3` directly when the provider is known at build\n * time and the extra indirection buys nothing.\n *\n * @throws StorageError `INVALID_ARGUMENT` for an unknown slug, and whatever the\n * adapter reports (mapped) when required config or credentials are missing.\n */\nexport async function createProviderStorageDriver(\n  options: ProviderStorageDriverOptions,\n): Promise<FilesSdkStorageDriver> {\n  const { provider, config, ...filesOptions } = options;\n  if (!isStorageProvider(provider)) {\n    throw unknownProvider(provider);\n  }\n\n  // `loadFiles` owns the slug → adapter mapping and keeps the import lazy; the\n  // client it returns is discarded so the caller's own driver options (prefix,\n  // hooks, plugins, readonly, retries) apply to the instance the bridge builds.\n  const adapter = await resolveAdapter(provider, config);\n  return createFilesSdkDriver({ ...filesOptions, adapter });\n}\n\nasync function resolveAdapter(\n  provider: StorageProviderName,\n  config: StorageProviderConfig | undefined,\n): Promise<Adapter> {\n  let resolved;\n  try {\n    resolved = await loadFiles({ ...config, provider });\n  } catch (error) {\n    throw mapFilesSdkError(error);\n  }\n  const { adapter } = resolved.files;\n  if (provider === 'fs') {\n    const { withFsConditionalMutation } = await import('../fs/index.js');\n    return withFsConditionalMutation(\n      adapter as Parameters<typeof withFsConditionalMutation>[0],\n    );\n  }\n  if (provider !== 's3') {\n    return adapter;\n  }\n  // Built by `s3(...)`, so its `raw` is an S3Client and the promotion path\n  // holds. The S3-compatible wrappers keep only what they declare themselves.\n  const { withS3Capabilities } = await import('../s3/index.js');\n  return withS3Capabilities(\n    adapter as Parameters<typeof withS3Capabilities>[0],\n    {\n      ...(typeof config?.endpoint === 'string' && {\n        endpoint: config.endpoint,\n      }),\n      ...(config?.publicBaseUrl !== undefined && {\n        publicBaseUrl: config.publicBaseUrl,\n      }),\n    },\n  );\n}\n\nfunction unknownProvider(provider: string): StorageError {\n  return new StorageError(\n    `Unknown storage provider: ${JSON.stringify(provider)}. Known providers: ${PROVIDER_NAMES.join(', ')}.`,\n    { code: StorageErrorCode.INVALID_ARGUMENT, permanent: true },\n  );\n}\n\n/** Narrows an untrusted string — an env var, a config file — to a known slug. */\nexport function isStorageProvider(value: string): value is StorageProviderName {\n  return getProvider(value) !== undefined;\n}\n\n/** Every provider that can be named, sorted by slug. */\nexport function listStorageProviders(): readonly Provider[] {\n  return PROVIDER_NAMES.flatMap((slug) => getProvider(slug) ?? []);\n}\n\n/** One provider's display name, description, native SDKs, and env contract. */\nexport function getStorageProvider(slug: string): Provider | undefined {\n  return getProvider(slug);\n}\n\n/**\n * Every environment variable a provider reads, flattened across required, all\n * credential modes, and optional. Useful for validating a deployment's config\n * before the first upload rather than at it.\n */\nexport function listStorageProviderEnvVars(slug: string): EnvVar[] {\n  return listEnvVars(slug);\n}\n\n/** The subset of {@link listStorageProviderEnvVars} that carries secrets. */\nexport function listStorageProviderSecretEnvVars(slug: string): EnvVar[] {\n  return getSecretEnvVars(slug);\n}\n\nexport type {\n  EnvVar as StorageProviderEnvVar,\n  Provider as StorageProviderInfo,\n} from 'files-sdk/providers';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/files-sdk/provider/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Adapter } from 'files-sdk';\nimport { loadFiles, type LoadFilesOptions } from 'files-sdk/loader';\nimport {\n  PROVIDER_NAMES,\n  getProvider,\n  getSecretEnvVars,\n  listEnvVars,\n  type EnvVar,\n  type Provider,\n  type ProviderSlug,\n} from 'files-sdk/providers';\n\nimport { StorageError, StorageErrorCode } from '../../storage.error.js';\nimport {\n  createFilesSdkDriver,\n  mapFilesSdkError,\n  type FilesSdkDriverOptions,\n  type FilesSdkStorageDriver,\n} from '../files-sdk.driver.js';\nimport type { S3Adapter, S3ProviderProfile } from '../s3/index.js';\nimport { recordS3ConstructionMetadata } from '../s3/construction-metadata.js';\n\n/** Slug of a storage provider this package can build a driver for. */\nexport type StorageProviderName = ProviderSlug;\n\n/**\n * Flat, provider-specific settings — `bucket` and `region` for an object store,\n * `root` for the filesystem, `accountName` and `container` for Azure, and so\n * on. Every provider reads what it needs and ignores the rest, so one config\n * shape serves a deployment that switches providers by name.\n *\n * Credentials may be omitted for any provider whose SDK resolves its own chain\n * (an IAM role, Application Default Credentials, a shared profile).\n */\nexport type StorageProviderConfig = Omit<LoadFilesOptions, 'provider'>;\n\nexport interface ProviderStorageDriverOptions extends Omit<\n  FilesSdkDriverOptions<Adapter>,\n  'adapter'\n> {\n  /** Which provider to build. Validate untrusted input with {@link isStorageProvider}. */\n  provider: StorageProviderName;\n  config?: StorageProviderConfig;\n  /** Verified operation profile for the `s3` slug, especially custom endpoints. */\n  s3ProviderProfile?: S3ProviderProfile;\n}\n\n/**\n * Builds a {@link FilesSdkStorageDriver} for a provider named at runtime,\n * importing that provider's adapter — and only that one — on demand. A\n * deployment selects its store with a string (`'s3'`, `'gcs'`, `'azure'`,\n * `'r2'`, `'fs'`, …) and installs one native SDK, instead of the application\n * hard-coding a driver per backend.\n *\n * The `s3` slug additionally gets the exact verified provider profile and\n * signed-policy capabilities {@link createS3StorageDriver} attaches. Providers\n * not backed by the AWS S3 SDK expose what their adapter declares;\n * noncanonical S3-backed providers default to an unverified, read-only profile.\n * Import `@nestm/storage/files-sdk/s3` directly when the provider is known at\n * build time and the extra indirection buys nothing.\n *\n * @throws StorageError `INVALID_ARGUMENT` for an unknown slug, and whatever the\n * adapter reports (mapped) when required config or credentials are missing.\n */\nexport async function createProviderStorageDriver(\n  options: ProviderStorageDriverOptions,\n): Promise<FilesSdkStorageDriver> {\n  const { provider, config, s3ProviderProfile, ...filesOptions } = options;\n  if (!isStorageProvider(provider)) {\n    throw unknownProvider(provider);\n  }\n\n  // `loadFiles` owns the slug → adapter mapping and keeps the import lazy; the\n  // client it returns is discarded so the caller's own driver options (prefix,\n  // hooks, plugins, readonly, retries) apply to the instance the bridge builds.\n  if (s3ProviderProfile !== undefined && provider !== 's3') {\n    throw new StorageError(\n      's3ProviderProfile can only be used with the \"s3\" provider.',\n      { code: StorageErrorCode.INVALID_ARGUMENT, permanent: true },\n    );\n  }\n  const adapter = await resolveAdapter(provider, config, s3ProviderProfile);\n  return createFilesSdkDriver({\n    ...filesOptions,\n    adapter,\n  });\n}\n\nfunction isS3BackedAdapter(adapter: Adapter): adapter is S3Adapter {\n  try {\n    const raw = adapter.raw;\n    if (typeof raw !== 'object' || raw === null) return false;\n    const candidate = raw as {\n      readonly config?: unknown;\n      readonly send?: unknown;\n    };\n    return (\n      typeof candidate.send === 'function' &&\n      typeof candidate.config === 'object' &&\n      candidate.config !== null &&\n      (candidate.config as { readonly serviceId?: unknown }).serviceId === 'S3'\n    );\n  } catch {\n    return false;\n  }\n}\n\nasync function resolveAdapter(\n  provider: StorageProviderName,\n  config: StorageProviderConfig | undefined,\n  s3ProviderProfile: S3ProviderProfile | undefined,\n): Promise<Adapter> {\n  let resolved;\n  try {\n    resolved = await loadFiles({ ...config, provider });\n  } catch (error) {\n    throw mapFilesSdkError(error);\n  }\n  const { adapter } = resolved.files;\n  if (provider === 'fs') {\n    const { withFsConditionalMutation } = await import('../fs/index.js');\n    return withFsConditionalMutation(\n      adapter as Parameters<typeof withFsConditionalMutation>[0],\n    );\n  }\n  if (!isS3BackedAdapter(adapter)) {\n    return adapter;\n  }\n  // Every AWS-SDK-backed wrapper gets fail-closed S3 provenance and endpoint\n  // hardening. Only the canonical `s3` slug may infer native AWS or accept an\n  // explicit verified profile; named compatibles remain unverified/read-only.\n  const { withS3Capabilities } = await import('../s3/index.js');\n  const configJsonPublicBaseUrl = config?.configJson?.publicBaseUrl;\n  const publicBaseUrl =\n    config?.publicBaseUrl ??\n    (typeof configJsonPublicBaseUrl === 'string'\n      ? configJsonPublicBaseUrl\n      : undefined);\n  const s3Adapter = adapter as Parameters<typeof withS3Capabilities>[0];\n  recordS3ConstructionMetadata(s3Adapter.raw, {\n    publicBaseUrlConfigured:\n      provider !== 's3' ||\n      config?.publicBaseUrl !== undefined ||\n      configJsonPublicBaseUrl !== undefined,\n  });\n  return withS3Capabilities(s3Adapter, {\n    ...(typeof config?.endpoint === 'string' && {\n      endpoint: config.endpoint,\n    }),\n    ...(publicBaseUrl !== undefined && {\n      publicBaseUrl,\n    }),\n    ...(s3ProviderProfile !== undefined && {\n      providerProfile: s3ProviderProfile,\n    }),\n  });\n}\n\nfunction unknownProvider(provider: string): StorageError {\n  return new StorageError(\n    `Unknown storage provider: ${JSON.stringify(provider)}. Known providers: ${PROVIDER_NAMES.join(', ')}.`,\n    { code: StorageErrorCode.INVALID_ARGUMENT, permanent: true },\n  );\n}\n\n/** Narrows an untrusted string — an env var, a config file — to a known slug. */\nexport function isStorageProvider(value: string): value is StorageProviderName {\n  return getProvider(value) !== undefined;\n}\n\n/** Every provider that can be named, sorted by slug. */\nexport function listStorageProviders(): readonly Provider[] {\n  return PROVIDER_NAMES.flatMap((slug) => getProvider(slug) ?? []);\n}\n\n/** One provider's display name, description, native SDKs, and env contract. */\nexport function getStorageProvider(slug: string): Provider | undefined {\n  return getProvider(slug);\n}\n\n/**\n * Every environment variable a provider reads, flattened across required, all\n * credential modes, and optional. Useful for validating a deployment's config\n * before the first upload rather than at it.\n */\nexport function listStorageProviderEnvVars(slug: string): EnvVar[] {\n  return listEnvVars(slug);\n}\n\n/** The subset of {@link listStorageProviderEnvVars} that carries secrets. */\nexport function listStorageProviderSecretEnvVars(slug: string): EnvVar[] {\n  return getSecretEnvVars(slug);\n}\n\nexport type {\n  EnvVar as StorageProviderEnvVar,\n  Provider as StorageProviderInfo,\n} from 'files-sdk/providers';\n"]}

package/dist/files-sdk/s3/construction-metadata.d.ts

@@ -0,0 +1,7 @@
+export interface S3ConstructionMetadata {
+    /** Whether URL generation bypasses signing through a configured public origin. */
+    readonly publicBaseUrlConfigured: boolean;
+}
+export declare function recordS3ConstructionMetadata(raw: object, metadata: S3ConstructionMetadata): void;
+export declare function getS3ConstructionMetadata(raw: object): Readonly<S3ConstructionMetadata> | undefined;
+//# sourceMappingURL=construction-metadata.d.ts.map

package/dist/files-sdk/s3/construction-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"construction-metadata.d.ts","sourceRoot":"","sources":["../../../src/files-sdk/s3/construction-metadata.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;CAC3C;AAOD,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,sBAAsB,GAC/B,IAAI,CASN;AAED,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,GACV,QAAQ,CAAC,sBAAsB,CAAC,GAAG,SAAS,CAE9C"}

package/dist/files-sdk/s3/construction-metadata.js

@@ -0,0 +1,13 @@
+const constructionMetadata = new WeakMap();
+export function recordS3ConstructionMetadata(raw, metadata) {
+    const existing = constructionMetadata.get(raw);
+    if (existing !== undefined &&
+        existing.publicBaseUrlConfigured !== metadata.publicBaseUrlConfigured) {
+        throw new TypeError('S3 adapter construction metadata cannot be changed.');
+    }
+    constructionMetadata.set(raw, Object.freeze({ ...metadata }));
+}
+export function getS3ConstructionMetadata(raw) {
+    return constructionMetadata.get(raw);
+}
+//# sourceMappingURL=construction-metadata.js.map

package/dist/files-sdk/s3/construction-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"construction-metadata.js","sourceRoot":"","sources":["../../../src/files-sdk/s3/construction-metadata.ts"],"names":[],"mappings":"AAKA,MAAM,oBAAoB,GAAG,IAAI,OAAO,EAGrC,CAAC;AAEJ,MAAM,UAAU,4BAA4B,CAC1C,GAAW,EACX,QAAgC;IAEhC,MAAM,QAAQ,GAAG,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/C,IACE,QAAQ,KAAK,SAAS;QACtB,QAAQ,CAAC,uBAAuB,KAAK,QAAQ,CAAC,uBAAuB,EACrE,CAAC;QACD,MAAM,IAAI,SAAS,CAAC,qDAAqD,CAAC,CAAC;IAC7E,CAAC;IACD,oBAAoB,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,GAAW;IAEX,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACvC,CAAC","sourcesContent":["export interface S3ConstructionMetadata {\n  /** Whether URL generation bypasses signing through a configured public origin. */\n  readonly publicBaseUrlConfigured: boolean;\n}\n\nconst constructionMetadata = new WeakMap<\n  object,\n  Readonly<S3ConstructionMetadata>\n>();\n\nexport function recordS3ConstructionMetadata(\n  raw: object,\n  metadata: S3ConstructionMetadata,\n): void {\n  const existing = constructionMetadata.get(raw);\n  if (\n    existing !== undefined &&\n    existing.publicBaseUrlConfigured !== metadata.publicBaseUrlConfigured\n  ) {\n    throw new TypeError('S3 adapter construction metadata cannot be changed.');\n  }\n  constructionMetadata.set(raw, Object.freeze({ ...metadata }));\n}\n\nexport function getS3ConstructionMetadata(\n  raw: object,\n): Readonly<S3ConstructionMetadata> | undefined {\n  return constructionMetadata.get(raw);\n}\n"]}

package/dist/files-sdk/s3/index.d.ts

@@ -1,34 +1,54 @@
-import { type S3Adapter, type S3AdapterOptions } from 'files-sdk/s3';
-import { type FilesSdkConditionalCopyAdapter, type FilesSdkConditionalMutationAdapter, type FilesSdkDriverOptions, type FilesSdkSignedUploadPolicyAdapter, type FilesSdkSignedDownloadPolicyAdapter, type FilesSdkStorageDriver } from '../files-sdk.driver.js';
+import { mapS3Error, type S3Adapter, type S3AdapterOptions } from 'files-sdk/s3';
+import type { StorageCapabilities } from '../../storage.types.js';
+import { type FilesSdkConditionalCopyAdapter, type FilesSdkConditionalDeleteAdapter, type FilesSdkConditionalReadAdapter, type FilesSdkConditionalUploadAdapter, type FilesSdkDriverOptions, type FilesSdkPhysicalKeyAdapter, type FilesSdkSignedUploadPolicyAdapter, type FilesSdkSignedDownloadPolicyAdapter, type FilesSdkStorageDriver } from '../files-sdk.driver.js';
 export interface S3StorageDriverOptions extends Omit<FilesSdkDriverOptions<S3Adapter>, 'adapter'> {
     adapter: S3AdapterOptions;
     /**
-     * Opt in or out of conditional writes for an S3-compatible endpoint whose
-     * support is known. Native AWS S3 enables them by default; custom endpoints
-     * default to false because compatibility varies.
+     * Exact, conformance-verified provider behavior. Native AWS S3 uses the
+     * built-in AWS profile when no endpoint override is present; an explicit
+     * native profile may only narrow that immutable ceiling. Endpoint overrides
+     * without an explicit profile force the whole driver read-only.
      */
-    conditionalMutation?: boolean;
+    providerProfile?: S3ProviderProfile;
 }
-type S3StorageAdapterBase = S3Adapter & FilesSdkConditionalCopyAdapter & FilesSdkSignedDownloadPolicyAdapter & FilesSdkSignedUploadPolicyAdapter;
-export type S3StorageAdapter = S3StorageAdapterBase & Partial<FilesSdkConditionalMutationAdapter>;
+type S3ProfileCapabilities = Pick<StorageCapabilities, 'conditionalCreate' | 'conditionalReplace' | 'conditionalDelete' | 'conditionalRead' | 'conditionalCopySource' | 'conditionalCopyDestination' | 'conditionalMultipartCompletion' | 'physicalKey' | 'signedUploadPolicy'>;
+declare const verifiedS3ProviderProfile: unique symbol;
+export interface S3ProviderProfileInput extends S3ProfileCapabilities {
+    /** Stable profile identity for configuration, diagnostics, and audit. */
+    readonly name: string;
+    /** Every S3-compatible profile must declare its complete-key byte budget. */
+    readonly physicalKey: NonNullable<S3ProfileCapabilities['physicalKey']>;
+    /** Constraints the provider proves; omission defaults both claims to false. */
+    readonly signedUploadPolicy?: NonNullable<S3ProfileCapabilities['signedUploadPolicy']>;
+}
+/** A validated profile created by {@link defineS3ProviderProfile}. */
+export type S3ProviderProfile = Readonly<Omit<S3ProviderProfileInput, 'signedUploadPolicy'> & {
+    readonly signedUploadPolicy: NonNullable<S3ProfileCapabilities['signedUploadPolicy']>;
+}> & {
+    readonly [verifiedS3ProviderProfile]: true;
+};
+/** Validates and deeply freezes an explicitly verified S3-compatible profile. */
+export declare function defineS3ProviderProfile(profile: S3ProviderProfileInput): S3ProviderProfile;
+export declare const AWS_S3_PROVIDER_PROFILE: S3ProviderProfile;
+export declare const CLOUDFLARE_R2_PROVIDER_PROFILE: S3ProviderProfile;
+type S3StorageAdapterBase = S3Adapter & FilesSdkPhysicalKeyAdapter & FilesSdkSignedDownloadPolicyAdapter & FilesSdkSignedUploadPolicyAdapter;
+export type S3StorageAdapter = S3StorageAdapterBase & Partial<FilesSdkConditionalCopyAdapter & FilesSdkConditionalDeleteAdapter & FilesSdkConditionalReadAdapter & FilesSdkConditionalUploadAdapter>;
+/** Constructs the upstream S3 adapter while retaining security-relevant metadata. */
+export declare function s3(options: S3AdapterOptions): S3Adapter;
 /**
- * Adds the S3-only capabilities to an adapter already built by `s3(...)`: an
- * ETag/version-conditional server-side promotion, and the signed upload and
- * download policies the bridge advertises through `capabilities`.
- *
- * Exported so the provider factory can apply them to the adapter `loadFiles`
- * resolved for the `s3` slug instead of re-deriving {@link S3AdapterOptions}
- * from flat provider config. It expects an adapter whose `raw` is an `S3Client`
- * — pass one built by `s3(...)`, not an S3-compatible wrapper.
+ * Adds only the exact operations declared by one verified provider profile.
+ * Each raw adapter may be decorated once so capability state cannot depend on
+ * profile application order. A native AWS SDK endpoint also bounds every
+ * explicit profile by the built-in AWS capability ceiling.
  */
 export declare function withS3Capabilities(base: S3Adapter, options?: Pick<S3AdapterOptions, 'endpoint' | 'publicBaseUrl'> & {
-    conditionalMutation?: boolean;
+    providerProfile?: S3ProviderProfile;
 }): S3StorageAdapter;
 /**
  * Creates the files-sdk S3 driver from the storage package's own dependency
- * context and adds an ETag/version-conditional server-side promotion.
+ * context and exposes only the operations in its verified provider profile.
  */
 export declare function createS3StorageDriver(options: S3StorageDriverOptions): FilesSdkStorageDriver<S3StorageAdapter>;
-export { mapS3Error, s3 } from 'files-sdk/s3';
+export { mapS3Error };
 export type { S3Adapter, S3AdapterOptions, S3Sdk } from 'files-sdk/s3';
 //# sourceMappingURL=index.d.ts.map

package/dist/files-sdk/s3/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/files-sdk/s3/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AAWtB,OAAO,EAEL,KAAK,8BAA8B,EACnC,KAAK,kCAAkC,EACvC,KAAK,qBAAqB,EAC1B,KAAK,iCAAiC,EACtC,KAAK,mCAAmC,EACxC,KAAK,qBAAqB,EAE3B,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAClD,qBAAqB,CAAC,SAAS,CAAC,EAChC,SAAS,CACV;IACC,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,KAAK,oBAAoB,GAAG,SAAS,GACnC,8BAA8B,GAC9B,mCAAmC,GACnC,iCAAiC,CAAC;AAEpC,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GACjD,OAAO,CAAC,kCAAkC,CAAC,CAAC;AAmL9C;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,eAAe,CAAC,GAAG;IAC9D,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC1B,GACL,gBAAgB,CA6JlB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAAC,gBAAgB,CAAC,CAUzC;AAED,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/files-sdk/s3/index.ts"],"names":[],"mappings":"AAgBA,OAAO,EACL,UAAU,EAEV,KAAK,SAAS,EACd,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAEV,mBAAmB,EAQpB,MAAM,wBAAwB,CAAC;AAUhC,OAAO,EAKL,KAAK,8BAA8B,EACnC,KAAK,gCAAgC,EACrC,KAAK,8BAA8B,EACnC,KAAK,gCAAgC,EACrC,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,iCAAiC,EACtC,KAAK,mCAAmC,EACxC,KAAK,qBAAqB,EAE3B,MAAM,wBAAwB,CAAC;AAMhC,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAClD,qBAAqB,CAAC,SAAS,CAAC,EAChC,SAAS,CACV;IACC,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,iBAAiB,CAAC;CACrC;AAED,KAAK,qBAAqB,GAAG,IAAI,CAC/B,mBAAmB,EACjB,mBAAmB,GACnB,oBAAoB,GACpB,mBAAmB,GACnB,iBAAiB,GACjB,uBAAuB,GACvB,4BAA4B,GAC5B,gCAAgC,GAChC,aAAa,GACb,oBAAoB,CACvB,CAAC;AAEF,QAAA,MAAM,yBAAyB,eAAsC,CAAC;AAGtE,MAAM,WAAW,sBAAuB,SAAQ,qBAAqB;IACnE,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,qBAAqB,CAAC,aAAa,CAAC,CAAC,CAAC;IACxE,+EAA+E;IAC/E,QAAQ,CAAC,kBAAkB,CAAC,EAAE,WAAW,CACvC,qBAAqB,CAAC,oBAAoB,CAAC,CAC5C,CAAC;CACH;AAED,sEAAsE;AACtE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CACtC,IAAI,CAAC,sBAAsB,EAAE,oBAAoB,CAAC,GAAG;IACnD,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CACtC,qBAAqB,CAAC,oBAAoB,CAAC,CAC5C,CAAC;CACH,CACF,GAAG;IACF,QAAQ,CAAC,CAAC,yBAAyB,CAAC,EAAE,IAAI,CAAC;CAC5C,CAAC;AAWF,iFAAiF;AACjF,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,sBAAsB,GAC9B,iBAAiB,CA4KnB;AA0ID,eAAO,MAAM,uBAAuB,mBAelC,CAAC;AAEH,eAAO,MAAM,8BAA8B,mBAQzC,CAAC;AAQH,KAAK,oBAAoB,GAAG,SAAS,GACnC,0BAA0B,GAC1B,mCAAmC,GACnC,iCAAiC,CAAC;AAEpC,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GACjD,OAAO,CACL,8BAA8B,GAC5B,gCAAgC,GAChC,8BAA8B,GAC9B,gCAAgC,CACnC,CAAC;AAwlBJ,qFAAqF;AACrF,wBAAgB,EAAE,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAOvD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,eAAe,CAAC,GAAG;IAC9D,eAAe,CAAC,EAAE,iBAAiB,CAAC;CAChC,GACL,gBAAgB,CAqalB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAAC,gBAAgB,CAAC,CAazC;AAED,OAAO,EAAE,UAAU,EAAE,CAAC;AACtB,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC"}