@push.rocks/smartsecret 1.4.0 → 1.6.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@push.rocks/smartsecret",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "private": false,
-  "description": "OS-backed secret storage plus strict Linux kernel-keyring and envelope APIs for Node.js.",
+  "description": "OS-backed secret storage plus strict Linux kernel-keyring, sealed-file, and envelope APIs for Node.js.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "type": "module",
@@ -31,9 +31,9 @@
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
     "@git.zone/tsrun": "^2.0.6",
-    "@git.zone/tsrust": "^1.7.0",
+    "@git.zone/tsrust": "^1.8.0",
     "@git.zone/tstest": "^4.0.0",
-    "@types/node": "^26.1.2"
+    "@types/node": "^26.2.0"
   },
   "files": [
     "ts/**/*",
@@ -53,8 +53,8 @@
   ],
   "dependencies": {
     "@push.rocks/smartcrypto": "^2.2.0",
-    "@push.rocks/smartipc": "^2.4.1",
-    "@push.rocks/smartrust": "^1.6.0"
+    "@push.rocks/smartipc": "^2.4.2",
+    "@push.rocks/smartrust": "^1.7.0"
   },
   "scripts": {
     "test": "(tstest test/ --verbose)",

package/readme.hints.md

@@ -24,7 +24,24 @@
 - No shell, PATH lookup, environment override, Secret Service, or filesystem secret fallback
 - Generic values are framed and limited to 0..16384 bytes; service/account names are valid scalar UTF-8 strings of 1..1024 bytes
 - Persistent-root service rings are revalidated on every operation; process keyring ownership is staging-only
+- Generic entry moves publish and verify the exact framed value at the destination before invalidating the source
 - Service-wide SmartIPC NamedMutex plus a single monotonic 1..60000 ms deadline bounds cooperating cross-process access
 - Any post-dispatch mutation ambiguity or worker integrity failure terminates and poisons the store
 - DevIdP v1 migration is opaque, receipt-bound, keyutils-only, and requires a quiescent legacy writer
 - Same-UID readability and kernel expiry/reboot behavior are part of the security model
+
+## SmartSecret Sealed File Store
+- Composes a caller-owned SmartSecretKernelStore; it never owns or closes the kernel worker
+- Stores one 32-byte master key per service/store/directory identity in the kernel keyring
+- Stores only strict AES-256-GCM envelopes in a caller-owned private directory
+- A non-secret manifest fingerprints the master key; missing kernel material never creates a replacement silently
+- Explicit reset is destructive and removes only store-owned manifest, entry, and temporary files
+- All identities targeting the same directory share one mutex; reset verifies any manifest identity before deletion
+- Relocation locks both paths in deterministic order, atomically renames on one filesystem, fsyncs both parents, and rebinds the unchanged master key
+- Relocation is idempotent after its own interrupted rename through an inode-bound receipt; arbitrary external moves are rejected
+- Callers must persist an exact-path relocation intent before invocation and retain it after every error because the directory may already be at the destination
+- While an intent or receipt may remain, recovery must retry relocate with the same paths instead of creating or resetting either location
+- Source writers must be quiescent and the retired source must not be initialized again
+- Directory traversal and store I/O are anchored to open descriptors; ancestors, final components, owners, modes, and O_NOFOLLOW are validated
+- A 64-operation admission cap and one 60-second monotonic queue-plus-mutex deadline bound retained operation inputs
+- Filesystem isolation assumes other processes under the same UID are trusted, matching the kernel-keyring boundary

package/readme.md

@@ -1,6 +1,6 @@
 # @push.rocks/smartsecret
 
-OS-backed secret storage plus strict Linux kernel-keyring and envelope APIs for Node.js.
+OS-backed secret storage plus strict Linux kernel-keyring, sealed-file, and envelope APIs for Node.js.
 
 ## Issue Reporting and Security
 
@@ -195,7 +195,7 @@ try {
 
 Service and account strings must contain valid Unicode scalar values and encode to 1 through 1,024 UTF-8 bytes. Values may contain 0 through 16,384 bytes. The stored value is framed with a fixed version and exact length before publication. Existing service rings and entries are accepted only when their type, description, owner, and private permissions match the package contract. Kernel per-user quotas may still reject writes before this per-entry limit is reached; the store reports the kernel failure and never falls back to filesystem storage.
 
-`setEntry()` copies its input before dispatch, and `getEntry()` returns a fresh byte array. The caller still owns its input and returned copies and should wipe them when no longer needed. JavaScript and operating-system buffers can retain additional copies, so this remains best-effort zeroization rather than guaranteed memory erasure.
+`setEntry()` copies its input before dispatch, and `getEntry()` returns a fresh byte array. `moveEntry()` moves one exact framed entry to another account under the same service-wide lease: it verifies the destination before invalidating the source, and matching source/destination values converge to the destination. A differing destination rejects with `TARGET_CONFLICT`. When the source is already absent, `alreadyMoved` reports only that a structurally valid destination entry exists; callers that did not observe the original source must independently bind the destination value to their durable state. The caller still owns its input and returned copies and should wipe them when no longer needed. JavaScript and operating-system buffers can retain additional copies, so this remains best-effort zeroization rather than guaranteed memory erasure.
 
 The store uses one persistent-user-owned service ring and stages unpublished objects in the process keyring. An inherited session link is preserved and revalidated, but it cannot override or conflict with the persistent root. A revoked inherited session keyring, which can remain after PAM logout, is treated as absent because it is optional and unusable; any failure to establish or validate the required process and persistent roots still fails closed. Publication is verified before staging ownership is removed. Every operation also acquires a service-wide `NamedMutex`, which coordinates cooperating processes running as the same OS identity on the same machine.
 
@@ -205,6 +205,47 @@ Kernel keyring permissions are an isolation boundary between OS identities, not
 
 Operation timeouts default to 5 seconds and may be set from 1 through 60,000 milliseconds. A timeout or abort covers queueing, mutex acquisition, and the worker request under one monotonic deadline. If a mutating request is interrupted after dispatch, or publication/release cannot be confirmed, the store rejects with a `SmartSecretKernelStoreError` whose code is `MUTATION_OUTCOME_UNKNOWN`, terminates the worker, and remains poisoned. Read-side worker integrity failures also poison and terminate the store. Always await `close()`; it waits for already-reserved operations and confirms worker termination.
 
+### Sealed file store
+
+`SmartSecretSealedFileStore` is a Linux-only API that composes a caller-owned `SmartSecretKernelStore` for data sets that exceed the kernel's per-user key quota. It stores one 32-byte master key in the kernel keyring and one authenticated AES-256-GCM envelope per account in a dedicated private directory supplied by the caller.
+
+```typescript
+import {
+  SmartSecretKernelStore,
+  SmartSecretSealedFileStore,
+} from '@push.rocks/smartsecret';
+
+const kernelStore = await SmartSecretKernelStore.create({
+  service: 'example.application',
+});
+try {
+  const sealedStore = await SmartSecretSealedFileStore.create({
+    kernelStore,
+    storeId: 'oauth-credentials',
+    directoryPath: '/absolute/private/application/directory/credentials',
+  });
+  try {
+    await sealedStore.setEntry('account-a', new TextEncoder().encode('secret'));
+    const value = await sealedStore.getEntry('account-a');
+    value?.fill(0);
+  } finally {
+    await sealedStore.close();
+  }
+} finally {
+  await kernelStore.close();
+}
+```
+
+The directory is required to be owned by the effective user and mode `0700`; envelope and manifest files are mode `0600`. Every directory component must be owned by root or the effective user and must not be group- or world-writable, except for root-owned sticky directories such as `/tmp`. Directory traversal, creation, and store I/O are anchored to open directory descriptors, and final components use `O_NOFOLLOW`. Writes use random exclusive temporary files, file and directory `fsync`, and atomic replacement. Reads reject unexpected owners or permissions, malformed envelopes, identity mismatches, oversized ciphertext, and authentication failures. The filesystem boundary, like the kernel keyring, trusts other processes running under the same UID.
+
+The non-secret manifest binds the directory to the kernel master-key fingerprint. If the kernel key is lost or expires while any manifest, envelope, or temporary artifact remains, `create()` fails with `MASTER_KEY_UNAVAILABLE` and never silently generates a replacement. `SmartSecretSealedFileStore.reset()` is an explicit destructive recovery operation: after verifying any existing manifest belongs to the requested service and store ID, it removes only the store-owned manifest, envelope, and temporary files, removes the old kernel entry if present, and creates a new empty store.
+
+`SmartSecretSealedFileStore.relocate()` moves an initialized store to another absolute path on the same filesystem and rebinds the exact master key to the destination path-derived account. It never decrypts or rewrites the manifest or envelopes. Both private parent directories must already exist, while the destination store directory must not exist before the first attempt. The operation locks both paths in deterministic order, writes an inode- and request-bound relocation receipt, atomically renames the directory, fsyncs both parents, moves the kernel entry, removes the receipt, and returns a ready destination store. The receipt allows the same call to resume its own interrupted rename; arbitrary external moves and copied destinations are rejected. A completed call remains idempotent because the destination key is verified against the unchanged manifest.
+
+The caller must durably record the exact service, store ID, source path, and destination path before quiescing writers and calling `relocate()`. Preserve that intent after every rejected call: `KERNEL_UNAVAILABLE`, `FILESYSTEM_FAILED`, master-key errors, and `MUTATION_OUTCOME_UNKNOWN` can all be reported after the directory was renamed, so an error code does not establish which path currently exists. Recovery must call `relocate()` again with the same path pair; create a fresh kernel store first when the prior store was poisoned or its worker integrity is uncertain. Do not call `create()` or `reset()` at either path while the intent or relocation receipt may remain, and never initialize a new store at the retired source path. Clear the caller-owned intent only after `relocate()` returns a ready destination store and the application has durably committed the destination as authoritative.
+
+Each store instance admits at most 64 operations at once. Each admitted operation has one 60-second monotonic deadline covering the local operation queue and cross-process mutex acquisition. The mutex is directory-wide, so different service or store identities targeting the same directory serialize with each other. Work already running after mutex acquisition is not interrupted by that admission deadline. `close()` rejects new operations, drains admitted operations, and then best-effort wipes the retained master-key copy.
+
 ### DevIdP v1 keyutils migration
 
 The two `DevIdP` migration methods are intentionally narrow. They are available only on a store created with service `global.idp.devidp` and accept only accounts matching `v1:[a-f0-9]{64}`:
@@ -282,11 +323,79 @@ SmartSecretKernelStore.create(
 | `getEntry` | `(account: string, options?) => Promise<Uint8Array \| null>` | Read a copied raw value or return `null` when absent |
 | `setEntry` | `(account: string, value: Uint8Array, options?) => Promise<void>` | Create or replace one framed entry |
 | `deleteEntry` | `(account: string, options?) => Promise<boolean>` | Delete an entry and report whether it existed |
+| `moveEntry` | `(sourceAccount: string, destinationAccount: string, options?) => Promise<'moved' \| 'alreadyMoved' \| 'sourceAbsent'>` | Idempotently move one exact framed entry without exposing its value |
 | `readDevIdpV1Legacy` | `(account: string, options?) => Promise<IDevIdpV1LegacyRead \| null>` | Read one verified, opaque keyutils legacy value |
 | `deleteDevIdpV1Legacy` | `(receipt, options?) => Promise<'deleted' \| 'alreadyAbsent'>` | Revalidate and consume one legacy receipt |
 | `close` | `() => Promise<void>` | Wait for reserved operations and confirm worker termination |
 
-Operation options contain optional `timeoutMs` and `signal: AbortSignal` properties. Failures are code-only `SmartSecretKernelStoreError` instances. Stable codes distinguish invalid input, unsupported runtime, unavailable kernel/worker/mutex resources, root conflicts, corrupt entries, changed migration sources, pre-dispatch aborts/timeouts, unknown mutation outcomes, poisoned/closed lifecycle state, and worker integrity failures. Secret values and underlying causes are never retained on these errors.
+Operation options contain optional `timeoutMs` and `signal: AbortSignal` properties. Failures are code-only `SmartSecretKernelStoreError` instances. Stable codes distinguish invalid input, unsupported runtime, unavailable kernel/worker/mutex resources, root conflicts, corrupt entries, changed sources, target conflicts, pre-dispatch aborts/timeouts, unknown mutation outcomes, poisoned/closed lifecycle state, and worker integrity failures. Secret values and underlying causes are never retained on these errors.
+
+### `SmartSecretSealedFileStore`
+
+Create a sealed store with a caller-owned kernel store and a dedicated absolute private directory:
+
+```typescript
+SmartSecretSealedFileStore.create(
+  options: ISmartSecretSealedFileStoreOptions,
+): Promise<SmartSecretSealedFileStore>
+```
+
+This API is available only on Linux. `directoryPath` must be an absolute normalized path. The exported options and kernel-store contract are:
+
+```typescript
+interface ISmartSecretSealedFileKernelStore {
+  readonly service: string;
+  getEntry(
+    account: string,
+    options?: ISmartSecretKernelOperationOptions,
+  ): Promise<Uint8Array | null>;
+  setEntry(
+    account: string,
+    value: Uint8Array,
+    options?: ISmartSecretKernelOperationOptions,
+  ): Promise<void>;
+  deleteEntry(
+    account: string,
+    options?: ISmartSecretKernelOperationOptions,
+  ): Promise<boolean>;
+}
+
+interface ISmartSecretSealedFileStoreOptions {
+  kernelStore: ISmartSecretSealedFileKernelStore;
+  storeId: string;
+  directoryPath: string;
+}
+
+interface ISmartSecretSealedFileRelocationKernelStore
+  extends ISmartSecretSealedFileKernelStore {
+  moveEntry(
+    sourceAccount: string,
+    destinationAccount: string,
+    options?: ISmartSecretKernelOperationOptions,
+  ): Promise<'moved' | 'alreadyMoved' | 'sourceAbsent'>;
+}
+
+interface ISmartSecretSealedFileStoreRelocationOptions {
+  kernelStore: ISmartSecretSealedFileRelocationKernelStore;
+  storeId: string;
+  sourceDirectoryPath: string;
+  destinationDirectoryPath: string;
+}
+```
+
+Instances expose readonly `service`, `storeId`, and `directoryPath` properties. The exported `smartSecretSealedFileMaximumEntryBytes` constant is `524288`.
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `create` | `(options) => Promise<SmartSecretSealedFileStore>` | Open or initialize a store without replacing missing key material |
+| `relocate` | `(options) => Promise<SmartSecretSealedFileStore>` | Move one initialized store, rebind its exact master key, and resume completed or interrupted moves |
+| `reset` | `(options) => Promise<SmartSecretSealedFileStore>` | Destructively discard store-owned ciphertext and create a new empty store |
+| `getEntry` | `(account: string) => Promise<Uint8Array \| null>` | Authenticate and decrypt a copied value or return `null` when absent |
+| `setEntry` | `(account: string, value: Uint8Array) => Promise<void>` | Atomically encrypt and replace an entry up to 524,288 bytes |
+| `deleteEntry` | `(account: string) => Promise<boolean>` | Delete an encrypted entry and report whether it existed |
+| `close` | `() => Promise<void>` | Drain admitted operations and best-effort wipe the retained master-key copy |
+
+Failures are code-only `SmartSecretSealedFileStoreError` instances. `TSmartSecretSealedFileStoreErrorCode` is the exact union `AUTHENTICATION_FAILED | ENVELOPE_INVALID | FILESYSTEM_FAILED | INVALID_ARGUMENT | KERNEL_UNAVAILABLE | MASTER_KEY_CONFLICT | MASTER_KEY_UNAVAILABLE | MUTATION_OUTCOME_UNKNOWN | MUTEX_FAILED | OPERATION_LIMIT_REACHED | SIZE_LIMIT_EXCEEDED | STORE_CLOSED`. `ISmartSecretSealedFileStoreErrorJson` describes the stable `{ name, code, message }` JSON and inspection shape. The caller retains ownership of the kernel store and must close it separately.
 
 ### Types
 
@@ -351,7 +460,7 @@ Both paths can be influenced by providing a custom `vaultPath` in the constructo
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository [license file](./license).
 
 The packaged Linux kernel worker contains statically linked third-party Rust components. Their copyright and license notices are reproduced in [third-party-notices.md](./third-party-notices.md).
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartsecret',
-  version: '1.4.0',
-  description: 'OS-backed secret storage plus strict Linux kernel-keyring and envelope APIs for Node.js.'
+  version: '1.6.0',
+  description: 'OS-backed secret storage plus strict Linux kernel-keyring, sealed-file, and envelope APIs for Node.js.'
 }

package/ts/index.ts

@@ -19,3 +19,9 @@ export type {
   ISmartSecretKernelStoreErrorJson,
   TSmartSecretKernelStoreErrorCode,
 } from './smartsecret.kernel.error.js';
+export * from './smartsecret.sealedfile.js';
+export { SmartSecretSealedFileStoreError } from './smartsecret.sealedfile.error.js';
+export type {
+  ISmartSecretSealedFileStoreErrorJson,
+  TSmartSecretSealedFileStoreErrorCode,
+} from './smartsecret.sealedfile.error.js';

package/ts/smartsecret.kernel.error.ts

@@ -11,6 +11,7 @@ export type TSmartSecretKernelStoreErrorCode =
   | 'SOURCE_CHANGED'
   | 'STORE_CLOSED'
   | 'STORE_POISONED'
+  | 'TARGET_CONFLICT'
   | 'UNSUPPORTED_RUNTIME'
   | 'WORKER_INTEGRITY_FAILED'
   | 'WORKER_UNAVAILABLE';
@@ -35,6 +36,7 @@ const errorCodes = new Set<TSmartSecretKernelStoreErrorCode>([
   'SOURCE_CHANGED',
   'STORE_CLOSED',
   'STORE_POISONED',
+  'TARGET_CONFLICT',
   'UNSUPPORTED_RUNTIME',
   'WORKER_INTEGRITY_FAILED',
   'WORKER_UNAVAILABLE',

package/ts/smartsecret.kernel.protocol.ts

@@ -32,7 +32,8 @@ export type TSmartSecretKernelDomainErrorCode =
   | 'KERNEL_UNAVAILABLE'
   | 'MUTATION_OUTCOME_UNKNOWN'
   | 'ROOT_CONFLICT'
-  | 'SOURCE_CHANGED';
+  | 'SOURCE_CHANGED'
+  | 'TARGET_CONFLICT';
 
 export interface ISmartSecretKernelDomainErrorResult {
   outcome: 'domainError';
@@ -86,6 +87,17 @@ export type TSmartSecretKernelDeleteResult =
   | ISmartSecretKernelDomainErrorResult
   | ISmartSecretKernelDeleteSuccess;
 
+export type TSmartSecretKernelMoveStatus = 'moved' | 'alreadyMoved' | 'sourceAbsent';
+
+export interface ISmartSecretKernelMoveSuccess {
+  outcome: 'success';
+  status: TSmartSecretKernelMoveStatus;
+}
+
+export type TSmartSecretKernelMoveResult =
+  | ISmartSecretKernelDomainErrorResult
+  | ISmartSecretKernelMoveSuccess;
+
 export interface ISmartSecretKernelLegacySuccessAbsent {
   outcome: 'success';
   found: false;
@@ -142,6 +154,10 @@ export type TSmartSecretKernelCommands = {
     params: { description: string };
     result: TSmartSecretKernelDeleteResult;
   };
+  moveEntry: {
+    params: { sourceDescription: string; destinationDescription: string };
+    result: TSmartSecretKernelMoveResult;
+  };
   readDevIdpV1Legacy: {
     params: { account: string };
     result: TSmartSecretKernelLegacyReadResult;
@@ -159,6 +175,7 @@ const domainErrorCodes: ReadonlySet<string> = new Set([
   'MUTATION_OUTCOME_UNKNOWN',
   'ROOT_CONFLICT',
   'SOURCE_CHANGED',
+  'TARGET_CONFLICT',
 ]);
 
 const isSmartSecretKernelDomainErrorCode = (
@@ -539,6 +556,28 @@ export const parseSmartSecretKernelDeleteResult = (
   return { kind: 'success', deleted: result.deleted };
 };
 
+export const parseSmartSecretKernelMoveResult = (
+  valueArg: unknown,
+):
+  | { kind: 'domainError'; domainError: ISmartSecretKernelDomainErrorResult }
+  | { kind: 'success'; status: TSmartSecretKernelMoveStatus } => {
+  const value = requireResultObject(valueArg);
+  const domainError = parseDomainError(value);
+  if (domainError) return { kind: 'domainError', domainError };
+  const result = requireExactObject(value, ['outcome', 'status'], false);
+  if (
+    result.outcome !== 'success'
+    || (
+      result.status !== 'moved'
+      && result.status !== 'alreadyMoved'
+      && result.status !== 'sourceAbsent'
+    )
+  ) {
+    throw createSmartSecretKernelStoreError('WORKER_INTEGRITY_FAILED');
+  }
+  return { kind: 'success', status: result.status };
+};
+
 export type TParsedSmartSecretKernelLegacyRead =
   | { kind: 'domainError'; domainError: ISmartSecretKernelDomainErrorResult }
   | { kind: 'success'; found: false }

package/ts/smartsecret.kernelstore.ts

@@ -17,6 +17,7 @@ import {
   parseSmartSecretKernelGetResult,
   parseSmartSecretKernelLegacyDeleteResult,
   parseSmartSecretKernelLegacyReadResult,
+  parseSmartSecretKernelMoveResult,
   parseSmartSecretKernelSetResult,
   smartSecretKernelDefaultTimeoutMs,
   smartSecretKernelLegacyService,
@@ -27,12 +28,14 @@ import {
   type ISmartSecretKernelOperationOptions,
   type ISmartSecretKernelStoreOptions,
   type TSmartSecretKernelCommands,
+  type TSmartSecretKernelMoveStatus,
 } from './smartsecret.kernel.protocol.js';
 import { isSupportedSmartSecretKernelRuntime } from './smartsecret.kernel.runtime.js';
 
 export type {
   ISmartSecretKernelOperationOptions,
   ISmartSecretKernelStoreOptions,
+  TSmartSecretKernelMoveStatus,
 } from './smartsecret.kernel.protocol.js';
 
 const legacyReceiptBrand = Symbol('SmartSecretDevIdpV1LegacyReceipt');
@@ -280,6 +283,38 @@ export class SmartSecretKernelStore {
     }));
   }
 
+  public moveEntry(
+    sourceAccountArg: string,
+    destinationAccountArg: string,
+    optionsArg?: ISmartSecretKernelOperationOptions,
+  ): Promise<TSmartSecretKernelMoveStatus> {
+    const sourceAccount = normalizeSmartSecretKernelAccount(sourceAccountArg);
+    const destinationAccount = normalizeSmartSecretKernelAccount(destinationAccountArg);
+    if (sourceAccount === destinationAccount) {
+      throw createSmartSecretKernelStoreError('INVALID_ARGUMENT');
+    }
+    const options = normalizeSmartSecretKernelOperationOptions(optionsArg);
+    const context = createOperationContext(options, true);
+    const sourceDescription = deriveSmartSecretKernelEntryDescription(this.service, sourceAccount);
+    const destinationDescription = deriveSmartSecretKernelEntryDescription(
+      this.service,
+      destinationAccount,
+    );
+    return this.reserveOperation(context, () => this.withKernelLease(context, async () => {
+      const parsed = await this.dispatchMutation(context, async (requestOptionsArg) =>
+        parseSmartSecretKernelMoveResult(await this.bridge.sendCommand(
+          'moveEntry',
+          { sourceDescription, destinationDescription },
+          requestOptionsArg,
+        ))
+      );
+      if (parsed.kind === 'domainError') {
+        return this.throwDomainError(parsed.domainError, context);
+      }
+      return parsed.status;
+    }));
+  }
+
   public readDevIdpV1Legacy(
     accountArg: string,
     optionsArg?: ISmartSecretKernelOperationOptions,
@@ -630,6 +665,9 @@ export class SmartSecretKernelStore {
     if (domainErrorArg.code === 'SOURCE_CHANGED') {
       throw createSmartSecretKernelStoreError('SOURCE_CHANGED');
     }
+    if (domainErrorArg.code === 'TARGET_CONFLICT') {
+      throw createSmartSecretKernelStoreError('TARGET_CONFLICT');
+    }
     if (
       domainErrorArg.code === 'MUTATION_OUTCOME_UNKNOWN'
       && contextArg.mutation

package/ts/smartsecret.sealedfile.error.ts

@@ -0,0 +1,72 @@
+export type TSmartSecretSealedFileStoreErrorCode =
+  | 'AUTHENTICATION_FAILED'
+  | 'ENVELOPE_INVALID'
+  | 'FILESYSTEM_FAILED'
+  | 'INVALID_ARGUMENT'
+  | 'KERNEL_UNAVAILABLE'
+  | 'MASTER_KEY_CONFLICT'
+  | 'MASTER_KEY_UNAVAILABLE'
+  | 'MUTATION_OUTCOME_UNKNOWN'
+  | 'MUTEX_FAILED'
+  | 'OPERATION_LIMIT_REACHED'
+  | 'SIZE_LIMIT_EXCEEDED'
+  | 'STORE_CLOSED';
+
+export interface ISmartSecretSealedFileStoreErrorJson {
+  name: 'SmartSecretSealedFileStoreError';
+  code: TSmartSecretSealedFileStoreErrorCode;
+  message: string;
+}
+
+const inspectSymbol = Symbol.for('nodejs.util.inspect.custom');
+const errorCodes = new Set<TSmartSecretSealedFileStoreErrorCode>([
+  'AUTHENTICATION_FAILED',
+  'ENVELOPE_INVALID',
+  'FILESYSTEM_FAILED',
+  'INVALID_ARGUMENT',
+  'KERNEL_UNAVAILABLE',
+  'MASTER_KEY_CONFLICT',
+  'MASTER_KEY_UNAVAILABLE',
+  'MUTATION_OUTCOME_UNKNOWN',
+  'MUTEX_FAILED',
+  'OPERATION_LIMIT_REACHED',
+  'SIZE_LIMIT_EXCEEDED',
+  'STORE_CLOSED',
+]);
+
+/** A code-only error that intentionally retains no secret values or causes. */
+export class SmartSecretSealedFileStoreError extends Error {
+  public readonly code: TSmartSecretSealedFileStoreErrorCode;
+  public readonly cause: undefined;
+
+  constructor(codeArg: TSmartSecretSealedFileStoreErrorCode) {
+    const code = errorCodes.has(codeArg) ? codeArg : 'INVALID_ARGUMENT';
+    const message = `SmartSecret sealed file store operation failed (${code}).`;
+    super(message);
+    this.name = 'SmartSecretSealedFileStoreError';
+    this.code = code;
+    this.stack = `${this.name}: ${message}`;
+    Object.defineProperty(this, 'cause', {
+      configurable: false,
+      enumerable: false,
+      value: undefined,
+      writable: false,
+    });
+  }
+
+  public toJSON(): ISmartSecretSealedFileStoreErrorJson {
+    return {
+      name: 'SmartSecretSealedFileStoreError',
+      code: this.code,
+      message: this.message,
+    };
+  }
+
+  public [inspectSymbol](): ISmartSecretSealedFileStoreErrorJson {
+    return this.toJSON();
+  }
+}
+
+export const createSmartSecretSealedFileStoreError = (
+  codeArg: TSmartSecretSealedFileStoreErrorCode,
+): SmartSecretSealedFileStoreError => new SmartSecretSealedFileStoreError(codeArg);