@secrefs/node 0.1.0

package/dist/secrefs.cjs

@@ -0,0 +1,876 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// bin/secrefs.ts
+var import_node_fs = require("fs");
+var import_node_path2 = __toESM(require("path"), 1);
+var import_commander = require("commander");
+var import_cross_spawn = __toESM(require("cross-spawn"), 1);
+
+// src/providers/aws.ts
+var import_client_secrets_manager = require("@aws-sdk/client-secrets-manager");
+
+// src/providers/base.ts
+var SecretFetchError = class extends Error {
+  constructor(provider, path3, cause) {
+    super(`[${provider}] failed to fetch secret at "${path3}": ${errorMessage(cause)}`);
+    this.provider = provider;
+    this.path = path3;
+    this.name = "SecretFetchError";
+  }
+  provider;
+  path;
+};
+var BaseSecretProvider = class {
+  async fetchBatch(requests) {
+    const settled = await Promise.allSettled(requests.map((r) => this.fetchOne(r)));
+    return settled.map((result, i) => {
+      const request = requests[i];
+      if (result.status === "fulfilled") {
+        return result.value;
+      }
+      throw new SecretFetchError(this.name, request?.path ?? "<unknown>", result.reason);
+    });
+  }
+};
+function errorMessage(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+function extractField(raw, field, context) {
+  if (!field) return raw;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      `[${context.provider}] secret at "${context.path}" is not JSON, cannot extract field "${field}"`
+    );
+  }
+  let current = parsed;
+  for (const part of field.split(".")) {
+    if (current === null || typeof current !== "object") {
+      throw new Error(
+        `[${context.provider}] field "${field}" not found in secret at "${context.path}"`
+      );
+    }
+    current = current[part];
+  }
+  if (current === void 0) {
+    throw new Error(
+      `[${context.provider}] field "${field}" not found in secret at "${context.path}"`
+    );
+  }
+  return typeof current === "object" ? JSON.stringify(current) : String(current);
+}
+
+// src/ttlCache.ts
+var TtlCache = class {
+  /** Settled values, only populated when a TTL is configured. */
+  entries = /* @__PURE__ */ new Map();
+  /** Requests currently in flight, tracked separately from `entries`
+   * because coalescing and caching are different things: sharing an
+   * unsettled request holds no value past the moment it resolves, so it
+   * stays correct even with caching fully disabled. */
+  inFlight = /* @__PURE__ */ new Map();
+  ttlMs;
+  now;
+  constructor(options = {}) {
+    this.ttlMs = options.ttlMs ?? 0;
+    this.now = options.now ?? Date.now;
+  }
+  /**
+   * Returns the cached value for `key` if it's still fresh, otherwise
+   * calls `load` and caches that. In-flight promises are shared, so N
+   * concurrent expansions of the same reference make one request rather
+   * than N even when the TTL is zero - that's request coalescing, not
+   * caching, and it doesn't hold a value past its use.
+   *
+   * A rejected load is evicted rather than remembered, so a transient
+   * failure doesn't become a sticky one.
+   */
+  async fetch(key, load) {
+    const pendingExisting = this.inFlight.get(key);
+    if (pendingExisting) return pendingExisting;
+    const cached = this.entries.get(key);
+    if (cached && this.ttlMs > 0 && this.now() - cached.storedAt < this.ttlMs) {
+      return cached.value;
+    }
+    const pending = load();
+    this.inFlight.set(key, pending);
+    try {
+      const value = await pending;
+      if (this.ttlMs > 0) {
+        this.entries.set(key, { value: Promise.resolve(value), storedAt: this.now() });
+      }
+      return value;
+    } catch (err) {
+      this.entries.delete(key);
+      throw err;
+    } finally {
+      this.inFlight.delete(key);
+    }
+  }
+  /** Drops everything - used when a credential changes underneath the
+   * cache and anything fetched with the old one is suspect. */
+  clear() {
+    this.entries.clear();
+  }
+};
+
+// src/controlPlaneClient.ts
+var ControlPlaneRequestError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "ControlPlaneRequestError";
+  }
+  status;
+};
+var ControlPlaneClient = class {
+  baseUrl;
+  token;
+  fetchImpl;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.token = options.token;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  /** Authenticates, authorizes, and resolves a credential for `alias`/`path`
+   * - see the control plane's `POST /v1/credentials/mint`. Throws
+   * `ControlPlaneRequestError` for any non-2xx response. */
+  async mintCredential(alias, path3) {
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}/v1/credentials/mint`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${this.token}` },
+        body: JSON.stringify({ alias, path: path3 })
+      });
+    } catch (err) {
+      throw new Error(
+        `could not reach control plane at ${this.baseUrl}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw new ControlPlaneRequestError(
+        response.status,
+        body.error ?? `control plane returned ${response.status} for alias "${alias}" path "${path3}"`
+      );
+    }
+    return await response.json();
+  }
+};
+
+// src/providers/aws.ts
+var AwsSecretsManagerProvider = class extends BaseSecretProvider {
+  name = "aws";
+  explicitClient;
+  region;
+  controlPlane;
+  controlPlaneClient;
+  ambientClient = null;
+  rawCache;
+  constructor(options = {}) {
+    super();
+    this.explicitClient = options.client;
+    this.region = options.region;
+    this.controlPlane = options.controlPlane;
+    this.rawCache = new TtlCache({ ttlMs: options.cacheTtlMs });
+    if (this.controlPlane) {
+      this.controlPlaneClient = this.controlPlane.client ?? new ControlPlaneClient({ baseUrl: this.controlPlane.baseUrl, token: this.controlPlane.token });
+    }
+  }
+  /** Resolves the `SecretsManagerClient` to use for one `path` - lazily
+   * built and reused in ambient mode, freshly minted per call in
+   * control-plane mode. `explicitClient` (test injection) always wins. */
+  async clientFor(path3) {
+    if (this.explicitClient) return this.explicitClient;
+    if (this.controlPlane && this.controlPlaneClient) {
+      const minted = await this.controlPlaneClient.mintCredential(this.controlPlane.alias, path3);
+      if (minted.provider !== "aws") {
+        throw new Error(
+          `control plane returned a "${minted.provider}" credential for alias "${this.controlPlane.alias}", expected "aws"`
+        );
+      }
+      return this.buildClientFromMintedCredentials(minted.credentials);
+    }
+    if (!this.ambientClient) this.ambientClient = new import_client_secrets_manager.SecretsManagerClient({ region: this.region });
+    return this.ambientClient;
+  }
+  buildClientFromMintedCredentials(credentials) {
+    return new import_client_secrets_manager.SecretsManagerClient({
+      region: this.region,
+      credentials: {
+        accessKeyId: credentials.accessKeyId,
+        secretAccessKey: credentials.secretAccessKey,
+        sessionToken: credentials.sessionToken
+      }
+    });
+  }
+  getRaw(path3) {
+    return this.rawCache.fetch(path3, async () => {
+      try {
+        const client = await this.clientFor(path3);
+        const response = await client.send(new import_client_secrets_manager.GetSecretValueCommand({ SecretId: path3 }));
+        if (typeof response.SecretString === "string") {
+          return response.SecretString;
+        }
+        if (response.SecretBinary) {
+          return Buffer.from(response.SecretBinary).toString("utf8");
+        }
+        throw new Error(`secret "${path3}" has no SecretString or SecretBinary payload`);
+      } catch (err) {
+        throw new Error(`could not fetch secret "${path3}": ${errorMessage(err)}`);
+      }
+    });
+  }
+  async fetchOne(request) {
+    const raw = await this.getRaw(request.path);
+    return extractField(raw, request.field, { provider: this.name, path: request.path });
+  }
+  async healthCheck() {
+    try {
+      if (this.controlPlane) {
+        const controlPlaneClient = this.controlPlane.client ?? new ControlPlaneClient({ baseUrl: this.controlPlane.baseUrl, token: this.controlPlane.token });
+        try {
+          await controlPlaneClient.mintCredential(this.controlPlane.alias, "__secrefs_health_check__");
+        } catch (err) {
+          if (err instanceof ControlPlaneRequestError) {
+            return { provider: this.name, ok: true, message: "control plane reachable" };
+          }
+          throw err;
+        }
+        return { provider: this.name, ok: true };
+      }
+      const client = await this.clientFor("__secrefs_health_check__");
+      await client.send(new import_client_secrets_manager.ListSecretsCommand({ MaxResults: 1 }));
+      return { provider: this.name, ok: true };
+    } catch (err) {
+      return { provider: this.name, ok: false, message: errorMessage(err) };
+    }
+  }
+};
+
+// src/providers/vault.ts
+var import_node_vault = __toESM(require("node-vault"), 1);
+var VaultProvider = class extends BaseSecretProvider {
+  name = "vault";
+  explicitClient;
+  endpoint;
+  token;
+  client = null;
+  dataCache;
+  constructor(options = {}) {
+    super();
+    this.explicitClient = options.client;
+    this.endpoint = options.endpoint ?? process.env.VAULT_ADDR;
+    this.token = options.token ?? process.env.VAULT_TOKEN;
+    this.dataCache = new TtlCache({ ttlMs: options.cacheTtlMs });
+  }
+  getClient() {
+    if (this.explicitClient) return this.explicitClient;
+    if (this.client) return this.client;
+    if (!this.endpoint) {
+      throw new Error("VAULT_ADDR is not set (required for sec://vault/... references)");
+    }
+    if (!this.token) {
+      throw new Error("VAULT_TOKEN is not set (required for sec://vault/... references)");
+    }
+    this.client = (0, import_node_vault.default)({ endpoint: this.endpoint, token: this.token });
+    return this.client;
+  }
+  getData(path3) {
+    return this.dataCache.fetch(
+      path3,
+      () => this.getClient().read(path3).then((response) => {
+        const outer = response.data;
+        if (outer === void 0 || outer === null) {
+          throw new Error(`no data returned for path "${path3}"`);
+        }
+        if (typeof outer === "object" && "data" in outer && "metadata" in outer) {
+          return outer.data;
+        }
+        return outer;
+      }).catch((err) => {
+        throw new Error(`could not read Vault path "${path3}": ${errorMessage(err)}`);
+      })
+    );
+  }
+  async fetchOne(request) {
+    const data = await this.getData(request.path);
+    if (!request.field) {
+      const keys = Object.keys(data);
+      if (keys.length === 1) {
+        const only = data[keys[0]];
+        return typeof only === "string" ? only : JSON.stringify(only);
+      }
+      return JSON.stringify(data);
+    }
+    return extractField(JSON.stringify(data), request.field, {
+      provider: this.name,
+      path: request.path
+    });
+  }
+  async healthCheck() {
+    try {
+      await this.getClient().health();
+      return { provider: this.name, ok: true };
+    } catch (err) {
+      return { provider: this.name, ok: false, message: errorMessage(err) };
+    }
+  }
+};
+
+// src/providers/local.ts
+var import_promises = require("fs/promises");
+var import_node_path = __toESM(require("path"), 1);
+var DEFAULT_FILENAME = ".secrefs.local.json";
+var LocalProvider = class extends BaseSecretProvider {
+  name = "local";
+  filePath;
+  /** Re-read on every fetch. The file is local and tiny, and caching
+   * it meant editing it mid-session silently did nothing. */
+  cache = null;
+  cacheFile;
+  constructor(options = {}) {
+    super();
+    this.filePath = options.filePath ?? process.env.SECREFS_LOCAL_FILE ?? import_node_path.default.join(process.cwd(), DEFAULT_FILENAME);
+    this.cacheFile = options.cacheFile ?? false;
+  }
+  async load() {
+    if (this.cache && this.cacheFile) return this.cache;
+    let raw;
+    try {
+      raw = await (0, import_promises.readFile)(this.filePath, "utf8");
+    } catch (err) {
+      throw new Error(
+        `[local] could not read local secrets file at "${this.filePath}": ${err instanceof Error ? err.message : String(err)}. This file is gitignored by convention - see .secrefs.local.json in .gitignore.`
+      );
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(
+        `[local] "${this.filePath}" is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`[local] "${this.filePath}" must contain a top-level JSON object`);
+    }
+    this.cache = parsed;
+    return this.cache;
+  }
+  async fetchOne(request) {
+    const data = await this.load();
+    if (!(request.path in data)) {
+      throw new Error(`[local] no entry for path "${request.path}" in ${this.filePath}`);
+    }
+    const entry = data[request.path];
+    const raw = typeof entry === "string" ? entry : JSON.stringify(entry);
+    return extractField(raw, request.field, { provider: this.name, path: request.path });
+  }
+  async healthCheck() {
+    try {
+      await this.load();
+      return { provider: this.name, ok: true, message: this.filePath };
+    } catch (err) {
+      return {
+        provider: this.name,
+        ok: false,
+        message: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+};
+
+// src/providers/bitwarden.ts
+var import_sdk_napi = require("@bitwarden/sdk-napi");
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var BitwardenProvider = class extends BaseSecretProvider {
+  name = "bitwarden";
+  explicitClient;
+  ambientAccessToken;
+  ambientOrganizationId;
+  apiUrl;
+  identityUrl;
+  stateFile;
+  controlPlane;
+  controlPlaneClient;
+  client = null;
+  loggedInAccessToken = null;
+  loggedIn = null;
+  organizationId;
+  /** Secret name -> id, populated by one `list()` call the first time a
+   * non-UUID path is requested. Invalidated if `organizationId` ever
+   * changes (control-plane mode, defensively - static in practice). */
+  nameToId = null;
+  constructor(options = {}) {
+    super();
+    this.explicitClient = options.client;
+    this.apiUrl = options.apiUrl ?? process.env.BWS_API_URL;
+    this.identityUrl = options.identityUrl ?? process.env.BWS_IDENTITY_URL;
+    this.stateFile = options.stateFile;
+    this.controlPlane = options.controlPlane;
+    if (this.controlPlane) {
+      this.controlPlaneClient = this.controlPlane.client ?? new ControlPlaneClient({ baseUrl: this.controlPlane.baseUrl, token: this.controlPlane.token });
+    } else {
+      this.ambientAccessToken = options.accessToken ?? process.env.BWS_ACCESS_TOKEN;
+      this.ambientOrganizationId = options.organizationId ?? process.env.BWS_ORGANIZATION_ID;
+      this.organizationId = this.ambientOrganizationId;
+    }
+  }
+  getClient() {
+    if (this.explicitClient) return this.explicitClient;
+    if (this.client) return this.client;
+    this.client = new import_sdk_napi.BitwardenClient({
+      apiUrl: this.apiUrl,
+      identityUrl: this.identityUrl
+    });
+    return this.client;
+  }
+  async loginWith(accessToken, organizationId) {
+    if (organizationId !== this.organizationId) {
+      this.nameToId = null;
+      this.organizationId = organizationId;
+    }
+    if (this.loggedInAccessToken === accessToken && this.loggedIn) return this.loggedIn;
+    this.loggedInAccessToken = accessToken;
+    this.loggedIn = this.getClient().auth().loginAccessToken(accessToken, this.stateFile).catch((err) => {
+      this.loggedIn = null;
+      this.loggedInAccessToken = null;
+      throw new Error(`could not authenticate with the given access token: ${errorMessage(err)}`);
+    });
+    return this.loggedIn;
+  }
+  /** Ensures a session exists for `path`. Ambient mode logs in once
+   * (memoized) with the ambient token; control-plane mode requests a
+   * distribution for this specific `path` every call - see the
+   * `controlPlane` option's docs for why that RBAC check has to be
+   * per-path even though the token it returns doesn't vary. */
+  async ensureLoggedInFor(path3) {
+    if (!this.controlPlane) {
+      if (!this.ambientAccessToken) {
+        throw new Error("BWS_ACCESS_TOKEN is not set (required for sec://bitwarden/... references)");
+      }
+      return this.loginWith(this.ambientAccessToken, this.ambientOrganizationId);
+    }
+    const minted = await this.controlPlaneClient.mintCredential(this.controlPlane.alias, path3);
+    if (minted.provider !== "bitwarden") {
+      throw new Error(
+        `control plane returned a "${minted.provider}" credential for alias "${this.controlPlane.alias}", expected "bitwarden"`
+      );
+    }
+    return this.loginWith(minted.credentials.accessToken, minted.credentials.organizationId);
+  }
+  /** Assumes `ensureLoggedInFor(path)` has already run for this exact
+   * `path` - callers always do that first, so `this.organizationId` is
+   * already whatever this path's session resolved to. */
+  async resolveSecretId(path3) {
+    if (UUID_PATTERN.test(path3)) return path3;
+    if (!this.organizationId) {
+      throw new Error(
+        `"${path3}" is not a secret UUID, and no organizationId is available to look up a secret by name (set BWS_ORGANIZATION_ID, use the UUID directly, or - in control-plane mode - the distributed credential didn't include one)`
+      );
+    }
+    if (!this.nameToId) {
+      const organizationId = this.organizationId;
+      this.nameToId = (async () => {
+        const { data } = await this.getClient().secrets().list(organizationId);
+        return new Map(data.map((s) => [s.key, s.id]));
+      })();
+    }
+    const map = await this.nameToId;
+    const id = map.get(path3);
+    if (!id) {
+      throw new Error(`no secret named "${path3}" found in organization "${this.organizationId}"`);
+    }
+    return id;
+  }
+  async fetchOne(request) {
+    let id;
+    let secret;
+    try {
+      await this.ensureLoggedInFor(request.path);
+      id = await this.resolveSecretId(request.path);
+      secret = await this.getClient().secrets().get(id);
+    } catch (err) {
+      throw new Error(`could not fetch secret "${request.path}": ${errorMessage(err)}`);
+    }
+    return extractField(secret.value, request.field, { provider: this.name, path: request.path });
+  }
+  async healthCheck() {
+    try {
+      await this.ensureLoggedInFor("__secrefs_health_check__");
+      return { provider: this.name, ok: true };
+    } catch (err) {
+      return { provider: this.name, ok: false, message: errorMessage(err) };
+    }
+  }
+};
+
+// src/parser.ts
+var SEC_REF_PATTERN = /^sec:\/\/([a-zA-Z0-9][a-zA-Z0-9_-]*)\/([^\s#]+)(?:#([^\s#]+))?$/;
+var SecRefParseError = class extends Error {
+  constructor(raw, reason) {
+    super(`Invalid secret reference "${raw}": ${reason}`);
+    this.raw = raw;
+    this.reason = reason;
+    this.name = "SecRefParseError";
+  }
+  raw;
+  reason;
+};
+function isSecretRef(value) {
+  return typeof value === "string" && value.startsWith("sec://");
+}
+function parseSecretRef(raw) {
+  if (typeof raw !== "string") {
+    throw new SecRefParseError(String(raw), "reference must be a string");
+  }
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("sec://")) {
+    throw new SecRefParseError(raw, 'must start with "sec://"');
+  }
+  const match = SEC_REF_PATTERN.exec(trimmed);
+  if (!match) {
+    throw new SecRefParseError(
+      raw,
+      "does not match sec://<provider>/<path>[#field] format"
+    );
+  }
+  const [, provider, path3, field] = match;
+  if (!provider) {
+    throw new SecRefParseError(raw, "missing provider alias");
+  }
+  if (!path3) {
+    throw new SecRefParseError(raw, "missing secret path");
+  }
+  return {
+    raw,
+    provider: provider.toLowerCase(),
+    path: path3,
+    field: field || void 0
+  };
+}
+
+// src/resolver.ts
+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")
+    );
+    this.errors = errors;
+    this.name = "SecRefsResolutionError";
+  }
+  errors;
+};
+async function resolveOne(ref, providers) {
+  const provider = providers[ref.provider];
+  if (!provider) {
+    const available = Object.keys(providers).join(", ") || "none configured";
+    throw new Error(`unknown provider "${ref.provider}" (available: ${available})`);
+  }
+  const request = { path: ref.path, field: ref.field };
+  return provider.fetchOne(request);
+}
+async function expandKeyValueMap(input, options) {
+  const strict = options.strict ?? true;
+  const output = {};
+  const pending = [];
+  for (const [key, value] of Object.entries(input)) {
+    if (value === void 0) continue;
+    if (!isSecretRef(value)) {
+      output[key] = value;
+      continue;
+    }
+    try {
+      pending.push({ key, ref: parseSecretRef(value) });
+    } catch (err) {
+      if (strict) throw err;
+      output[key] = value;
+    }
+  }
+  if (pending.length === 0) {
+    return output;
+  }
+  const settled = await Promise.allSettled(
+    pending.map(({ ref }) => resolveOne(ref, options.providers))
+  );
+  const errors = [];
+  settled.forEach((result, i) => {
+    const { key, ref } = pending[i];
+    if (result.status === "fulfilled") {
+      output[key] = result.value;
+    } else {
+      errors.push({ key, ref: ref.raw, message: errorMessage(result.reason) });
+    }
+  });
+  if (errors.length > 0) {
+    throw new SecRefsResolutionError(errors);
+  }
+  return output;
+}
+async function expandProcessEnv(options) {
+  const resolved = await expandKeyValueMap(process.env, options);
+  const changedKeys = [];
+  for (const [key, value] of Object.entries(resolved)) {
+    if (process.env[key] !== value) {
+      process.env[key] = value;
+      changedKeys.push(key);
+    }
+  }
+  return changedKeys;
+}
+async function checkReferences(input, options) {
+  const results = [];
+  const parsedEntries = [];
+  for (const [key, value] of Object.entries(input)) {
+    if (value === void 0 || !isSecretRef(value)) continue;
+    try {
+      parsedEntries.push({ key, ref: parseSecretRef(value) });
+    } catch (err) {
+      results.push({ key, ref: value, provider: "unknown", ok: false, message: errorMessage(err) });
+    }
+  }
+  const settled = await Promise.allSettled(
+    parsedEntries.map(({ ref }) => resolveOne(ref, options.providers))
+  );
+  settled.forEach((result, i) => {
+    const { key, ref } = parsedEntries[i];
+    results.push({
+      key,
+      ref: ref.raw,
+      provider: ref.provider,
+      ok: result.status === "fulfilled",
+      message: result.status === "rejected" ? errorMessage(result.reason) : void 0
+    });
+  });
+  return results;
+}
+
+// src/envFile.ts
+var import_dotenv = require("dotenv");
+var UNQUOTED_SEC_REF_LINE = /^[ \t]*(?:export[ \t]+)?([A-Za-z_][A-Za-z0-9_]*)[ \t]*=[ \t]*(sec:\/\/\S.*)$/;
+function recoverTruncatedSecRefs(rawText, parsed) {
+  const result = { ...parsed };
+  for (const line of rawText.split(/\r?\n/)) {
+    const match = UNQUOTED_SEC_REF_LINE.exec(line);
+    if (!match) continue;
+    const [, key, value] = match;
+    if (!key || value === void 0) continue;
+    result[key] = value.trimEnd();
+  }
+  return result;
+}
+function parseEnvFileText(rawText) {
+  const parsed = (0, import_dotenv.parse)(rawText);
+  return recoverTruncatedSecRefs(rawText, parsed);
+}
+
+// src/index.ts
+function createDefaultProviders() {
+  return {
+    aws: new AwsSecretsManagerProvider(),
+    vault: new VaultProvider(),
+    local: new LocalProvider(),
+    bitwarden: new BitwardenProvider()
+  };
+}
+var SecRefs = class {
+  providers;
+  strict;
+  constructor(options = {}) {
+    this.providers = options.providers ?? createDefaultProviders();
+    this.strict = options.strict ?? true;
+  }
+  get expandOptions() {
+    return { providers: this.providers, strict: this.strict };
+  }
+  /**
+   * Expands every `sec://` value found in `process.env`, mutating it in
+   * place. Returns the list of env var names that were rewritten.
+   */
+  async init() {
+    return expandProcessEnv(this.expandOptions);
+  }
+  /**
+   * Expands `sec://` values in an arbitrary key/value map (e.g. a parsed
+   * `.env` file) without touching `process.env`.
+   */
+  async expandEnv(env) {
+    return expandKeyValueMap(env, this.expandOptions);
+  }
+  /** Expands a single string if it's a `sec://` reference; otherwise returns it unchanged. */
+  async expandString(value) {
+    if (!isSecretRef(value)) return value;
+    const resolved = await expandKeyValueMap({ __value__: value }, this.expandOptions);
+    return resolved.__value__;
+  }
+  /**
+   * Dry-run validation of every `sec://` reference in `env` (defaults to
+   * `process.env`). Never returns plaintext secret values.
+   */
+  async check(env = process.env) {
+    return checkReferences(env, this.expandOptions);
+  }
+};
+var secRefs = new SecRefs();
+
+// bin/secrefs.ts
+var CLI_VERSION = "0.1.0";
+function loadEnvFile(opts) {
+  if (opts.envFile === false) return;
+  const envFilePath = import_node_path2.default.resolve(process.cwd(), opts.envFile);
+  if (!(0, import_node_fs.existsSync)(envFilePath)) return;
+  let rawText;
+  try {
+    rawText = (0, import_node_fs.readFileSync)(envFilePath, "utf8");
+  } catch (err) {
+    console.error(
+      `secrefs: failed to read ${envFilePath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    process.exitCode = 1;
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = parseEnvFileText(rawText);
+  } catch (err) {
+    console.error(
+      `secrefs: failed to parse ${envFilePath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    process.exitCode = 1;
+    throw err;
+  }
+  for (const [key, value] of Object.entries(parsed)) {
+    if (process.env[key] === void 0) {
+      process.env[key] = value;
+    }
+  }
+}
+async function runCommand(commandArgs, opts) {
+  if (commandArgs.length === 0) {
+    console.error("secrefs run: no command given. Usage: secrefs run -- <command> [args...]");
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    loadEnvFile(opts);
+  } catch {
+    return;
+  }
+  const instance = new SecRefs();
+  try {
+    const changedKeys = await instance.init();
+    if (changedKeys.length > 0) {
+      console.error(
+        `secrefs: resolved ${changedKeys.length} secret reference(s): ${changedKeys.join(", ")}`
+      );
+    }
+  } catch (err) {
+    if (err instanceof SecRefsResolutionError) {
+      console.error("secrefs: failed to resolve one or more secret references:");
+      console.error(err.message);
+    } else {
+      console.error(`secrefs: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const [cmd, ...args] = commandArgs;
+  const child = (0, import_cross_spawn.default)(cmd, args, { stdio: "inherit", env: process.env });
+  const forwardedSignals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  const handlers = /* @__PURE__ */ new Map();
+  for (const signal of forwardedSignals) {
+    const handler = () => {
+      if (child.pid) child.kill(signal);
+    };
+    handlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+  const cleanupSignalHandlers = () => {
+    for (const [signal, handler] of handlers) {
+      process.removeListener(signal, handler);
+    }
+  };
+  child.on("error", (err) => {
+    cleanupSignalHandlers();
+    console.error(`secrefs: failed to start "${cmd}": ${err.message}`);
+    process.exitCode = 1;
+  });
+  child.on("exit", (code, signal) => {
+    cleanupSignalHandlers();
+    if (signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exitCode = code ?? 0;
+    }
+  });
+}
+async function checkCommand(opts) {
+  try {
+    loadEnvFile(opts);
+  } catch {
+    return;
+  }
+  const instance = new SecRefs();
+  const results = await instance.check();
+  if (results.length === 0) {
+    console.log("secrefs check: no sec:// references found in the environment.");
+    return;
+  }
+  let failureCount = 0;
+  for (const result of results) {
+    const icon = result.ok ? "\u2713" : "\u2717";
+    console.log(`${icon} ${result.key} -> ${result.ref}`);
+    if (!result.ok) {
+      failureCount += 1;
+      console.error(`    ${result.message}`);
+    }
+  }
+  const okCount = results.length - failureCount;
+  console.log(`
+${okCount}/${results.length} reference(s) resolved successfully.`);
+  if (failureCount > 0) {
+    process.exitCode = 1;
+  }
+}
+var program = new import_commander.Command();
+program.name("secrefs").description("BYOV secret reference engine - expand sec:// references in memory at runtime").version(CLI_VERSION);
+program.command("run").description("Resolve sec:// references and spawn a child process with the hydrated environment").option("-f, --env-file <path>", "path to a .env file to load before resolving", ".env").option("--no-env-file", "skip loading a .env file").argument("<command...>", "command to run, e.g. secrefs run -- node server.js").action(async (commandArgs, opts) => {
+  await runCommand(commandArgs, opts);
+});
+program.command("check").description("Validate sec:// references and provider reachability without printing plaintext values").option("-f, --env-file <path>", "path to a .env file to load before checking", ".env").option("--no-env-file", "skip loading a .env file").action(async (opts) => {
+  await checkCommand(opts);
+});
+program.parseAsync(process.argv).catch((err) => {
+  console.error(`secrefs: unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exitCode = 1;
+});
+//# sourceMappingURL=secrefs.cjs.map