bulgur 1.1.0 → 1.2.0

package/README.md

@@ -61,17 +61,60 @@ publish time from the goreleaser build.
 
 ## Runtime SDK
 
-This package also exports a tiny, dependency-free runtime SDK for loading
+This package also exports a tiny runtime SDK for loading
 secrets into `process.env` at process startup — no CLI binary involved:
 
 ```js
 const { load } = require("bulgur");
 // or: import { load } from "bulgur";
 
-await load(); // reads BULGUR_DSN, assigns onto process.env
+await load(); // reads BULGUR_DSN from the environment or .env, then loads values
 ```
 
 Set `BULGUR_DSN` to a **runtime-scoped** token DSN:
 `bulgur://TOKEN@HOST/ORG/PROJECT/ENV`. See the repo root `README.md`
 ("Runtime (deploy platforms)") for platform examples. `load()` accepts
-`{ dsn, override, optional }` — see `index.d.ts` for details.
+`{ dsn, envFile, override, optional }` — see `index.d.ts` for details. Token mode has no runtime dependencies.
+
+In token mode, an explicit `dsn` takes precedence over the `BULGUR_DSN`
+process variable; if neither is set, the SDK reads only `BULGUR_DSN` from
+`.env` in the current working directory. It does not import other file variables
+into `process.env` or expand references. When bootstrapping from a file,
+`load()` also skips returned authentication-setting names so they cannot alter
+later authentication. Use `envFile: "path/to/file"` to
+select another file, or `envFile: false` to disable this lookup. A missing
+implicit `.env` is ignored; an explicitly selected missing file or a malformed
+file fails even with `optional: true`. Keep `.env` out of version control.
+Vercel OIDC never reads this file; its mode is selected by options or the
+process environment only.
+
+### Vercel OIDC runtime
+
+Vercel OIDC requires Node.js 20 or later and the optional helper:
+
+```sh
+npm install @vercel/oidc@^4.0.7
+```
+
+Create a Vercel workload identity in bulgur, and enable Vercel OIDC for the
+project. In a Vercel Function, call inside the request handler:
+
+```js
+const { loadValues } = require("bulgur");
+const values = await loadValues({
+  auth: "vercel-oidc",
+  identityId: process.env.BULGUR_IDENTITY_ID,
+});
+// Use values.DATABASE_URL in this request.
+```
+
+The identity chooses the environment. An optional tokenless
+`bulgur://api.bulgur.dev/ORG/PROJECT/ENV` DSN can select and verify the target;
+a token-bearing DSN is rejected in this mode. `BULGUR_AUTH=vercel-oidc` and
+`BULGUR_IDENTITY_ID` provide defaults. Explicit OIDC failures are always
+reported, including with `optional: true`; they never fall back to a token.
+
+`loadValues()` returns a request-local object and does not change `process.env`.
+`load()` writes process-global environment variables and is intended for
+one-time startup, not concurrent requests that can have different identities.
+The Vercel helper needs request context inside functions; avoid module-level calls.

package/bin/bulgur.js

@@ -2,7 +2,7 @@
 "use strict";
 
 // Thin launcher: pick the bundled bulgur binary that matches the host
-// platform/arch and exec it, forwarding stdio, the exit code, and signals.
+// platform/arch and run it, inheriting stdio and propagating its exit status.
 // The binaries are fat-bundled into this package at pack time (see the repo
 // Makefile `npm-pack` target), so there is NO network/postinstall step —
 // this works even while the GitHub repo is private.
@@ -40,9 +40,8 @@ if (!fs.existsSync(binPath)) {
   process.exit(1);
 }
 
-// spawnSync with stdio: inherit forwards stdin/stdout/stderr transparently and
-// relays terminating signals to the child on POSIX, so the run command's signal
-// handling keeps working.
+// Inherit stdio; if the child terminates by signal, re-raise that signal in
+// the launcher so the parent sees the corresponding termination cause.
 const result = spawnSync(binPath, process.argv.slice(2), { stdio: "inherit" });
 
 if (result.error) {

package/dotenv-dsn.js

@@ -0,0 +1,109 @@
+"use strict";
+
+const fs = require("node:fs/promises");
+const { constants } = require("node:fs");
+const MAX_BYTES = 1024 * 1024;
+const invalid = () => new Error("bulgur: invalid environment file");
+
+// Parse assignments without interpolation or modifying process.env. Parsing
+// the whole file prevents a malformed credential from silently falling back.
+function parseDSN(text) {
+  if (text.includes("\0")) throw invalid();
+  let i = 0;
+  let dsn;
+  let found = false;
+  if (text.charCodeAt(0) === 0xfeff) i++;
+  while (i < text.length) {
+    while (
+      text[i] === " " ||
+      text[i] === "\t" ||
+      text[i] === "\r" ||
+      text[i] === "\n"
+    )
+      i++;
+    if (i >= text.length) break;
+    if (text[i] === "#") {
+      while (i < text.length && text[i] !== "\n") i++;
+      continue;
+    }
+    if (text.startsWith("export ", i) || text.startsWith("export\t", i)) {
+      i += 7;
+      while (text[i] === " " || text[i] === "\t") i++;
+    }
+    const begin = i;
+    while (i < text.length && /[A-Za-z0-9_.-]/.test(text[i])) i++;
+    const key = text.slice(begin, i);
+    if (!key) throw invalid();
+    while (text[i] === " " || text[i] === "\t") i++;
+    if (text[i++] !== "=") throw invalid();
+    while (text[i] === " " || text[i] === "\t") i++;
+    let value = "";
+    if (text[i] === '"' || text[i] === "'") {
+      const quote = text[i++];
+      let closed = false;
+      while (i < text.length) {
+        const ch = text[i++];
+        if (ch === quote) {
+          closed = true;
+          break;
+        }
+        if (quote === '"' && ch === "\\" && i < text.length) {
+          const next = text[i++];
+          if (next === "n") value += "\n";
+          else if (next === "r") value += "\r";
+          else if (next === '"' || next === "\\") value += next;
+          else value += "\\" + next;
+        } else value += ch;
+      }
+      if (!closed) throw invalid();
+      while (text[i] === " " || text[i] === "\t" || text[i] === "\r") i++;
+      if (i < text.length && text[i] !== "\n" && text[i] !== "#")
+        throw invalid();
+    } else {
+      const start = i;
+      while (i < text.length && text[i] !== "\n" && text[i] !== "#") i++;
+      value = text.slice(start, i).trim();
+    }
+    if (text[i] === "#") while (i < text.length && text[i] !== "\n") i++;
+    if (i < text.length && text[i] === "\n") i++;
+    if (key === "BULGUR_DSN") {
+      if (found) throw invalid();
+      found = true;
+      if (!value || /[\s\x00-\x1f\x7f]/u.test(value)) throw invalid();
+      dsn = value;
+    }
+  }
+  return dsn;
+}
+
+async function readDSN(path, allowMissing) {
+  let file;
+  try {
+    file = await fs.open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size > MAX_BYTES) throw invalid();
+    const bytes = Buffer.alloc(MAX_BYTES + 1);
+    let used = 0;
+    while (used < bytes.length) {
+      const { bytesRead } = await file.read(
+        bytes,
+        used,
+        bytes.length - used,
+        null,
+      );
+      if (bytesRead === 0) break;
+      used += bytesRead;
+    }
+    if (used > MAX_BYTES) throw invalid();
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(
+      bytes.subarray(0, used),
+    );
+    return parseDSN(text);
+  } catch (err) {
+    if (allowMissing && err && err.code === "ENOENT") return undefined;
+    throw invalid();
+  } finally {
+    if (file) await file.close().catch(() => {});
+  }
+}
+module.exports = { readDSN };

package/index.d.ts

@@ -2,14 +2,27 @@
 // Hand-written; no build step. Kept in sync with index.js by hand.
 
 export interface LoadOptions {
+  /** Authentication mode. Defaults to BULGUR_AUTH or "token". */
+  auth?: "token" | "vercel-oidc";
+  /** Organization workload identity UUID (or BULGUR_IDENTITY_ID). */
+  identityId?: string;
   /**
    * The DSN to load, of the form `bulgur://TOKEN@HOST/ORG/PROJECT/ENV`.
-   * Defaults to `process.env.BULGUR_DSN`.
+   * In token mode, defaults to `process.env.BULGUR_DSN`, then `BULGUR_DSN`
+   * from the selected .env file. In Vercel OIDC mode, omit it to
+   * use the identity target, or use `bulgur://HOST/ORG/PROJECT/ENV` without a token.
    */
   dsn?: string;
 
+  /** Token mode only: custom .env path, or false to disable file lookup.
+   * Defaults to .env in the current working directory. An explicitly selected
+   * missing or malformed file throws, even when optional is true. When a DSN
+   * comes from this file, load() skips returned authentication-setting names.
+   */
+  envFile?: string | false;
+
   /**
-   * When true, values fetched from bulgur overwrite any existing
+   * For load() only: when true, values fetched from bulgur overwrite any existing
    * `process.env` entry with the same name.
    *
    * Default: false — existing `process.env` values win, and the fetched
@@ -18,10 +31,10 @@ export interface LoadOptions {
   override?: boolean;
 
   /**
-   * When true:
-   *   - a missing/empty DSN resolves `{ loaded: 0 }` instead of throwing.
-   *   - a network failure or non-2xx HTTP response resolves `{ loaded: 0 }`
-   *     instead of throwing.
+   * In token mode, when true, a missing DSN, network failure, or non-2xx
+   * response resolves with no values: load() returns `{ loaded: 0 }` and
+   * loadValues() returns an empty object. In Vercel OIDC mode, authentication
+   * and request failures always throw regardless of this option.
    * A DSN that IS present but malformed (bad scheme, missing token, wrong
    * number of path segments, etc.) always throws regardless of this option
    * — a configuration typo should be loud.
@@ -61,13 +74,18 @@ export interface ParsedDsn {
 
 /**
  * Load secret values for the environment identified by `options.dsn` (or
- * `process.env.BULGUR_DSN`) and assign them onto `process.env`.
+ * `process.env.BULGUR_DSN` or the selected .env file) and assign them onto `process.env`.
  *
- * This is a one-shot call: after it resolves, this module has no further
- * runtime effect and holds no open connections.
+ * Startup only: this writes process-global environment variables. Use
+ * loadValues for request-isolated access in concurrent serverless functions.
  */
 export function load(options?: LoadOptions): Promise<LoadResult>;
 
+/** Fetch values without mutating process.env. Use for request-isolated access. */
+export function loadValues(
+  options?: LoadOptions,
+): Promise<Record<string, string>>;
+
 /**
  * Parse and validate a `bulgur://TOKEN@HOST/ORG/PROJECT/ENV` DSN without
  * making a network call. Thrown error messages never include the token.

package/index.js

@@ -31,14 +31,14 @@ function parseDsn(dsn) {
   const schemeIdx = dsn.indexOf(SCHEME_SEP);
   if (schemeIdx === -1) {
     throw new Error(
-      'bulgur: invalid DSN: expected "bulgur://TOKEN@HOST/ORG/PROJECT/ENV"'
+      'bulgur: invalid DSN: expected "bulgur://TOKEN@HOST/ORG/PROJECT/ENV"',
     );
   }
 
   const scheme = dsn.slice(0, schemeIdx);
   if (scheme !== "bulgur") {
     throw new Error(
-      `bulgur: invalid DSN: scheme must be "bulgur", got "${scheme}"`
+      `bulgur: invalid DSN: scheme must be "bulgur", got "${scheme}"`,
     );
   }
 
@@ -48,7 +48,7 @@ function parseDsn(dsn) {
   const atIdx = rest.indexOf("@");
   if (atIdx === -1) {
     throw new Error(
-      "bulgur: invalid DSN: missing token (expected TOKEN@HOST/...)"
+      "bulgur: invalid DSN: missing token (expected TOKEN@HOST/...)",
     );
   }
 
@@ -61,7 +61,7 @@ function parseDsn(dsn) {
   const slashIdx = afterAt.indexOf("/");
   if (slashIdx === -1) {
     throw new Error(
-      "bulgur: invalid DSN: missing path (expected /ORG/PROJECT/ENV)"
+      "bulgur: invalid DSN: missing path (expected /ORG/PROJECT/ENV)",
     );
   }
 
@@ -79,7 +79,7 @@ function parseDsn(dsn) {
   if (segments.length !== 3 || segments.some((s) => s.length === 0)) {
     throw new Error(
       "bulgur: invalid DSN: path must have exactly 3 non-empty segments " +
-        `(/ORG/PROJECT/ENV), got ${segments.length} segment(s)`
+        `(/ORG/PROJECT/ENV), got ${segments.length} segment(s)`,
     );
   }
   const [org, project, envSlug] = segments;
@@ -114,21 +114,44 @@ function parseDsn(dsn) {
  * @param {{dsn?: string, override?: boolean, optional?: boolean}} [options]
  * @returns {Promise<{loaded: number}>}
  */
-async function load(options) {
+async function loadTokenValues(options) {
   const opts = options || {};
-  const dsn = opts.dsn !== undefined ? opts.dsn : process.env.BULGUR_DSN;
-  const override = opts.override === true;
+  let dsn;
+  let fromFile = false;
+  if (opts.dsn !== undefined) {
+    dsn = opts.dsn;
+  } else if (process.env.BULGUR_DSN !== undefined) {
+    dsn = process.env.BULGUR_DSN;
+  } else if (opts.envFile !== false) {
+    if (
+      opts.envFile !== undefined &&
+      (typeof opts.envFile !== "string" || !opts.envFile)
+    ) {
+      throw new Error("bulgur: invalid environment file");
+    }
+    dsn = await require("./dotenv-dsn.js").readDSN(
+      opts.envFile ?? ".env",
+      opts.envFile === undefined,
+    );
+    fromFile = dsn !== undefined;
+  }
   const optional = opts.optional === true;
 
   if (!dsn) {
-    if (optional) return { loaded: 0 };
+    if (optional) return { secrets: [], fromFile };
     throw new Error(
-      "bulgur: missing DSN (set BULGUR_DSN or pass { dsn } to load())"
+      "bulgur: missing DSN (set BULGUR_DSN or pass { dsn } to load())",
     );
   }
 
   // Malformed DSN is always loud, even with optional:true.
-  const parsed = parseDsn(dsn);
+  let parsed;
+  try {
+    parsed = parseDsn(dsn);
+  } catch (err) {
+    if (fromFile) throw new Error("bulgur: invalid environment file DSN");
+    throw err;
+  }
   const { token, host, org, project, env, baseUrl } = parsed;
 
   const url =
@@ -145,18 +168,22 @@ async function load(options) {
       },
     });
   } catch (err) {
-    if (optional) return { loaded: 0 };
+    if (optional) return { secrets: [], fromFile };
+    if (fromFile)
+      throw new Error("bulgur: environment file DSN request failed");
     throw new Error(
       `bulgur: failed to reach ${host} (org=${org}, project=${project}, ` +
-        `env=${env}): ${err && err.message ? err.message : err}`
+        `env=${env}): ${err && err.message ? err.message : err}`,
     );
   }
 
   if (!res.ok) {
-    if (optional) return { loaded: 0 };
+    if (optional) return { secrets: [], fromFile };
+    if (fromFile)
+      throw new Error("bulgur: environment file DSN request failed");
     throw new Error(
       `bulgur: request to ${host} failed with HTTP ${res.status} ` +
-        `(org=${org}, project=${project}, env=${env})`
+        `(org=${org}, project=${project}, env=${env})`,
     );
   }
 
@@ -164,28 +191,71 @@ async function load(options) {
   try {
     body = await res.json();
   } catch (err) {
-    if (optional) return { loaded: 0 };
+    if (optional) return { secrets: [], fromFile };
+    if (fromFile)
+      throw new Error("bulgur: environment file DSN request failed");
     throw new Error(
       `bulgur: failed to parse response from ${host} as JSON ` +
-        `(org=${org}, project=${project}, env=${env})`
+        `(org=${org}, project=${project}, env=${env})`,
     );
   }
 
-  const secrets = body && Array.isArray(body.secrets) ? body.secrets : [];
+  return {
+    secrets: body && Array.isArray(body.secrets) ? body.secrets : [],
+    fromFile,
+  };
+}
+
+const reserved = new Set([
+  "VERCEL_OIDC_TOKEN",
+  "VERCEL_OIDC_TOKEN_FILE",
+  "ACTIONS_ID_TOKEN_REQUEST_URL",
+  "ACTIONS_ID_TOKEN_REQUEST_TOKEN",
+  "BULGUR_AUTH",
+  "BULGUR_TOKEN",
+  "BULGUR_IDENTITY_ID",
+  "BULGUR_DSN",
+  "BULGUR_HOST",
+  "__proto__",
+]);
+function modeFor(opts) {
+  const mode = opts.auth ?? process.env.BULGUR_AUTH ?? "token";
+  if (mode !== "token" && mode !== "vercel-oidc")
+    throw new Error("bulgur: invalid authentication mode");
+  return mode;
+}
+async function fetchSecrets(opts, mode) {
+  return mode === "vercel-oidc"
+    ? { secrets: await require("./oidc.js").loadOIDC(opts), fromFile: false }
+    : loadTokenValues(opts);
+}
+async function loadValues(options) {
+  const opts = options || {};
+  const { secrets } = await fetchSecrets(opts, modeFor(opts));
+  const result = Object.create(null);
+  for (const secret of secrets) {
+    if (secret && typeof secret.name === "string")
+      result[secret.name] = secret.value == null ? "" : String(secret.value);
+  }
+  return result;
+}
+async function load(options) {
+  const opts = options || {};
+  const mode = modeFor(opts);
+  const { secrets, fromFile } = await fetchSecrets(opts, mode);
   let loaded = 0;
   for (const secret of secrets) {
     if (!secret || typeof secret.name !== "string") continue;
     const key = secret.name;
-    const hasExisting = Object.prototype.hasOwnProperty.call(
-      process.env,
-      key
-    );
-    if (hasExisting && !override) continue; // existing env vars win by default
+    if ((mode === "vercel-oidc" || fromFile) && reserved.has(key)) continue;
+    if (
+      Object.prototype.hasOwnProperty.call(process.env, key) &&
+      opts.override !== true
+    )
+      continue;
     process.env[key] = secret.value == null ? "" : String(secret.value);
     loaded++;
   }
-
   return { loaded };
 }
-
-module.exports = { load, parseDsn };
+module.exports = { load, loadValues, parseDsn };

package/oidc.js

@@ -0,0 +1,263 @@
+"use strict";
+
+const { createHash } = require("node:crypto");
+const sessions = new Map();
+const inflight = new Map();
+const targets = new Map();
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const fail = () =>
+  new Error("bulgur: Vercel OIDC authentication or request failed");
+
+function configFor(opts) {
+  const identity = opts.identityId ?? process.env.BULGUR_IDENTITY_ID;
+  if (
+    typeof identity !== "string" ||
+    !uuid.test(identity) ||
+    /^0{8}-0{4}-0{4}-0{4}-0{12}$/.test(identity)
+  )
+    throw fail();
+  const dsn = opts.dsn !== undefined ? opts.dsn : process.env.BULGUR_DSN;
+  if (!dsn) return { identity, base: "https://api.bulgur.dev", path: "" };
+  if (typeof dsn !== "string" || !dsn.startsWith("bulgur://")) throw fail();
+  let u;
+  try {
+    u = new URL(dsn);
+  } catch {
+    throw fail();
+  }
+  if (u.username || u.password || u.search || u.hash || !u.hostname)
+    throw fail();
+  const parts = u.pathname.replace(/\/$/, "").split("/").slice(1);
+  if (
+    parts.length !== 3 ||
+    parts.some((v) => !/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(v))
+  )
+    throw fail();
+  const host = u.hostname.toLowerCase();
+  const cloud = host === "api.bulgur.dev" && (!u.port || u.port === "443");
+  const local =
+    host === "localhost" || host === "127.0.0.1" || host === "[::1]";
+  if (!cloud && !local) throw fail();
+  return {
+    identity,
+    base: cloud ? "https://api.bulgur.dev" : `http://${u.host}`,
+    path: `/v1/orgs/${parts[0]}/projects/${parts[1]}/environments/${parts[2]}/values`,
+  };
+}
+
+async function providerToken(fresh = false) {
+  try {
+    const provider = await import("@vercel/oidc");
+    let timer;
+    const token = await Promise.race([
+      provider.getVercelOidcToken({
+        audience: "https://api.bulgur.dev",
+        ...(fresh ? { skipCache: true } : {}),
+      }),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(fail()), 5000);
+      }),
+    ]).finally(() => clearTimeout(timer));
+    if (typeof token !== "string" || !token || token.length > 16384)
+      throw fail();
+    return token;
+  } catch {
+    throw fail();
+  }
+}
+function sourceExpiry(jwt) {
+  try {
+    const payload = JSON.parse(
+      Buffer.from(jwt.split(".")[1], "base64url").toString("utf8"),
+    );
+    if (!Number.isFinite(payload.exp)) throw fail();
+    return payload.exp * 1000;
+  } catch {
+    throw fail();
+  }
+}
+async function requestJSON(url, init, limit) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 5000);
+  try {
+    const res = await fetch(url, {
+      ...init,
+      redirect: "error",
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      if (res.body) await res.body.cancel();
+      return { status: res.status };
+    }
+    if (!res.body) throw fail();
+    const reader = res.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+      const item = await reader.read();
+      if (item.done) break;
+      size += item.value.length;
+      if (size > limit) {
+        await reader.cancel();
+        throw fail();
+      }
+      chunks.push(item.value);
+    }
+    return {
+      status: res.status,
+      body: JSON.parse(Buffer.concat(chunks).toString("utf8")),
+    };
+  } catch {
+    throw fail();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function keyFor(config, jwt) {
+  return createHash("sha256")
+    .update(JSON.stringify([config.identity, config.base, config.path, jwt]))
+    .digest("hex");
+}
+async function exchange(config, jwt, previous) {
+  const result = await requestJSON(
+    `${config.base}/v1/auth/oidc`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify({
+        provider: "vercel",
+        identityId: config.identity,
+        jwt,
+      }),
+    },
+    65536,
+  );
+  const b = result.body;
+  const expiry = b && Date.parse(b.expiresAt);
+  if (
+    result.status !== 200 ||
+    !b ||
+    typeof b.token !== "string" ||
+    !b.token.startsWith("blg_wl_") ||
+    b.tokenType !== "Bearer" ||
+    !uuid.test(b.projectId || "") ||
+    !uuid.test(b.environmentId || "") ||
+    !Number.isFinite(expiry) ||
+    expiry <= Date.now() ||
+    expiry > Date.now() + 305000 ||
+    expiry > sourceExpiry(jwt) ||
+    (previous &&
+      (previous.projectId !== b.projectId ||
+        previous.environmentId !== b.environmentId))
+  )
+    throw fail();
+  return {
+    token: b.token,
+    expiry,
+    projectId: b.projectId,
+    environmentId: b.environmentId,
+  };
+}
+async function sessionFor(config, jwt, previous) {
+  const key = keyFor(config, jwt);
+  const cached = sessions.get(key);
+  if (
+    cached &&
+    cached.expiry > Date.now() + 30000 &&
+    (!previous ||
+      (cached.projectId === previous.projectId &&
+        cached.environmentId === previous.environmentId))
+  ) {
+    sessions.delete(key);
+    sessions.set(key, cached);
+    return { key, session: cached };
+  }
+  sessions.delete(key);
+  let pending = inflight.get(key);
+  if (!pending) {
+    if (inflight.size >= 64) throw fail();
+    pending = exchange(config, jwt, previous);
+    inflight.set(key, pending);
+  }
+  try {
+    const session = await pending;
+    if (
+      previous &&
+      (session.projectId !== previous.projectId ||
+        session.environmentId !== previous.environmentId)
+    )
+      throw fail();
+    sessions.set(key, session);
+    while (sessions.size > 64) sessions.delete(sessions.keys().next().value);
+    return { key, session };
+  } finally {
+    if (inflight.get(key) === pending) inflight.delete(key);
+  }
+}
+async function loadOIDC(opts) {
+  const config = configFor(opts);
+  const targetKey = JSON.stringify([config.identity, config.base, config.path]);
+  let current = await sessionFor(
+    config,
+    await providerToken(),
+    targets.get(targetKey),
+  );
+  const prior = targets.get(targetKey);
+  if (
+    prior &&
+    (prior.projectId !== current.session.projectId ||
+      prior.environmentId !== current.session.environmentId)
+  )
+    throw fail();
+  targets.delete(targetKey);
+  targets.set(targetKey, {
+    projectId: current.session.projectId,
+    environmentId: current.session.environmentId,
+  });
+  while (targets.size > 64) targets.delete(targets.keys().next().value);
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const path =
+      config.path ||
+      `/v1/environments/${current.session.environmentId}/secrets/values`;
+    const result = await requestJSON(
+      config.base + path,
+      {
+        headers: {
+          Authorization: `Bearer ${current.session.token}`,
+          Accept: "application/json",
+        },
+      },
+      8 * 1024 * 1024,
+    );
+    if (
+      result.status === 200 &&
+      result.body &&
+      Array.isArray(result.body.secrets)
+    ) {
+      const secrets = result.body.secrets;
+      if (
+        !secrets.every(
+          (item) =>
+            item &&
+            typeof item.name === "string" &&
+            /^[A-Za-z_][A-Za-z0-9_]*$/.test(item.name) &&
+            typeof item.value === "string",
+        )
+      )
+        throw fail();
+      return secrets;
+    }
+    if (result.status !== 401 || attempt !== 0) throw fail();
+    sessions.delete(current.key);
+    current = await sessionFor(
+      config,
+      await providerToken(true),
+      current.session,
+    );
+  }
+  throw fail();
+}
+module.exports = { loadOIDC };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulgur",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Ultra-simple secrets manager CLI (bulgur), plus a runtime SDK: `import { load } from \"bulgur\"`",
   "bin": {
     "bulgur": "bin/bulgur.js"
@@ -20,10 +20,14 @@
     "binaries/",
     "index.js",
     "index.d.ts",
-    "README.md"
+    "README.md",
+    "oidc.js",
+    "dotenv-dsn.js",
+    "scripts/prepack.cjs"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "prepack": "node scripts/prepack.cjs"
   },
   "engines": {
     "node": ">=18"
@@ -46,5 +50,13 @@
     "dotenv",
     "environment-variables",
     "secrets-manager"
-  ]
+  ],
+  "peerDependencies": {
+    "@vercel/oidc": "^4.0.7"
+  },
+  "peerDependenciesMeta": {
+    "@vercel/oidc": {
+      "optional": true
+    }
+  }
 }

package/scripts/prepack.cjs

@@ -0,0 +1,24 @@
+"use strict";
+// Fail closed for a direct pack/publish from an incomplete source checkout.
+const fs = require("node:fs");
+const path = require("node:path");
+const root = path.resolve(__dirname, "..");
+const required = ["bin/bulgur.js", "index.js", "index.d.ts", "oidc.js", "dotenv-dsn.js"];
+for (const name of ["darwin-x64", "darwin-arm64", "linux-x64", "linux-arm64"]) {
+  required.push(`binaries/${name}/bulgur`);
+}
+for (const name of required) {
+  let info;
+  try { info = fs.lstatSync(path.join(root, name)); } catch { throw new Error("Incomplete release bundle; build it with make npm-pack"); }
+  if (!info.isFile() || info.size === 0 || ((name.startsWith("binaries/") || name === "bin/bulgur.js") && !(info.mode & 0o111))) {
+    throw new Error("Incomplete release bundle; build it with make npm-pack");
+  }
+}
+const version = require(path.join(root, "package.json")).version;
+for (const platform of ["darwin-x64", "darwin-arm64", "linux-x64", "linux-arm64"]) {
+  const bytes = fs.readFileSync(path.join(root, "binaries", platform, "bulgur"));
+  const validFormat = bytes.length >= 20 && (platform.startsWith("linux-")
+    ? bytes.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])) && bytes.readUInt16LE(18) === (platform.endsWith("x64") ? 62 : 183)
+    : bytes.readUInt32LE(0) === 0xfeedfacf && bytes.readUInt32LE(4) === (platform.endsWith("x64") ? 0x01000007 : 0x0100000c));
+  if (!validFormat || !bytes.includes(Buffer.from(version))) throw new Error("Invalid release binary; build it with make npm-pack");
+}