@push.rocks/smartsecret 1.5.0 → 1.6.0

package/ts/smartsecret.sealedfile.ts

@@ -6,6 +6,7 @@ import {
   normalizeSmartSecretKernelAccount,
   normalizeSmartSecretKernelService,
   type ISmartSecretKernelOperationOptions,
+  type TSmartSecretKernelMoveStatus,
 } from './smartsecret.kernel.protocol.js';
 import {
   SmartSecretSealedFileStoreError,
@@ -17,6 +18,7 @@ export const smartSecretSealedFileMaximumEntryBytes = 512 * 1_024;
 const schemaVersion = 1 as const;
 const profile = 'smartsecret-kernel-aes-256-gcm-file-v1' as const;
 const manifestName = 'manifest.json';
+const relocationReceiptName = '.smartsecret-relocation.json';
 const masterKeyBytes = 32;
 const maximumEnvelopeBytes = 768 * 1_024;
 const operationTimeoutMs = 60_000;
@@ -43,12 +45,34 @@ export interface ISmartSecretSealedFileKernelStore {
   ): Promise<boolean>;
 }
 
+export interface ISmartSecretSealedFileRelocationKernelStore
+  extends ISmartSecretSealedFileKernelStore {
+  moveEntry(
+    sourceAccountArg: string,
+    destinationAccountArg: string,
+    optionsArg?: ISmartSecretKernelOperationOptions,
+  ): Promise<TSmartSecretKernelMoveStatus>;
+}
+
 export interface ISmartSecretSealedFileStoreOptions {
   kernelStore: ISmartSecretSealedFileKernelStore;
   storeId: string;
   directoryPath: string;
 }
 
+export interface ISmartSecretSealedFileStoreRelocationOptions {
+  kernelStore: ISmartSecretSealedFileRelocationKernelStore;
+  storeId: string;
+  sourceDirectoryPath: string;
+  destinationDirectoryPath: string;
+}
+
+interface INormalizedRelocationOptions {
+  kernelStore: ISmartSecretSealedFileRelocationKernelStore;
+  source: INormalizedOptions;
+  destination: INormalizedOptions;
+}
+
 interface INormalizedOptions {
   kernelStore: ISmartSecretSealedFileKernelStore;
   service: string;
@@ -76,6 +100,33 @@ interface IEnvelopeV1 {
   tag: string;
 }
 
+interface IDirectoryIdentity {
+  device: string;
+  inode: string;
+}
+
+interface IRelocationReceiptV1 extends IDirectoryIdentity {
+  schemaVersion: 1;
+  kind: 'relocation';
+  profile: typeof profile;
+  serviceDigest: string;
+  storeId: string;
+  sourcePathDigest: string;
+  destinationPathDigest: string;
+  masterKeyFingerprint: string;
+}
+
+interface IRelocationDirectoryInspection {
+  manifest: IManifestV1;
+  receiptValue?: unknown;
+}
+
+interface IRelocationMasterKeyState {
+  key: Uint8Array;
+  sourcePresent: boolean;
+  destinationPresent: boolean;
+}
+
 type TLifecycleState = 'ready' | 'closing' | 'closed';
 type TBigIntStats = plugins.fs.BigIntStats;
 
@@ -195,6 +246,71 @@ const normalizeOptions = (optionsArg: ISmartSecretSealedFileStoreOptions): INorm
   }
 };
 
+const normalizeRelocationOptions = (
+  optionsArg: ISmartSecretSealedFileStoreRelocationOptions,
+): INormalizedRelocationOptions => {
+  try {
+    if (!optionsArg || typeof optionsArg !== 'object' || Array.isArray(optionsArg)) {
+      throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+    }
+    const expectedKeys = [
+      'kernelStore',
+      'storeId',
+      'sourceDirectoryPath',
+      'destinationDirectoryPath',
+    ];
+    const keys = Reflect.ownKeys(optionsArg);
+    if (
+      keys.length !== expectedKeys.length
+      || keys.some((keyArg) => typeof keyArg !== 'string')
+      || expectedKeys.some((keyArg) => !keys.includes(keyArg))
+    ) throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+    const values: Record<string, unknown> = Object.create(null);
+    for (const key of keys as string[]) {
+      const descriptor = Object.getOwnPropertyDescriptor(optionsArg, key);
+      if (!descriptor?.enumerable || !('value' in descriptor)) {
+        throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+      }
+      values[key] = descriptor.value;
+    }
+    const kernelStoreValue = values.kernelStore;
+    if (!kernelStoreValue || typeof kernelStoreValue !== 'object') {
+      throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+    }
+    const moveEntry = dataPropertyValue(kernelStoreValue, 'moveEntry');
+    if (typeof moveEntry !== 'function') {
+      throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+    }
+    const source = normalizeOptions({
+      kernelStore: kernelStoreValue as ISmartSecretSealedFileKernelStore,
+      storeId: values.storeId as string,
+      directoryPath: values.sourceDirectoryPath as string,
+    });
+    const destination = normalizeOptions({
+      kernelStore: kernelStoreValue as ISmartSecretSealedFileKernelStore,
+      storeId: values.storeId as string,
+      directoryPath: values.destinationDirectoryPath as string,
+    });
+    if (source.directoryPath === destination.directoryPath) {
+      throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+    }
+    const kernelStore: ISmartSecretSealedFileRelocationKernelStore = {
+      ...source.kernelStore,
+      moveEntry: (sourceAccountArg, destinationAccountArg, operationOptionsArg) => Reflect.apply(
+        moveEntry,
+        kernelStoreValue,
+        [sourceAccountArg, destinationAccountArg, operationOptionsArg],
+      ) as Promise<TSmartSecretKernelMoveStatus>,
+    };
+    source.kernelStore = kernelStore;
+    destination.kernelStore = kernelStore;
+    return { kernelStore, source, destination };
+  } catch (errorArg) {
+    if (errorArg instanceof SmartSecretSealedFileStoreError) throw errorArg;
+    throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+  }
+};
+
 const exactObject = (
   valueArg: unknown,
   keysArg: readonly string[],
@@ -349,6 +465,66 @@ const manifestFor = (optionsArg: INormalizedOptions, fingerprintArg: string): IM
   masterKeyFingerprint: fingerprintArg,
 });
 
+const directoryIdentity = (statsArg: TBigIntStats): IDirectoryIdentity => ({
+  device: statsArg.dev.toString(10),
+  inode: statsArg.ino.toString(10),
+});
+
+const directoryIdentitiesEqual = (
+  leftArg: IDirectoryIdentity,
+  rightArg: IDirectoryIdentity,
+): boolean => leftArg.device === rightArg.device && leftArg.inode === rightArg.inode;
+
+const relocationReceiptFor = (
+  optionsArg: INormalizedRelocationOptions,
+  fingerprintArg: string,
+  identityArg: IDirectoryIdentity,
+): IRelocationReceiptV1 => ({
+  schemaVersion,
+  kind: 'relocation',
+  profile,
+  serviceDigest: digest(encoder.encode(optionsArg.source.service)),
+  storeId: optionsArg.source.storeId,
+  sourcePathDigest: digest(encoder.encode(optionsArg.source.directoryPath)),
+  destinationPathDigest: digest(encoder.encode(optionsArg.destination.directoryPath)),
+  masterKeyFingerprint: fingerprintArg,
+  ...identityArg,
+});
+
+const parseRelocationReceipt = (
+  valueArg: unknown,
+  optionsArg: INormalizedRelocationOptions,
+  fingerprintArg: string,
+  identityArg: IDirectoryIdentity,
+): IRelocationReceiptV1 => {
+  const value = exactObject(valueArg, [
+    'schemaVersion',
+    'kind',
+    'profile',
+    'serviceDigest',
+    'storeId',
+    'sourcePathDigest',
+    'destinationPathDigest',
+    'masterKeyFingerprint',
+    'device',
+    'inode',
+  ], 'FILESYSTEM_FAILED');
+  const expected = relocationReceiptFor(optionsArg, fingerprintArg, identityArg);
+  if (
+    value.schemaVersion !== expected.schemaVersion
+    || value.kind !== expected.kind
+    || value.profile !== expected.profile
+    || value.serviceDigest !== expected.serviceDigest
+    || value.storeId !== expected.storeId
+    || value.sourcePathDigest !== expected.sourcePathDigest
+    || value.destinationPathDigest !== expected.destinationPathDigest
+    || value.masterKeyFingerprint !== expected.masterKeyFingerprint
+    || value.device !== expected.device
+    || value.inode !== expected.inode
+  ) throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  return value as unknown as IRelocationReceiptV1;
+};
+
 const parseManifest = (valueArg: unknown, optionsArg: INormalizedOptions): IManifestV1 => {
   const value = exactObject(valueArg, [
     'schemaVersion',
@@ -455,7 +631,10 @@ const validateDirectory = (
   ) throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
 };
 
-const ensureDirectory = async (directoryPathArg: string): Promise<plugins.fs.promises.FileHandle> => {
+const openDirectory = async (
+  directoryPathArg: string,
+  createArg: boolean,
+): Promise<plugins.fs.promises.FileHandle> => {
   let currentHandle: plugins.fs.promises.FileHandle | undefined;
   try {
     const effectiveUid = process.geteuid?.();
@@ -475,10 +654,12 @@ const ensureDirectory = async (directoryPathArg: string): Promise<plugins.fs.pro
     validateDirectory(await currentHandle.stat({ bigint: true }), BigInt(effectiveUid!), false);
     for (let index = 0; index < components.length; index++) {
       const componentPath = directoryHandlePath(currentHandle, components[index]);
-      try {
-        await plugins.fs.promises.mkdir(componentPath, { mode: 0o700 });
-      } catch (errorArg) {
-        if ((errorArg as NodeJS.ErrnoException).code !== 'EEXIST') throw errorArg;
+      if (createArg) {
+        try {
+          await plugins.fs.promises.mkdir(componentPath, { mode: 0o700 });
+        } catch (errorArg) {
+          if ((errorArg as NodeJS.ErrnoException).code !== 'EEXIST') throw errorArg;
+        }
       }
       let nextHandle: plugins.fs.promises.FileHandle | undefined;
       try {
@@ -514,6 +695,47 @@ const ensureDirectory = async (directoryPathArg: string): Promise<plugins.fs.pro
   }
 };
 
+const ensureDirectory = (directoryPathArg: string): Promise<plugins.fs.promises.FileHandle> =>
+  openDirectory(directoryPathArg, true);
+
+const openExistingDirectory = (
+  directoryPathArg: string,
+): Promise<plugins.fs.promises.FileHandle> => openDirectory(directoryPathArg, false);
+
+const openChildDirectoryIfPresent = async (
+  parentHandleArg: plugins.fs.promises.FileHandle,
+  nameArg: string,
+): Promise<plugins.fs.promises.FileHandle | undefined> => {
+  let handle: plugins.fs.promises.FileHandle | undefined;
+  try {
+    try {
+      handle = await plugins.fs.promises.open(
+        directoryHandlePath(parentHandleArg, nameArg),
+        plugins.fs.constants.O_RDONLY
+          | plugins.fs.constants.O_DIRECTORY
+          | plugins.fs.constants.O_NOFOLLOW,
+      );
+    } catch (errorArg) {
+      if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+      throw errorArg;
+    }
+    const effectiveUid = process.geteuid?.();
+    if (!Number.isSafeInteger(effectiveUid) || effectiveUid! < 0) {
+      throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+    }
+    validateDirectory(await handle.stat({ bigint: true }), BigInt(effectiveUid!), true);
+    const result = handle;
+    handle = undefined;
+    return result;
+  } catch (errorArg) {
+    let operationError: unknown = errorArg instanceof SmartSecretSealedFileStoreError
+      ? errorArg
+      : createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+    if (handle) operationError = await closeFileHandleWithError(handle, operationError);
+    throw operationError;
+  }
+};
+
 const readStrictJsonFile = async (
   directoryHandleArg: plugins.fs.promises.FileHandle,
   fileNameArg: string,
@@ -655,11 +877,13 @@ const removeAndSync = async (
 
 const listOwnedFiles = async (
   directoryHandleArg: plugins.fs.promises.FileHandle,
+  allowRelocationReceiptArg = false,
 ): Promise<string[]> => {
   try {
     const names = await plugins.fs.promises.readdir(directoryHandlePath(directoryHandleArg));
     if (names.some((nameArg) => (
       nameArg !== manifestName
+      && !(allowRelocationReceiptArg && nameArg === relocationReceiptName)
       && !entryFilePattern.test(nameArg)
       && !temporaryFilePattern.test(nameArg)
     ))) throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
@@ -721,6 +945,185 @@ const readMasterKey = async (optionsArg: INormalizedOptions): Promise<Uint8Array
   }
 };
 
+const mapRelocationKernelError = (errorArg: unknown): SmartSecretSealedFileStoreError => {
+  if (!(errorArg instanceof SmartSecretKernelStoreError)) {
+    return createSmartSecretSealedFileStoreError('KERNEL_UNAVAILABLE');
+  }
+  if (errorArg.code === 'MUTATION_OUTCOME_UNKNOWN') {
+    return createSmartSecretSealedFileStoreError('MUTATION_OUTCOME_UNKNOWN');
+  }
+  if (errorArg.code === 'TARGET_CONFLICT' || errorArg.code === 'SOURCE_CHANGED') {
+    return createSmartSecretSealedFileStoreError('MASTER_KEY_CONFLICT');
+  }
+  if (errorArg.code === 'INVALID_ARGUMENT') {
+    return createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+  }
+  return createSmartSecretSealedFileStoreError('KERNEL_UNAVAILABLE');
+};
+
+const acquireRelocationLeases = async (
+  optionsArg: INormalizedRelocationOptions,
+): Promise<plugins.smartipc.NamedMutexLease[]> => {
+  const deadline = performance.now() + operationTimeoutMs;
+  const ordered = [optionsArg.source, optionsArg.destination]
+    .sort((leftArg, rightArg) => leftArg.mutexNamespace < rightArg.mutexNamespace
+      ? -1
+      : leftArg.mutexNamespace > rightArg.mutexNamespace
+        ? 1
+        : 0);
+  const leases: plugins.smartipc.NamedMutexLease[] = [];
+  try {
+    for (const options of ordered) leases.push(await acquireLease(options, deadline));
+    return leases;
+  } catch (errorArg) {
+    let operationError: unknown = errorArg;
+    for (const lease of leases.reverse()) {
+      try {
+        await lease.release();
+      } catch {
+        operationError = preferCleanupError(
+          operationError,
+          createSmartSecretSealedFileStoreError('MUTEX_FAILED'),
+        );
+      }
+    }
+    throw operationError;
+  }
+};
+
+const inspectRelocationDirectory = async (
+  directoryHandleArg: plugins.fs.promises.FileHandle,
+  optionsArg: INormalizedOptions,
+): Promise<IRelocationDirectoryInspection> => {
+  const names = await listOwnedFiles(directoryHandleArg, true);
+  if (!names.includes(manifestName)) {
+    throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  }
+  const manifestValue = await readStrictJsonFile(
+    directoryHandleArg,
+    manifestName,
+    4 * 1_024,
+  );
+  if (manifestValue === undefined) {
+    throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  }
+  const receiptValue = names.includes(relocationReceiptName)
+    ? await readStrictJsonFile(directoryHandleArg, relocationReceiptName, 4 * 1_024)
+    : undefined;
+  if (names.includes(relocationReceiptName) && receiptValue === undefined) {
+    throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  }
+  return {
+    manifest: parseManifest(manifestValue, optionsArg),
+    ...(receiptValue === undefined ? {} : { receiptValue }),
+  };
+};
+
+const readRelocationMasterKey = async (
+  sourceArg: INormalizedOptions,
+  destinationArg: INormalizedOptions,
+  expectedFingerprintArg: string,
+): Promise<IRelocationMasterKeyState> => {
+  let sourceKey: Uint8Array | null = null;
+  let destinationKey: Uint8Array | null = null;
+  try {
+    sourceKey = await readMasterKey(sourceArg);
+    destinationKey = await readMasterKey(destinationArg);
+    if (!sourceKey && !destinationKey) {
+      throw createSmartSecretSealedFileStoreError('MASTER_KEY_UNAVAILABLE');
+    }
+    if (
+      (sourceKey && fingerprint(sourceKey) !== expectedFingerprintArg)
+      || (destinationKey && fingerprint(destinationKey) !== expectedFingerprintArg)
+      || (
+        sourceKey
+        && destinationKey
+        && !plugins.crypto.timingSafeEqual(sourceKey, destinationKey)
+      )
+    ) throw createSmartSecretSealedFileStoreError('MASTER_KEY_CONFLICT');
+    return {
+      key: new Uint8Array(sourceKey ?? destinationKey!),
+      sourcePresent: sourceKey !== null,
+      destinationPresent: destinationKey !== null,
+    };
+  } finally {
+    sourceKey?.fill(0);
+    destinationKey?.fill(0);
+  }
+};
+
+const syncRelocationParents = async (
+  sourceParentHandleArg: plugins.fs.promises.FileHandle,
+  sourceParentPathArg: string,
+  destinationParentHandleArg: plugins.fs.promises.FileHandle,
+  destinationParentPathArg: string,
+): Promise<void> => {
+  try {
+    await sourceParentHandleArg.sync();
+    if (sourceParentPathArg !== destinationParentPathArg) {
+      await destinationParentHandleArg.sync();
+    }
+  } catch {
+    throw createSmartSecretSealedFileStoreError('MUTATION_OUTCOME_UNKNOWN');
+  }
+};
+
+const assertOpenChildIdentity = async (
+  parentHandleArg: plugins.fs.promises.FileHandle,
+  nameArg: string,
+  childHandleArg: plugins.fs.promises.FileHandle,
+): Promise<IDirectoryIdentity> => {
+  try {
+    const [pathStats, handleStats] = await Promise.all([
+      plugins.fs.promises.lstat(directoryHandlePath(parentHandleArg, nameArg), { bigint: true }),
+      childHandleArg.stat({ bigint: true }),
+    ]);
+    if (
+      pathStats.isSymbolicLink()
+      || !pathStats.isDirectory()
+      || pathStats.dev !== handleStats.dev
+      || pathStats.ino !== handleStats.ino
+    ) throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+    return directoryIdentity(handleStats);
+  } catch (errorArg) {
+    if (errorArg instanceof SmartSecretSealedFileStoreError) throw errorArg;
+    throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  }
+};
+
+const readChildIdentity = async (
+  parentHandleArg: plugins.fs.promises.FileHandle,
+  nameArg: string,
+): Promise<IDirectoryIdentity | undefined> => {
+  try {
+    const stats = await plugins.fs.promises.lstat(
+      directoryHandlePath(parentHandleArg, nameArg),
+      { bigint: true },
+    );
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+      throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+    }
+    return directoryIdentity(stats);
+  } catch (errorArg) {
+    if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    if (errorArg instanceof SmartSecretSealedFileStoreError) throw errorArg;
+    throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  }
+};
+
+const assertChildAbsent = async (
+  parentHandleArg: plugins.fs.promises.FileHandle,
+  nameArg: string,
+): Promise<void> => {
+  try {
+    await plugins.fs.promises.lstat(directoryHandlePath(parentHandleArg, nameArg));
+  } catch (errorArg) {
+    if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  }
+  throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+};
+
 const createMasterKey = async (optionsArg: INormalizedOptions): Promise<Uint8Array> => {
   const generated = plugins.smartcrypto.generateAes256GcmKey();
   let written = false;
@@ -754,14 +1157,26 @@ const createMasterKey = async (optionsArg: INormalizedOptions): Promise<Uint8Arr
   }
 };
 
-const bootstrapUnderLease = async (optionsArg: INormalizedOptions): Promise<Uint8Array> => {
-  const directoryHandle = await ensureDirectory(optionsArg.directoryPath);
+const bootstrapUnderLease = async (
+  optionsArg: INormalizedOptions,
+  existingIdentityArg?: IDirectoryIdentity,
+  allowRelocationReceiptArg = false,
+): Promise<Uint8Array> => {
+  const directoryHandle = existingIdentityArg
+    ? await openExistingDirectory(optionsArg.directoryPath)
+    : await ensureDirectory(optionsArg.directoryPath);
   let key: Uint8Array | null = null;
   let result: Uint8Array | undefined;
   let createdMasterKey = false;
   let operationError: unknown;
   try {
-    const names = await listOwnedFiles(directoryHandle);
+    if (existingIdentityArg) {
+      const currentIdentity = directoryIdentity(await directoryHandle.stat({ bigint: true }));
+      if (!directoryIdentitiesEqual(currentIdentity, existingIdentityArg)) {
+        throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+      }
+    }
+    const names = await listOwnedFiles(directoryHandle, allowRelocationReceiptArg);
     const manifestValue = await readStrictJsonFile(
       directoryHandle,
       manifestName,
@@ -873,6 +1288,230 @@ export class SmartSecretSealedFileStore {
     return store;
   }
 
+  /** Moves an initialized store and rebinds its exact kernel master key. */
+  public static async relocate(
+    optionsArg: ISmartSecretSealedFileStoreRelocationOptions,
+  ): Promise<SmartSecretSealedFileStore> {
+    const options = normalizeRelocationOptions(optionsArg);
+    if (process.platform !== 'linux' || typeof process.geteuid !== 'function') {
+      throw createSmartSecretSealedFileStoreError('KERNEL_UNAVAILABLE');
+    }
+    const leases = await acquireRelocationLeases(options);
+    let sourceParentHandle: plugins.fs.promises.FileHandle | undefined;
+    let destinationParentHandle: plugins.fs.promises.FileHandle | undefined;
+    let sourceDirectoryHandle: plugins.fs.promises.FileHandle | undefined;
+    let destinationDirectoryHandle: plugins.fs.promises.FileHandle | undefined;
+    let expectedKey: Uint8Array | undefined;
+    let expectedIdentity: IDirectoryIdentity | undefined;
+    let resultKey: Uint8Array | undefined;
+    let mutationPossible = false;
+    let operationError: unknown;
+    const sourceParentPath = plugins.path.dirname(options.source.directoryPath);
+    const destinationParentPath = plugins.path.dirname(options.destination.directoryPath);
+    const sourceName = plugins.path.basename(options.source.directoryPath);
+    const destinationName = plugins.path.basename(options.destination.directoryPath);
+    try {
+      sourceParentHandle = await openExistingDirectory(sourceParentPath);
+      destinationParentHandle = await openExistingDirectory(destinationParentPath);
+      const [sourceParentStats, destinationParentStats] = await Promise.all([
+        sourceParentHandle.stat({ bigint: true }),
+        destinationParentHandle.stat({ bigint: true }),
+      ]);
+      if (sourceParentStats.dev !== destinationParentStats.dev) {
+        throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+      }
+      sourceDirectoryHandle = await openChildDirectoryIfPresent(sourceParentHandle, sourceName);
+      destinationDirectoryHandle = await openChildDirectoryIfPresent(
+        destinationParentHandle,
+        destinationName,
+      );
+      if (Boolean(sourceDirectoryHandle) === Boolean(destinationDirectoryHandle)) {
+        throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+      }
+      const storeAtSource = sourceDirectoryHandle !== undefined;
+      const currentOptions = storeAtSource ? options.source : options.destination;
+      const currentHandle = sourceDirectoryHandle ?? destinationDirectoryHandle!;
+      expectedIdentity = await assertOpenChildIdentity(
+        storeAtSource ? sourceParentHandle : destinationParentHandle,
+        storeAtSource ? sourceName : destinationName,
+        currentHandle,
+      );
+      if (expectedIdentity.device !== sourceParentStats.dev.toString(10)) {
+        throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+      }
+      const inspection = await inspectRelocationDirectory(currentHandle, currentOptions);
+      const keyState = await readRelocationMasterKey(
+        options.source,
+        options.destination,
+        inspection.manifest.masterKeyFingerprint,
+      );
+      expectedKey = keyState.key;
+      let receipt = inspection.receiptValue === undefined
+        ? undefined
+        : parseRelocationReceipt(
+            inspection.receiptValue,
+            options,
+            inspection.manifest.masterKeyFingerprint,
+            expectedIdentity,
+          );
+      if (storeAtSource) {
+        if (!keyState.sourcePresent) {
+          throw createSmartSecretSealedFileStoreError('MASTER_KEY_UNAVAILABLE');
+        }
+        if (!receipt) {
+          await atomicWriteJson(
+            currentHandle,
+            relocationReceiptName,
+            relocationReceiptFor(
+              options,
+              inspection.manifest.masterKeyFingerprint,
+              expectedIdentity,
+            ),
+          );
+          mutationPossible = true;
+          const receiptValue = await readStrictJsonFile(
+            currentHandle,
+            relocationReceiptName,
+            4 * 1_024,
+          );
+          if (receiptValue === undefined) {
+            throw createSmartSecretSealedFileStoreError('MUTATION_OUTCOME_UNKNOWN');
+          }
+          receipt = parseRelocationReceipt(
+            receiptValue,
+            options,
+            inspection.manifest.masterKeyFingerprint,
+            expectedIdentity,
+          );
+        }
+        await assertOpenChildIdentity(sourceParentHandle, sourceName, sourceDirectoryHandle!);
+        await assertChildAbsent(destinationParentHandle, destinationName);
+        try {
+          await plugins.fs.promises.rename(
+            directoryHandlePath(sourceParentHandle, sourceName),
+            directoryHandlePath(destinationParentHandle, destinationName),
+          );
+          mutationPossible = true;
+        } catch {
+          const [sourceAfter, destinationAfter] = await Promise.all([
+            readChildIdentity(sourceParentHandle, sourceName),
+            readChildIdentity(destinationParentHandle, destinationName),
+          ]);
+          if (
+            sourceAfter
+            && directoryIdentitiesEqual(sourceAfter, expectedIdentity)
+            && destinationAfter === undefined
+          ) {
+            try {
+              if (!await removeAndSync(currentHandle, relocationReceiptName)) {
+                throw createSmartSecretSealedFileStoreError('MUTATION_OUTCOME_UNKNOWN');
+              }
+            } catch (errorArg) {
+              if (mutationOutcomeUnknown(errorArg)) throw errorArg;
+              throw createSmartSecretSealedFileStoreError('MUTATION_OUTCOME_UNKNOWN');
+            }
+            throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+          }
+          if (
+            sourceAfter === undefined
+            && destinationAfter
+            && directoryIdentitiesEqual(destinationAfter, expectedIdentity)
+          ) {
+            mutationPossible = true;
+          } else {
+            throw createSmartSecretSealedFileStoreError('MUTATION_OUTCOME_UNKNOWN');
+          }
+        }
+      } else {
+        if (!receipt && (keyState.sourcePresent || !keyState.destinationPresent)) {
+          throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+        }
+      }
+      await syncRelocationParents(
+        sourceParentHandle,
+        sourceParentPath,
+        destinationParentHandle,
+        destinationParentPath,
+      );
+      mutationPossible = true;
+      let moveStatus: TSmartSecretKernelMoveStatus;
+      try {
+        moveStatus = await options.kernelStore.moveEntry(
+          options.source.masterKeyAccount,
+          options.destination.masterKeyAccount,
+        );
+      } catch (errorArg) {
+        throw mapRelocationKernelError(errorArg);
+      }
+      if (moveStatus === 'sourceAbsent') {
+        throw createSmartSecretSealedFileStoreError('MASTER_KEY_UNAVAILABLE');
+      }
+      const destinationKey = await readMasterKey(options.destination);
+      try {
+        if (!destinationKey || !plugins.crypto.timingSafeEqual(destinationKey, expectedKey)) {
+          throw createSmartSecretSealedFileStoreError('MASTER_KEY_CONFLICT');
+        }
+      } finally {
+        destinationKey?.fill(0);
+      }
+      resultKey = await bootstrapUnderLease(options.destination, expectedIdentity, Boolean(receipt));
+      if (!plugins.crypto.timingSafeEqual(resultKey, expectedKey)) {
+        throw createSmartSecretSealedFileStoreError('MASTER_KEY_CONFLICT');
+      }
+      if (receipt) {
+        try {
+          if (!await removeAndSync(currentHandle, relocationReceiptName)) {
+            throw createSmartSecretSealedFileStoreError('MUTATION_OUTCOME_UNKNOWN');
+          }
+        } catch (errorArg) {
+          if (mutationOutcomeUnknown(errorArg)) throw errorArg;
+          throw createSmartSecretSealedFileStoreError('MUTATION_OUTCOME_UNKNOWN');
+        }
+      }
+    } catch (errorArg) {
+      operationError = errorArg;
+    }
+
+    for (const handle of [
+      sourceDirectoryHandle,
+      destinationDirectoryHandle,
+      sourceParentHandle,
+      destinationParentHandle,
+    ]) {
+      if (!handle) continue;
+      try {
+        await closeFileHandle(handle);
+      } catch (errorArg) {
+        operationError = preferCleanupError(
+          operationError,
+          mutationPossible
+            ? createSmartSecretSealedFileStoreError('MUTATION_OUTCOME_UNKNOWN')
+            : errorArg,
+        );
+      }
+    }
+    for (const lease of leases.reverse()) {
+      try {
+        await lease.release();
+      } catch {
+        operationError = preferCleanupError(
+          operationError,
+          createSmartSecretSealedFileStoreError(
+            mutationPossible ? 'MUTATION_OUTCOME_UNKNOWN' : 'MUTEX_FAILED',
+          ),
+        );
+      }
+    }
+    expectedKey?.fill(0);
+    if (operationError) {
+      resultKey?.fill(0);
+      throw operationError;
+    }
+    const store = new SmartSecretSealedFileStore(options.destination, resultKey!);
+    resultKey = undefined;
+    return store;
+  }
+
   /** Explicitly discards this store's ciphertext and kernel master key. */
   public static async reset(
     optionsArg: ISmartSecretSealedFileStoreOptions,
@@ -948,7 +1587,7 @@ export class SmartSecretSealedFileStore {
       deadlineArg,
       markAcquiredArg,
       async () => {
-        const directoryHandle = await ensureDirectory(this.directoryPath);
+        const directoryHandle = await openExistingDirectory(this.directoryPath);
         const id = entryId(this.options, account);
         let value: unknown | undefined;
         let operationError: unknown;
@@ -1017,7 +1656,7 @@ export class SmartSecretSealedFileStore {
         deadlineArg,
         markAcquiredArg,
         async () => {
-        const directoryHandle = await ensureDirectory(this.directoryPath);
+        const directoryHandle = await openExistingDirectory(this.directoryPath);
         let encrypted: plugins.smartcrypto.IAesGcmCiphertext | undefined;
         const id = entryId(this.options, account);
         const keyFingerprint = fingerprint(this.masterKey);
@@ -1078,7 +1717,7 @@ export class SmartSecretSealedFileStore {
       deadlineArg,
       markAcquiredArg,
       async () => {
-      const directoryHandle = await ensureDirectory(this.directoryPath);
+      const directoryHandle = await openExistingDirectory(this.directoryPath);
       let result: boolean | undefined;
       let operationError: unknown;
       try {