@push.rocks/smartsecret 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartsecret",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "private": false,
   "description": "OS-backed secret storage plus strict Linux kernel-keyring, sealed-file, and envelope APIs for Node.js.",
   "main": "dist_ts/index.js",

package/readme.hints.md

@@ -24,6 +24,7 @@
 - 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
@@ -36,6 +37,11 @@
 - 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

@@ -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.
 
@@ -240,6 +240,10 @@ The directory is required to be owned by the effective user and mode `0700`; env
 
 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
@@ -319,11 +323,12 @@ 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`
 
@@ -360,6 +365,22 @@ interface ISmartSecretSealedFileStoreOptions {
   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`.
@@ -367,6 +388,7 @@ Instances expose readonly `service`, `storeId`, and `directoryPath` properties.
 | 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 |

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartsecret',
-  version: '1.5.0',
+  version: '1.6.0',
   description: 'OS-backed secret storage plus strict Linux kernel-keyring, sealed-file, and envelope APIs for Node.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