@push.rocks/smartsecret 1.4.0 → 1.5.0

package/ts/smartsecret.sealedfile.ts

@@ -0,0 +1,1195 @@
+import * as plugins from './smartsecret.plugins.js';
+import {
+  SmartSecretKernelStoreError,
+} from './smartsecret.kernel.error.js';
+import {
+  normalizeSmartSecretKernelAccount,
+  normalizeSmartSecretKernelService,
+  type ISmartSecretKernelOperationOptions,
+} 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 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 ISmartSecretSealedFileStoreOptions {
+  kernelStore: ISmartSecretSealedFileKernelStore;
+  storeId: string;
+  directoryPath: string;
+}
+
+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;
+}
+
+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 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 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 ensureDirectory = async (directoryPathArg: string): 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]);
+      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 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,
+): Promise<string[]> => {
+  try {
+    const names = await plugins.fs.promises.readdir(directoryHandlePath(directoryHandleArg));
+    if (names.some((nameArg) => (
+      nameArg !== manifestName
+      && !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 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): Promise<Uint8Array> => {
+  const directoryHandle = 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);
+    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;
+  }
+
+  /** 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 ensureDirectory(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 ensureDirectory(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 ensureDirectory(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');
+    }
+  }
+}