@secrefs/node 0.1.0 → 0.2.0

package/README.md

@@ -121,4 +121,4 @@ MIT. See [LICENSE](./LICENSE).
 
 The client libraries are MIT permanently and unconditionally — the SecRefs
 control plane is licensed separately. See
-[LICENSING.md](https://github.com/Armistice-Group/secrefs/blob/main/LICENSING.md).
+[LICENSING.md](https://github.com/secrefs/secrefs/blob/main/LICENSING.md).

package/dist/index.cjs

@@ -33,6 +33,8 @@ __export(src_exports, {
   AwsSecretsManagerProvider: () => AwsSecretsManagerProvider,
   BaseSecretProvider: () => BaseSecretProvider,
   BitwardenProvider: () => BitwardenProvider,
+  CONFIG_FILENAME: () => CONFIG_FILENAME,
+  ConfigError: () => ConfigError,
   ControlPlaneClient: () => ControlPlaneClient,
   ControlPlaneRequestError: () => ControlPlaneRequestError,
   LocalProvider: () => LocalProvider,
@@ -42,12 +44,15 @@ __export(src_exports, {
   SecretFetchError: () => SecretFetchError,
   TtlCache: () => TtlCache,
   VaultProvider: () => VaultProvider,
+  buildProviders: () => buildProviders,
   checkReferences: () => checkReferences,
   createDefaultProviders: () => createDefaultProviders,
   expandKeyValueMap: () => expandKeyValueMap,
   expandProcessEnv: () => expandProcessEnv,
   extractField: () => extractField,
   isSecretRef: () => isSecretRef,
+  loadConfigFrom: () => loadConfigFrom,
+  parseConfig: () => parseConfig,
   parseEnvFileText: () => parseEnvFileText,
   parseSecretRef: () => parseSecretRef,
   recoverTruncatedSecRefs: () => recoverTruncatedSecRefs,
@@ -59,16 +64,143 @@ module.exports = __toCommonJS(src_exports);
 // src/providers/aws.ts
 var import_client_secrets_manager = require("@aws-sdk/client-secrets-manager");
 
+// src/providers/errors.ts
+var AUTH_NAMES = /* @__PURE__ */ new Set([
+  "CredentialsProviderError",
+  "TokenProviderError",
+  "ExpiredToken",
+  "ExpiredTokenException",
+  "InvalidClientTokenId",
+  "UnrecognizedClientException",
+  "InvalidIdentityToken",
+  "AuthFailure",
+  "SSOTokenProviderFailure"
+]);
+var NOT_FOUND_NAMES = /* @__PURE__ */ new Set([
+  "ResourceNotFoundException",
+  "NoSuchEntity",
+  "SecretNotFound"
+]);
+var DENIED_NAMES = /* @__PURE__ */ new Set([
+  "AccessDeniedException",
+  "AccessDenied",
+  "AuthorizationError",
+  "UnauthorizedOperation"
+]);
+var TRANSIENT_NAMES = /* @__PURE__ */ new Set([
+  "TimeoutError",
+  "NetworkingError",
+  "RequestTimeout",
+  "RequestTimeoutException",
+  "ThrottlingException",
+  "TooManyRequestsException",
+  "InternalServiceError",
+  "InternalServerError",
+  "ServiceUnavailable",
+  "ServiceUnavailableException",
+  "AbortError",
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "EAI_AGAIN"
+]);
+var AUTH_FRAGMENTS = [
+  "could not load credentials",
+  "sso session associated with this profile has expired",
+  "security token included in the request is expired",
+  "unable to locate credentials",
+  "token is expired",
+  "credentials have expired",
+  "is expired"
+];
+var TRANSIENT_FRAGMENTS = [
+  "socket hang up",
+  "network error",
+  "timed out",
+  "timeout",
+  "econnreset",
+  "econnrefused",
+  "getaddrinfo"
+];
+function nameOf(err) {
+  if (typeof err !== "object" || err === null) return "";
+  const e = err;
+  for (const candidate of [e.name, e.code, e.__type]) {
+    if (typeof candidate === "string" && candidate) return candidate;
+  }
+  return "";
+}
+function statusOf(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const meta = err.$metadata;
+  if (typeof meta?.httpStatusCode === "number") return meta.httpStatusCode;
+  const status = err.status ?? err.statusCode;
+  return typeof status === "number" ? status : void 0;
+}
+function classifyError(err) {
+  const name = nameOf(err);
+  if (AUTH_NAMES.has(name)) return "auth";
+  if (NOT_FOUND_NAMES.has(name)) return "not_found";
+  if (DENIED_NAMES.has(name)) return "denied";
+  if (TRANSIENT_NAMES.has(name)) return "transient";
+  const status = statusOf(err);
+  if (status === 401) return "auth";
+  if (status === 403) return "denied";
+  if (status === 404) return "not_found";
+  if (status === 408 || status === 429) return "transient";
+  if (status !== void 0 && status >= 500) return "transient";
+  const message = (err instanceof Error ? err.message : String(err ?? "")).toLowerCase();
+  if (AUTH_FRAGMENTS.some((f) => message.includes(f))) return "auth";
+  if (TRANSIENT_FRAGMENTS.some((f) => message.includes(f))) return "transient";
+  return "unknown";
+}
+function isStaleServable(kind) {
+  return kind === "transient";
+}
+function remedyFor(kind, provider, err) {
+  if (kind !== "auth") return void 0;
+  const message = err instanceof Error ? err.message : "";
+  if (/sso session/i.test(message)) {
+    const profile = process.env.AWS_PROFILE;
+    return profile ? `Run: aws sso login --profile ${profile}` : "Run: aws sso login --profile <your-profile>";
+  }
+  switch (provider) {
+    case "aws": {
+      const profile = process.env.AWS_PROFILE;
+      return profile ? `Check credentials for AWS profile "${profile}" - if it uses SSO, run: aws sso login --profile ${profile}` : "No AWS credentials found. Set AWS_PROFILE, export static keys, or attach an instance role.";
+    }
+    case "bitwarden":
+      return "Set BWS_ACCESS_TOKEN to a valid Bitwarden machine account token.";
+    case "vault":
+      return "Set VAULT_ADDR and VAULT_TOKEN, or renew the token if it has expired.";
+    default:
+      return void 0;
+  }
+}
+
 // src/providers/base.ts
 var SecretFetchError = class extends Error {
   constructor(provider, path2, cause) {
-    super(`[${provider}] failed to fetch secret at "${path2}": ${errorMessage(cause)}`);
+    const kind = classifyError(cause);
+    super(
+      kind === "auth" ? `[${provider}] cannot authenticate: ${errorMessage(cause)}` : `[${provider}] failed to fetch secret at "${path2}": ${errorMessage(cause)}`
+    );
     this.provider = provider;
     this.path = path2;
+    this.cause = cause;
     this.name = "SecretFetchError";
+    this.kind = kind;
+    this.remedy = remedyFor(kind, provider, cause);
   }
   provider;
   path;
+  cause;
+  /** Whose problem this is - see {@link SecretErrorKind}. Classified from
+   * `cause` so every existing throw site is categorised without having to
+   * know about categories. */
+  kind;
+  /** The action that fixes it, when there is one (auth failures). */
+  remedy;
 };
 var BaseSecretProvider = class {
   async fetchBatch(requests) {
@@ -113,6 +245,9 @@ function extractField(raw, field, context) {
   return typeof current === "object" ? JSON.stringify(current) : String(current);
 }
 
+// src/providers/aws.ts
+var import_credential_providers = require("@aws-sdk/credential-providers");
+
 // src/ttlCache.ts
 var TtlCache = class {
   /** Settled values, only populated when a TTL is configured. */
@@ -123,9 +258,15 @@ var TtlCache = class {
    * stays correct even with caching fully disabled. */
   inFlight = /* @__PURE__ */ new Map();
   ttlMs;
+  staleGraceMs;
+  isStaleServable;
+  onStale;
   now;
   constructor(options = {}) {
     this.ttlMs = options.ttlMs ?? 0;
+    this.staleGraceMs = options.staleGraceMs ?? 0;
+    this.isStaleServable = options.isStaleServable ?? (() => false);
+    this.onStale = options.onStale;
     this.now = options.now ?? Date.now;
   }
   /**
@@ -149,11 +290,19 @@ var TtlCache = class {
     this.inFlight.set(key, pending);
     try {
       const value = await pending;
-      if (this.ttlMs > 0) {
+      if (this.ttlMs > 0 || this.staleGraceMs > 0) {
         this.entries.set(key, { value: Promise.resolve(value), storedAt: this.now() });
       }
       return value;
     } catch (err) {
+      const previous = this.entries.get(key);
+      if (previous && this.staleGraceMs > 0 && this.isStaleServable(err)) {
+        const ageMs = this.now() - previous.storedAt;
+        if (ageMs <= this.staleGraceMs) {
+          this.onStale?.(key, ageMs, err);
+          return previous.value;
+        }
+      }
       this.entries.delete(key);
       throw err;
     } finally {
@@ -217,6 +366,7 @@ var AwsSecretsManagerProvider = class extends BaseSecretProvider {
   name = "aws";
   explicitClient;
   region;
+  profile;
   controlPlane;
   controlPlaneClient;
   ambientClient = null;
@@ -225,8 +375,14 @@ var AwsSecretsManagerProvider = class extends BaseSecretProvider {
     super();
     this.explicitClient = options.client;
     this.region = options.region;
+    this.profile = options.profile;
     this.controlPlane = options.controlPlane;
-    this.rawCache = new TtlCache({ ttlMs: options.cacheTtlMs });
+    this.rawCache = new TtlCache({
+      ttlMs: options.cacheTtlMs,
+      staleGraceMs: options.staleGraceMs,
+      isStaleServable: (err) => isStaleServable(classifyError(err)),
+      onStale: options.onStaleValue
+    });
     if (this.controlPlane) {
       this.controlPlaneClient = this.controlPlane.client ?? new ControlPlaneClient({ baseUrl: this.controlPlane.baseUrl, token: this.controlPlane.token });
     }
@@ -245,7 +401,15 @@ var AwsSecretsManagerProvider = class extends BaseSecretProvider {
       }
       return this.buildClientFromMintedCredentials(minted.credentials);
     }
-    if (!this.ambientClient) this.ambientClient = new import_client_secrets_manager.SecretsManagerClient({ region: this.region });
+    if (!this.ambientClient) {
+      this.ambientClient = new import_client_secrets_manager.SecretsManagerClient({
+        region: this.region,
+        // fromNodeProviderChain honours the same precedence as the
+        // ambient default, just pinned to one profile - so instance
+        // roles and env vars still work when no profile is named.
+        ...this.profile ? { credentials: (0, import_credential_providers.fromNodeProviderChain)({ profile: this.profile }) } : {}
+      });
+    }
     return this.ambientClient;
   }
   buildClientFromMintedCredentials(credentials) {
@@ -271,7 +435,8 @@ var AwsSecretsManagerProvider = class extends BaseSecretProvider {
         }
         throw new Error(`secret "${path2}" has no SecretString or SecretBinary payload`);
       } catch (err) {
-        throw new Error(`could not fetch secret "${path2}": ${errorMessage(err)}`);
+        if (err instanceof SecretFetchError) throw err;
+        throw new SecretFetchError(this.name, path2, err);
       }
     });
   }
@@ -613,16 +778,37 @@ function tryParseSecretRef(raw) {
 }
 
 // src/resolver.ts
+function formatFailures(errors) {
+  const auth = errors.filter((e) => e.kind === "auth");
+  const rest = errors.filter((e) => e.kind !== "auth");
+  const lines = [];
+  for (const provider of [...new Set(auth.map((e) => e.provider ?? "unknown"))]) {
+    const group = auth.filter((e) => (e.provider ?? "unknown") === provider);
+    lines.push(`Cannot authenticate to provider "${provider}".`);
+    lines.push(`  ${group[0].message}`);
+    const remedy = group.find((e) => e.remedy)?.remedy;
+    if (remedy) lines.push(`  ${remedy}`);
+    lines.push(`  Not resolved: ${group.map((e) => e.key).join(", ")}`);
+  }
+  if (rest.length > 0) {
+    if (lines.length > 0) lines.push("");
+    lines.push(`Failed to resolve ${rest.length} secret reference(s):`);
+    for (const e of rest) lines.push(`  - ${e.key}: ${e.ref} -> ${e.message}`);
+  }
+  return lines.join("\n");
+}
 var SecRefsResolutionError = class extends Error {
   constructor(errors) {
-    super(
-      `Failed to resolve ${errors.length} secret reference(s):
-` + errors.map((e) => `  - ${e.key}: ${e.ref} -> ${e.message}`).join("\n")
-    );
+    super(formatFailures(errors));
     this.errors = errors;
     this.name = "SecRefsResolutionError";
   }
   errors;
+  /** True when every failure was an environment/auth problem, so a caller
+   * can tell "your credentials lapsed" from "your references are wrong". */
+  get isAuthOnly() {
+    return this.errors.length > 0 && this.errors.every((e) => e.kind === "auth");
+  }
 };
 async function resolveOne(ref, providers) {
   const provider = providers[ref.provider];
@@ -662,7 +848,15 @@ async function expandKeyValueMap(input, options) {
     if (result.status === "fulfilled") {
       output[key] = result.value;
     } else {
-      errors.push({ key, ref: ref.raw, message: errorMessage(result.reason) });
+      const reason = result.reason;
+      errors.push({
+        key,
+        ref: ref.raw,
+        message: errorMessage(reason),
+        kind: reason instanceof SecretFetchError ? reason.kind : void 0,
+        provider: reason instanceof SecretFetchError ? reason.provider : ref.provider,
+        remedy: reason instanceof SecretFetchError ? reason.remedy : void 0
+      });
     }
   });
   if (errors.length > 0) {
@@ -727,6 +921,128 @@ function parseEnvFileText(rawText) {
   return recoverTruncatedSecRefs(rawText, parsed);
 }
 
+// src/config.ts
+var import_node_fs = require("fs");
+var import_node_path2 = require("path");
+var CONFIG_FILENAME = "secrefs.config.json";
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+var FORBIDDEN_KEYS = /* @__PURE__ */ new Set([
+  "token",
+  "accessToken",
+  "access_token",
+  "secret",
+  "secretKey",
+  "secretAccessKey",
+  "password",
+  "apiKey",
+  "credential",
+  "credentials"
+]);
+function assertNoInlineSecrets(alias, config) {
+  for (const key of Object.keys(config)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      throw new ConfigError(
+        `${CONFIG_FILENAME}: provider "${alias}" sets "${key}". This file is meant to be committed and must never contain a credential. Reference the environment variable that holds it instead - e.g. "tokenEnv": "BWS_ACCESS_TOKEN".`
+      );
+    }
+  }
+}
+function requireEnv(alias, varName, env) {
+  const value = env[varName];
+  if (!value) {
+    throw new ConfigError(
+      `${CONFIG_FILENAME}: provider "${alias}" expects the credential in ${varName}, but that environment variable is not set.`
+    );
+  }
+  return value;
+}
+function parseConfig(raw, source = CONFIG_FILENAME) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new ConfigError(`${source} is not valid JSON: ${err.message}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new ConfigError(`${source} must contain a JSON object.`);
+  }
+  const providers = parsed.providers;
+  if (typeof providers !== "object" || providers === null) {
+    throw new ConfigError(`${source} must have a "providers" object.`);
+  }
+  for (const [alias, value] of Object.entries(providers)) {
+    if (typeof value !== "object" || value === null) {
+      throw new ConfigError(`${source}: provider "${alias}" must be an object.`);
+    }
+    const type = value.type;
+    if (type !== "aws" && type !== "bitwarden" && type !== "vault" && type !== "local") {
+      throw new ConfigError(
+        `${source}: provider "${alias}" has type ${JSON.stringify(type)}; expected one of "aws", "bitwarden", "vault", "local".`
+      );
+    }
+    assertNoInlineSecrets(alias, value);
+  }
+  return parsed;
+}
+function buildProviders(config, options = {}) {
+  const env = options.env ?? process.env;
+  const configDir = options.configDir ?? process.cwd();
+  const registry = {};
+  for (const [alias, entry] of Object.entries(config.providers)) {
+    switch (entry.type) {
+      case "aws":
+        registry[alias] = new AwsSecretsManagerProvider({
+          region: entry.region,
+          cacheTtlMs: entry.cacheTtlMs,
+          staleGraceMs: entry.staleGraceMs,
+          profile: entry.profile
+        });
+        break;
+      case "bitwarden":
+        registry[alias] = new BitwardenProvider({
+          accessToken: requireEnv(alias, entry.tokenEnv ?? "BWS_ACCESS_TOKEN", env),
+          organizationId: entry.organizationIdEnv ? requireEnv(alias, entry.organizationIdEnv, env) : env.BWS_ORGANIZATION_ID,
+          apiUrl: entry.apiUrl,
+          identityUrl: entry.identityUrl
+        });
+        break;
+      case "vault":
+        registry[alias] = new VaultProvider({
+          endpoint: entry.addr ?? env.VAULT_ADDR,
+          token: requireEnv(alias, entry.tokenEnv ?? "VAULT_TOKEN", env)
+        });
+        break;
+      case "local":
+        registry[alias] = new LocalProvider({
+          filePath: entry.file ? (0, import_node_path2.resolve)(configDir, entry.file) : void 0
+        });
+        break;
+    }
+  }
+  return registry;
+}
+function loadConfigFrom(dir = process.cwd()) {
+  let current = (0, import_node_path2.resolve)(dir);
+  for (; ; ) {
+    const candidate = (0, import_node_path2.resolve)(current, CONFIG_FILENAME);
+    let raw;
+    try {
+      raw = (0, import_node_fs.readFileSync)(candidate, "utf8");
+    } catch {
+      const parent = (0, import_node_path2.dirname)(current);
+      if (parent === current) return void 0;
+      current = parent;
+      continue;
+    }
+    return { config: parseConfig(raw, candidate), path: candidate };
+  }
+}
+
 // src/index.ts
 function createDefaultProviders() {
   return {
@@ -780,6 +1096,8 @@ var secRefs = new SecRefs();
   AwsSecretsManagerProvider,
   BaseSecretProvider,
   BitwardenProvider,
+  CONFIG_FILENAME,
+  ConfigError,
   ControlPlaneClient,
   ControlPlaneRequestError,
   LocalProvider,
@@ -789,12 +1107,15 @@ var secRefs = new SecRefs();
   SecretFetchError,
   TtlCache,
   VaultProvider,
+  buildProviders,
   checkReferences,
   createDefaultProviders,
   expandKeyValueMap,
   expandProcessEnv,
   extractField,
   isSecretRef,
+  loadConfigFrom,
+  parseConfig,
   parseEnvFileText,
   parseSecretRef,
   recoverTruncatedSecRefs,