@anchor-secrets/sdk 0.0.0-stage → 0.5.0

package/dist/index.js

@@ -0,0 +1,564 @@
+// 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
+  ]);
+}
+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());
+  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 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();
+    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 {
+      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?.etag),
+      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 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 };
+    } 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) => {
+    if (signal?.aborted) return reject(abortedError());
+    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
+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: deepFreeze(decodeAll(entry.secrets))
+});
+async function openFolder(core, query, options = {}) {
+  let snapshot = snapshotOf(await core.loadEntry(query, { signal: options.signal }));
+  let checkedAt = snapshot.entry.fetchedAt;
+  let failed = false;
+  let pending;
+  const accept = (entry) => {
+    failed = false;
+    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) => {
+      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, ifNoneMatch) {
+  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 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 { status: res.status, etag, body: 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, etag) {
+  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 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(res.status, "bad_response", "Anchor returned an unexpected response");
+  }
+  return { secrets: body.secrets.map(toSecret), etag: res.etag };
+}
+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) {
+        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, etag) => fetchFolder(cfg, query, emit, signal, etag),
+        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,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 (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, ifNoneMatch?: string): Promise<JsonResponse>;

package/dist/transport.d.ts

@@ -0,0 +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 (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, ifNoneMatch?: string): Promise<JsonResponse>;