@anchor-secrets/sdk 0.4.0 → 0.5.0

package/README.md

@@ -35,8 +35,11 @@ folder.get<string>("DATABASE_URL"); // synchronous, never waits for the network
 ```
 
 - `client.folder(query)` loads once and returns an `AnchorFolder`: `get`, `getOrThrow`, `has`,
-  `keys`, `toObject` (frozen) and `refresh()`. A read of values older than the cache ttl returns
-  them at once and starts one background refresh.
+  `keys`, `toObject` (frozen all the way down) and `refresh()`. A read of values older than the
+  cache ttl returns them at once and starts one background refresh; there is no timer.
+- A refresh sends the folder's last `ETag` as `If-None-Match`. When nothing changed, Anchor
+  answers `304` with no body and the cached values are kept. `cache: false` sends no
+  `If-None-Match`.
 - `loadSecrets(query)` returns `{ KEY: value }` with typed values decoded: `number` and `boolean`
   become numbers and booleans, `json` and `list` are parsed, `string` and `pem` stay strings.
   `listSecrets(query)` returns the secrets with their metadata (`key`, `path`, `type`,
@@ -74,7 +77,8 @@ Every failure is an `AnchorError` with `status` (0 when there was no response),
 `aborted`, `stale`, or the server's error code such as `unauthenticated`, `forbidden` or `not_found`.
 Messages and events never contain tokens or values.
 
-Every value the client reads is recorded in the project's audit log under the token's name.
+Every request that returns values is recorded in the project's audit log under the token's
+name. A `304` returns no values and is not recorded.
 
 ## License
 

package/dist/cache.d.cts

@@ -1,6 +1,12 @@
 import type { AnchorEvent, AnchorSecret, CacheEntry, CacheOptions, CacheStore, ListQuery } from "./types.cjs";
 export type { CacheEntry, CacheOptions, CacheStore } from "./types.cjs";
 export type CachePolicy = Required<CacheOptions>;
+/** What a fetch got from Anchor: new secrets and their tag, or a 304 for the tag it sent. */
+export type Fetched = {
+    secrets: AnchorSecret[];
+    etag?: string;
+} | "unchanged";
+type FetchFn = (signal: AbortSignal, etag: string | undefined) => Promise<Fetched>;
 export declare function memoryStore(): CacheStore;
 /**
  * The cache key of one folder as one token sees it. The token is reduced to a SHA-256
@@ -19,12 +25,14 @@ export declare class SecretCache {
     private readonly inflight;
     /** When the last fetch of a key failed; the stale entry is served without asking for one ttl. */
     private readonly failedAt;
+    /** The newest entry this instance fetched per key, in case the store returns an older one. */
+    private readonly latest;
     constructor(policy: CachePolicy, emit: (event: AnchorEvent) => void, now?: () => number);
     /**
      * 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.
      */
-    load(key: string, fetch: (signal: AbortSignal) => Promise<AnchorSecret[]>, opts?: {
+    load(key: string, fetch: FetchFn, opts?: {
         fresh?: boolean;
         signal?: AbortSignal;
         strict?: boolean;

package/dist/cache.d.ts

@@ -1,6 +1,12 @@
 import type { AnchorEvent, AnchorSecret, CacheEntry, CacheOptions, CacheStore, ListQuery } from "./types.js";
 export type { CacheEntry, CacheOptions, CacheStore } from "./types.js";
 export type CachePolicy = Required<CacheOptions>;
+/** What a fetch got from Anchor: new secrets and their tag, or a 304 for the tag it sent. */
+export type Fetched = {
+    secrets: AnchorSecret[];
+    etag?: string;
+} | "unchanged";
+type FetchFn = (signal: AbortSignal, etag: string | undefined) => Promise<Fetched>;
 export declare function memoryStore(): CacheStore;
 /**
  * The cache key of one folder as one token sees it. The token is reduced to a SHA-256
@@ -19,12 +25,14 @@ export declare class SecretCache {
     private readonly inflight;
     /** When the last fetch of a key failed; the stale entry is served without asking for one ttl. */
     private readonly failedAt;
+    /** The newest entry this instance fetched per key, in case the store returns an older one. */
+    private readonly latest;
     constructor(policy: CachePolicy, emit: (event: AnchorEvent) => void, now?: () => number);
     /**
      * 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.
      */
-    load(key: string, fetch: (signal: AbortSignal) => Promise<AnchorSecret[]>, opts?: {
+    load(key: string, fetch: FetchFn, opts?: {
         fresh?: boolean;
         signal?: AbortSignal;
         strict?: boolean;

package/dist/folder.d.cts

@@ -1,5 +1,7 @@
 import type { ClientCore } from "./client.cjs";
 import type { AnchorFolder, ListQuery } from "./types.cjs";
+/** Freezes plain objects and arrays all the way down: one folder's values are shared by every reader. */
+export declare function deepFreeze<T>(value: T): T;
 export declare function openFolder(core: ClientCore, query: ListQuery, options?: {
     signal?: AbortSignal;
 }): Promise<AnchorFolder>;

package/dist/folder.d.ts

@@ -1,5 +1,7 @@
 import type { ClientCore } from "./client.js";
 import type { AnchorFolder, ListQuery } from "./types.js";
+/** Freezes plain objects and arrays all the way down: one folder's values are shared by every reader. */
+export declare function deepFreeze<T>(value: T): T;
 export declare function openFolder(core: ClientCore, query: ListQuery, options?: {
     signal?: AbortSignal;
 }): Promise<AnchorFolder>;

package/dist/index.cjs

@@ -70,6 +70,7 @@ function cacheKey(origin, token, q) {
     q.includeImports
   ]);
 }
+var newer = (a, b) => a && b ? b.fetchedAt > a.fetchedAt ? b : a : a ?? b;
 function untilAborted(promise, signal) {
   if (!signal) return promise;
   if (signal.aborted) return Promise.reject(abortedError());
@@ -91,15 +92,20 @@ var SecretCache = class {
   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 newest entry this instance fetched per key, in case the store returns an older one. */
+  latest = /* @__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);
+    let flight = opts.fresh ? void 0 : this.inflight.get(key);
+    if (!flight) {
+      const entry = newer(await this.read(key), this.latest.get(key));
+      if (entry && !opts.fresh && this.servable(key, entry)) return entry;
+      flight = this.inflight.get(key) ?? this.start(key, fetch, entry);
+    }
     flight.waiters++;
     let outcome;
     try {
@@ -118,7 +124,7 @@ var SecretCache = class {
     const controller = new AbortController();
     const promise = this.fetch(
       key,
-      () => fetch(controller.signal),
+      () => fetch(controller.signal, stale?.etag),
       stale,
       controller.signal
     ).finally(() => {
@@ -155,7 +161,16 @@ var SecretCache = class {
   }
   async fetch(key, fetch, stale, signal) {
     try {
-      const entry = { secrets: await fetch(), fetchedAt: this.now() };
+      const fetched = await fetch();
+      if (fetched === "unchanged" && !stale) {
+        throw new AnchorError(
+          304,
+          "bad_response",
+          "Anchor answered 304 to a request without a tag"
+        );
+      }
+      const entry = fetched === "unchanged" ? { secrets: stale.secrets, fetchedAt: this.now(), etag: stale?.etag } : { secrets: fetched.secrets, fetchedAt: this.now(), etag: fetched.etag };
+      this.latest.set(key, entry);
       await this.write(key, entry);
       this.failedAt.delete(key);
       return { entry };
@@ -180,6 +195,7 @@ function delayFor(error, attempt, policy) {
 }
 function wait(ms, signal) {
   return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(abortedError());
     const onAbort = () => {
       clearTimeout(timer);
       reject(abortedError());
@@ -354,18 +370,27 @@ function decodeAll(secrets) {
 }
 
 // src/folder.ts
+function deepFreeze(value) {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
 var snapshotOf = (entry) => ({
   entry,
-  values: Object.freeze(decodeAll(entry.secrets))
+  values: deepFreeze(decodeAll(entry.secrets))
 });
 async function openFolder(core, query, options = {}) {
   let snapshot = snapshotOf(await core.loadEntry(query, { signal: options.signal }));
-  let checkedAt = Date.now();
+  let checkedAt = snapshot.entry.fetchedAt;
   let failed = false;
   let pending;
   const accept = (entry) => {
     failed = false;
-    if (entry !== snapshot.entry) snapshot = snapshotOf(entry);
+    if (entry.fetchedAt < snapshot.entry.fetchedAt) return;
+    if (entry.secrets === snapshot.entry.secrets) snapshot = { entry, values: snapshot.values };
+    else snapshot = snapshotOf(entry);
   };
   const refreshInBackground = () => {
     pending = core.loadEntry(query).then(accept, (error) => {
@@ -435,7 +460,7 @@ async function errorFromResponse(res) {
   }
   return new AnchorError(res.status, "http_error", `Anchor answered HTTP ${res.status}`, options);
 }
-async function fetchJson(cfg, url, signal) {
+async function fetchJson(cfg, url, signal, ifNoneMatch) {
   if (signal?.aborted) throw abortedError();
   const controller = new AbortController();
   let timedOut = false;
@@ -446,14 +471,17 @@ async function fetchJson(cfg, url, signal) {
   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
-    });
+    const headers = {
+      authorization: `Bearer ${cfg.token}`,
+      accept: "application/json"
+    };
+    if (ifNoneMatch) headers["if-none-match"] = ifNoneMatch;
+    const res = await cfg.fetch(url, { method: "GET", headers, signal: controller.signal });
+    const etag = res.headers.get("etag") ?? void 0;
+    if (res.status === 304) return { status: 304, etag, body: void 0 };
     if (!res.ok) throw await errorFromResponse(res);
     try {
-      return await res.json();
+      return { status: res.status, etag, body: await res.json() };
     } catch (cause) {
       if (controller.signal.aborted) throw cause;
       throw new AnchorError(
@@ -494,7 +522,7 @@ function normalize(q) {
     includeImports: q.includeImports ?? true
   };
 }
-async function fetchFolder(cfg, q, emit, signal) {
+async function fetchFolder(cfg, q, emit, signal, etag) {
   const params = new URLSearchParams({
     path: q.path,
     reveal: "true",
@@ -502,14 +530,16 @@ async function fetchFolder(cfg, q, emit, signal) {
     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, {
+  const res = await withRetry(() => fetchJson(cfg, url, signal, etag), cfg.retry, {
     signal,
     emit
   });
+  if (res.status === 304) return "unchanged";
+  const body = res.body;
   if (!body || !Array.isArray(body.secrets)) {
-    throw new AnchorError(200, "bad_response", "Anchor returned an unexpected response");
+    throw new AnchorError(res.status, "bad_response", "Anchor returned an unexpected response");
   }
-  return body.secrets.map(toSecret);
+  return { secrets: body.secrets.map(toSecret), etag: res.etag };
 }
 var copy = (s) => s.importedFrom ? { ...s, importedFrom: { ...s.importedFrom } } : { ...s };
 function createClientCore(options) {
@@ -525,11 +555,19 @@ function createClientCore(options) {
       const cfg = resolveConfig(options);
       const query = normalize(q);
       if (!cache) {
-        return { secrets: await fetchFolder(cfg, query, emit, o.signal), fetchedAt: Date.now() };
+        const fetched = await fetchFolder(cfg, query, emit, o.signal);
+        if (fetched === "unchanged") {
+          throw new AnchorError(
+            304,
+            "bad_response",
+            "Anchor answered 304 to a request without a tag"
+          );
+        }
+        return { secrets: fetched.secrets, fetchedAt: Date.now() };
       }
       return cache.load(
         cacheKey(cfg.origin, cfg.token, query),
-        (signal) => fetchFolder(cfg, query, emit, signal),
+        (signal, etag) => fetchFolder(cfg, query, emit, signal, etag),
         o
       );
     }

package/dist/index.js

@@ -42,6 +42,7 @@ function cacheKey(origin, token, q) {
     q.includeImports
   ]);
 }
+var newer = (a, b) => a && b ? b.fetchedAt > a.fetchedAt ? b : a : a ?? b;
 function untilAborted(promise, signal) {
   if (!signal) return promise;
   if (signal.aborted) return Promise.reject(abortedError());
@@ -63,15 +64,20 @@ var SecretCache = class {
   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 newest entry this instance fetched per key, in case the store returns an older one. */
+  latest = /* @__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);
+    let flight = opts.fresh ? void 0 : this.inflight.get(key);
+    if (!flight) {
+      const entry = newer(await this.read(key), this.latest.get(key));
+      if (entry && !opts.fresh && this.servable(key, entry)) return entry;
+      flight = this.inflight.get(key) ?? this.start(key, fetch, entry);
+    }
     flight.waiters++;
     let outcome;
     try {
@@ -90,7 +96,7 @@ var SecretCache = class {
     const controller = new AbortController();
     const promise = this.fetch(
       key,
-      () => fetch(controller.signal),
+      () => fetch(controller.signal, stale?.etag),
       stale,
       controller.signal
     ).finally(() => {
@@ -127,7 +133,16 @@ var SecretCache = class {
   }
   async fetch(key, fetch, stale, signal) {
     try {
-      const entry = { secrets: await fetch(), fetchedAt: this.now() };
+      const fetched = await fetch();
+      if (fetched === "unchanged" && !stale) {
+        throw new AnchorError(
+          304,
+          "bad_response",
+          "Anchor answered 304 to a request without a tag"
+        );
+      }
+      const entry = fetched === "unchanged" ? { secrets: stale.secrets, fetchedAt: this.now(), etag: stale?.etag } : { secrets: fetched.secrets, fetchedAt: this.now(), etag: fetched.etag };
+      this.latest.set(key, entry);
       await this.write(key, entry);
       this.failedAt.delete(key);
       return { entry };
@@ -152,6 +167,7 @@ function delayFor(error, attempt, policy) {
 }
 function wait(ms, signal) {
   return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(abortedError());
     const onAbort = () => {
       clearTimeout(timer);
       reject(abortedError());
@@ -326,18 +342,27 @@ function decodeAll(secrets) {
 }
 
 // src/folder.ts
+function deepFreeze(value) {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
 var snapshotOf = (entry) => ({
   entry,
-  values: Object.freeze(decodeAll(entry.secrets))
+  values: deepFreeze(decodeAll(entry.secrets))
 });
 async function openFolder(core, query, options = {}) {
   let snapshot = snapshotOf(await core.loadEntry(query, { signal: options.signal }));
-  let checkedAt = Date.now();
+  let checkedAt = snapshot.entry.fetchedAt;
   let failed = false;
   let pending;
   const accept = (entry) => {
     failed = false;
-    if (entry !== snapshot.entry) snapshot = snapshotOf(entry);
+    if (entry.fetchedAt < snapshot.entry.fetchedAt) return;
+    if (entry.secrets === snapshot.entry.secrets) snapshot = { entry, values: snapshot.values };
+    else snapshot = snapshotOf(entry);
   };
   const refreshInBackground = () => {
     pending = core.loadEntry(query).then(accept, (error) => {
@@ -407,7 +432,7 @@ async function errorFromResponse(res) {
   }
   return new AnchorError(res.status, "http_error", `Anchor answered HTTP ${res.status}`, options);
 }
-async function fetchJson(cfg, url, signal) {
+async function fetchJson(cfg, url, signal, ifNoneMatch) {
   if (signal?.aborted) throw abortedError();
   const controller = new AbortController();
   let timedOut = false;
@@ -418,14 +443,17 @@ async function fetchJson(cfg, url, signal) {
   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
-    });
+    const headers = {
+      authorization: `Bearer ${cfg.token}`,
+      accept: "application/json"
+    };
+    if (ifNoneMatch) headers["if-none-match"] = ifNoneMatch;
+    const res = await cfg.fetch(url, { method: "GET", headers, signal: controller.signal });
+    const etag = res.headers.get("etag") ?? void 0;
+    if (res.status === 304) return { status: 304, etag, body: void 0 };
     if (!res.ok) throw await errorFromResponse(res);
     try {
-      return await res.json();
+      return { status: res.status, etag, body: await res.json() };
     } catch (cause) {
       if (controller.signal.aborted) throw cause;
       throw new AnchorError(
@@ -466,7 +494,7 @@ function normalize(q) {
     includeImports: q.includeImports ?? true
   };
 }
-async function fetchFolder(cfg, q, emit, signal) {
+async function fetchFolder(cfg, q, emit, signal, etag) {
   const params = new URLSearchParams({
     path: q.path,
     reveal: "true",
@@ -474,14 +502,16 @@ async function fetchFolder(cfg, q, emit, signal) {
     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, {
+  const res = await withRetry(() => fetchJson(cfg, url, signal, etag), cfg.retry, {
     signal,
     emit
   });
+  if (res.status === 304) return "unchanged";
+  const body = res.body;
   if (!body || !Array.isArray(body.secrets)) {
-    throw new AnchorError(200, "bad_response", "Anchor returned an unexpected response");
+    throw new AnchorError(res.status, "bad_response", "Anchor returned an unexpected response");
   }
-  return body.secrets.map(toSecret);
+  return { secrets: body.secrets.map(toSecret), etag: res.etag };
 }
 var copy = (s) => s.importedFrom ? { ...s, importedFrom: { ...s.importedFrom } } : { ...s };
 function createClientCore(options) {
@@ -497,11 +527,19 @@ function createClientCore(options) {
       const cfg = resolveConfig(options);
       const query = normalize(q);
       if (!cache) {
-        return { secrets: await fetchFolder(cfg, query, emit, o.signal), fetchedAt: Date.now() };
+        const fetched = await fetchFolder(cfg, query, emit, o.signal);
+        if (fetched === "unchanged") {
+          throw new AnchorError(
+            304,
+            "bad_response",
+            "Anchor answered 304 to a request without a tag"
+          );
+        }
+        return { secrets: fetched.secrets, fetchedAt: Date.now() };
       }
       return cache.load(
         cacheKey(cfg.origin, cfg.token, query),
-        (signal) => fetchFolder(cfg, query, emit, signal),
+        (signal, etag) => fetchFolder(cfg, query, emit, signal, etag),
         o
       );
     }

package/dist/transport.d.cts

@@ -1,6 +1,12 @@
 import type { Config } from "./config.cjs";
+export type JsonResponse = {
+    status: number;
+    etag: string | undefined;
+    body: unknown;
+};
 /**
- * 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.
+ * One GET: the parsed body of a 2xx (none for a 304 answering `ifNoneMatch`), 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>;
+export declare function fetchJson(cfg: Config, url: string, signal?: AbortSignal, ifNoneMatch?: string): Promise<JsonResponse>;

package/dist/transport.d.ts

@@ -1,6 +1,12 @@
 import type { Config } from "./config.js";
+export type JsonResponse = {
+    status: number;
+    etag: string | undefined;
+    body: unknown;
+};
 /**
- * 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.
+ * One GET: the parsed body of a 2xx (none for a 304 answering `ifNoneMatch`), 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>;
+export declare function fetchJson(cfg: Config, url: string, signal?: AbortSignal, ifNoneMatch?: string): Promise<JsonResponse>;

package/dist/types.d.cts

@@ -109,6 +109,8 @@ export interface AnchorFolder {
 export type CacheEntry = {
     secrets: AnchorSecret[];
     fetchedAt: number;
+    /** The server's tag for these secrets, sent back as `If-None-Match`; absent before 0.5.0. */
+    etag?: string;
 };
 /**
  * Where cached folders live; the default keeps them in memory. A custom store (a file, Redis)

package/dist/types.d.ts

@@ -109,6 +109,8 @@ export interface AnchorFolder {
 export type CacheEntry = {
     secrets: AnchorSecret[];
     fetchedAt: number;
+    /** The server's tag for these secrets, sent back as `If-None-Match`; absent before 0.5.0. */
+    etag?: string;
 };
 /**
  * Where cached folders live; the default keeps them in memory. A custom store (a file, Redis)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchor-secrets/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Node client for Anchor, a self-hosted secrets manager on Cloudflare Workers",
   "keywords": [
     "secrets",
@@ -47,7 +47,7 @@
     "node": ">=20"
   },
   "devDependencies": {
-    "@anchor/shared": "0.4.0",
+    "@anchor/shared": "0.5.0",
     "@arethetypeswrong/cli": "^0.18.5",
     "@types/node": "^22.20.5",
     "esbuild": "^0.28.2",