@lossless.org/objectstorage 9.0.0

package/ts/index.ts

@@ -0,0 +1,1932 @@
+import * as plugins from './plugins.js';
+import * as paths from './paths.js';
+
+/**
+ * Authentication configuration
+ */
+export interface IStorageCredential {
+  accessKeyId: string;
+  secretAccessKey: string;
+  bucketName?: string;
+  region?: string;
+}
+
+export interface IStorageCredentialMetadata {
+  accessKeyId: string;
+  bucketName?: string;
+  region?: string;
+}
+
+/**
+ * Authentication configuration
+ */
+export interface IAuthConfig {
+  enabled: boolean;
+  credentials: IStorageCredential[];
+}
+
+/**
+ * CORS configuration
+ */
+export interface ICorsConfig {
+  enabled: boolean;
+  allowedOrigins?: string[];
+  allowedMethods?: string[];
+  allowedHeaders?: string[];
+  exposedHeaders?: string[];
+  maxAge?: number;
+  allowCredentials?: boolean;
+}
+
+/**
+ * Logging configuration
+ */
+export interface ILoggingConfig {
+  level?: 'error' | 'warn' | 'info' | 'debug';
+  format?: 'text' | 'json';
+  enabled?: boolean;
+}
+
+/**
+ * Request limits configuration
+ */
+export interface ILimitsConfig {
+  maxObjectSize?: number;
+  maxMetadataSize?: number;
+  requestTimeout?: number;
+}
+
+/**
+ * Multipart upload configuration
+ */
+export interface IMultipartConfig {
+  expirationDays?: number;
+  cleanupIntervalMinutes?: number;
+}
+
+/**
+ * Server configuration
+ */
+export interface IServerConfig {
+  port?: number;
+  address?: string;
+  silent?: boolean;
+  region?: string;
+}
+
+/**
+ * Storage configuration
+ */
+export interface ILocalFilesystemStoragePoolBackend {
+  kind: 'localFs';
+}
+
+export interface IMountedFilesystemStoragePoolBackend {
+  kind: 'mountedFs';
+  expectedFilesystemType: 'nfs' | 'smb';
+  expectedSource: string;
+}
+
+export type TStoragePoolBackend =
+  | ILocalFilesystemStoragePoolBackend
+  | IMountedFilesystemStoragePoolBackend;
+
+export interface IStoragePoolConfig {
+  id: string;
+  directory: string;
+  backend: TStoragePoolBackend;
+}
+
+export interface IMountedStoragePoolConfig extends IStoragePoolConfig {
+  backend: IMountedFilesystemStoragePoolBackend;
+}
+
+export interface IStorageConfig {
+  directory?: string;
+  cleanSlate?: boolean;
+  /**
+   * One ObjectStorage process serves one pool. `directory` remains as a
+   * compatibility alias and must resolve to the same path when both are set.
+   */
+  pool?: IStoragePoolConfig;
+}
+
+/**
+ * Erasure coding configuration
+ */
+export interface IErasureConfig {
+  dataShards?: number;
+  parityShards?: number;
+  chunkSizeBytes?: number;
+}
+
+/**
+ * Drive configuration for multi-drive support
+ */
+export interface IDriveConfig {
+  paths: string[];
+}
+
+/**
+ * Cluster configuration for distributed mode
+ */
+export interface IClusterConfig {
+  enabled: boolean;
+  nodeId?: string;
+  quicPort?: number;
+  seedNodes?: string[];
+  erasure?: IErasureConfig;
+  drives?: IDriveConfig;
+  heartbeatIntervalMs?: number;
+  heartbeatTimeoutMs?: number;
+}
+
+/**
+ * Complete objectstorage configuration
+ */
+export interface IObjectStorageConfig {
+  server?: IServerConfig;
+  storage?: IStorageConfig;
+  auth?: IAuthConfig;
+  cors?: ICorsConfig;
+  logging?: ILoggingConfig;
+  limits?: ILimitsConfig;
+  multipart?: IMultipartConfig;
+  cluster?: IClusterConfig;
+}
+
+/**
+ * Logical bucket stats maintained by the Rust runtime.
+ * Values are initialized from native storage on startup and updated on objectstorage mutations.
+ */
+export interface IBucketSummary {
+  name: string;
+  objectCount: number;
+  totalSizeBytes: number;
+  creationDate?: number;
+}
+
+/**
+ * Filesystem-level capacity snapshot for the storage directory or configured drive path.
+ */
+export interface IStorageLocationSummary {
+  path: string;
+  totalBytes?: number;
+  availableBytes?: number;
+  usedBytes?: number;
+  pool?: IStoragePoolObservation;
+}
+
+export type TStoragePoolCheckStatus =
+  | 'passed'
+  | 'failed'
+  | 'notRun'
+  | 'notApplicable';
+
+export interface IStoragePoolCheck {
+  status: TStoragePoolCheckStatus;
+  reason?: string;
+}
+
+export interface IStoragePoolChecks {
+  directoryExists: IStoragePoolCheck;
+  exactMount: IStoragePoolCheck;
+  filesystemType: IStoragePoolCheck;
+  source: IStoragePoolCheck;
+  symlinkConfinement: IStoragePoolCheck;
+  remoteLocking: IStoragePoolCheck;
+  rootOwnership: IStoragePoolCheck;
+  sameFilesystem: IStoragePoolCheck;
+  lockContention: IStoragePoolCheck;
+  atomicDirectoryExchange: IStoragePoolCheck;
+  directoryFsync: IStoragePoolCheck;
+  providerIdentity: IStoragePoolCheck;
+  mountStable: IStoragePoolCheck;
+}
+
+export interface IStoragePoolFilesystemObservation {
+  filesystemType?: string;
+  source?: string;
+  mountPoint?: string;
+  mountId?: number;
+  device?: string;
+  networkBacked: boolean;
+  blockSizeBytes?: number;
+  readSizeBytes?: number;
+  writeSizeBytes?: number;
+  symlinkFollowingDisabled?: boolean;
+  remoteLockingMode?:
+    | 'serverCoordinated'
+    | 'disabled'
+    | 'localOnly'
+    | 'unrecognized'
+    | 'notApplicable';
+}
+
+export type TStoragePoolFailureCode =
+  | 'pathUnavailable'
+  | 'mountInfoInvalid'
+  | 'exactMountRequired'
+  | 'filesystemTypeMismatch'
+  | 'sourceMismatch'
+  | 'mountChanged'
+  | 'descriptorMismatch'
+  | 'filesystemMagicMismatch'
+  | 'symlinkFollowingAllowed'
+  | 'lockingModeUnsafe'
+  | 'activationPoisoned';
+
+export interface IStoragePoolObservation {
+  schemaVersion: 1;
+  poolId: string;
+  directory: string;
+  role: 'controlAndBlob';
+  backendKind: 'localFs' | 'mountedFs';
+  filesystem: IStoragePoolFilesystemObservation;
+  checks: IStoragePoolChecks;
+  supported: boolean | null;
+  productionEligible: boolean;
+  activationValid?: boolean;
+  poisoned?: boolean;
+  poisonReason?: string;
+  failure?: {
+    code: TStoragePoolFailureCode;
+    message: string;
+  };
+}
+
+/**
+ * Runtime storage stats served by the Rust core without issuing S3 list calls.
+ */
+export interface IStorageStats {
+  bucketCount: number;
+  totalObjectCount: number;
+  totalStorageBytes: number;
+  buckets: IBucketSummary[];
+  storageDirectory: string;
+  storageLocations?: IStorageLocationSummary[];
+}
+
+export interface IStorageStopResult {
+  complete: true;
+  terminalError?: string;
+}
+
+export interface IBucketTenantInput {
+  bucketName: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  region?: string;
+  retention?: IBucketRetentionPolicyInput;
+}
+
+export interface IEnsureBucketTenantInput {
+  bucketName: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  region?: string;
+  retention?: IBucketRetentionPolicyInput;
+  fence?: IObjectStorageResourceFence;
+}
+
+export interface IDeleteBucketTenantInput {
+  bucketName: string;
+  accessKeyId?: string;
+}
+
+export interface IBucketTenantMetadata {
+  bucketName: string;
+  accessKeyId: string;
+  region?: string;
+  retention?: IBucketRetentionReceipt;
+}
+
+export interface IBucketRetentionPolicyInput {
+  mode: 'compliance';
+  policyId: string;
+  retentionDurationSeconds: number;
+}
+
+export interface IObjectRetentionReceipt {
+  mode: 'compliance';
+  policyId: string;
+  retentionDurationSeconds: number;
+  createdAt: number;
+  retainUntil: number;
+  payloadSha256: string;
+  metadataSha256: string;
+  etag: string;
+}
+
+export interface IBucketRetentionReceipt extends IBucketRetentionPolicyInput {
+  bucketName: string;
+  configuredAt: number;
+  sentinelKey: string;
+  sentinel: IObjectRetentionReceipt;
+}
+
+export interface IBucketRetentionCapability {
+  version: 1;
+  supported: boolean;
+  backend: 'standalone' | 'clustered';
+  modes: 'compliance'[];
+  atomicCreateOnly: boolean;
+  retainedMultipartSupported: false;
+}
+
+export interface IObjectStorageMigrationBinding {
+  migrationId: string;
+  authorityId: string;
+  logicalBucket: string;
+  sourceProviderIdentitySha256: string;
+  destinationProviderIdentitySha256: string;
+  destinationReceiptPublicKeyEd25519: string;
+}
+
+export type TObjectStorageSourceMigrationPhase =
+  | 'active'
+  | 'sealed'
+  | 'cutoverCommitted'
+  | 'retired'
+  | 'released';
+
+export type TObjectStorageDestinationMigrationPhase =
+  | 'holding'
+  | 'verified'
+  | 'cutoverAuthorized'
+  | 'published'
+  | 'aborted';
+
+export type TObjectStorageMigrationPhase =
+  | { role: 'source'; phase: TObjectStorageSourceMigrationPhase }
+  | { role: 'destination'; phase: TObjectStorageDestinationMigrationPhase };
+
+export interface IObjectStorageMigrationCreateInput {
+  binding: IObjectStorageMigrationBinding;
+  fenceToken: number;
+  opaqueCapability: string;
+  /** Required for source creation; omitted for destination creation. */
+  sourceCleanupAccessKeyId?: string;
+}
+
+export interface IObjectStorageMigrationTerminalReceipt {
+  version: 1;
+  kind: 'smartstorage.bucket-migration.terminal-receipt.standalone-v1';
+  binding: IObjectStorageMigrationBinding;
+  providerIdentitySha256: string;
+  fenceToken: number;
+  requestDigestSha256: string;
+  phase: TObjectStorageMigrationPhase;
+  manifestDigestSha256?: string;
+  counterpartTerminalReceiptSha256?: string;
+  signingPublicKeyEd25519: string;
+  signatureEd25519: string;
+  receiptSha256: string;
+}
+
+export interface IObjectStorageMigrationTransitionReceipt {
+  version: 1;
+  kind: 'smartstorage.bucket-migration.transition-receipt.standalone-v1';
+  binding: IObjectStorageMigrationBinding;
+  providerIdentitySha256: string;
+  fenceToken: number;
+  requestDigestSha256: string;
+  phase: TObjectStorageMigrationPhase;
+  manifestDigestSha256?: string;
+  terminalReceiptSha256?: string;
+  receiptSha256: string;
+}
+
+export interface IObjectStorageSourceMigrationTransitionInput {
+  binding: IObjectStorageMigrationBinding;
+  fenceToken: number;
+  opaqueCapability: string;
+  targetPhase: Exclude<TObjectStorageSourceMigrationPhase, 'active'>;
+  manifestDigestSha256?: string;
+  destinationAbortReceipt?: IObjectStorageMigrationTerminalReceipt;
+}
+
+export interface IObjectStorageDestinationMigrationTransitionInput {
+  binding: IObjectStorageMigrationBinding;
+  fenceToken: number;
+  opaqueCapability: string;
+  targetPhase: Exclude<TObjectStorageDestinationMigrationPhase, 'holding'>;
+  manifestDigestSha256?: string;
+}
+
+export interface IObjectStorageSourceMigrationCleanupInput {
+  binding: IObjectStorageMigrationBinding;
+  cleanupFenceToken: number;
+  opaqueCapability: string;
+  sourceRetiredReceiptSha256: string;
+  destinationPublishedReceipt: IObjectStorageMigrationTerminalReceipt;
+  resourceFence: IObjectStorageResourceFence;
+  accessKeyId: string;
+}
+
+export interface IObjectStorageSourceMigrationCleanupReceipt {
+  version: 1;
+  kind: 'smartstorage.bucket-migration.source-cleanup-receipt.standalone-v1';
+  binding: IObjectStorageMigrationBinding;
+  providerIdentitySha256: string;
+  cleanupFenceToken: number;
+  requestDigestSha256: string;
+  sourceRetiredReceiptSha256: string;
+  destinationPublishedReceiptSha256: string;
+  resourceFenceScopeId: string;
+  resourceFenceToken: number;
+  resourceFenceMutationId: string;
+  resourceFencePayloadSha256: string;
+  accessKeyIdSha256: string;
+  deleteResultSha256: string;
+  receiptSha256: string;
+}
+
+export interface IObjectStorageSourceMigrationCleanupInspection {
+  phase: 'requested' | 'completed';
+  cleanupFenceToken: number;
+  requestDigestSha256: string;
+  sourceRetiredReceiptSha256: string;
+  destinationPublishedReceipt: IObjectStorageMigrationTerminalReceipt;
+  resourceFence: IObjectStorageResourceFence;
+  accessKeyIdSha256: string;
+  deleteResultSha256?: string;
+  receipt?: IObjectStorageSourceMigrationCleanupReceipt;
+}
+
+export interface IObjectStorageMigrationInspection {
+  binding: IObjectStorageMigrationBinding;
+  providerIdentitySha256: string;
+  highestFenceToken: number;
+  requestDigestSha256: string;
+  phase: TObjectStorageMigrationPhase;
+  manifestDigestSha256?: string;
+  boundDestinationAbortReceipt?: IObjectStorageMigrationTerminalReceipt;
+  terminalReceipt?: IObjectStorageMigrationTerminalReceipt;
+  lastReceipt: IObjectStorageMigrationTransitionReceipt;
+  sourceCleanupAccessKeyIdSha256?: string;
+  sourceCleanup?: IObjectStorageSourceMigrationCleanupInspection;
+}
+
+export interface IObjectStorageBucketMigrationCapability {
+  version: 1;
+  supported: boolean;
+  backend: 'standalone' | 'clustered';
+  providerIdentitySha256?: string;
+  receiptPublicKeyEd25519?: string;
+  sourceSealDrainsMutations: boolean;
+  sourceReadsRemainAvailableWhileSealed: boolean;
+  destinationPublicationRequiresControllerCredentialHold: true;
+  sourceRetirementCleanupSupported: boolean;
+  sourceRetirementCleanupControllerRetryRequired: true;
+  sourceRetirementCleanupAutomaticStartupDeletion: false;
+  reason?: string;
+}
+
+export interface IBucketTenantDescriptor extends plugins.tsclass.storage.IS3Descriptor {
+  endpoint: string;
+  port: number;
+  region: string;
+  bucket: string;
+  bucketName: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  accessKey: string;
+  accessSecret: string;
+  useSsl: boolean;
+  ssl: boolean;
+  env: Record<string, string>;
+  /** Present when ensureBucketTenant completed under a resource fence. */
+  resourceFence?: IObjectStorageResourceFenceReceipt;
+  /** Engine-verified immutable-retention evidence when configured for the bucket. */
+  retention?: IBucketRetentionReceipt;
+}
+
+export interface IBucketExportObject {
+  key: string;
+  size: number;
+  md5: string;
+  metadata: Record<string, string>;
+  dataHex: string;
+}
+
+export interface IBucketExport {
+  format: 'smartstorage.bucket.v1';
+  bucketName: string;
+  exportedAt: number;
+  objects: IBucketExportObject[];
+}
+
+export interface IObjectStorageReplaceEffectivePayloadV1 {
+  version: 1;
+  kind: 'smartstorage.bucket.replace.v1';
+  bucketName: string;
+  accessKeyId?: string;
+  /** Request a durable write-publication barrier after provider replacement. */
+  holdPublication?: boolean;
+  source: IBucketExport;
+}
+
+export interface IObjectStorageExactDeleteEffectivePayloadV1 {
+  version: 1;
+  kind: 'smartstorage.bucket.delete.v1';
+  bucketName: string;
+  accessKeyId: string;
+  /** Request a durable write-publication barrier after provider deletion. */
+  holdPublication?: boolean;
+}
+
+export interface IObjectStorageEnsureEffectivePayloadV1 {
+  version: 1;
+  kind: 'smartstorage.bucket.ensure.v1';
+  bucketName: string;
+  accessKeyId: string;
+  /** Hashed before it is incorporated into the effective payload digest. */
+  secretAccessKey: string;
+  /** The effective region applied by the provider. */
+  region: string;
+  /** Optional immutable-retention intent applied as part of the fenced ensure. */
+  retention?: IBucketRetentionPolicyInput;
+}
+
+export type TObjectStorageResourceFenceEffectivePayloadV1 =
+  | IObjectStorageReplaceEffectivePayloadV1
+  | IObjectStorageExactDeleteEffectivePayloadV1
+  | IObjectStorageEnsureEffectivePayloadV1;
+
+const resourceFenceV1Limits = {
+  maximumObjects: 10_000,
+  maximumObjectBytes: 64 * 1024 * 1024,
+  maximumImportBytes: 64 * 1024 * 1024,
+  maximumKeyBytes: 1024,
+  maximumMetadataEntries: 64,
+  maximumMetadataBytes: 8 * 1024,
+  maximumTotalKeyBytes: 1024 * 1024,
+  maximumTotalMetadataBytes: 1024 * 1024,
+  maximumIdentifierBytes: 256,
+} as const;
+
+const resourceFenceV1Uint64 = (valueArg: number): Buffer => {
+  if (!Number.isSafeInteger(valueArg) || valueArg < 0) {
+    throw new Error('ObjectStorage resource fence v1 integers must be non-negative safe integers.');
+  }
+  const encoded = Buffer.alloc(8);
+  encoded.writeBigUInt64BE(BigInt(valueArg));
+  return encoded;
+};
+
+const resourceFenceV1Utf8 = (valueArg: string, fieldArg: string): Buffer => {
+  if (typeof valueArg !== 'string') {
+    throw new Error(`${fieldArg} must be a string.`);
+  }
+  const encoded = Buffer.from(valueArg, 'utf8');
+  if (encoded.toString('utf8') !== valueArg) {
+    throw new Error(`${fieldArg} must contain valid Unicode scalar values.`);
+  }
+  return encoded;
+};
+
+const compareResourceFenceV1Utf8 = (leftArg: string, rightArg: string): number =>
+  Buffer.compare(Buffer.from(leftArg, 'utf8'), Buffer.from(rightArg, 'utf8'));
+
+const assertResourceFenceV1BucketName = (bucketNameArg: string): void => {
+  const encoded = resourceFenceV1Utf8(bucketNameArg, 'bucketName');
+  const ipv4Parts = bucketNameArg.split('.');
+  const isIpv4Address = ipv4Parts.length === 4 && ipv4Parts.every((part) =>
+    /^[0-9]+$/.test(part) && Number(part) <= 255
+  );
+  if (
+    encoded.length < 3
+    || encoded.length > 63
+    || !/^[a-z0-9][a-z0-9.-]*[a-z0-9]$/.test(bucketNameArg)
+    || bucketNameArg.includes('..')
+    || isIpv4Address
+  ) {
+    throw new Error('bucketName is not a canonical S3 bucket name.');
+  }
+};
+
+const assertResourceFenceV1Identifier = (valueArg: string, fieldArg: string): void => {
+  const encoded = resourceFenceV1Utf8(valueArg, fieldArg);
+  if (
+    encoded.length === 0
+    || encoded.length > resourceFenceV1Limits.maximumIdentifierBytes
+    || !/^[A-Za-z0-9][A-Za-z0-9._:@-]*$/.test(valueArg)
+  ) {
+    throw new Error(`${fieldArg} is not a canonical identifier.`);
+  }
+};
+
+const canonicalResourceFenceV1Metadata = (
+  metadataArg: Record<string, string>,
+  objectKeyArg: string,
+): Buffer => {
+  if (!metadataArg || typeof metadataArg !== 'object' || Array.isArray(metadataArg)) {
+    throw new Error(`Object '${objectKeyArg}' metadata must be an object.`);
+  }
+  const entries = Object.entries(metadataArg);
+  if (entries.length > resourceFenceV1Limits.maximumMetadataEntries) {
+    throw new Error(`Object '${objectKeyArg}' has too many metadata entries.`);
+  }
+  for (const [key, value] of entries) {
+    const keyBytes = resourceFenceV1Utf8(key, `Object '${objectKeyArg}' metadata key`);
+    const valueBytes = resourceFenceV1Utf8(value, `Object '${objectKeyArg}' metadata value`);
+    if (
+      keyBytes.length === 0
+      || keyBytes.length > 128
+      || valueBytes.length > 2048
+      || keyBytes.some((byte) => byte <= 0x1f || byte === 0x7f)
+      || valueBytes.some((byte) => (byte <= 0x1f && byte !== 0x09) || byte === 0x7f)
+    ) {
+      throw new Error(`Object '${objectKeyArg}' metadata is invalid.`);
+    }
+  }
+  entries.sort(([left], [right]) => compareResourceFenceV1Utf8(left, right));
+  const encoded = Buffer.from(
+    `{${entries.map(([key, value]) => `${JSON.stringify(key)}:${JSON.stringify(value)}`).join(',')}}`,
+    'utf8',
+  );
+  if (encoded.length > resourceFenceV1Limits.maximumMetadataBytes) {
+    throw new Error(`Object '${objectKeyArg}' metadata exceeds its size limit.`);
+  }
+  return encoded;
+};
+
+/**
+ * Computes the canonical provider-side effective payload digest for resource
+ * fencing v1. This intentionally excludes backup timestamps and source bucket
+ * names, matching the Rust engine's replacement and exact-delete profiles.
+ */
+export const computeObjectStorageResourceFenceEffectivePayloadSha256V1 = (
+  payloadArg: TObjectStorageResourceFenceEffectivePayloadV1,
+): string => {
+  if (payloadArg.version !== 1) {
+    throw new Error('ObjectStorage resource fence effective payload version is unsupported.');
+  }
+  assertResourceFenceV1BucketName(payloadArg.bucketName);
+  const hash = plugins.crypto.createHash('sha256');
+  const digestField = (valueArg: string | Buffer): void => {
+    const value = typeof valueArg === 'string'
+      ? resourceFenceV1Utf8(valueArg, 'resource fence digest field')
+      : valueArg;
+    hash.update(resourceFenceV1Uint64(value.length));
+    hash.update(value);
+  };
+
+  if (payloadArg.kind === 'smartstorage.bucket.delete.v1') {
+    assertResourceFenceV1Identifier(payloadArg.accessKeyId, 'accessKeyId');
+    digestField(payloadArg.kind);
+    digestField(payloadArg.bucketName);
+    digestField(payloadArg.accessKeyId);
+    if (payloadArg.holdPublication === true) {
+      digestField('smartstorage.resource-fence.hold-publication.v1');
+      digestField(Buffer.from([1]));
+    }
+    return hash.digest('hex');
+  }
+  if (payloadArg.kind === 'smartstorage.bucket.ensure.v1') {
+    assertResourceFenceV1Identifier(payloadArg.accessKeyId, 'accessKeyId');
+    const secretAccessKey = resourceFenceV1Utf8(
+      payloadArg.secretAccessKey,
+      'secretAccessKey',
+    );
+    if (!payloadArg.secretAccessKey.trim()) {
+      throw new Error('secretAccessKey must not be empty.');
+    }
+    const region = resourceFenceV1Utf8(payloadArg.region, 'region');
+    if (!payloadArg.region.trim()) {
+      throw new Error('region must not be empty.');
+    }
+    digestField(payloadArg.kind);
+    digestField(payloadArg.bucketName);
+    digestField(payloadArg.accessKeyId);
+    digestField(plugins.crypto.createHash('sha256').update(secretAccessKey).digest('hex'));
+    digestField(region);
+    if (payloadArg.retention) {
+      if (
+        payloadArg.retention.mode !== 'compliance'
+        || !/^[A-Za-z0-9._-]{1,96}$/.test(payloadArg.retention.policyId)
+        || !Number.isSafeInteger(payloadArg.retention.retentionDurationSeconds)
+        || payloadArg.retention.retentionDurationSeconds <= 0
+        || payloadArg.retention.retentionDurationSeconds > 100 * 366 * 24 * 60 * 60
+      ) {
+        throw new Error('retention must contain canonical compliance-retention intent.');
+      }
+      digestField('smartstorage.bucket.retention.v1');
+      digestField(payloadArg.retention.mode);
+      digestField(payloadArg.retention.policyId);
+      digestField(resourceFenceV1Uint64(payloadArg.retention.retentionDurationSeconds));
+    }
+    return hash.digest('hex');
+  }
+  if (payloadArg.kind !== 'smartstorage.bucket.replace.v1') {
+    throw new Error('ObjectStorage resource fence effective payload kind is unsupported.');
+  }
+  if (payloadArg.accessKeyId !== undefined) {
+    assertResourceFenceV1Identifier(payloadArg.accessKeyId, 'accessKeyId');
+  }
+
+  const source = payloadArg.source;
+  if (source.format !== 'smartstorage.bucket.v1') {
+    throw new Error('source format must be smartstorage.bucket.v1.');
+  }
+  assertResourceFenceV1BucketName(source.bucketName);
+  if (!Number.isSafeInteger(source.exportedAt) || source.exportedAt < 0) {
+    throw new Error('source exportedAt must be a non-negative safe integer.');
+  }
+  if (!Array.isArray(source.objects) || source.objects.length > resourceFenceV1Limits.maximumObjects) {
+    throw new Error(`source exceeds the ${resourceFenceV1Limits.maximumObjects}-object limit.`);
+  }
+
+  const logicalKeys = new Set<string>();
+  let totalBytes = 0;
+  let totalKeyBytes = 0;
+  let totalMetadataBytes = 0;
+  const prepared = source.objects.map((object) => {
+    const keyBytes = resourceFenceV1Utf8(object.key, 'object key');
+    if (
+      keyBytes.length === 0
+      || keyBytes.length > resourceFenceV1Limits.maximumKeyBytes
+    ) {
+      throw new Error(
+        `Object key '${object.key}' must contain between 1 and ${resourceFenceV1Limits.maximumKeyBytes} UTF-8 bytes.`,
+      );
+    }
+    if (logicalKeys.has(object.key)) {
+      throw new Error(`source contains duplicate object key '${object.key}'.`);
+    }
+    logicalKeys.add(object.key);
+    totalKeyBytes += keyBytes.length;
+    if (totalKeyBytes > resourceFenceV1Limits.maximumTotalKeyBytes) {
+      throw new Error(`source exceeds the ${resourceFenceV1Limits.maximumTotalKeyBytes}-byte aggregate key limit.`);
+    }
+
+    if (
+      !Number.isSafeInteger(object.size)
+      || object.size < 0
+      || object.size > resourceFenceV1Limits.maximumObjectBytes
+      || object.dataHex.length !== object.size * 2
+      || !/^[0-9a-f]*$/.test(object.dataHex)
+    ) {
+      throw new Error(`Object '${object.key}' dataHex or size is not canonical.`);
+    }
+    const data = Buffer.from(object.dataHex, 'hex');
+    if (data.length !== object.size) {
+      throw new Error(`Object '${object.key}' size does not match dataHex.`);
+    }
+    if (!/^[0-9a-f]{32}$/.test(object.md5)) {
+      throw new Error(`Object '${object.key}' md5 is not canonical.`);
+    }
+    const actualMd5 = plugins.crypto.createHash('md5').update(data).digest('hex');
+    if (actualMd5 !== object.md5) {
+      throw new Error(`Object '${object.key}' md5 does not match payload.`);
+    }
+
+    const metadata = canonicalResourceFenceV1Metadata(object.metadata, object.key);
+    totalMetadataBytes += metadata.length;
+    if (totalMetadataBytes > resourceFenceV1Limits.maximumTotalMetadataBytes) {
+      throw new Error(`source exceeds the ${resourceFenceV1Limits.maximumTotalMetadataBytes}-byte aggregate metadata limit.`);
+    }
+    totalBytes += object.size;
+    if (totalBytes > resourceFenceV1Limits.maximumImportBytes) {
+      throw new Error(`source exceeds the ${resourceFenceV1Limits.maximumImportBytes}-byte import limit.`);
+    }
+    return {
+      key: object.key,
+      size: object.size,
+      md5: object.md5,
+      metadata,
+      dataSha256: plugins.crypto.createHash('sha256').update(data).digest('hex'),
+    };
+  });
+  prepared.sort((left, right) => compareResourceFenceV1Utf8(left.key, right.key));
+
+  digestField(payloadArg.kind);
+  digestField(payloadArg.bucketName);
+  if (payloadArg.accessKeyId !== undefined) {
+    digestField(payloadArg.accessKeyId);
+  }
+  digestField(resourceFenceV1Uint64(prepared.length));
+  for (const object of prepared) {
+    digestField(object.key);
+    digestField(resourceFenceV1Uint64(object.size));
+    digestField(object.md5);
+    digestField(object.metadata);
+    digestField(object.dataSha256);
+  }
+  if (payloadArg.holdPublication === true) {
+    digestField('smartstorage.resource-fence.hold-publication.v1');
+    digestField(Buffer.from([1]));
+  }
+  return hash.digest('hex');
+};
+
+export interface IExportBucketInput {
+  bucketName: string;
+}
+
+export interface IImportBucketInput {
+  bucketName: string;
+  source: IBucketExport;
+  /** Exact exclusive bucket credential required by the fenced replacement. */
+  accessKeyId?: string;
+  fence?: IObjectStorageResourceFence;
+  /** Keep target writes closed until commitResourcePublication succeeds. */
+  holdPublication?: boolean;
+}
+
+export interface IDeleteBucketInput {
+  bucketName: string;
+  /**
+   * Exact bucket-scoped credential to revoke. When supplied, the access key
+   * is included in the durable mutation identity and retries treat an already
+   * absent key as a successful idempotent revocation. Omitting it retains the
+   * legacy data-only deletion behavior that preserves credentials and policy.
+   */
+  accessKeyId?: string;
+  fence: IObjectStorageResourceFence;
+  /** Keep target writes closed until commitResourcePublication succeeds. */
+  holdPublication?: boolean;
+}
+
+export interface IObjectStorageResourceFence {
+  version: 1;
+  scopeId: string;
+  token: number;
+  mutationId: string;
+  payloadSha256: string;
+}
+
+export interface IObjectStorageResourceFenceReceipt
+  extends IObjectStorageResourceFence {
+  kind:
+    | 'smartstorage.bucket.replace.v1'
+    | 'smartstorage.bucket.delete.v1'
+    | 'smartstorage.bucket.ensure.v1';
+  effectivePayloadSha256: string;
+}
+
+export interface IObjectStorageResourcePublicationBarrier {
+  version: 1;
+  kind: 'smartstorage.bucket.write-publication.v1';
+  providerRootIdentitySha256: string;
+  bucketName: string;
+  resourceIdSha256: string;
+  scopeId: string;
+  token: number;
+  mutationId: string;
+  mutationKind: 'smartstorage.bucket.replace.v1' | 'smartstorage.bucket.delete.v1';
+  payloadSha256: string;
+  effectivePayloadSha256: string;
+  mutationReceiptSha256: string;
+  /** Opaque CSPRNG capability. Never log or persist outside protected control state. */
+  commitCapability: string;
+}
+
+export interface IObjectStorageResourcePublicationReleaseReceipt {
+  version: 1;
+  kind: 'smartstorage.bucket.write-publication.release.v1';
+  providerRootIdentitySha256: string;
+  bucketName: string;
+  resourceIdSha256: string;
+  scopeId: string;
+  token: number;
+  mutationId: string;
+  mutationKind: 'smartstorage.bucket.replace.v1' | 'smartstorage.bucket.delete.v1';
+  payloadSha256: string;
+  effectivePayloadSha256: string;
+  mutationReceiptSha256: string;
+  barrierSha256: string;
+}
+
+export interface ICommitObjectStorageResourcePublicationInput {
+  barrier: IObjectStorageResourcePublicationBarrier;
+  resourceFenceReceipt: IObjectStorageResourceFenceReceipt;
+}
+
+export interface IObjectStorageBucketMutationResult {
+  bucketName: string;
+  objects?: number;
+  totalBytes?: number;
+  bucketDeleted?: boolean;
+  /**
+   * Credentials removed during the completing attempt. A crash-recovery
+   * retry can report zero after the exact credential was already persisted
+   * as absent.
+   */
+  deletedCredentials?: number;
+  credentialsPreserved?: boolean;
+  policyPreserved?: boolean;
+  resourceFence?: IObjectStorageResourceFenceReceipt;
+  resourcePublicationBarrier?: IObjectStorageResourcePublicationBarrier;
+  resourcePublicationRelease?: IObjectStorageResourcePublicationReleaseReceipt;
+}
+
+export interface IObjectStorageResourceFencingCapability {
+  version: 1;
+  supported: boolean;
+  requiresDrain: true;
+  publicationHoldVersion: 1;
+  publicationHoldSupported: boolean;
+  publicationHoldRequiresExternalDrain: false;
+  reason?: string;
+}
+
+export interface IObjectStorageHealth {
+  ok: boolean;
+  running: boolean;
+  storageDirectory: string;
+  storageLocations?: IStorageLocationSummary[];
+  auth: {
+    enabled: boolean;
+    credentialCount: number;
+    tenantCredentialCount: number;
+  };
+  bucketCount: number;
+  objectCount: number;
+  totalBytes: number;
+  cluster: IClusterHealth;
+  resourceFencingVersion: 1;
+  resourceFencingSupported: boolean;
+  resourceFencingRequiresDrain: true;
+  resourcePublicationHoldVersion: 1;
+  resourcePublicationHoldSupported: boolean;
+  resourcePublicationHoldRequiresExternalDrain: false;
+  resourceFencingReason?: string;
+}
+
+export const objectStorageResourceFenceErrorCodes = [
+  'EFENCE_REQUIRED',
+  'EFENCE_STALE',
+  'EFENCE_SCOPE_MISMATCH',
+  'EFENCE_UNSUPPORTED',
+  'EFENCE_MUTATION_MISMATCH',
+  'EFENCE_STATE_CORRUPT',
+  'EFENCE_RECEIPT_LIMIT',
+  'EFENCE_BUSY',
+  'EFENCE_OWNERSHIP_MISMATCH',
+  'EFENCE_PUBLICATION_HELD',
+  'EFENCE_PUBLICATION_MISMATCH',
+  'EFENCE_PUBLICATION_CAPABILITY',
+] as const;
+
+export type TObjectStorageResourceFenceErrorCode =
+  (typeof objectStorageResourceFenceErrorCodes)[number];
+
+export class ObjectStorageResourceFenceError extends Error {
+  public readonly code: TObjectStorageResourceFenceErrorCode;
+
+  public constructor(
+    codeArg: TObjectStorageResourceFenceErrorCode,
+    messageArg: string,
+    causeArg?: unknown,
+  ) {
+    super(`${codeArg}: ${messageArg}`, { cause: causeArg });
+    this.name = 'ObjectStorageResourceFenceError';
+    this.code = codeArg;
+  }
+}
+
+const normalizeResourceFenceError = (errorArg: unknown): Error => {
+  const error = errorArg instanceof Error ? errorArg : new Error(String(errorArg));
+  const match = /(EFENCE_[A-Z_]+):\s*(.*)$/s.exec(error.message);
+  if (
+    !match ||
+    !objectStorageResourceFenceErrorCodes.includes(
+      match[1] as TObjectStorageResourceFenceErrorCode,
+    )
+  ) {
+    return error;
+  }
+  return new ObjectStorageResourceFenceError(
+    match[1] as TObjectStorageResourceFenceErrorCode,
+    match[2],
+    error,
+  );
+};
+
+export interface IObjectStorageMetrics {
+  bucketCount: number;
+  objectCount: number;
+  totalBytes: number;
+  authCredentialCount: number;
+  tenantCredentialCount: number;
+  clusterEnabled: boolean;
+  prometheusText: string;
+}
+
+/**
+ * Known peer status from the local node's current cluster view.
+ */
+export interface IClusterPeerHealth {
+  nodeId: string;
+  status: 'online' | 'suspect' | 'offline';
+  quicAddress?: string;
+  s3Address?: string;
+  driveCount?: number;
+  lastHeartbeat?: number;
+  missedHeartbeats?: number;
+}
+
+/**
+ * Local drive health as measured by objectstorage's runtime probes.
+ */
+export interface IClusterDriveHealth {
+  index: number;
+  path: string;
+  status: 'online' | 'degraded' | 'offline' | 'healing';
+  totalBytes?: number;
+  usedBytes?: number;
+  availableBytes?: number;
+  errorCount?: number;
+  lastError?: string;
+  lastCheck?: number;
+  erasureSetId?: number;
+}
+
+export interface IClusterErasureHealth {
+  dataShards: number;
+  parityShards: number;
+  chunkSizeBytes: number;
+  totalShards: number;
+  readQuorum: number;
+  writeQuorum: number;
+  erasureSetCount: number;
+}
+
+export interface IClusterRepairHealth {
+  active: boolean;
+  scanIntervalMs?: number;
+  lastRunStartedAt?: number;
+  lastRunCompletedAt?: number;
+  lastDurationMs?: number;
+  shardsChecked?: number;
+  shardsHealed?: number;
+  failed?: number;
+  lastError?: string;
+}
+
+/**
+ * Cluster runtime health from the Rust core.
+ * When clustering is disabled, the response is `{ enabled: false }`.
+ */
+export interface IClusterHealth {
+  enabled: boolean;
+  nodeId?: string;
+  quorumHealthy?: boolean;
+  majorityHealthy?: boolean;
+  peers?: IClusterPeerHealth[];
+  drives?: IClusterDriveHealth[];
+  erasure?: IClusterErasureHealth;
+  repairs?: IClusterRepairHealth;
+}
+
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG: IObjectStorageConfig = {
+  server: {
+    port: 3000,
+    address: '0.0.0.0',
+    silent: false,
+    region: 'us-east-1',
+  },
+  storage: {
+    directory: paths.bucketsDir,
+    cleanSlate: false,
+  },
+  auth: {
+    enabled: false,
+    credentials: [
+      {
+        accessKeyId: 'STORAGE',
+        secretAccessKey: 'STORAGE',
+      },
+    ],
+  },
+  cors: {
+    enabled: false,
+    allowedOrigins: ['*'],
+    allowedMethods: ['GET', 'POST', 'PUT', 'DELETE', 'HEAD', 'OPTIONS'],
+    allowedHeaders: ['*'],
+    exposedHeaders: ['ETag', 'x-amz-request-id', 'x-amz-version-id'],
+    maxAge: 86400,
+    allowCredentials: false,
+  },
+  logging: {
+    level: 'info',
+    format: 'text',
+    enabled: true,
+  },
+  limits: {
+    maxObjectSize: 5 * 1024 * 1024 * 1024, // 5GB
+    maxMetadataSize: 2048,
+    requestTimeout: 300000, // 5 minutes
+  },
+  multipart: {
+    expirationDays: 7,
+    cleanupIntervalMinutes: 60,
+  },
+};
+
+// A fenced import may contain 64 MiB of raw object data encoded as hexadecimal.
+// Keep this aligned with the bounded Rust management-line reader.
+const MAXIMUM_MANAGEMENT_PAYLOAD_BYTES = 144 * 1024 * 1024;
+
+function assertExactMountedDirectory(directoryArg: string, fieldArg: string): void {
+  if (
+    directoryArg.length === 0 ||
+    !plugins.path.isAbsolute(directoryArg) ||
+    plugins.path.normalize(directoryArg) !== directoryArg ||
+    plugins.path.resolve(directoryArg) !== directoryArg
+  ) {
+    throw new Error(
+      `${fieldArg} must be a non-empty absolute lexically exact mountpoint without '.', '..', duplicate separators, or a trailing separator.`,
+    );
+  }
+}
+
+/**
+ * Merge user config with defaults (deep merge)
+ */
+function mergeConfig(userConfig: IObjectStorageConfig): Required<IObjectStorageConfig> {
+  const userStorage = userConfig.storage || {};
+  const defaultDirectory = DEFAULT_CONFIG.storage!.directory!;
+  const legacyDirectory = userStorage.directory;
+  const configuredPool = userStorage.pool;
+  const configuredMountedPool = configuredPool?.backend.kind === 'mountedFs';
+
+  if (configuredMountedPool) {
+    assertExactMountedDirectory(
+      configuredPool.directory,
+      'storage.pool.directory',
+    );
+    if (legacyDirectory !== undefined) {
+      assertExactMountedDirectory(legacyDirectory, 'storage.directory');
+      if (legacyDirectory !== configuredPool.directory) {
+        throw new Error(
+          'storage.directory and storage.pool.directory must be the same exact mountedFs path.',
+        );
+      }
+    }
+  }
+
+  const effectiveDirectory =
+    configuredPool?.directory || legacyDirectory || defaultDirectory;
+
+  if (
+    configuredPool &&
+    !configuredMountedPool &&
+    legacyDirectory &&
+    plugins.path.resolve(configuredPool.directory) !==
+      plugins.path.resolve(legacyDirectory)
+  ) {
+    throw new Error(
+      'storage.directory and storage.pool.directory must resolve to the same path.',
+    );
+  }
+
+  const pool: IStoragePoolConfig = configuredPool
+    ? {
+        ...configuredPool,
+        directory: plugins.path.resolve(effectiveDirectory),
+        backend: { ...configuredPool.backend },
+      }
+    : {
+        id: 'default',
+        directory: plugins.path.resolve(effectiveDirectory),
+        backend: { kind: 'localFs' },
+      };
+
+  if (!/^[a-z][a-z0-9-]{0,62}$/.test(pool.id)) {
+    throw new Error(
+      'storage.pool.id must start with a lowercase letter and contain at most 63 lowercase letters, digits, or hyphens.',
+    );
+  }
+  if (
+    pool.backend.kind === 'mountedFs' &&
+    pool.backend.expectedSource.trim().length === 0
+  ) {
+    throw new Error(
+      'storage.pool.backend.expectedSource must not be empty for mountedFs.',
+    );
+  }
+  if (pool.backend.kind === 'mountedFs' && userStorage.cleanSlate) {
+    throw new Error('storage.cleanSlate is not permitted for mountedFs pools.');
+  }
+
+  return {
+    server: {
+      ...DEFAULT_CONFIG.server!,
+      ...(userConfig.server || {}),
+    },
+    storage: {
+      ...DEFAULT_CONFIG.storage!,
+      ...userStorage,
+      directory: pool.directory,
+      pool,
+    },
+    auth: {
+      ...DEFAULT_CONFIG.auth!,
+      ...(userConfig.auth || {}),
+    },
+    cors: {
+      ...DEFAULT_CONFIG.cors!,
+      ...(userConfig.cors || {}),
+    },
+    logging: {
+      ...DEFAULT_CONFIG.logging!,
+      ...(userConfig.logging || {}),
+    },
+    limits: {
+      ...DEFAULT_CONFIG.limits!,
+      ...(userConfig.limits || {}),
+    },
+    multipart: {
+      ...DEFAULT_CONFIG.multipart!,
+      ...(userConfig.multipart || {}),
+    },
+    ...(userConfig.cluster ? { cluster: userConfig.cluster } : {}),
+  } as Required<IObjectStorageConfig>;
+}
+
+function createAccessKeyId(): string {
+  return `SS${plugins.crypto.randomBytes(10).toString('hex').toUpperCase()}`;
+}
+
+function createSecretAccessKey(): string {
+  return plugins.crypto.randomBytes(32).toString('hex');
+}
+
+function getRustStorageBinaryNames(): string[] {
+  const platformTargetMap: Record<string, string> = {
+    'linux:x64': 'linux_amd64',
+    'linux:arm64': 'linux_arm64',
+    'darwin:x64': 'macos_amd64',
+    'darwin:arm64': 'macos_arm64',
+  };
+  const platformTarget = platformTargetMap[`${process.platform}:${process.arch}`];
+  return [platformTarget ? `ruststorage_${platformTarget}` : null, 'ruststorage']
+    .filter((binaryNameArg): binaryNameArg is string => Boolean(binaryNameArg));
+}
+
+/**
+ * IPC command type map for RustBridge
+ */
+type TRustStorageCommands = {
+  probeStoragePool: {
+    params: { pool: IMountedStoragePoolConfig };
+    result: IStoragePoolObservation;
+  };
+  getStoragePoolDiagnostic: {
+    params: {};
+    result: IStoragePoolObservation | null;
+  };
+  start: { params: { config: Required<IObjectStorageConfig> }; result: {} };
+  stop: { params: {}; result: IStorageStopResult };
+  createBucket: { params: { name: string }; result: {} };
+  createBucketTenant: {
+    params: {
+      bucketName: string;
+      accessKeyId: string;
+      secretAccessKey: string;
+      region?: string;
+      retention?: IBucketRetentionPolicyInput;
+    };
+    result: IStorageCredential & { retention?: IBucketRetentionReceipt };
+  };
+  ensureBucketTenant: {
+    params: IEnsureBucketTenantInput;
+    result: IStorageCredential & {
+      resourceFence?: IObjectStorageResourceFenceReceipt;
+      retention?: IBucketRetentionReceipt;
+    };
+  };
+  deleteBucketTenant: {
+    params: { bucketName: string; accessKeyId?: string };
+    result: {};
+  };
+  rotateBucketTenantCredentials: {
+    params: {
+      bucketName: string;
+      accessKeyId: string;
+      secretAccessKey: string;
+      region?: string;
+    };
+    result: IStorageCredential & { retention?: IBucketRetentionReceipt };
+  };
+  listBucketTenants: { params: {}; result: IBucketTenantMetadata[] };
+  getBucketTenantCredential: {
+    params: { bucketName: string };
+    result: IStorageCredential & { retention?: IBucketRetentionReceipt };
+  };
+  getBucketRetentionCapability: { params: {}; result: IBucketRetentionCapability };
+  getBucketRetentionReceipt: {
+    params: { bucketName: string };
+    result: IBucketRetentionReceipt | null;
+  };
+  getBucketMigrationCapability: {
+    params: {};
+    result: IObjectStorageBucketMigrationCapability;
+  };
+  createSourceMigration: {
+    params: IObjectStorageMigrationCreateInput;
+    result: IObjectStorageMigrationTransitionReceipt;
+  };
+  createDestinationMigration: {
+    params: IObjectStorageMigrationCreateInput;
+    result: IObjectStorageMigrationTransitionReceipt;
+  };
+  transitionSourceMigration: {
+    params: IObjectStorageSourceMigrationTransitionInput;
+    result: IObjectStorageMigrationTransitionReceipt;
+  };
+  transitionDestinationMigration: {
+    params: IObjectStorageDestinationMigrationTransitionInput;
+    result: IObjectStorageMigrationTransitionReceipt;
+  };
+  cleanupSourceMigration: {
+    params: IObjectStorageSourceMigrationCleanupInput;
+    result: IObjectStorageSourceMigrationCleanupReceipt;
+  };
+  inspectBucketMigration: {
+    params: { migrationId: string };
+    result: IObjectStorageMigrationInspection | null;
+  };
+  exportBucket: { params: { bucketName: string }; result: IBucketExport };
+  importBucket: {
+    params: IImportBucketInput;
+    result: IObjectStorageBucketMutationResult;
+  };
+  deleteBucket: {
+    params: IDeleteBucketInput;
+    result: IObjectStorageBucketMutationResult;
+  };
+  commitResourcePublication: {
+    params: ICommitObjectStorageResourcePublicationInput;
+    result: IObjectStorageResourcePublicationReleaseReceipt;
+  };
+  getResourceFencingCapability: {
+    params: {};
+    result: IObjectStorageResourceFencingCapability;
+  };
+  getStorageStats: { params: {}; result: IStorageStats };
+  listBucketSummaries: { params: {}; result: IBucketSummary[] };
+  listCredentials: { params: {}; result: IStorageCredentialMetadata[] };
+  replaceCredentials: { params: { credentials: IStorageCredential[] }; result: {} };
+  getClusterHealth: { params: {}; result: IClusterHealth };
+};
+
+/**
+ * Main ObjectStorage class - production-ready S3-compatible storage server
+ */
+export class ObjectStorage {
+  // STATIC
+  public static async createAndStart(configArg: IObjectStorageConfig = {}) {
+    const objectStorageInstance = new ObjectStorage(configArg);
+    await objectStorageInstance.start();
+    return objectStorageInstance;
+  }
+
+  public static async probeStoragePool(
+    poolArg: IMountedStoragePoolConfig,
+  ): Promise<IStoragePoolObservation> {
+    const objectStorageInstance = new ObjectStorage({
+      server: { silent: true },
+      storage: {
+        directory: poolArg.directory,
+        cleanSlate: false,
+        pool: poolArg,
+      },
+    });
+    await objectStorageInstance.ensureLocalBinariesExecutable();
+    const spawned = await objectStorageInstance.bridge.spawn();
+    if (!spawned) {
+      throw new Error(
+        'Failed to spawn ruststorage binary. Make sure it is compiled (pnpm build).',
+      );
+    }
+    try {
+      return await objectStorageInstance.bridge.sendCommand('probeStoragePool', {
+        pool: objectStorageInstance.config.storage
+          .pool as IMountedStoragePoolConfig,
+      });
+    } finally {
+      await objectStorageInstance.bridge.terminate();
+    }
+  }
+
+  // INSTANCE
+  public config: Required<IObjectStorageConfig>;
+  private localBinaryPaths: string[];
+  private bridge: InstanceType<typeof plugins.RustBridge<TRustStorageCommands>>;
+  private running = false;
+  private completedStopResult: IStorageStopResult | undefined;
+  private startPromise: Promise<void> | undefined;
+  private stopPromise: Promise<void> | undefined;
+  private bridgeOwned = false;
+  private stopRequested = false;
+  private stopCompleted = false;
+
+  constructor(configArg: IObjectStorageConfig = {}) {
+    this.config = mergeConfig(configArg);
+    this.localBinaryPaths = getRustStorageBinaryNames().map((binaryNameArg) =>
+      plugins.path.join(paths.packageDir, 'dist_rust', binaryNameArg),
+    );
+    this.bridge = new plugins.RustBridge<TRustStorageCommands>({
+      binaryName: 'ruststorage',
+      localPaths: this.localBinaryPaths,
+      readyTimeoutMs: 30000,
+      requestTimeoutMs: 300000,
+      maxPayloadSize: MAXIMUM_MANAGEMENT_PAYLOAD_BYTES,
+    });
+  }
+
+  private async ensureLocalBinariesExecutable() {
+    for (const localBinaryPath of this.localBinaryPaths) {
+      const binaryStat = await plugins.fs.stat(localBinaryPath).catch((errorArg: NodeJS.ErrnoException) => {
+        if (errorArg.code !== 'ENOENT') {
+          throw errorArg;
+        }
+        return null;
+      });
+      if (!binaryStat || (binaryStat.mode & 0o111) !== 0) {
+        continue;
+      }
+      await plugins.fs.chmod(localBinaryPath, binaryStat.mode | 0o755);
+    }
+  }
+
+  public start(): Promise<void> {
+    if (this.stopRequested && !this.stopCompleted) {
+      return Promise.reject(new Error('Storage shutdown must complete before restarting.'));
+    }
+    if (this.startPromise) {
+      return this.startPromise;
+    }
+    if (this.running) {
+      return Promise.resolve();
+    }
+    if (this.bridgeOwned) {
+      return Promise.reject(new Error('Storage startup cleanup must complete before restarting.'));
+    }
+    this.stopRequested = false;
+    this.stopCompleted = false;
+    this.stopPromise = undefined;
+    this.completedStopResult = undefined;
+    const start = this.startInternal();
+    this.startPromise = start;
+    const releaseStart = () => {
+      if (this.startPromise === start) {
+        this.startPromise = undefined;
+      }
+    };
+    start.then(releaseStart, releaseStart);
+    return start;
+  }
+
+  private async startInternal(): Promise<void> {
+    try {
+      await this.ensureLocalBinariesExecutable();
+      // A failed spawn can still own a transport whose termination needs retrying.
+      this.bridgeOwned = true;
+      const spawned = await this.bridge.spawn();
+      if (!spawned) {
+        throw new Error('Failed to spawn ruststorage binary. Make sure it is compiled (pnpm build).');
+      }
+      await this.bridge.sendCommand('start', { config: this.config });
+    } catch (error) {
+      try {
+        if (this.bridgeOwned) {
+          await this.bridge.terminate();
+          this.bridgeOwned = false;
+        }
+      } catch (terminationError) {
+        throw new AggregateError(
+          [error, terminationError],
+          'Storage startup failed and Rust bridge termination could not be confirmed.',
+          { cause: error },
+        );
+      }
+      throw error;
+    }
+    this.running = true;
+
+    if (!this.config.server.silent) {
+      console.log('storage server is running');
+    }
+  }
+
+  public async getStorageDescriptor(
+    optionsArg?: Partial<plugins.tsclass.storage.IS3Descriptor>,
+  ): Promise<plugins.tsclass.storage.IS3Descriptor> {
+    const cred = this.config.auth.credentials[0] || {
+      accessKeyId: 'STORAGE',
+      secretAccessKey: 'STORAGE',
+    };
+
+    const descriptor: plugins.tsclass.storage.IS3Descriptor = {
+      endpoint: this.config.server.address === '0.0.0.0' ? 'localhost' : this.config.server.address!,
+      port: this.config.server.port!,
+      useSsl: false,
+      accessKey: cred.accessKeyId,
+      accessSecret: cred.secretAccessKey,
+      bucketName: '',
+    };
+
+    return {
+      ...descriptor,
+      ...(optionsArg ? optionsArg : {}),
+    };
+  }
+
+  private getEndpoint(): string {
+    return this.config.server.address === '0.0.0.0' ? 'localhost' : this.config.server.address!;
+  }
+
+  private buildBucketTenantDescriptor(
+    credential: IStorageCredential & {
+      resourceFence?: IObjectStorageResourceFenceReceipt;
+      retention?: IBucketRetentionReceipt;
+    },
+    bucketNameArg: string,
+  ): IBucketTenantDescriptor {
+    const bucketName = credential.bucketName || bucketNameArg;
+    const region = credential.region || this.config.server.region || 'us-east-1';
+    const endpoint = this.getEndpoint();
+    const port = this.config.server.port!;
+    const useSsl = false;
+
+    const descriptor: IBucketTenantDescriptor = {
+      endpoint,
+      port,
+      region,
+      bucket: bucketName,
+      bucketName,
+      accessKeyId: credential.accessKeyId,
+      secretAccessKey: credential.secretAccessKey,
+      accessKey: credential.accessKeyId,
+      accessSecret: credential.secretAccessKey,
+      useSsl,
+      ssl: useSsl,
+      env: {
+        S3_ENDPOINT: endpoint,
+        S3_PORT: String(port),
+        S3_REGION: region,
+        S3_BUCKET: bucketName,
+        S3_ACCESS_KEY_ID: credential.accessKeyId,
+        S3_SECRET_ACCESS_KEY: credential.secretAccessKey,
+        S3_USE_SSL: String(useSsl),
+        AWS_ACCESS_KEY_ID: credential.accessKeyId,
+        AWS_SECRET_ACCESS_KEY: credential.secretAccessKey,
+        AWS_REGION: region,
+      },
+    };
+    if (credential.resourceFence) {
+      descriptor.resourceFence = credential.resourceFence;
+    }
+    if (credential.retention) {
+      descriptor.retention = credential.retention;
+    }
+    return descriptor;
+  }
+
+  private assertTenantAuthEnabled(): void {
+    if (!this.config.auth.enabled) {
+      throw new Error('Bucket tenant APIs require auth.enabled=true.');
+    }
+  }
+
+  public async createBucket(bucketNameArg: string) {
+    try {
+      await this.bridge.sendCommand('createBucket', { name: bucketNameArg });
+      return { name: bucketNameArg };
+    } catch (error) {
+      throw normalizeResourceFenceError(error);
+    }
+  }
+
+  public async createBucketTenant(
+    tenantArg: IBucketTenantInput,
+  ): Promise<IBucketTenantDescriptor> {
+    this.assertTenantAuthEnabled();
+    try {
+      const credential = await this.bridge.sendCommand('createBucketTenant', {
+        bucketName: tenantArg.bucketName,
+        accessKeyId: tenantArg.accessKeyId || createAccessKeyId(),
+        secretAccessKey: tenantArg.secretAccessKey || createSecretAccessKey(),
+        region: tenantArg.region || this.config.server.region,
+        ...(tenantArg.retention ? { retention: tenantArg.retention } : {}),
+      });
+      return this.buildBucketTenantDescriptor(credential, tenantArg.bucketName);
+    } catch (error) {
+      throw normalizeResourceFenceError(error);
+    }
+  }
+
+  public async ensureBucketTenant(
+    tenantArg: IEnsureBucketTenantInput,
+  ): Promise<IBucketTenantDescriptor> {
+    this.assertTenantAuthEnabled();
+    try {
+      const credential = await this.bridge.sendCommand('ensureBucketTenant', {
+        ...tenantArg,
+        region: tenantArg.region || this.config.server.region,
+      });
+      return this.buildBucketTenantDescriptor(credential, tenantArg.bucketName);
+    } catch (error) {
+      throw normalizeResourceFenceError(error);
+    }
+  }
+
+  public async deleteBucketTenant(tenantArg: IDeleteBucketTenantInput): Promise<void> {
+    this.assertTenantAuthEnabled();
+    try {
+      await this.bridge.sendCommand('deleteBucketTenant', tenantArg);
+    } catch (error) {
+      throw normalizeResourceFenceError(error);
+    }
+  }
+
+  public async rotateBucketTenantCredentials(
+    tenantArg: IBucketTenantInput,
+  ): Promise<IBucketTenantDescriptor> {
+    this.assertTenantAuthEnabled();
+    try {
+      const credential = await this.bridge.sendCommand('rotateBucketTenantCredentials', {
+        bucketName: tenantArg.bucketName,
+        accessKeyId: tenantArg.accessKeyId || createAccessKeyId(),
+        secretAccessKey: tenantArg.secretAccessKey || createSecretAccessKey(),
+        region: tenantArg.region || this.config.server.region,
+      });
+      return this.buildBucketTenantDescriptor(credential, tenantArg.bucketName);
+    } catch (error) {
+      throw normalizeResourceFenceError(error);
+    }
+  }
+
+  public async listBucketTenants(): Promise<IBucketTenantMetadata[]> {
+    this.assertTenantAuthEnabled();
+    return this.bridge.sendCommand('listBucketTenants', {});
+  }
+
+  public async getBucketTenantDescriptor(optionsArg: {
+    bucketName: string;
+  }): Promise<IBucketTenantDescriptor> {
+    this.assertTenantAuthEnabled();
+    const credential = await this.bridge.sendCommand('getBucketTenantCredential', {
+      bucketName: optionsArg.bucketName,
+    });
+    return this.buildBucketTenantDescriptor(credential, optionsArg.bucketName);
+  }
+
+  public async getBucketRetentionCapability(): Promise<IBucketRetentionCapability> {
+    return this.bridge.sendCommand('getBucketRetentionCapability', {});
+  }
+
+  public async getBucketRetentionReceipt(optionsArg: {
+    bucketName: string;
+  }): Promise<IBucketRetentionReceipt | null> {
+    return this.bridge.sendCommand('getBucketRetentionReceipt', optionsArg);
+  }
+
+  public async getBucketMigrationCapability(): Promise<IObjectStorageBucketMigrationCapability> {
+    return this.bridge.sendCommand('getBucketMigrationCapability', {});
+  }
+
+  public async createSourceMigration(
+    optionsArg: IObjectStorageMigrationCreateInput,
+  ): Promise<IObjectStorageMigrationTransitionReceipt> {
+    return this.bridge.sendCommand('createSourceMigration', optionsArg);
+  }
+
+  public async createDestinationMigration(
+    optionsArg: IObjectStorageMigrationCreateInput,
+  ): Promise<IObjectStorageMigrationTransitionReceipt> {
+    return this.bridge.sendCommand('createDestinationMigration', optionsArg);
+  }
+
+  public async transitionSourceMigration(
+    optionsArg: IObjectStorageSourceMigrationTransitionInput,
+  ): Promise<IObjectStorageMigrationTransitionReceipt> {
+    return this.bridge.sendCommand('transitionSourceMigration', optionsArg);
+  }
+
+  public async transitionDestinationMigration(
+    optionsArg: IObjectStorageDestinationMigrationTransitionInput,
+  ): Promise<IObjectStorageMigrationTransitionReceipt> {
+    return this.bridge.sendCommand('transitionDestinationMigration', optionsArg);
+  }
+
+  public async cleanupSourceMigration(
+    optionsArg: IObjectStorageSourceMigrationCleanupInput,
+  ): Promise<IObjectStorageSourceMigrationCleanupReceipt> {
+    try {
+      return await this.bridge.sendCommand('cleanupSourceMigration', optionsArg);
+    } catch (error) {
+      throw normalizeResourceFenceError(error);
+    }
+  }
+
+  public async inspectBucketMigration(optionsArg: {
+    migrationId: string;
+  }): Promise<IObjectStorageMigrationInspection | null> {
+    return this.bridge.sendCommand('inspectBucketMigration', optionsArg);
+  }
+
+  public async exportBucket(optionsArg: IExportBucketInput): Promise<IBucketExport> {
+    return this.bridge.sendCommand('exportBucket', { bucketName: optionsArg.bucketName });
+  }
+
+  public async importBucket(
+    optionsArg: IImportBucketInput,
+  ): Promise<IObjectStorageBucketMutationResult> {
+    try {
+      return await this.bridge.sendCommand('importBucket', optionsArg);
+    } catch (error) {
+      throw normalizeResourceFenceError(error);
+    }
+  }
+
+  public async deleteBucket(
+    optionsArg: IDeleteBucketInput,
+  ): Promise<IObjectStorageBucketMutationResult> {
+    try {
+      return await this.bridge.sendCommand('deleteBucket', optionsArg);
+    } catch (error) {
+      throw normalizeResourceFenceError(error);
+    }
+  }
+
+  public async commitResourcePublication(
+    optionsArg: ICommitObjectStorageResourcePublicationInput,
+  ): Promise<IObjectStorageResourcePublicationReleaseReceipt> {
+    try {
+      return await this.bridge.sendCommand('commitResourcePublication', optionsArg);
+    } catch (error) {
+      throw normalizeResourceFenceError(error);
+    }
+  }
+
+  public async getResourceFencingCapability(): Promise<IObjectStorageResourceFencingCapability> {
+    return this.bridge.sendCommand('getResourceFencingCapability', {});
+  }
+
+  public async getStorageStats(): Promise<IStorageStats> {
+    return this.bridge.sendCommand('getStorageStats', {});
+  }
+
+  public async getStoragePoolDiagnostic(): Promise<IStoragePoolObservation | null> {
+    return this.bridge.sendCommand('getStoragePoolDiagnostic', {});
+  }
+
+  public async listBucketSummaries(): Promise<IBucketSummary[]> {
+    return this.bridge.sendCommand('listBucketSummaries', {});
+  }
+
+  public async listCredentials(): Promise<IStorageCredentialMetadata[]> {
+    return this.bridge.sendCommand('listCredentials', {});
+  }
+
+  /**
+   * Trusted process-local administrative override. Resource lifecycle code
+   * must use fenced ensure/delete instead; completed exact receipts fail closed
+   * if this override introduces ownership or credential-material drift.
+   */
+  public async replaceCredentials(credentials: IStorageCredential[]): Promise<void> {
+    await this.bridge.sendCommand('replaceCredentials', { credentials });
+    this.config.auth.credentials = credentials.map((credential) => ({ ...credential }));
+  }
+
+  public async getClusterHealth(): Promise<IClusterHealth> {
+    return this.bridge.sendCommand('getClusterHealth', {});
+  }
+
+  public async getHealth(): Promise<IObjectStorageHealth> {
+    if (!this.running) {
+      return {
+        ok: false,
+        running: false,
+        storageDirectory: this.config.storage.directory || paths.bucketsDir,
+        storageLocations: [],
+        auth: {
+          enabled: this.config.auth.enabled,
+          credentialCount: this.config.auth.credentials.length,
+          tenantCredentialCount: 0,
+        },
+        bucketCount: 0,
+        objectCount: 0,
+        totalBytes: 0,
+        cluster: { enabled: false },
+        resourceFencingVersion: 1,
+        resourceFencingSupported: false,
+        resourceFencingRequiresDrain: true,
+        resourcePublicationHoldVersion: 1,
+        resourcePublicationHoldSupported: false,
+        resourcePublicationHoldRequiresExternalDrain: false,
+      };
+    }
+
+    const [stats, credentials, tenants, cluster, resourceFencing] = await Promise.all([
+      this.getStorageStats(),
+      this.listCredentials(),
+      this.config.auth.enabled ? this.listBucketTenants() : Promise.resolve([]),
+      this.getClusterHealth(),
+      this.getResourceFencingCapability(),
+    ]);
+    return {
+      ok: true,
+      running: true,
+      storageDirectory: stats.storageDirectory,
+      storageLocations: stats.storageLocations || [],
+      auth: {
+        enabled: this.config.auth.enabled,
+        credentialCount: credentials.length,
+        tenantCredentialCount: tenants.length,
+      },
+      bucketCount: stats.bucketCount,
+      objectCount: stats.totalObjectCount,
+      totalBytes: stats.totalStorageBytes,
+      cluster,
+      resourceFencingVersion: resourceFencing.version,
+      resourceFencingSupported: resourceFencing.supported,
+      resourceFencingRequiresDrain: resourceFencing.requiresDrain,
+      resourcePublicationHoldVersion: resourceFencing.publicationHoldVersion,
+      resourcePublicationHoldSupported: resourceFencing.publicationHoldSupported,
+      resourcePublicationHoldRequiresExternalDrain:
+        resourceFencing.publicationHoldRequiresExternalDrain,
+      resourceFencingReason: resourceFencing.reason,
+    };
+  }
+
+  public async getMetrics(): Promise<IObjectStorageMetrics> {
+    const health = await this.getHealth();
+    const clusterEnabled = health.cluster.enabled;
+    return {
+      bucketCount: health.bucketCount,
+      objectCount: health.objectCount,
+      totalBytes: health.totalBytes,
+      authCredentialCount: health.auth.credentialCount,
+      tenantCredentialCount: health.auth.tenantCredentialCount,
+      clusterEnabled,
+      prometheusText: [
+        '# HELP objectstorage_buckets_total Runtime bucket count.',
+        '# TYPE objectstorage_buckets_total gauge',
+        `objectstorage_buckets_total ${health.bucketCount}`,
+        '# HELP objectstorage_objects_total Runtime object count.',
+        '# TYPE objectstorage_objects_total gauge',
+        `objectstorage_objects_total ${health.objectCount}`,
+        '# HELP objectstorage_storage_bytes_total Runtime storage bytes.',
+        '# TYPE objectstorage_storage_bytes_total gauge',
+        `objectstorage_storage_bytes_total ${health.totalBytes}`,
+        '# HELP objectstorage_tenant_credentials_total Scoped bucket tenant credential count.',
+        '# TYPE objectstorage_tenant_credentials_total gauge',
+        `objectstorage_tenant_credentials_total ${health.auth.tenantCredentialCount}`,
+        '# HELP objectstorage_cluster_enabled Cluster mode enabled.',
+        '# TYPE objectstorage_cluster_enabled gauge',
+        `objectstorage_cluster_enabled ${clusterEnabled ? 1 : 0}`,
+      ].join('\n'),
+    };
+  }
+
+  /**
+   * Retains the Rust bridge when shutdown is incomplete so a later call can
+   * retry ownership draining. Completed terminal errors kill the bridge before
+   * they are rethrown.
+   */
+  public stop(): Promise<void> {
+    if (this.stopPromise) {
+      return this.stopPromise;
+    }
+    this.stopRequested = true;
+    const stop = this.stopInternal();
+    this.stopPromise = stop;
+    stop.then(undefined, () => {
+      if (!this.stopCompleted && this.stopPromise === stop) {
+        this.stopPromise = undefined;
+      }
+    });
+    return stop;
+  }
+
+  private async stopInternal(): Promise<void> {
+    if (this.startPromise) {
+      // Startup keeps its own rejection; stop joins only its resource ownership.
+      await Promise.allSettled([this.startPromise]);
+    }
+    if (this.bridgeOwned) {
+      if (this.running) {
+        this.completedStopResult ??= await this.bridge.sendCommand('stop', {});
+      }
+      await this.bridge.terminate();
+      this.bridgeOwned = false;
+      this.running = false;
+    }
+    this.stopCompleted = true;
+    if (this.completedStopResult?.terminalError) {
+      throw new Error(
+        `Storage server shutdown completed with terminal errors: ${this.completedStopResult.terminalError}`,
+      );
+    }
+  }
+}