@push.rocks/smartsecret 1.4.0 → 1.6.0

package/ts/smartsecret.sealedfile.ts

@@ -0,0 +1,1834 @@
+import * as plugins from './smartsecret.plugins.js';
+import {
+  SmartSecretKernelStoreError,
+} from './smartsecret.kernel.error.js';
+import {
+  normalizeSmartSecretKernelAccount,
+  normalizeSmartSecretKernelService,
+  type ISmartSecretKernelOperationOptions,
+  type TSmartSecretKernelMoveStatus,
+} from './smartsecret.kernel.protocol.js';
+import {
+  SmartSecretSealedFileStoreError,
+  createSmartSecretSealedFileStoreError,
+} from './smartsecret.sealedfile.error.js';
+
+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;
+const canonicalDigestPattern = /^[A-Za-z0-9_-]{43}$/;
+const entryFilePattern = /^[A-Za-z0-9_-]{43}\.sealed\.json$/;
+const temporaryFilePattern = /^\.smartsecret-[A-Za-z0-9_-]{22}\.tmp$/;
+const maximumPendingOperations = 64;
+const encoder = new TextEncoder();
+
+export interface ISmartSecretSealedFileKernelStore {
+  readonly service: string;
+  getEntry(
+    accountArg: string,
+    optionsArg?: ISmartSecretKernelOperationOptions,
+  ): Promise<Uint8Array | null>;
+  setEntry(
+    accountArg: string,
+    valueArg: Uint8Array,
+    optionsArg?: ISmartSecretKernelOperationOptions,
+  ): Promise<void>;
+  deleteEntry(
+    accountArg: string,
+    optionsArg?: ISmartSecretKernelOperationOptions,
+  ): 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;
+  storeId: string;
+  directoryPath: string;
+  masterKeyAccount: string;
+  mutexNamespace: string;
+}
+
+interface IManifestV1 {
+  schemaVersion: 1;
+  profile: typeof profile;
+  serviceDigest: string;
+  storeId: string;
+  masterKeyFingerprint: string;
+}
+
+interface IEnvelopeV1 {
+  schemaVersion: 1;
+  profile: typeof profile;
+  entryId: string;
+  masterKeyFingerprint: string;
+  nonce: string;
+  ciphertext: string;
+  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;
+
+const sha256 = (...valuesArg: Uint8Array[]): Uint8Array => {
+  const hash = plugins.crypto.createHash('sha256');
+  for (const value of valuesArg) hash.update(value);
+  return new Uint8Array(hash.digest());
+};
+
+const digest = (...valuesArg: Uint8Array[]): string =>
+  Buffer.from(sha256(...valuesArg)).toString('base64url');
+
+const fingerprint = (keyArg: Uint8Array): string => digest(
+  encoder.encode('@push.rocks/smartsecret/sealed-file/master-key/v1\0'),
+  keyArg,
+);
+
+const normalizeStoreId = (valueArg: unknown): string => {
+  if (
+    typeof valueArg !== 'string'
+    || !/^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg)
+  ) throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+  return valueArg;
+};
+
+const normalizeDirectoryPath = (valueArg: unknown): string => {
+  if (
+    typeof valueArg !== 'string'
+    || !plugins.path.isAbsolute(valueArg)
+    || plugins.path.resolve(valueArg) !== valueArg
+    || valueArg === plugins.path.parse(valueArg).root
+  ) throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+  return valueArg;
+};
+
+const dataPropertyValue = (objectArg: object, keyArg: string): unknown => {
+  let current: object | null = objectArg;
+  while (current) {
+    const descriptor = Object.getOwnPropertyDescriptor(current, keyArg);
+    if (descriptor) {
+      if (!('value' in descriptor)) {
+        throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+      }
+      return descriptor.value;
+    }
+    current = Object.getPrototypeOf(current) as object | null;
+  }
+  throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+};
+
+const normalizeOptions = (optionsArg: ISmartSecretSealedFileStoreOptions): INormalizedOptions => {
+  try {
+    if (!optionsArg || typeof optionsArg !== 'object' || Array.isArray(optionsArg)) {
+      throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+    }
+    const keys = Reflect.ownKeys(optionsArg);
+    if (
+      keys.length !== 3
+      || keys.some((keyArg) => typeof keyArg !== 'string')
+      || !['kernelStore', 'storeId', 'directoryPath'].every((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 service = normalizeSmartSecretKernelService(
+      dataPropertyValue(kernelStoreValue, 'service'),
+    );
+    const getEntry = dataPropertyValue(kernelStoreValue, 'getEntry');
+    const setEntry = dataPropertyValue(kernelStoreValue, 'setEntry');
+    const deleteEntry = dataPropertyValue(kernelStoreValue, 'deleteEntry');
+    if (
+      typeof getEntry !== 'function'
+      || typeof setEntry !== 'function'
+      || typeof deleteEntry !== 'function'
+    ) throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+    const kernelStore: ISmartSecretSealedFileKernelStore = {
+      service,
+      getEntry: (accountArg, operationOptionsArg) => Reflect.apply(
+        getEntry,
+        kernelStoreValue,
+        [accountArg, operationOptionsArg],
+      ) as Promise<Uint8Array | null>,
+      setEntry: (accountArg, valueArg, operationOptionsArg) => Reflect.apply(
+        setEntry,
+        kernelStoreValue,
+        [accountArg, valueArg, operationOptionsArg],
+      ) as Promise<void>,
+      deleteEntry: (accountArg, operationOptionsArg) => Reflect.apply(
+        deleteEntry,
+        kernelStoreValue,
+        [accountArg, operationOptionsArg],
+      ) as Promise<boolean>,
+    };
+    const storeId = normalizeStoreId(values.storeId);
+    const directoryPath = normalizeDirectoryPath(values.directoryPath);
+    const identity = encoder.encode(`${service}\0${storeId}\0${directoryPath}`);
+    return {
+      kernelStore,
+      service,
+      storeId,
+      directoryPath,
+      masterKeyAccount: `sealed-file-master:v1:${digest(identity)}`,
+      mutexNamespace: `smartsecret-sealed-file:v1:${digest(encoder.encode(directoryPath))}`,
+    };
+  } catch {
+    throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+  }
+};
+
+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[],
+  errorCodeArg: 'ENVELOPE_INVALID' | 'FILESYSTEM_FAILED',
+): Record<string, unknown> => {
+  try {
+    if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+      throw createSmartSecretSealedFileStoreError(errorCodeArg);
+    }
+    const prototype = Object.getPrototypeOf(valueArg);
+    const keys = Reflect.ownKeys(valueArg);
+    if (
+      (prototype !== Object.prototype && prototype !== null)
+      || keys.length !== keysArg.length
+      || keys.some((keyArg) => typeof keyArg !== 'string')
+      || keysArg.some((keyArg) => !keys.includes(keyArg))
+    ) throw createSmartSecretSealedFileStoreError(errorCodeArg);
+    const result: Record<string, unknown> = Object.create(null);
+    for (const key of keys as string[]) {
+      const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+      if (!descriptor?.enumerable || !('value' in descriptor)) {
+        throw createSmartSecretSealedFileStoreError(errorCodeArg);
+      }
+      result[key] = descriptor.value;
+    }
+    return result;
+  } catch (errorArg) {
+    if (errorArg instanceof SmartSecretSealedFileStoreError) throw errorArg;
+    throw createSmartSecretSealedFileStoreError(errorCodeArg);
+  }
+};
+
+const decodeBase64Url = (
+  valueArg: unknown,
+  maximumBytesArg: number,
+  exactBytesArg?: number,
+): Uint8Array => {
+  if (
+    typeof valueArg !== 'string'
+    || !/^[A-Za-z0-9_-]*$/.test(valueArg)
+    || valueArg.length % 4 === 1
+    || valueArg.length > Math.ceil(maximumBytesArg * 4 / 3)
+  ) throw createSmartSecretSealedFileStoreError('ENVELOPE_INVALID');
+  const decoded = Buffer.from(valueArg, 'base64url');
+  if (
+    decoded.byteLength > maximumBytesArg
+    || (exactBytesArg !== undefined && decoded.byteLength !== exactBytesArg)
+    || decoded.toString('base64url') !== valueArg
+  ) {
+    decoded.fill(0);
+    throw createSmartSecretSealedFileStoreError('ENVELOPE_INVALID');
+  }
+  const result = new Uint8Array(decoded);
+  decoded.fill(0);
+  return result;
+};
+
+const parseEnvelope = (valueArg: unknown): {
+  envelope: IEnvelopeV1;
+  encryptedData: plugins.smartcrypto.IAesGcmCiphertext;
+} => {
+  const value = exactObject(valueArg, [
+    'schemaVersion',
+    'profile',
+    'entryId',
+    'masterKeyFingerprint',
+    'nonce',
+    'ciphertext',
+    'tag',
+  ], 'ENVELOPE_INVALID');
+  if (
+    value.schemaVersion !== schemaVersion
+    || value.profile !== profile
+    || typeof value.entryId !== 'string'
+    || !canonicalDigestPattern.test(value.entryId)
+    || typeof value.masterKeyFingerprint !== 'string'
+    || !canonicalDigestPattern.test(value.masterKeyFingerprint)
+  ) throw createSmartSecretSealedFileStoreError('ENVELOPE_INVALID');
+  let nonce: Uint8Array | undefined;
+  let ciphertext: Uint8Array | undefined;
+  let tag: Uint8Array | undefined;
+  try {
+    nonce = decodeBase64Url(value.nonce, 12, 12);
+    ciphertext = decodeBase64Url(value.ciphertext, smartSecretSealedFileMaximumEntryBytes);
+    tag = decodeBase64Url(value.tag, 16, 16);
+    return {
+      envelope: {
+        schemaVersion,
+        profile,
+        entryId: value.entryId,
+        masterKeyFingerprint: value.masterKeyFingerprint,
+        nonce: value.nonce as string,
+        ciphertext: value.ciphertext as string,
+        tag: value.tag as string,
+      },
+      encryptedData: { nonce, ciphertext, tag },
+    };
+  } catch (errorArg) {
+    nonce?.fill(0);
+    ciphertext?.fill(0);
+    tag?.fill(0);
+    throw errorArg;
+  }
+};
+
+const encodeBase64Url = (valueArg: Uint8Array): string => {
+  const copy = Buffer.from(valueArg);
+  try {
+    return copy.toString('base64url');
+  } finally {
+    copy.fill(0);
+  }
+};
+
+const encodeEncryptedData = (
+  valueArg: plugins.smartcrypto.IAesGcmCiphertext,
+): Pick<IEnvelopeV1, 'nonce' | 'ciphertext' | 'tag'> => ({
+  nonce: encodeBase64Url(valueArg.nonce),
+  ciphertext: encodeBase64Url(valueArg.ciphertext),
+  tag: encodeBase64Url(valueArg.tag),
+});
+
+const entryId = (optionsArg: INormalizedOptions, accountArg: string): string => digest(
+  encoder.encode('@push.rocks/smartsecret/sealed-file/entry/v1\0'),
+  encoder.encode(optionsArg.service),
+  new Uint8Array([0]),
+  encoder.encode(optionsArg.storeId),
+  new Uint8Array([0]),
+  encoder.encode(accountArg),
+);
+
+const entryAad = (
+  optionsArg: INormalizedOptions,
+  accountArg: string,
+  entryIdArg: string,
+  fingerprintArg: string,
+): Uint8Array => encoder.encode(JSON.stringify({
+  schemaVersion,
+  profile,
+  service: optionsArg.service,
+  storeId: optionsArg.storeId,
+  account: accountArg,
+  entryId: entryIdArg,
+  masterKeyFingerprint: fingerprintArg,
+}));
+
+const manifestFor = (optionsArg: INormalizedOptions, fingerprintArg: string): IManifestV1 => ({
+  schemaVersion,
+  profile,
+  serviceDigest: digest(encoder.encode(optionsArg.service)),
+  storeId: optionsArg.storeId,
+  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',
+    'profile',
+    'serviceDigest',
+    'storeId',
+    'masterKeyFingerprint',
+  ], 'FILESYSTEM_FAILED');
+  if (
+    value.schemaVersion !== schemaVersion
+    || value.profile !== profile
+    || value.serviceDigest !== digest(encoder.encode(optionsArg.service))
+    || value.storeId !== optionsArg.storeId
+    || typeof value.masterKeyFingerprint !== 'string'
+    || !canonicalDigestPattern.test(value.masterKeyFingerprint)
+  ) throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  return value as unknown as IManifestV1;
+};
+
+const mapKernelError = (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 === 'INVALID_ARGUMENT') {
+    return createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+  }
+  return createSmartSecretSealedFileStoreError('KERNEL_UNAVAILABLE');
+};
+
+const mapMutexError = (errorArg: unknown): SmartSecretSealedFileStoreError => {
+  if (errorArg instanceof plugins.smartipc.NamedMutexError) {
+    if (errorArg.code === 'ABORTED' || errorArg.code === 'TIMEOUT') {
+      return createSmartSecretSealedFileStoreError('MUTEX_FAILED');
+    }
+  }
+  return createSmartSecretSealedFileStoreError('MUTEX_FAILED');
+};
+
+const directoryHandlePath = (
+  directoryHandleArg: plugins.fs.promises.FileHandle,
+  nameArg?: string,
+): string => nameArg
+  ? plugins.path.join(`/proc/self/fd/${directoryHandleArg.fd}`, nameArg)
+  : `/proc/self/fd/${directoryHandleArg.fd}`;
+
+const mutationOutcomeUnknown = (errorArg: unknown): boolean =>
+  errorArg instanceof SmartSecretSealedFileStoreError
+  && errorArg.code === 'MUTATION_OUTCOME_UNKNOWN';
+
+const preferCleanupError = (operationErrorArg: unknown, cleanupErrorArg: unknown): unknown =>
+  mutationOutcomeUnknown(operationErrorArg) ? operationErrorArg : cleanupErrorArg;
+
+const closeFileHandle = async (handleArg: plugins.fs.promises.FileHandle): Promise<void> => {
+  try {
+    await handleArg.close();
+  } catch {
+    try {
+      await handleArg.close();
+    } catch {}
+    throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  }
+};
+
+const closeFileHandleWithError = async (
+  handleArg: plugins.fs.promises.FileHandle,
+  operationErrorArg: unknown,
+): Promise<unknown> => {
+  try {
+    await closeFileHandle(handleArg);
+    return operationErrorArg;
+  } catch (errorArg) {
+    return preferCleanupError(operationErrorArg, errorArg);
+  }
+};
+
+const wipeDiscardedResult = (valueArg: unknown): void => {
+  if (valueArg instanceof Uint8Array) valueArg.fill(0);
+};
+
+const validateDirectory = (
+  statsArg: TBigIntStats,
+  effectiveUidArg: bigint,
+  finalArg: boolean,
+): void => {
+  if (!statsArg.isDirectory()) {
+    throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  }
+  const mode = statsArg.mode & 0o7777n;
+  if (finalArg) {
+    if (statsArg.uid !== effectiveUidArg || mode !== 0o700n) {
+      throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+    }
+    return;
+  }
+  if (statsArg.uid !== 0n && statsArg.uid !== effectiveUidArg) {
+    throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  }
+  if (
+    (mode & 0o022n) !== 0n
+    && !(statsArg.uid === 0n && (mode & 0o1000n) !== 0n)
+  ) throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+};
+
+const openDirectory = async (
+  directoryPathArg: string,
+  createArg: boolean,
+): Promise<plugins.fs.promises.FileHandle> => {
+  let currentHandle: plugins.fs.promises.FileHandle | undefined;
+  try {
+    const effectiveUid = process.geteuid?.();
+    if (!Number.isSafeInteger(effectiveUid) || effectiveUid! < 0) {
+      throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+    }
+    const root = plugins.path.parse(directoryPathArg).root;
+    const components = plugins.path.relative(root, directoryPathArg)
+      .split(plugins.path.sep)
+      .filter(Boolean);
+    currentHandle = await plugins.fs.promises.open(
+      root,
+      plugins.fs.constants.O_RDONLY
+        | plugins.fs.constants.O_DIRECTORY
+        | plugins.fs.constants.O_NOFOLLOW,
+    );
+    validateDirectory(await currentHandle.stat({ bigint: true }), BigInt(effectiveUid!), false);
+    for (let index = 0; index < components.length; index++) {
+      const componentPath = directoryHandlePath(currentHandle, components[index]);
+      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 {
+        nextHandle = await plugins.fs.promises.open(
+          componentPath,
+          plugins.fs.constants.O_RDONLY
+            | plugins.fs.constants.O_DIRECTORY
+            | plugins.fs.constants.O_NOFOLLOW,
+        );
+        validateDirectory(
+          await nextHandle.stat({ bigint: true }),
+          BigInt(effectiveUid!),
+          index === components.length - 1,
+        );
+        await closeFileHandle(currentHandle);
+        currentHandle = nextHandle;
+        nextHandle = undefined;
+      } finally {
+        if (nextHandle) await closeFileHandle(nextHandle);
+      }
+    }
+    const result = currentHandle;
+    currentHandle = undefined;
+    return result;
+  } catch (errorArg) {
+    let operationError: unknown = errorArg instanceof SmartSecretSealedFileStoreError
+      ? errorArg
+      : createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+    if (currentHandle) {
+      operationError = await closeFileHandleWithError(currentHandle, operationError);
+    }
+    throw operationError;
+  }
+};
+
+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,
+  maximumBytesArg: number,
+): Promise<unknown | undefined> => {
+  let handle: plugins.fs.promises.FileHandle | undefined;
+  let bytes: Buffer | undefined;
+  let result: unknown | undefined;
+  let operationError: unknown;
+  try {
+    try {
+      handle = await plugins.fs.promises.open(
+        directoryHandlePath(directoryHandleArg, fileNameArg),
+        plugins.fs.constants.O_RDONLY | plugins.fs.constants.O_NOFOLLOW,
+      );
+    } catch (errorArg) {
+      if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+      throw errorArg;
+    }
+    const stats = await handle.stat();
+    const effectiveUid = process.geteuid?.();
+    if (
+      !stats.isFile()
+      || stats.nlink !== 1
+      || stats.size < 1
+      || stats.size > maximumBytesArg
+      || (effectiveUid !== undefined && stats.uid !== effectiveUid)
+      || (stats.mode & 0o7777) !== 0o600
+    ) throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+    bytes = await handle.readFile();
+    if (bytes.byteLength !== stats.size) {
+      throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+    }
+    result = JSON.parse(bytes.toString('utf8')) as unknown;
+  } catch (errorArg) {
+    operationError = errorArg instanceof SmartSecretSealedFileStoreError
+      ? errorArg
+      : createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  }
+  bytes?.fill(0);
+  if (handle) {
+    try {
+      await closeFileHandle(handle);
+    } catch (errorArg) {
+      operationError = preferCleanupError(operationError, errorArg);
+    }
+  }
+  if (operationError) throw operationError;
+  return result;
+};
+
+const atomicWriteJson = async (
+  directoryHandleArg: plugins.fs.promises.FileHandle,
+  targetNameArg: string,
+  valueArg: unknown,
+): Promise<void> => {
+  const temporaryName = `.smartsecret-${plugins.crypto.randomBytes(16).toString('base64url')}.tmp`;
+  const temporaryPath = directoryHandlePath(directoryHandleArg, temporaryName);
+  const targetPath = directoryHandlePath(directoryHandleArg, targetNameArg);
+  let handle: plugins.fs.promises.FileHandle | undefined;
+  let bytes: Buffer | undefined;
+  let renamed = false;
+  let mutationApplied = false;
+  let operationError: unknown;
+  try {
+    bytes = Buffer.from(JSON.stringify(valueArg), 'utf8');
+    handle = await plugins.fs.promises.open(
+      temporaryPath,
+      plugins.fs.constants.O_WRONLY
+        | plugins.fs.constants.O_CREAT
+        | plugins.fs.constants.O_EXCL
+        | plugins.fs.constants.O_NOFOLLOW,
+      0o600,
+    );
+    const stats = await handle.stat();
+    const effectiveUid = process.geteuid?.();
+    if (
+      !stats.isFile()
+      || stats.nlink !== 1
+      || (effectiveUid !== undefined && stats.uid !== effectiveUid)
+      || (stats.mode & 0o7777) !== 0o600
+    ) {
+      throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+    }
+    await handle.writeFile(bytes);
+    await handle.sync();
+    await closeFileHandle(handle);
+    handle = undefined;
+    await plugins.fs.promises.rename(temporaryPath, targetPath);
+    renamed = true;
+    mutationApplied = true;
+    await directoryHandleArg.sync();
+  } catch (errorArg) {
+    operationError = errorArg instanceof SmartSecretSealedFileStoreError
+      ? errorArg
+      : createSmartSecretSealedFileStoreError(
+        mutationApplied ? 'MUTATION_OUTCOME_UNKNOWN' : 'FILESYSTEM_FAILED',
+      );
+  }
+  bytes?.fill(0);
+  if (handle) {
+    try {
+      await closeFileHandle(handle);
+    } catch (errorArg) {
+      operationError = preferCleanupError(operationError, errorArg);
+    }
+  }
+  if (!renamed) {
+    try {
+      await plugins.fs.promises.unlink(temporaryPath);
+      await directoryHandleArg.sync();
+    } catch (errorArg) {
+      if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') {
+        operationError = createSmartSecretSealedFileStoreError('MUTATION_OUTCOME_UNKNOWN');
+      }
+    }
+  }
+  if (operationError) throw operationError;
+};
+
+const removeAndSync = async (
+  directoryHandleArg: plugins.fs.promises.FileHandle,
+  fileNameArg: string,
+): Promise<boolean> => {
+  try {
+    await plugins.fs.promises.unlink(directoryHandlePath(directoryHandleArg, fileNameArg));
+    try {
+      await directoryHandleArg.sync();
+    } catch {
+      throw createSmartSecretSealedFileStoreError('MUTATION_OUTCOME_UNKNOWN');
+    }
+    return true;
+  } catch (errorArg) {
+    if (errorArg instanceof SmartSecretSealedFileStoreError) throw errorArg;
+    if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  }
+};
+
+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');
+    return names;
+  } catch (errorArg) {
+    if (errorArg instanceof SmartSecretSealedFileStoreError) throw errorArg;
+    throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+  }
+};
+
+const acquireLease = async (
+  optionsArg: INormalizedOptions,
+  deadlineArg = performance.now() + operationTimeoutMs,
+): Promise<plugins.smartipc.NamedMutexLease> => {
+  const remainingMs = deadlineArg - performance.now();
+  if (remainingMs <= 0) {
+    throw createSmartSecretSealedFileStoreError('MUTEX_FAILED');
+  }
+  try {
+    const mutex = new plugins.smartipc.NamedMutex(optionsArg.mutexNamespace);
+    const lease = await mutex.acquire({ timeoutMs: Math.max(0, Math.floor(remainingMs)) });
+    if (performance.now() >= deadlineArg) {
+      await lease.release().catch(() => undefined);
+      throw createSmartSecretSealedFileStoreError('MUTEX_FAILED');
+    }
+    return lease;
+  } catch (errorArg) {
+    throw mapMutexError(errorArg);
+  }
+};
+
+const readMasterKey = async (optionsArg: INormalizedOptions): Promise<Uint8Array | null> => {
+  let value: unknown;
+  try {
+    value = await optionsArg.kernelStore.getEntry(optionsArg.masterKeyAccount);
+  } catch (errorArg) {
+    throw mapKernelError(errorArg);
+  }
+  if (value === null) return null;
+  let result: Uint8Array | undefined;
+  try {
+    if (!(value instanceof Uint8Array)) {
+      throw createSmartSecretSealedFileStoreError('MASTER_KEY_CONFLICT');
+    }
+    result = new Uint8Array(value);
+    try {
+      value.fill(0);
+    } catch {}
+    if (result.byteLength !== masterKeyBytes) {
+      result.fill(0);
+      result = undefined;
+      throw createSmartSecretSealedFileStoreError('MASTER_KEY_CONFLICT');
+    }
+    return result;
+  } catch (errorArg) {
+    result?.fill(0);
+    if (errorArg instanceof SmartSecretSealedFileStoreError) throw errorArg;
+    throw createSmartSecretSealedFileStoreError('MASTER_KEY_CONFLICT');
+  }
+};
+
+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;
+  try {
+    try {
+      await optionsArg.kernelStore.setEntry(optionsArg.masterKeyAccount, generated);
+      written = true;
+    } catch (errorArg) {
+      throw mapKernelError(errorArg);
+    }
+    const readback = await readMasterKey(optionsArg);
+    if (
+      !readback
+      || !plugins.crypto.timingSafeEqual(readback, generated)
+    ) {
+      readback?.fill(0);
+      throw createSmartSecretSealedFileStoreError('MASTER_KEY_CONFLICT');
+    }
+    return readback;
+  } catch (errorArg) {
+    if (written) {
+      try {
+        await optionsArg.kernelStore.deleteEntry(optionsArg.masterKeyAccount);
+      } catch (deleteErrorArg) {
+        throw mapKernelError(deleteErrorArg);
+      }
+    }
+    throw errorArg;
+  } finally {
+    generated.fill(0);
+  }
+};
+
+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 {
+    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,
+      4 * 1_024,
+    );
+    const manifest = manifestValue === undefined ? undefined : parseManifest(manifestValue, optionsArg);
+    key = await readMasterKey(optionsArg);
+    if (!key) {
+      if (names.length > 0) {
+        throw createSmartSecretSealedFileStoreError('MASTER_KEY_UNAVAILABLE');
+      }
+      key = await createMasterKey(optionsArg);
+      createdMasterKey = true;
+    }
+    if (key.byteLength !== masterKeyBytes) {
+      throw createSmartSecretSealedFileStoreError('MASTER_KEY_CONFLICT');
+    }
+    const keyFingerprint = fingerprint(key);
+    if (manifest && manifest.masterKeyFingerprint !== keyFingerprint) {
+      throw createSmartSecretSealedFileStoreError('MASTER_KEY_CONFLICT');
+    }
+    for (const name of names.filter((nameArg) => temporaryFilePattern.test(nameArg))) {
+      await removeAndSync(directoryHandle, name);
+    }
+    if (!manifest) {
+      await atomicWriteJson(
+        directoryHandle,
+        manifestName,
+        manifestFor(optionsArg, keyFingerprint),
+      );
+    }
+    result = new Uint8Array(key);
+    key.fill(0);
+    key = null;
+  } catch (errorArg) {
+    operationError = errorArg;
+  }
+  key?.fill(0);
+  operationError = await closeFileHandleWithError(directoryHandle, operationError);
+  if (operationError) {
+    result?.fill(0);
+    result = undefined;
+    if (createdMasterKey && !mutationOutcomeUnknown(operationError)) {
+      try {
+        await optionsArg.kernelStore.deleteEntry(optionsArg.masterKeyAccount);
+      } catch (deleteErrorArg) {
+        const deleteError = mapKernelError(deleteErrorArg);
+        throw preferCleanupError(operationError, deleteError);
+      }
+    }
+    throw operationError;
+  }
+  return result!;
+};
+
+/**
+ * Stores one small master key in a strict kernel store and authenticated
+ * ciphertext in a caller-owned private directory. The kernel store lifecycle
+ * remains owned by the caller.
+ */
+export class SmartSecretSealedFileStore {
+  public readonly service: string;
+  public readonly storeId: string;
+  public readonly directoryPath: string;
+
+  private lifecycleState: TLifecycleState = 'ready';
+  private operationTail: Promise<void> = Promise.resolve();
+  private pendingOperations = 0;
+  private closePromise?: Promise<void>;
+
+  private constructor(
+    private readonly options: INormalizedOptions,
+    private readonly masterKey: Uint8Array,
+  ) {
+    this.service = options.service;
+    this.storeId = options.storeId;
+    this.directoryPath = options.directoryPath;
+  }
+
+  public static async create(
+    optionsArg: ISmartSecretSealedFileStoreOptions,
+  ): Promise<SmartSecretSealedFileStore> {
+    const options = normalizeOptions(optionsArg);
+    if (process.platform !== 'linux' || typeof process.geteuid !== 'function') {
+      throw createSmartSecretSealedFileStoreError('KERNEL_UNAVAILABLE');
+    }
+    const lease = await acquireLease(options);
+    let key: Uint8Array | undefined;
+    let operationError: unknown;
+    try {
+      key = await bootstrapUnderLease(options);
+    } catch (errorArg) {
+      operationError = errorArg;
+    }
+    try {
+      await lease.release();
+    } catch {
+      operationError = preferCleanupError(
+        operationError,
+        createSmartSecretSealedFileStoreError('MUTEX_FAILED'),
+      );
+    }
+    if (operationError) {
+      key?.fill(0);
+      throw operationError;
+    }
+    const store = new SmartSecretSealedFileStore(options, key!);
+    key = undefined;
+    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,
+  ): Promise<SmartSecretSealedFileStore> {
+    const options = normalizeOptions(optionsArg);
+    if (process.platform !== 'linux' || typeof process.geteuid !== 'function') {
+      throw createSmartSecretSealedFileStoreError('KERNEL_UNAVAILABLE');
+    }
+    const lease = await acquireLease(options);
+    let key: Uint8Array | undefined;
+    let operationError: unknown;
+    try {
+      const directoryHandle = await ensureDirectory(options.directoryPath);
+      try {
+        const names = await listOwnedFiles(directoryHandle);
+        if (names.some((nameArg) => (
+          nameArg === manifestName || entryFilePattern.test(nameArg)
+        ))) {
+          const manifestValue = await readStrictJsonFile(
+            directoryHandle,
+            manifestName,
+            4 * 1_024,
+          );
+          if (manifestValue === undefined) {
+            throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+          }
+          parseManifest(manifestValue, options);
+        }
+        try {
+          await options.kernelStore.deleteEntry(options.masterKeyAccount);
+        } catch (errorArg) {
+          throw mapKernelError(errorArg);
+        }
+        const deletionOrder = names.filter((nameArg) => nameArg !== manifestName);
+        if (names.includes(manifestName)) deletionOrder.push(manifestName);
+        for (const name of deletionOrder) {
+          await removeAndSync(directoryHandle, name);
+        }
+      } catch (errorArg) {
+        operationError = errorArg;
+      }
+      operationError = await closeFileHandleWithError(directoryHandle, operationError);
+      if (operationError) throw operationError;
+      key = await bootstrapUnderLease(options);
+    } catch (errorArg) {
+      operationError = errorArg;
+    }
+    try {
+      await lease.release();
+    } catch {
+      operationError = preferCleanupError(
+        operationError,
+        createSmartSecretSealedFileStoreError('MUTEX_FAILED'),
+      );
+    }
+    if (operationError) {
+      key?.fill(0);
+      throw operationError;
+    }
+    const store = new SmartSecretSealedFileStore(options, key!);
+    key = undefined;
+    return store;
+  }
+
+  public getEntry(accountArg: string): Promise<Uint8Array | null> {
+    let account: string;
+    try {
+      account = normalizeSmartSecretKernelAccount(accountArg);
+    } catch {
+      throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+    }
+    return this.reserveOperation((deadlineArg, markAcquiredArg) => this.withLease(
+      deadlineArg,
+      markAcquiredArg,
+      async () => {
+        const directoryHandle = await openExistingDirectory(this.directoryPath);
+        const id = entryId(this.options, account);
+        let value: unknown | undefined;
+        let operationError: unknown;
+        try {
+          await this.verifyManifest(directoryHandle);
+          value = await readStrictJsonFile(
+            directoryHandle,
+            `${id}.sealed.json`,
+            maximumEnvelopeBytes,
+          );
+        } catch (errorArg) {
+          operationError = errorArg;
+        }
+        operationError = await closeFileHandleWithError(directoryHandle, operationError);
+        if (operationError) throw operationError;
+        if (value === undefined) return null;
+        const parsed = parseEnvelope(value);
+        const aad = entryAad(this.options, account, id, fingerprint(this.masterKey));
+        try {
+          if (
+            parsed.envelope.entryId !== id
+            || parsed.envelope.masterKeyFingerprint !== fingerprint(this.masterKey)
+          ) throw createSmartSecretSealedFileStoreError('ENVELOPE_INVALID');
+          try {
+            return await plugins.smartcrypto.aesGcmDecrypt({
+              key: this.masterKey,
+              encryptedData: parsed.encryptedData,
+              aad,
+            });
+          } catch {
+            throw createSmartSecretSealedFileStoreError('AUTHENTICATION_FAILED');
+          }
+        } finally {
+          aad.fill(0);
+          parsed.encryptedData.nonce.fill(0);
+          parsed.encryptedData.ciphertext.fill(0);
+          parsed.encryptedData.tag.fill(0);
+        }
+      },
+    ));
+  }
+
+  public setEntry(accountArg: string, valueArg: Uint8Array): Promise<void> {
+    let account: string;
+    try {
+      account = normalizeSmartSecretKernelAccount(accountArg);
+    } catch {
+      throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+    }
+    let value: Uint8Array;
+    try {
+      if (!(valueArg instanceof Uint8Array)) {
+        throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+      }
+      if (valueArg.byteLength > smartSecretSealedFileMaximumEntryBytes) {
+        throw createSmartSecretSealedFileStoreError('SIZE_LIMIT_EXCEEDED');
+      }
+      value = new Uint8Array(valueArg);
+    } catch (errorArg) {
+      if (errorArg instanceof SmartSecretSealedFileStoreError) throw errorArg;
+      throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+    }
+    let result: Promise<void>;
+    try {
+      result = this.reserveOperation((deadlineArg, markAcquiredArg) => this.withLease(
+        deadlineArg,
+        markAcquiredArg,
+        async () => {
+        const directoryHandle = await openExistingDirectory(this.directoryPath);
+        let encrypted: plugins.smartcrypto.IAesGcmCiphertext | undefined;
+        const id = entryId(this.options, account);
+        const keyFingerprint = fingerprint(this.masterKey);
+        const aad = entryAad(this.options, account, id, keyFingerprint);
+        let operationError: unknown;
+        try {
+          await this.verifyManifest(directoryHandle);
+          try {
+            encrypted = await plugins.smartcrypto.aesGcmEncrypt({
+              key: this.masterKey,
+              plaintext: value,
+              aad,
+            });
+          } catch {
+            throw createSmartSecretSealedFileStoreError('AUTHENTICATION_FAILED');
+          }
+          const envelope: IEnvelopeV1 = {
+            schemaVersion,
+            profile,
+            entryId: id,
+            masterKeyFingerprint: keyFingerprint,
+            ...encodeEncryptedData(encrypted),
+          };
+          await atomicWriteJson(
+            directoryHandle,
+            `${id}.sealed.json`,
+            envelope,
+          );
+        } catch (errorArg) {
+          operationError = errorArg;
+        }
+        try {
+          aad.fill(0);
+          encrypted?.nonce.fill(0);
+          encrypted?.ciphertext.fill(0);
+          encrypted?.tag.fill(0);
+        } finally {
+          operationError = await closeFileHandleWithError(directoryHandle, operationError);
+        }
+        if (operationError) throw operationError;
+        },
+      ));
+    } catch (errorArg) {
+      value.fill(0);
+      throw errorArg;
+    }
+    return result.finally(() => value.fill(0));
+  }
+
+  public deleteEntry(accountArg: string): Promise<boolean> {
+    let account: string;
+    try {
+      account = normalizeSmartSecretKernelAccount(accountArg);
+    } catch {
+      throw createSmartSecretSealedFileStoreError('INVALID_ARGUMENT');
+    }
+    return this.reserveOperation((deadlineArg, markAcquiredArg) => this.withLease(
+      deadlineArg,
+      markAcquiredArg,
+      async () => {
+      const directoryHandle = await openExistingDirectory(this.directoryPath);
+      let result: boolean | undefined;
+      let operationError: unknown;
+      try {
+        await this.verifyManifest(directoryHandle);
+        const id = entryId(this.options, account);
+        result = await removeAndSync(directoryHandle, `${id}.sealed.json`);
+      } catch (errorArg) {
+        operationError = errorArg;
+      }
+      operationError = await closeFileHandleWithError(directoryHandle, operationError);
+      if (operationError) throw operationError;
+      return result!;
+      },
+    ));
+  }
+
+  public close(): Promise<void> {
+    if (this.closePromise) return this.closePromise;
+    this.lifecycleState = 'closing';
+    const operationTail = this.operationTail;
+    const closePromise = operationTail.finally(() => {
+      this.masterKey.fill(0);
+      this.lifecycleState = 'closed';
+    });
+    this.closePromise = closePromise;
+    return closePromise;
+  }
+
+  private reserveOperation<T>(
+    operationArg: (deadlineArg: number, markAcquiredArg: () => void) => Promise<T>,
+  ): Promise<T> {
+    if (this.lifecycleState !== 'ready') {
+      throw createSmartSecretSealedFileStoreError('STORE_CLOSED');
+    }
+    if (this.pendingOperations >= maximumPendingOperations) {
+      throw createSmartSecretSealedFileStoreError('OPERATION_LIMIT_REACHED');
+    }
+    this.pendingOperations += 1;
+    const deadline = performance.now() + operationTimeoutMs;
+    let admissionExpired = false;
+    let admissionTimer: NodeJS.Timeout | undefined;
+    let rejectAdmission!: (errorArg: SmartSecretSealedFileStoreError) => void;
+    const admissionTimeout = new Promise<never>((_resolveArg, rejectArg) => {
+      rejectAdmission = rejectArg;
+    });
+    const clearAdmissionTimer = (): void => {
+      if (admissionTimer) {
+        clearTimeout(admissionTimer);
+        admissionTimer = undefined;
+      }
+    };
+    const markAcquired = (): void => clearAdmissionTimer();
+    admissionTimer = setTimeout(() => {
+      admissionExpired = true;
+      admissionTimer = undefined;
+      rejectAdmission(createSmartSecretSealedFileStoreError('MUTEX_FAILED'));
+    }, operationTimeoutMs);
+    const execution = this.operationTail.then(() => {
+      if (admissionExpired || performance.now() >= deadline) {
+        throw createSmartSecretSealedFileStoreError('MUTEX_FAILED');
+      }
+      return operationArg(deadline, markAcquired);
+    });
+    this.operationTail = execution.then(() => undefined, () => undefined);
+    execution.then(() => {
+      clearAdmissionTimer();
+      this.pendingOperations -= 1;
+    }, () => {
+      clearAdmissionTimer();
+      this.pendingOperations -= 1;
+    });
+    return Promise.race([execution, admissionTimeout]);
+  }
+
+  private async withLease<T>(
+    deadlineArg: number,
+    markAcquiredArg: () => void,
+    operationArg: () => Promise<T>,
+  ): Promise<T> {
+    const lease = await acquireLease(this.options, deadlineArg);
+    markAcquiredArg();
+    let result: T | undefined;
+    let operationError: unknown;
+    try {
+      result = await operationArg();
+    } catch (errorArg) {
+      operationError = errorArg;
+    }
+    try {
+      await lease.release();
+    } catch {
+      wipeDiscardedResult(result);
+      if (mutationOutcomeUnknown(operationError)) throw operationError;
+      throw createSmartSecretSealedFileStoreError('MUTEX_FAILED');
+    }
+    if (operationError) throw operationError;
+    return result as T;
+  }
+
+  private async verifyManifest(
+    directoryHandleArg: plugins.fs.promises.FileHandle,
+  ): Promise<void> {
+    const value = await readStrictJsonFile(
+      directoryHandleArg,
+      manifestName,
+      4 * 1_024,
+    );
+    if (value === undefined) throw createSmartSecretSealedFileStoreError('FILESYSTEM_FAILED');
+    const manifest = parseManifest(value, this.options);
+    if (manifest.masterKeyFingerprint !== fingerprint(this.masterKey)) {
+      throw createSmartSecretSealedFileStoreError('MASTER_KEY_CONFLICT');
+    }
+  }
+}