@push.rocks/smartsecret 1.3.0 → 1.5.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@push.rocks/smartsecret",
-  "version": "1.3.0",
+  "version": "1.5.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

@@ -22,9 +22,20 @@
 - Additive strict API; legacy SmartSecret backend selection remains unchanged
 - Requires Node.js 24 or 25, Linux x64, Linux keyutils, and the exact package-owned static Rust worker
 - No shell, PATH lookup, environment override, Secret Service, or filesystem secret fallback
-- Generic values are framed and limited to 0..1024 bytes; service/account names are valid scalar UTF-8 strings of 1..1024 bytes
+- 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
 - 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
+- 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
 
@@ -193,7 +193,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 1,024 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.
+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.
 
@@ -205,6 +205,43 @@ 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.
+
+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}`:
@@ -288,6 +325,56 @@ SmartSecretKernelStore.create(
 
 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.
 
+### `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;
+}
+```
+
+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 |
+| `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
 
 ```typescript
@@ -351,7 +438,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.3.0',
-  description: 'OS-backed secret storage plus strict Linux kernel-keyring and envelope APIs for Node.js.'
+  version: '1.5.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.protocol.ts

@@ -6,9 +6,9 @@ import {
 
 export const smartSecretKernelDefaultTimeoutMs = 5_000;
 export const smartSecretKernelMaximumTimeoutMs = 60_000;
-export const smartSecretKernelMaximumEntryBytes = 1_024;
+export const smartSecretKernelMaximumEntryBytes = 16 * 1_024;
 export const smartSecretKernelMaximumLegacyBytes = 16 * 1_024;
-export const smartSecretKernelMaximumMessageBytes = 32 * 1_024;
+export const smartSecretKernelMaximumMessageBytes = 32_767;
 export const smartSecretKernelLegacyService = 'global.idp.devidp';
 
 const serviceDomain = Buffer.from(

package/ts/smartsecret.kernelstore.ts

@@ -381,7 +381,7 @@ export class SmartSecretKernelStore {
     if (this.closePromise) return this.closePromise;
     this.lifecycleState = 'closing';
     const operationTail = this.operationTail;
-    this.closePromise = (async (): Promise<void> => {
+    const closePromise = (async (): Promise<void> => {
       await operationTail;
       const terminated = await this.terminateBridgeConfirmed();
       this.lifecycleState = 'closed';
@@ -390,7 +390,11 @@ export class SmartSecretKernelStore {
         throw createSmartSecretKernelStoreError('WORKER_INTEGRITY_FAILED');
       }
     })();
-    return this.closePromise;
+    this.closePromise = closePromise;
+    void closePromise.catch(() => {
+      if (this.closePromise === closePromise) this.closePromise = undefined;
+    });
+    return closePromise;
   }
 
   private assertCanReserve(): void {
@@ -643,14 +647,19 @@ export class SmartSecretKernelStore {
     try {
       termination = this.bridge.terminate({ gracePeriodMs: 0 });
     } catch {
-      this.terminationPromise = Promise.resolve(false);
-      return this.terminationPromise;
+      return Promise.resolve(false);
     }
-    this.terminationPromise = termination.then(
+    const terminationAttempt = termination.then(
       () => true,
       () => false,
     );
-    return this.terminationPromise;
+    this.terminationPromise = terminationAttempt;
+    void terminationAttempt.then(() => {
+      if (this.terminationPromise === terminationAttempt) {
+        this.terminationPromise = undefined;
+      }
+    });
+    return terminationAttempt;
   }
 
   private async poisonAndTerminate(): Promise<void> {

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);