@rezwanul7/settings 1.0.0 → 1.1.0

package/README.md

@@ -307,15 +307,17 @@ again later. `reset()` deletes without a version check. `MemoryStore` keeps an O
 
 ## Secret settings
 
-The package doesn't encrypt anything. Keep a secret setting, such as an SMTP password, sealed with
-[`@rezwanul7/secret-vault`](../secret-vault/README.md): seal it before `set()`, store the Sealed value as a string,
-and open it after `get()`. Give the Context the Owner, so a Sealed value copied to another Owner doesn't open.
+Keep a secret setting, such as an SMTP password, sealed by wrapping your Store in `SealedStore` with a
+[`@rezwanul7/secret-vault`](../secret-vault/README.md) `Vault`. List the paths to seal; you call `set` and `get` with
+plain values, the schema validates the Plaintext, and the wrapped Store only ever holds a Sealed value there. This
+package doesn't depend on Secret Vault: `vault` only needs `encryptJson`, `decryptJson` and, optionally, `isSealed`
+(without it, a string starting with `vault:` counts as sealed, which is what a `Vault` writes).
 
 ```ts
 import {
   createSettings,
   defineSettings,
-  type Owner,
+  SealedStore,
 } from "@rezwanul7/settings";
 import { PrismaStore } from "@rezwanul7/settings/prisma";
 import { z } from "zod";
@@ -326,8 +328,7 @@ const organization = defineSettings({
   schema: z.object({
     smtp: z.object({
       host: z.string(),
-      // A Sealed value made by the Vault, never the password itself.
-      password: z.string().startsWith("vault:").nullable(),
+      password: z.string().min(1).nullable(),
     }),
   }),
   defaults: { smtp: { host: "localhost", password: null } },
@@ -335,30 +336,74 @@ const organization = defineSettings({
 
 const settings = createSettings({
   definitions: { organization },
-  store: new PrismaStore({ delegate: prisma.setting }),
+  store: new SealedStore({
+    store: new PrismaStore({ delegate: prisma.setting }),
+    vault,
+    paths: ["smtp.password"],
+  }),
 });
 
-function smtpPasswordContext(owner: Owner): string {
-  return `settings:smtp.password:${owner.scope}:${owner.id}`;
-}
+await settings.scope("organization", orgId).set("smtp.password", "hunter2");
+const password = await settings
+  .scope("organization", orgId)
+  .get("smtp.password"); // "hunter2"
+```
 
-export async function saveSmtpPassword(orgId: string, password: string) {
-  const org = settings.scope("organization", orgId);
-  const sealed = await vault.encrypt(password, smtpPasswordContext(org.owner));
-  await org.set("smtp.password", sealed);
-}
+- Each Sealed value is bound to its Owner and path (Context `settings:` plus `JSON.stringify([scope, id, path])`), so
+  one copied to another Owner or path doesn't open. A script that moves a Sealed setting must open it and seal it
+  again.
+- A path may name an object, which is sealed whole as JSON. No path may be inside another.
+- A Sealed value that doesn't open, such as after a wrong Vault secret, makes the read **throw**. It is never ignored
+  as a stale Override, because the next write would replace the secret with its default.
+- Every write seals again with the Vault's current secret, so a Rotation finishes for an Owner the next time it is
+  written.
+- Adding a path to `paths` on a deployment that already has plain values there is safe: they read as before and are
+  sealed on each Owner's next write. Values at unlisted paths are never opened.
+- The Effective settings now hold the **Plaintext**. Don't log them or pass them to the client; read the secret on the
+  server, only where it is used.
+- Switching from values you sealed by hand: their Context differs, so open each with your old Context once and write
+  the Plaintext back through the settings with a script; `SealedStore` then seals it under its own Context.
+
+## Caching reads
+
+`CachedStore` keeps what the Store it wraps returns for `ttl` seconds, so reading one Owner's settings in several
+requests doesn't query the database each time. An Owner with nothing stored is cached too. Every write, conflict and
+delete evicts the Owner, so a write on this instance is read back at once and two concurrent writes both take effect.
 
-export async function readSmtpPassword(orgId: string): Promise<string | null> {
-  const org = settings.scope("organization", orgId);
-  const sealed = await org.get("smtp.password");
-  return sealed === null
-    ? null
-    : vault.decrypt(sealed, smtpPasswordContext(org.owner));
-}
+```ts
+import { CachedStore, MemoryCache, SealedStore } from "@rezwanul7/settings";
+
+const store = new SealedStore({
+  store: new CachedStore({
+    store: new PrismaStore({ delegate: prisma.setting }),
+    cache: new MemoryCache({ maxEntries: 5000 }),
+    ttl: 60,
+  }),
+  vault,
+  paths: ["smtp.password"],
+});
 ```
 
-The Effective settings then hold only the Sealed value, so they can be logged or passed around without exposing the
-secret; open it on the server, only where it is used.
+Nest `SealedStore` outermost so the cache only holds Sealed values. A cache that throws is passed to the optional
+`onError` and the Store answers instead; a failing `delete` leaves the entry to expire with its TTL.
+
+`MemoryCache` is per process. With several instances, another instance can serve Overrides up to `ttl` seconds old
+after a write elsewhere. Share a cache to avoid that; any object with three string methods fits `SettingsCache`:
+
+```ts
+import type { SettingsCache } from "@rezwanul7/settings";
+import { redis } from "./redis";
+
+const redisCache: SettingsCache = {
+  get: async (key) => (await redis.get(key)) ?? undefined,
+  set: async (key, value, ttlSeconds) => {
+    await redis.set(key, value, "EX", Math.ceil(ttlSeconds));
+  },
+  delete: async (key) => {
+    await redis.del(key);
+  },
+};
+```
 
 ## Errors
 

package/dist/index.cjs

@@ -469,7 +469,193 @@ function asJson(overrides) {
   return JSON.parse(JSON.stringify(overrides));
 }
 
+// src/sealed-store.ts
+function defaultIsSealed(value) {
+  return typeof value === "string" && value.startsWith("vault:");
+}
+function contextOf(owner, path) {
+  return `settings:${JSON.stringify([owner.scope, owner.id, path])}`;
+}
+var SealedStore = class {
+  #store;
+  #vault;
+  #paths;
+  /**
+   * @param options - The Store to wrap, the Vault and the sealed paths.
+   * @throws `TypeError` when a path is empty or inside another path.
+   */
+  constructor(options) {
+    this.#store = options.store;
+    this.#vault = options.vault;
+    this.#paths = [...new Set(options.paths)];
+    for (const path of this.#paths) {
+      if (path === "") throw new TypeError("SealedStore: a path is empty.");
+      const inner = this.#paths.find((p) => p.startsWith(`${path}.`));
+      if (inner !== void 0) {
+        throw new TypeError(
+          `SealedStore: path "${inner}" is inside path "${path}".`
+        );
+      }
+    }
+  }
+  /** {@inheritDoc SettingsStore.read} */
+  async read(owner) {
+    const stored = await this.#store.read(owner);
+    if (stored === null) return null;
+    const isSealed = this.#vault.isSealed?.bind(this.#vault) ?? defaultIsSealed;
+    let overrides = stored.overrides;
+    for (const path of this.#paths) {
+      const value = getAt(overrides, path);
+      if (!isSealed(value)) continue;
+      const plaintext = await this.#vault.decryptJson(
+        value,
+        contextOf(owner, path)
+      );
+      overrides = setAt(overrides, path, plaintext);
+    }
+    return { overrides, version: stored.version };
+  }
+  /** {@inheritDoc SettingsStore.write} */
+  async write(owner, overrides, expectedVersion) {
+    let sealed = overrides;
+    for (const path of this.#paths) {
+      if (!hasAt(sealed, path)) continue;
+      const value = getAt(sealed, path);
+      if (value === void 0) continue;
+      sealed = setAt(
+        sealed,
+        path,
+        await this.#vault.encryptJson(value, contextOf(owner, path))
+      );
+    }
+    return this.#store.write(owner, sealed, expectedVersion);
+  }
+  /** {@inheritDoc SettingsStore.delete} */
+  async delete(owner) {
+    await this.#store.delete(owner);
+  }
+};
+
+// src/cached-store.ts
+var CachedStore = class {
+  #store;
+  #cache;
+  #ttl;
+  #prefix;
+  #onError;
+  /**
+   * @param options - The Store to wrap, the cache and the TTL.
+   * @throws `RangeError` when `ttl` isn't a positive number.
+   */
+  constructor(options) {
+    if (!(options.ttl > 0) || !Number.isFinite(options.ttl)) {
+      throw new RangeError("CachedStore: ttl must be a positive number.");
+    }
+    this.#store = options.store;
+    this.#cache = options.cache;
+    this.#ttl = options.ttl;
+    this.#prefix = options.prefix ?? "settings";
+    this.#onError = options.onError;
+  }
+  /** {@inheritDoc SettingsStore.read} */
+  async read(owner) {
+    const key2 = this.#key(owner);
+    try {
+      const cached = await this.#cache.get(key2);
+      if (cached !== void 0) {
+        return JSON.parse(cached);
+      }
+    } catch (error) {
+      this.#report(error);
+    }
+    const stored = await this.#store.read(owner);
+    try {
+      await this.#cache.set(key2, JSON.stringify(stored), this.#ttl);
+    } catch (error) {
+      this.#report(error);
+    }
+    return stored;
+  }
+  /** {@inheritDoc SettingsStore.write} */
+  async write(owner, overrides, expectedVersion) {
+    try {
+      return await this.#store.write(owner, overrides, expectedVersion);
+    } finally {
+      await this.#evict(owner);
+    }
+  }
+  /** {@inheritDoc SettingsStore.delete} */
+  async delete(owner) {
+    try {
+      await this.#store.delete(owner);
+    } finally {
+      await this.#evict(owner);
+    }
+  }
+  async #evict(owner) {
+    try {
+      await this.#cache.delete(this.#key(owner));
+    } catch (error) {
+      this.#report(error);
+    }
+  }
+  #key(owner) {
+    return `${this.#prefix}:${JSON.stringify([owner.scope, owner.id])}`;
+  }
+  #report(error) {
+    this.#onError?.(error);
+  }
+};
+
+// src/memory-cache.ts
+var MemoryCache = class {
+  #entries = /* @__PURE__ */ new Map();
+  #maxEntries;
+  /**
+   * @param options - The size limit.
+   * @throws `RangeError` when `maxEntries` isn't a positive integer.
+   */
+  constructor(options = {}) {
+    const { maxEntries = 1e3 } = options;
+    if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+      throw new RangeError(
+        "MemoryCache: maxEntries must be a positive integer."
+      );
+    }
+    this.#maxEntries = maxEntries;
+  }
+  /** {@inheritDoc SettingsCache.get} */
+  async get(key2) {
+    const entry = this.#entries.get(key2);
+    if (entry === void 0) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      this.#entries.delete(key2);
+      return void 0;
+    }
+    return entry.value;
+  }
+  /** {@inheritDoc SettingsCache.set} */
+  async set(key2, value, ttlSeconds) {
+    this.#entries.delete(key2);
+    this.#entries.set(key2, {
+      value,
+      expiresAt: Date.now() + ttlSeconds * 1e3
+    });
+    while (this.#entries.size > this.#maxEntries) {
+      const oldest = this.#entries.keys().next().value;
+      this.#entries.delete(oldest);
+    }
+  }
+  /** {@inheritDoc SettingsCache.delete} */
+  async delete(key2) {
+    this.#entries.delete(key2);
+  }
+};
+
+exports.CachedStore = CachedStore;
+exports.MemoryCache = MemoryCache;
 exports.MemoryStore = MemoryStore;
+exports.SealedStore = SealedStore;
 exports.SettingsConflictError = SettingsConflictError;
 exports.SettingsDefinitionError = SettingsDefinitionError;
 exports.SettingsValidationError = SettingsValidationError;

package/dist/index.d.cts

@@ -314,6 +314,175 @@ declare class MemoryStore implements SettingsStore {
     delete(owner: Owner): Promise<void>;
 }
 
+/**
+ * The part of a Secret Vault `Vault` that {@link SealedStore} uses, so this package doesn't depend on Secret Vault.
+ * A `Vault` fits.
+ */
+interface SealingVault {
+    /**
+     * Seals a JSON value.
+     *
+     * @param value - The value to seal.
+     * @param context - Where the Sealed value is stored.
+     * @returns The Sealed value.
+     */
+    encryptJson(value: unknown, context: string): Promise<string>;
+    /**
+     * Opens a Sealed value made by `encryptJson`; rejects when it doesn't open.
+     *
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under.
+     * @returns The Plaintext value.
+     */
+    decryptJson(sealed: string, context: string): Promise<unknown>;
+    /**
+     * Whether a stored value is a Sealed value rather than plain text still stored at a listed path. Optional: a Secret
+     * Vault `Vault` has `isSealed` only as a static method, so without it `SealedStore` treats a string starting with
+     * `vault:` as sealed.
+     *
+     * @param value - A stored value.
+     */
+    isSealed?(value: unknown): boolean;
+}
+/** Options of {@link SealedStore}. */
+interface SealedStoreOptions {
+    /** The Store that keeps the Sealed values. */
+    readonly store: SettingsStore;
+    /** Seals and opens values; a Secret Vault `Vault` fits. */
+    readonly vault: SealingVault;
+    /**
+     * Dot paths into the settings to keep sealed, such as `"smtp.password"`. A path may name an object, which is sealed
+     * whole as JSON. No path may be inside another.
+     */
+    readonly paths: readonly string[];
+}
+/**
+ * A Store that keeps the Overrides at the listed paths as Sealed values in the Store it wraps, and hands the core
+ * their Plaintext. The schema validates the Plaintext, and the app calls `set` and `get` with plain values.
+ *
+ * Every write seals again with the Vault's current secret, which finishes a Rotation for that Owner. A Sealed value
+ * that doesn't open makes the read throw: it is never ignored as a stale Override, because the next write would
+ * replace the secret with its default. A plain value at a listed path reads as it is and is sealed on the Owner's next
+ * write. Values at unlisted paths are never opened.
+ *
+ * Nest it outermost, around a {@link CachedStore}, so the cache holds only Sealed values.
+ *
+ * @example
+ * const store = new SealedStore({
+ *   store: new PrismaStore({ delegate: prisma.setting }),
+ *   vault,
+ *   paths: ["smtp.password"],
+ * });
+ */
+declare class SealedStore implements SettingsStore {
+    #private;
+    /**
+     * @param options - The Store to wrap, the Vault and the sealed paths.
+     * @throws `TypeError` when a path is empty or inside another path.
+     */
+    constructor(options: SealedStoreOptions);
+    /** {@inheritDoc SettingsStore.read} */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /** {@inheritDoc SettingsStore.write} */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /** {@inheritDoc SettingsStore.delete} */
+    delete(owner: Owner): Promise<void>;
+}
+
+/**
+ * A cache of strings with a time to live, which {@link CachedStore} keeps Overrides in. {@link MemoryCache} fits;
+ * so does a thin wrapper around Redis or Keyv.
+ */
+interface SettingsCache {
+    /**
+     * Reads an entry.
+     *
+     * @param key - The cache key.
+     * @returns The value, or `undefined` when there is none or it expired.
+     */
+    get(key: string): Promise<string | undefined>;
+    /**
+     * Stores an entry, replacing any under the key.
+     *
+     * @param key - The cache key.
+     * @param value - The string to keep.
+     * @param ttlSeconds - Seconds until the entry expires.
+     */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Removes an entry; removing a missing one does nothing.
+     *
+     * @param key - The cache key.
+     */
+    delete(key: string): Promise<void>;
+}
+/** Options of {@link CachedStore}. */
+interface CachedStoreOptions {
+    /** The Store to read through. */
+    readonly store: SettingsStore;
+    /** Where to keep what the Store returns. */
+    readonly cache: SettingsCache;
+    /** Seconds an entry stays cached. */
+    readonly ttl: number;
+    /** Starts every cache key. Defaults to `"settings"`. */
+    readonly prefix?: string;
+    /** Called with an error a cache method threw; the Store then answers instead. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * A Store that keeps what the Store it wraps returns in a cache for `ttl` seconds, an Owner with nothing stored
+ * included. Every write, conflict and delete evicts the Owner, so a write on this instance is read back at once and a
+ * conflicting write retries against fresh Overrides. A cache that throws is reported to `onError` and the Store
+ * answers instead.
+ *
+ * With a per-process cache and several instances, another instance can read Overrides up to `ttl` seconds old. Share
+ * a cache, such as Redis, to avoid it.
+ *
+ * @example
+ * const store = new CachedStore({ store: prismaStore, cache: new MemoryCache(), ttl: 60 });
+ */
+declare class CachedStore implements SettingsStore {
+    #private;
+    /**
+     * @param options - The Store to wrap, the cache and the TTL.
+     * @throws `RangeError` when `ttl` isn't a positive number.
+     */
+    constructor(options: CachedStoreOptions);
+    /** {@inheritDoc SettingsStore.read} */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /** {@inheritDoc SettingsStore.write} */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /** {@inheritDoc SettingsStore.delete} */
+    delete(owner: Owner): Promise<void>;
+}
+
+/** Options of {@link MemoryCache}. */
+interface MemoryCacheOptions {
+    /** Most entries kept; the oldest are evicted past it. Defaults to 1000. */
+    readonly maxEntries?: number;
+}
+/**
+ * A {@link SettingsCache} in process memory. Entries expire after their TTL and the oldest are evicted past
+ * `maxEntries`. It is per process: instances don't share it.
+ *
+ * @example
+ * const cache = new MemoryCache({ maxEntries: 5000 });
+ */
+declare class MemoryCache implements SettingsCache {
+    #private;
+    /**
+     * @param options - The size limit.
+     * @throws `RangeError` when `maxEntries` isn't a positive integer.
+     */
+    constructor(options?: MemoryCacheOptions);
+    /** {@inheritDoc SettingsCache.get} */
+    get(key: string): Promise<string | undefined>;
+    /** {@inheritDoc SettingsCache.set} */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /** {@inheritDoc SettingsCache.delete} */
+    delete(key: string): Promise<void>;
+}
+
 /**
  * A write would make an Owner's Effective settings fail its Scope's schema, so nothing was stored. `issues` are the
  * Standard Schema issues, with paths into the Effective settings, for showing next to a form field.
@@ -358,4 +527,4 @@ declare class SettingsDefinitionError extends Error {
     constructor(message: string, scope: string, issues?: ReadonlyArray<StandardSchemaV1.Issue>);
 }
 
-export { MemoryStore, Owner, type Path, type PathValue, type ScopedSettings, SettingsConflictError, type SettingsDefinition, SettingsDefinitionError, type SettingsOptions, SettingsStore, SettingsValidationError, StoredOverrides, createSettings, defineSettings };
+export { CachedStore, type CachedStoreOptions, MemoryCache, type MemoryCacheOptions, MemoryStore, Owner, type Path, type PathValue, type ScopedSettings, SealedStore, type SealedStoreOptions, type SealingVault, type SettingsCache, SettingsConflictError, type SettingsDefinition, SettingsDefinitionError, type SettingsOptions, SettingsStore, SettingsValidationError, StoredOverrides, createSettings, defineSettings };

package/dist/index.d.ts

@@ -314,6 +314,175 @@ declare class MemoryStore implements SettingsStore {
     delete(owner: Owner): Promise<void>;
 }
 
+/**
+ * The part of a Secret Vault `Vault` that {@link SealedStore} uses, so this package doesn't depend on Secret Vault.
+ * A `Vault` fits.
+ */
+interface SealingVault {
+    /**
+     * Seals a JSON value.
+     *
+     * @param value - The value to seal.
+     * @param context - Where the Sealed value is stored.
+     * @returns The Sealed value.
+     */
+    encryptJson(value: unknown, context: string): Promise<string>;
+    /**
+     * Opens a Sealed value made by `encryptJson`; rejects when it doesn't open.
+     *
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under.
+     * @returns The Plaintext value.
+     */
+    decryptJson(sealed: string, context: string): Promise<unknown>;
+    /**
+     * Whether a stored value is a Sealed value rather than plain text still stored at a listed path. Optional: a Secret
+     * Vault `Vault` has `isSealed` only as a static method, so without it `SealedStore` treats a string starting with
+     * `vault:` as sealed.
+     *
+     * @param value - A stored value.
+     */
+    isSealed?(value: unknown): boolean;
+}
+/** Options of {@link SealedStore}. */
+interface SealedStoreOptions {
+    /** The Store that keeps the Sealed values. */
+    readonly store: SettingsStore;
+    /** Seals and opens values; a Secret Vault `Vault` fits. */
+    readonly vault: SealingVault;
+    /**
+     * Dot paths into the settings to keep sealed, such as `"smtp.password"`. A path may name an object, which is sealed
+     * whole as JSON. No path may be inside another.
+     */
+    readonly paths: readonly string[];
+}
+/**
+ * A Store that keeps the Overrides at the listed paths as Sealed values in the Store it wraps, and hands the core
+ * their Plaintext. The schema validates the Plaintext, and the app calls `set` and `get` with plain values.
+ *
+ * Every write seals again with the Vault's current secret, which finishes a Rotation for that Owner. A Sealed value
+ * that doesn't open makes the read throw: it is never ignored as a stale Override, because the next write would
+ * replace the secret with its default. A plain value at a listed path reads as it is and is sealed on the Owner's next
+ * write. Values at unlisted paths are never opened.
+ *
+ * Nest it outermost, around a {@link CachedStore}, so the cache holds only Sealed values.
+ *
+ * @example
+ * const store = new SealedStore({
+ *   store: new PrismaStore({ delegate: prisma.setting }),
+ *   vault,
+ *   paths: ["smtp.password"],
+ * });
+ */
+declare class SealedStore implements SettingsStore {
+    #private;
+    /**
+     * @param options - The Store to wrap, the Vault and the sealed paths.
+     * @throws `TypeError` when a path is empty or inside another path.
+     */
+    constructor(options: SealedStoreOptions);
+    /** {@inheritDoc SettingsStore.read} */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /** {@inheritDoc SettingsStore.write} */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /** {@inheritDoc SettingsStore.delete} */
+    delete(owner: Owner): Promise<void>;
+}
+
+/**
+ * A cache of strings with a time to live, which {@link CachedStore} keeps Overrides in. {@link MemoryCache} fits;
+ * so does a thin wrapper around Redis or Keyv.
+ */
+interface SettingsCache {
+    /**
+     * Reads an entry.
+     *
+     * @param key - The cache key.
+     * @returns The value, or `undefined` when there is none or it expired.
+     */
+    get(key: string): Promise<string | undefined>;
+    /**
+     * Stores an entry, replacing any under the key.
+     *
+     * @param key - The cache key.
+     * @param value - The string to keep.
+     * @param ttlSeconds - Seconds until the entry expires.
+     */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Removes an entry; removing a missing one does nothing.
+     *
+     * @param key - The cache key.
+     */
+    delete(key: string): Promise<void>;
+}
+/** Options of {@link CachedStore}. */
+interface CachedStoreOptions {
+    /** The Store to read through. */
+    readonly store: SettingsStore;
+    /** Where to keep what the Store returns. */
+    readonly cache: SettingsCache;
+    /** Seconds an entry stays cached. */
+    readonly ttl: number;
+    /** Starts every cache key. Defaults to `"settings"`. */
+    readonly prefix?: string;
+    /** Called with an error a cache method threw; the Store then answers instead. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * A Store that keeps what the Store it wraps returns in a cache for `ttl` seconds, an Owner with nothing stored
+ * included. Every write, conflict and delete evicts the Owner, so a write on this instance is read back at once and a
+ * conflicting write retries against fresh Overrides. A cache that throws is reported to `onError` and the Store
+ * answers instead.
+ *
+ * With a per-process cache and several instances, another instance can read Overrides up to `ttl` seconds old. Share
+ * a cache, such as Redis, to avoid it.
+ *
+ * @example
+ * const store = new CachedStore({ store: prismaStore, cache: new MemoryCache(), ttl: 60 });
+ */
+declare class CachedStore implements SettingsStore {
+    #private;
+    /**
+     * @param options - The Store to wrap, the cache and the TTL.
+     * @throws `RangeError` when `ttl` isn't a positive number.
+     */
+    constructor(options: CachedStoreOptions);
+    /** {@inheritDoc SettingsStore.read} */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /** {@inheritDoc SettingsStore.write} */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /** {@inheritDoc SettingsStore.delete} */
+    delete(owner: Owner): Promise<void>;
+}
+
+/** Options of {@link MemoryCache}. */
+interface MemoryCacheOptions {
+    /** Most entries kept; the oldest are evicted past it. Defaults to 1000. */
+    readonly maxEntries?: number;
+}
+/**
+ * A {@link SettingsCache} in process memory. Entries expire after their TTL and the oldest are evicted past
+ * `maxEntries`. It is per process: instances don't share it.
+ *
+ * @example
+ * const cache = new MemoryCache({ maxEntries: 5000 });
+ */
+declare class MemoryCache implements SettingsCache {
+    #private;
+    /**
+     * @param options - The size limit.
+     * @throws `RangeError` when `maxEntries` isn't a positive integer.
+     */
+    constructor(options?: MemoryCacheOptions);
+    /** {@inheritDoc SettingsCache.get} */
+    get(key: string): Promise<string | undefined>;
+    /** {@inheritDoc SettingsCache.set} */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /** {@inheritDoc SettingsCache.delete} */
+    delete(key: string): Promise<void>;
+}
+
 /**
  * A write would make an Owner's Effective settings fail its Scope's schema, so nothing was stored. `issues` are the
  * Standard Schema issues, with paths into the Effective settings, for showing next to a form field.
@@ -358,4 +527,4 @@ declare class SettingsDefinitionError extends Error {
     constructor(message: string, scope: string, issues?: ReadonlyArray<StandardSchemaV1.Issue>);
 }
 
-export { MemoryStore, Owner, type Path, type PathValue, type ScopedSettings, SettingsConflictError, type SettingsDefinition, SettingsDefinitionError, type SettingsOptions, SettingsStore, SettingsValidationError, StoredOverrides, createSettings, defineSettings };
+export { CachedStore, type CachedStoreOptions, MemoryCache, type MemoryCacheOptions, MemoryStore, Owner, type Path, type PathValue, type ScopedSettings, SealedStore, type SealedStoreOptions, type SealingVault, type SettingsCache, SettingsConflictError, type SettingsDefinition, SettingsDefinitionError, type SettingsOptions, SettingsStore, SettingsValidationError, StoredOverrides, createSettings, defineSettings };

package/dist/index.js

@@ -467,4 +467,187 @@ function asJson(overrides) {
   return JSON.parse(JSON.stringify(overrides));
 }
 
-export { MemoryStore, SettingsConflictError, SettingsDefinitionError, SettingsValidationError, createSettings, defineSettings };
+// src/sealed-store.ts
+function defaultIsSealed(value) {
+  return typeof value === "string" && value.startsWith("vault:");
+}
+function contextOf(owner, path) {
+  return `settings:${JSON.stringify([owner.scope, owner.id, path])}`;
+}
+var SealedStore = class {
+  #store;
+  #vault;
+  #paths;
+  /**
+   * @param options - The Store to wrap, the Vault and the sealed paths.
+   * @throws `TypeError` when a path is empty or inside another path.
+   */
+  constructor(options) {
+    this.#store = options.store;
+    this.#vault = options.vault;
+    this.#paths = [...new Set(options.paths)];
+    for (const path of this.#paths) {
+      if (path === "") throw new TypeError("SealedStore: a path is empty.");
+      const inner = this.#paths.find((p) => p.startsWith(`${path}.`));
+      if (inner !== void 0) {
+        throw new TypeError(
+          `SealedStore: path "${inner}" is inside path "${path}".`
+        );
+      }
+    }
+  }
+  /** {@inheritDoc SettingsStore.read} */
+  async read(owner) {
+    const stored = await this.#store.read(owner);
+    if (stored === null) return null;
+    const isSealed = this.#vault.isSealed?.bind(this.#vault) ?? defaultIsSealed;
+    let overrides = stored.overrides;
+    for (const path of this.#paths) {
+      const value = getAt(overrides, path);
+      if (!isSealed(value)) continue;
+      const plaintext = await this.#vault.decryptJson(
+        value,
+        contextOf(owner, path)
+      );
+      overrides = setAt(overrides, path, plaintext);
+    }
+    return { overrides, version: stored.version };
+  }
+  /** {@inheritDoc SettingsStore.write} */
+  async write(owner, overrides, expectedVersion) {
+    let sealed = overrides;
+    for (const path of this.#paths) {
+      if (!hasAt(sealed, path)) continue;
+      const value = getAt(sealed, path);
+      if (value === void 0) continue;
+      sealed = setAt(
+        sealed,
+        path,
+        await this.#vault.encryptJson(value, contextOf(owner, path))
+      );
+    }
+    return this.#store.write(owner, sealed, expectedVersion);
+  }
+  /** {@inheritDoc SettingsStore.delete} */
+  async delete(owner) {
+    await this.#store.delete(owner);
+  }
+};
+
+// src/cached-store.ts
+var CachedStore = class {
+  #store;
+  #cache;
+  #ttl;
+  #prefix;
+  #onError;
+  /**
+   * @param options - The Store to wrap, the cache and the TTL.
+   * @throws `RangeError` when `ttl` isn't a positive number.
+   */
+  constructor(options) {
+    if (!(options.ttl > 0) || !Number.isFinite(options.ttl)) {
+      throw new RangeError("CachedStore: ttl must be a positive number.");
+    }
+    this.#store = options.store;
+    this.#cache = options.cache;
+    this.#ttl = options.ttl;
+    this.#prefix = options.prefix ?? "settings";
+    this.#onError = options.onError;
+  }
+  /** {@inheritDoc SettingsStore.read} */
+  async read(owner) {
+    const key2 = this.#key(owner);
+    try {
+      const cached = await this.#cache.get(key2);
+      if (cached !== void 0) {
+        return JSON.parse(cached);
+      }
+    } catch (error) {
+      this.#report(error);
+    }
+    const stored = await this.#store.read(owner);
+    try {
+      await this.#cache.set(key2, JSON.stringify(stored), this.#ttl);
+    } catch (error) {
+      this.#report(error);
+    }
+    return stored;
+  }
+  /** {@inheritDoc SettingsStore.write} */
+  async write(owner, overrides, expectedVersion) {
+    try {
+      return await this.#store.write(owner, overrides, expectedVersion);
+    } finally {
+      await this.#evict(owner);
+    }
+  }
+  /** {@inheritDoc SettingsStore.delete} */
+  async delete(owner) {
+    try {
+      await this.#store.delete(owner);
+    } finally {
+      await this.#evict(owner);
+    }
+  }
+  async #evict(owner) {
+    try {
+      await this.#cache.delete(this.#key(owner));
+    } catch (error) {
+      this.#report(error);
+    }
+  }
+  #key(owner) {
+    return `${this.#prefix}:${JSON.stringify([owner.scope, owner.id])}`;
+  }
+  #report(error) {
+    this.#onError?.(error);
+  }
+};
+
+// src/memory-cache.ts
+var MemoryCache = class {
+  #entries = /* @__PURE__ */ new Map();
+  #maxEntries;
+  /**
+   * @param options - The size limit.
+   * @throws `RangeError` when `maxEntries` isn't a positive integer.
+   */
+  constructor(options = {}) {
+    const { maxEntries = 1e3 } = options;
+    if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+      throw new RangeError(
+        "MemoryCache: maxEntries must be a positive integer."
+      );
+    }
+    this.#maxEntries = maxEntries;
+  }
+  /** {@inheritDoc SettingsCache.get} */
+  async get(key2) {
+    const entry = this.#entries.get(key2);
+    if (entry === void 0) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      this.#entries.delete(key2);
+      return void 0;
+    }
+    return entry.value;
+  }
+  /** {@inheritDoc SettingsCache.set} */
+  async set(key2, value, ttlSeconds) {
+    this.#entries.delete(key2);
+    this.#entries.set(key2, {
+      value,
+      expiresAt: Date.now() + ttlSeconds * 1e3
+    });
+    while (this.#entries.size > this.#maxEntries) {
+      const oldest = this.#entries.keys().next().value;
+      this.#entries.delete(oldest);
+    }
+  }
+  /** {@inheritDoc SettingsCache.delete} */
+  async delete(key2) {
+    this.#entries.delete(key2);
+  }
+};
+
+export { CachedStore, MemoryCache, MemoryStore, SealedStore, SettingsConflictError, SettingsDefinitionError, SettingsValidationError, createSettings, defineSettings };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rezwanul7/settings",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -45,6 +45,7 @@
   },
   "devDependencies": {
     "@repo/eslint-config": "0.0.0",
+    "@rezwanul7/secret-vault": "0.1.0",
     "@repo/typescript-config": "0.0.0",
     "@types/node": "^22.15.3",
     "@vitest/coverage-v8": "4.0.18",