@anchor-secrets/sdk 0.0.0-stage → 0.4.0

package/dist/index.js

@@ -0,0 +1,526 @@
+// src/cache.ts
+import { createHash } from "node:crypto";
+
+// src/errors.ts
+var AnchorError = class extends Error {
+  status;
+  code;
+  /** Whether repeating the request may succeed (network, timeout, 429, 502, 503, 504). */
+  retryable;
+  /** The server's `Retry-After`, in milliseconds, when it sent one. */
+  retryAfterMs;
+  constructor(status, code, message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "AnchorError";
+    this.status = status;
+    this.code = code;
+    this.retryable = options.retryable ?? false;
+    if (options.retryAfterMs !== void 0) this.retryAfterMs = options.retryAfterMs;
+  }
+};
+var abortedError = () => new AnchorError(0, "aborted", "The request to Anchor was cancelled");
+
+// src/cache.ts
+function memoryStore() {
+  const entries = /* @__PURE__ */ new Map();
+  return {
+    get: (key) => entries.get(key),
+    set: (key, entry) => {
+      entries.set(key, entry);
+    }
+  };
+}
+function cacheKey(origin, token, q) {
+  const fingerprint = createHash("sha256").update(token).digest("hex").slice(0, 16);
+  return JSON.stringify([
+    origin,
+    fingerprint,
+    q.project,
+    q.environment,
+    q.path,
+    q.expand,
+    q.includeImports
+  ]);
+}
+function untilAborted(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(abortedError());
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortedError());
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+  });
+}
+var SecretCache = class {
+  constructor(policy, emit, now = () => Date.now()) {
+    this.policy = policy;
+    this.emit = emit;
+    this.now = now;
+  }
+  policy;
+  emit;
+  now;
+  inflight = /* @__PURE__ */ new Map();
+  /** When the last fetch of a key failed; the stale entry is served without asking for one ttl. */
+  failedAt = /* @__PURE__ */ new Map();
+  /**
+   * The folder's entry. With `strict`, a failed fetch rejects instead of falling back, so a
+   * caller that asked for new values learns it did not get them.
+   */
+  async load(key, fetch, opts = {}) {
+    if (opts.signal?.aborted) throw abortedError();
+    const entry = await this.read(key);
+    if (entry && !opts.fresh && this.servable(key, entry)) return entry;
+    const flight = this.inflight.get(key) ?? this.start(key, fetch, entry);
+    flight.waiters++;
+    let outcome;
+    try {
+      outcome = await untilAborted(flight.promise, opts.signal);
+    } catch (error) {
+      if (opts.signal?.aborted && --flight.waiters === 0) {
+        flight.controller.abort();
+        if (this.inflight.get(key) === flight) this.inflight.delete(key);
+      }
+      throw error;
+    }
+    if (opts.strict && outcome.error) throw outcome.error;
+    return outcome.entry;
+  }
+  start(key, fetch, stale) {
+    const controller = new AbortController();
+    const promise = this.fetch(
+      key,
+      () => fetch(controller.signal),
+      stale,
+      controller.signal
+    ).finally(() => {
+      if (this.inflight.get(key)?.promise === promise) this.inflight.delete(key);
+    });
+    const flight = { promise, controller, waiters: 0 };
+    this.inflight.set(key, flight);
+    return flight;
+  }
+  /** A store that fails is a miss: Anchor stays reachable when Redis (or a file) is not. */
+  async read(key) {
+    try {
+      return await this.policy.store.get(key);
+    } catch (error) {
+      this.emit({ type: "store_failed", operation: "get", error });
+      return void 0;
+    }
+  }
+  async write(key, entry) {
+    try {
+      await this.policy.store.set(key, entry);
+    } catch (error) {
+      this.emit({ type: "store_failed", operation: "set", error });
+    }
+  }
+  servable(key, entry) {
+    const now = this.now();
+    if (now - entry.fetchedAt < this.policy.ttlMs) return true;
+    const failed = this.failedAt.get(key);
+    return failed !== void 0 && now - failed < this.policy.ttlMs && this.usable(entry, now);
+  }
+  usable(entry, now) {
+    return now - entry.fetchedAt <= this.policy.ttlMs + this.policy.maxStaleMs;
+  }
+  async fetch(key, fetch, stale, signal) {
+    try {
+      const entry = { secrets: await fetch(), fetchedAt: this.now() };
+      await this.write(key, entry);
+      this.failedAt.delete(key);
+      return { entry };
+    } catch (error) {
+      if (signal.aborted) throw error;
+      const now = this.now();
+      if (!(error instanceof AnchorError) || !stale || !this.usable(stale, now)) throw error;
+      this.failedAt.set(key, now);
+      const staleForMs = Math.max(0, now - stale.fetchedAt - this.policy.ttlMs);
+      this.emit({ type: "refresh_failed", error, staleForMs });
+      return { entry: stale, error };
+    }
+  }
+};
+
+// src/retry.ts
+var DEFAULT_RETRY = { attempts: 3, baseDelayMs: 250, maxDelayMs: 5e3 };
+function delayFor(error, attempt, policy) {
+  if (error.retryAfterMs !== void 0) return Math.min(error.retryAfterMs, policy.maxDelayMs);
+  const cap = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** (attempt - 1));
+  return Math.floor(Math.random() * cap);
+}
+function wait(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortedError());
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function withRetry(run, policy, opts) {
+  const attempts = policy ? Math.max(1, policy.attempts) : 1;
+  for (let attempt = 1; ; attempt++) {
+    if (opts.signal?.aborted) throw abortedError();
+    try {
+      return await run();
+    } catch (error) {
+      if (!policy || !(error instanceof AnchorError) || !error.retryable || attempt >= attempts) {
+        throw error;
+      }
+      const delayMs = delayFor(error, attempt, policy);
+      opts.emit({ type: "retry", attempt, delayMs, error });
+      await wait(delayMs, opts.signal);
+    }
+  }
+}
+
+// src/config.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+function fromEnv(name) {
+  const value = typeof process === "undefined" ? void 0 : process.env[name];
+  return value === "" ? void 0 : value;
+}
+function resolveConfig(opts) {
+  const apiUrl = opts.apiUrl || fromEnv("ANCHOR_API_URL");
+  if (!apiUrl) {
+    throw new AnchorError(
+      0,
+      "config",
+      "Anchor API URL is not set: pass apiUrl or set ANCHOR_API_URL"
+    );
+  }
+  let origin;
+  try {
+    origin = new URL(apiUrl).origin;
+  } catch {
+    throw new AnchorError(
+      0,
+      "config",
+      "Anchor API URL is not a valid URL (apiUrl or ANCHOR_API_URL)"
+    );
+  }
+  const token = opts.token || fromEnv("ANCHOR_TOKEN");
+  if (!token) {
+    throw new AnchorError(0, "config", "Anchor token is not set: pass token or set ANCHOR_TOKEN");
+  }
+  const f = opts.fetch ?? globalThis.fetch;
+  if (typeof f !== "function") {
+    throw new AnchorError(
+      0,
+      "config",
+      "No fetch implementation: use Node 20 or later, or pass fetch"
+    );
+  }
+  return {
+    base: apiUrl.replace(/\/+$/, ""),
+    origin,
+    token,
+    fetch: f,
+    timeoutMs: timeoutOption(opts.timeoutMs),
+    retry: retryPolicy(opts.retry),
+    onEvent: opts.onEvent
+  };
+}
+function numberOption(name, value, fallback, rule) {
+  if (value === void 0) return fallback;
+  const valid = typeof value === "number" && !Number.isNaN(value) && (rule.infinite || Number.isFinite(value)) && value >= rule.min && (!rule.integer || Number.isInteger(value));
+  if (!valid) {
+    const kind = rule.integer ? "an integer" : "a number";
+    throw new AnchorError(
+      0,
+      "config",
+      `Anchor option ${name} must be ${kind} of at least ${rule.min}`
+    );
+  }
+  return value;
+}
+var timeoutOption = (value) => numberOption("timeoutMs", value, DEFAULT_TIMEOUT_MS, { min: 1 });
+function retryPolicy(retry) {
+  if (retry === false) return false;
+  return {
+    attempts: numberOption("retry.attempts", retry?.attempts, DEFAULT_RETRY.attempts, {
+      min: 1,
+      integer: true
+    }),
+    baseDelayMs: numberOption("retry.baseDelayMs", retry?.baseDelayMs, DEFAULT_RETRY.baseDelayMs, {
+      min: 0
+    }),
+    maxDelayMs: numberOption("retry.maxDelayMs", retry?.maxDelayMs, DEFAULT_RETRY.maxDelayMs, {
+      min: 0
+    })
+  };
+}
+function validateOptions(opts) {
+  timeoutOption(opts.timeoutMs);
+  retryPolicy(opts.retry);
+}
+function emitSafely(onEvent, event) {
+  try {
+    onEvent?.(event);
+  } catch {
+  }
+}
+var DEFAULT_TTL_MS = 6e4;
+function cachePolicy(cache) {
+  if (cache === false) return false;
+  return {
+    ttlMs: numberOption("cache.ttlMs", cache?.ttlMs, DEFAULT_TTL_MS, { min: 0 }),
+    maxStaleMs: numberOption("cache.maxStaleMs", cache?.maxStaleMs, Number.POSITIVE_INFINITY, {
+      min: 0,
+      infinite: true
+    }),
+    store: cache?.store ?? memoryStore()
+  };
+}
+
+// ../shared/src/value-decode.ts
+function decodeTypedValue(type, value) {
+  switch (type) {
+    case "json":
+    case "list":
+      return JSON.parse(value);
+    case "number":
+      return Number(value);
+    case "boolean":
+      return value === "true";
+    default:
+      return value;
+  }
+}
+
+// src/decode.ts
+function toSecret(s) {
+  if (typeof s.value !== "string") {
+    throw new AnchorError(200, "bad_response", `Anchor returned ${s.key} without a value`);
+  }
+  const out = {
+    key: s.key,
+    path: s.path,
+    type: s.type,
+    sensitive: s.sensitive,
+    version: s.version,
+    value: s.value
+  };
+  if (s.importedFrom) out.importedFrom = { ...s.importedFrom };
+  return out;
+}
+function decode(s) {
+  try {
+    return decodeTypedValue(s.type, s.value);
+  } catch {
+    throw new AnchorError(200, "bad_response", `Secret ${s.key} is not valid ${s.type}`);
+  }
+}
+function decodeAll(secrets) {
+  const entries = /* @__PURE__ */ new Map();
+  for (const s of secrets) {
+    if (!entries.has(s.key)) entries.set(s.key, decode(s));
+  }
+  return Object.fromEntries(entries);
+}
+
+// src/folder.ts
+var snapshotOf = (entry) => ({
+  entry,
+  values: Object.freeze(decodeAll(entry.secrets))
+});
+async function openFolder(core, query, options = {}) {
+  let snapshot = snapshotOf(await core.loadEntry(query, { signal: options.signal }));
+  let checkedAt = Date.now();
+  let failed = false;
+  let pending;
+  const accept = (entry) => {
+    failed = false;
+    if (entry !== snapshot.entry) snapshot = snapshotOf(entry);
+  };
+  const refreshInBackground = () => {
+    pending = core.loadEntry(query).then(accept, (error) => {
+      failed = true;
+      if (error instanceof AnchorError) {
+        const staleForMs = Math.max(0, Date.now() - snapshot.entry.fetchedAt - core.ttlMs);
+        core.emit({ type: "refresh_failed", error, staleForMs });
+      }
+    }).finally(() => {
+      checkedAt = Date.now();
+      pending = void 0;
+    });
+  };
+  const values = () => {
+    if (!pending && Date.now() - checkedAt >= core.ttlMs) refreshInBackground();
+    if (failed && Date.now() - snapshot.entry.fetchedAt > core.ttlMs + core.maxStaleMs) {
+      throw new AnchorError(
+        0,
+        "stale",
+        "Anchor values are older than ttlMs + maxStaleMs and refreshing them failed"
+      );
+    }
+    return snapshot.values;
+  };
+  const has = (key) => Object.hasOwn(values(), key);
+  return {
+    get: (key) => has(key) ? snapshot.values[key] : void 0,
+    getOrThrow(key) {
+      if (!has(key)) throw new Error(`Anchor secret ${key} is not set`);
+      return snapshot.values[key];
+    },
+    has,
+    keys: () => Object.keys(values()),
+    toObject: values,
+    async refresh() {
+      try {
+        accept(await core.loadEntry(query, { fresh: true, strict: true }));
+      } finally {
+        checkedAt = Date.now();
+      }
+    }
+  };
+}
+
+// src/transport.ts
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
+function retryAfterMs(res) {
+  if (res.status !== 429 && res.status !== 503) return void 0;
+  const header = res.headers.get("retry-after")?.trim();
+  if (!header || !/^\d+$/.test(header)) return void 0;
+  return Number(header) * 1e3;
+}
+async function errorFromResponse(res) {
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    body = void 0;
+  }
+  const options = {
+    retryable: RETRYABLE_STATUSES.has(res.status),
+    retryAfterMs: retryAfterMs(res)
+  };
+  const error = body?.error;
+  if (typeof error?.code === "string" && typeof error.message === "string") {
+    return new AnchorError(res.status, error.code, error.message, options);
+  }
+  return new AnchorError(res.status, "http_error", `Anchor answered HTTP ${res.status}`, options);
+}
+async function fetchJson(cfg, url, signal) {
+  if (signal?.aborted) throw abortedError();
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, cfg.timeoutMs);
+  const onAbort = () => controller.abort();
+  signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    const res = await cfg.fetch(url, {
+      method: "GET",
+      headers: { authorization: `Bearer ${cfg.token}`, accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!res.ok) throw await errorFromResponse(res);
+    try {
+      return await res.json();
+    } catch (cause) {
+      if (controller.signal.aborted) throw cause;
+      throw new AnchorError(
+        res.status,
+        "bad_response",
+        "Anchor returned a response that is not JSON"
+      );
+    }
+  } catch (cause) {
+    if (cause instanceof AnchorError) throw cause;
+    if (timedOut) {
+      throw new AnchorError(
+        0,
+        "timeout",
+        `Anchor at ${cfg.origin} did not answer within ${cfg.timeoutMs} ms`,
+        { retryable: true }
+      );
+    }
+    if (signal?.aborted) throw abortedError();
+    const reason = cause instanceof Error ? cause.message : "request failed";
+    throw new AnchorError(0, "network", `Could not reach Anchor at ${cfg.origin}: ${reason}`, {
+      cause,
+      retryable: true
+    });
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+// src/client.ts
+function normalize(q) {
+  return {
+    project: q.project,
+    environment: q.environment,
+    path: q.path ?? "/",
+    expand: q.expand ?? true,
+    includeImports: q.includeImports ?? true
+  };
+}
+async function fetchFolder(cfg, q, emit, signal) {
+  const params = new URLSearchParams({
+    path: q.path,
+    reveal: "true",
+    expand: String(q.expand),
+    includeImports: String(q.includeImports)
+  });
+  const url = `${cfg.base}/api/v1/projects/${encodeURIComponent(q.project)}/environments/${encodeURIComponent(q.environment)}/secrets?${params}`;
+  const body = await withRetry(() => fetchJson(cfg, url, signal), cfg.retry, {
+    signal,
+    emit
+  });
+  if (!body || !Array.isArray(body.secrets)) {
+    throw new AnchorError(200, "bad_response", "Anchor returned an unexpected response");
+  }
+  return body.secrets.map(toSecret);
+}
+var copy = (s) => s.importedFrom ? { ...s, importedFrom: { ...s.importedFrom } } : { ...s };
+function createClientCore(options) {
+  validateOptions(options);
+  const emit = (event) => emitSafely(options.onEvent, event);
+  const policy = cachePolicy(options.cache);
+  const cache = policy ? new SecretCache(policy, emit) : void 0;
+  return {
+    ttlMs: policy ? policy.ttlMs : DEFAULT_TTL_MS,
+    maxStaleMs: policy ? policy.maxStaleMs : Number.POSITIVE_INFINITY,
+    emit,
+    async loadEntry(q, o = {}) {
+      const cfg = resolveConfig(options);
+      const query = normalize(q);
+      if (!cache) {
+        return { secrets: await fetchFolder(cfg, query, emit, o.signal), fetchedAt: Date.now() };
+      }
+      return cache.load(
+        cacheKey(cfg.origin, cfg.token, query),
+        (signal) => fetchFolder(cfg, query, emit, signal),
+        o
+      );
+    }
+  };
+}
+function createAnchorClient(options = {}) {
+  const core = createClientCore(options);
+  return {
+    async listSecrets(q, o) {
+      return (await core.loadEntry(q, o)).secrets.map(copy);
+    },
+    async loadSecrets(q, o) {
+      return decodeAll((await core.loadEntry(q, o)).secrets);
+    },
+    folder: (q, o) => openFolder(core, q, o)
+  };
+}
+export {
+  AnchorError,
+  createAnchorClient,
+  memoryStore
+};

package/dist/retry.d.cts

@@ -0,0 +1,8 @@
+import type { AnchorEvent, RetryOptions } from "./types.cjs";
+export type RetryPolicy = Required<RetryOptions>;
+export declare const DEFAULT_RETRY: RetryPolicy;
+/** Runs `run` until it succeeds, fails with a non-retryable error, or runs out of attempts. */
+export declare function withRetry<T>(run: () => Promise<T>, policy: RetryPolicy | false, opts: {
+    signal?: AbortSignal;
+    emit: (event: AnchorEvent) => void;
+}): Promise<T>;

package/dist/retry.d.ts

@@ -0,0 +1,8 @@
+import type { AnchorEvent, RetryOptions } from "./types.js";
+export type RetryPolicy = Required<RetryOptions>;
+export declare const DEFAULT_RETRY: RetryPolicy;
+/** Runs `run` until it succeeds, fails with a non-retryable error, or runs out of attempts. */
+export declare function withRetry<T>(run: () => Promise<T>, policy: RetryPolicy | false, opts: {
+    signal?: AbortSignal;
+    emit: (event: AnchorEvent) => void;
+}): Promise<T>;

package/dist/transport.d.cts

@@ -0,0 +1,6 @@
+import type { Config } from "./config.cjs";
+/**
+ * One GET: the parsed body of a 2xx, or an `AnchorError` whose `retryable` says whether another
+ * attempt may succeed. Aborts after `cfg.timeoutMs`, or as soon as `signal` aborts.
+ */
+export declare function fetchJson(cfg: Config, url: string, signal?: AbortSignal): Promise<unknown>;

package/dist/transport.d.ts

@@ -0,0 +1,6 @@
+import type { Config } from "./config.js";
+/**
+ * One GET: the parsed body of a 2xx, or an `AnchorError` whose `retryable` says whether another
+ * attempt may succeed. Aborts after `cfg.timeoutMs`, or as soon as `signal` aborts.
+ */
+export declare function fetchJson(cfg: Config, url: string, signal?: AbortSignal): Promise<unknown>;

package/dist/types.d.cts

@@ -0,0 +1,128 @@
+/** Public types of the SDK. They never come from `@anchor/shared`, which is bundled. */
+import type { AnchorError } from "./errors.cjs";
+/** The value type a secret declares. */
+export type AnchorValueType = "string" | "json" | "pem" | "number" | "boolean" | "list";
+/** A decoded secret value, as `loadSecrets` returns it. */
+export type AnchorValue = string | number | boolean | unknown[] | Record<string, unknown>;
+/** One secret, with its value as the server returned it (a string). */
+export type AnchorSecret = {
+    key: string;
+    path: string;
+    type: AnchorValueType;
+    sensitive: boolean;
+    version: number;
+    value: string;
+    /** Set when the secret comes from a folder this folder imports. */
+    importedFrom?: {
+        environment: string;
+        path: string;
+    };
+};
+export type ClientOptions = {
+    /** Base URL of the Anchor server. Defaults to `ANCHOR_API_URL`. */
+    apiUrl?: string;
+    /** A service token or another bearer Anchor accepts. Defaults to `ANCHOR_TOKEN`. */
+    token?: string;
+    /** Replaces the global `fetch`, for proxies and tests. */
+    fetch?: typeof fetch;
+    /** Per attempt; default 10 000 ms. */
+    timeoutMs?: number;
+    /** Retries of network errors, timeouts and HTTP 429/502/503/504; `false` turns them off. */
+    retry?: RetryOptions | false;
+    /** Caching of fetched folders; `false` turns it off. */
+    cache?: CacheOptions | false;
+    /** Receives retries and failed refreshes. Exceptions it throws are ignored. */
+    onEvent?: (event: AnchorEvent) => void;
+};
+export type RetryOptions = {
+    /** Attempts in total, including the first; default 3. */
+    attempts?: number;
+    /** Upper bound of the first wait; it doubles per attempt. Default 250 ms. */
+    baseDelayMs?: number;
+    /** Upper bound of any wait, including `Retry-After`; default 5 000 ms. */
+    maxDelayMs?: number;
+};
+/** What the client reports through `onEvent`. Never carries a token or a value. */
+export type AnchorEvent = {
+    type: "retry";
+    attempt: number;
+    delayMs: number;
+    error: AnchorError;
+} | {
+    type: "refresh_failed";
+    error: AnchorError;
+    staleForMs: number;
+}
+/** A custom `CacheStore` threw; the read went to Anchor, or the fetched values were not kept. */
+ | {
+    type: "store_failed";
+    operation: "get" | "set";
+    error: unknown;
+};
+export type ListQuery = {
+    /** Project slug. */
+    project: string;
+    /** Environment slug. */
+    environment: string;
+    /** Folder path; default `/`. */
+    path?: string;
+    /** Expand `${...}` references; default `true`, like `anchor run`. */
+    expand?: boolean;
+    /** Add the secrets of the folder's imports; default `true`, like `anchor run`. */
+    includeImports?: boolean;
+};
+export type RequestOptions = {
+    /** Cancels the call; it rejects with code `aborted`. */
+    signal?: AbortSignal;
+    /** Ask the server even when the cached folder is fresh; still falls back to it on failure. */
+    fresh?: boolean;
+};
+export interface AnchorClient {
+    /** The secrets of one folder, with values. */
+    listSecrets(query: ListQuery, options?: RequestOptions): Promise<AnchorSecret[]>;
+    /** The same secrets as `{ KEY: value }`, with typed values decoded. */
+    loadSecrets(query: ListQuery, options?: RequestOptions): Promise<Record<string, AnchorValue>>;
+    /** Loads the folder once, then serves it synchronously and refreshes it in the background. */
+    folder(query: ListQuery, options?: {
+        signal?: AbortSignal;
+    }): Promise<AnchorFolder>;
+}
+/**
+ * One folder's decoded secrets. Reads are synchronous and never wait for the network: a read of
+ * values older than the cache ttl starts one background refresh and returns the current values.
+ * Once a refresh has failed past `ttlMs + maxStaleMs`, reads throw `AnchorError` code `stale`
+ * until Anchor answers again.
+ */
+export interface AnchorFolder {
+    /** The value of `key`, or `undefined` when the folder has no such secret. */
+    get<T = AnchorValue>(key: string): T | undefined;
+    /** The value of `key`; throws `Anchor secret <KEY> is not set` when it is missing. */
+    getOrThrow<T = AnchorValue>(key: string): T;
+    has(key: string): boolean;
+    keys(): string[];
+    /** Every value, frozen; the same object until new values arrive. */
+    toObject(): Readonly<Record<string, AnchorValue>>;
+    /** Fetches now; rejects when that fails, keeping the current values. */
+    refresh(): Promise<void>;
+}
+/** What the cache keeps per folder. `secrets` hold plaintext values. */
+export type CacheEntry = {
+    secrets: AnchorSecret[];
+    fetchedAt: number;
+};
+/**
+ * Where cached folders live; the default keeps them in memory. A custom store (a file, Redis)
+ * receives plaintext values and must protect them, for example by encrypting them.
+ */
+export interface CacheStore {
+    get(key: string): CacheEntry | undefined | Promise<CacheEntry | undefined>;
+    set(key: string, entry: CacheEntry): void | Promise<void>;
+}
+export type CacheOptions = {
+    /** How long a fetched folder is served without asking the server; default 60 000 ms. */
+    ttlMs?: number;
+    /** How long past `ttlMs` a folder may still be served when the server fails; default no limit. */
+    maxStaleMs?: number;
+    /** Default: an in-memory store per client. */
+    store?: CacheStore;
+};