@datarails-ai/dr-cli 1.6.97 → 1.6.98

package/README.md

@@ -230,6 +230,20 @@ under one identity and run as another.
 { "apiKey": "<key>", "server": "DEV", "email": "svc@datarails.com" }
 ```
 
+The key may instead live in an environment variable, with the file carrying
+only the variable's **name** — the shape for CI (the key stays in the runner's
+secret env, never on disk) and for agent sandboxes (where the variable's
+in-sandbox value is an opaque vault placeholder substituted at egress, passed
+verbatim and never validated):
+
+```json
+{ "apiKeyEnvVar": "DR_API_KEY", "server": "DEV", "email": "svc@datarails.com" }
+```
+
+`apiKey` and `apiKeyEnvVar` are mutually exclusive — a file carrying both is
+refused rather than guessed about. An unset variable fails the command with an
+error naming it; the stored file is never modified by that failure.
+
 `email` names the stored identity — what `--account` selects and what the
 keychain entry is keyed by. It need not match the principal the key is bound to;
 the token the exchange mints is what every request authenticates as, and

package/dist/cli.js

@@ -8,7 +8,7 @@ import { fileURLToPath as fileURLToPath3 } from "url";
 // package.json
 var package_default = {
   name: "@datarails-ai/dr-cli",
-  version: "1.6.97",
+  version: "1.6.98",
   description: "Datarails CLI",
   type: "module",
   engines: {
@@ -38,7 +38,7 @@ var package_default = {
     postinstall: "node scripts/postinstall.mjs"
   },
   dependencies: {
-    "@datarails-ai/dr-appspace-cli": "0.10.20",
+    "@datarails-ai/dr-appspace-cli": "0.10.21",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     commander: "^12.1.0",
@@ -67,7 +67,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-05T07:44:13.912Z";
+var BUILD_TIME = "2026-10-05T10:25:04.884Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -151,14 +151,17 @@ function parseApiKeyExpiry(value) {
 function hasApiKey(s) {
   return s.apiKey !== void 0 && s.apiKey !== "";
 }
+function hasApiKeyEnvVar(s) {
+  return s.apiKeyEnvVar !== void 0 && s.apiKeyEnvVar !== "";
+}
 function isImpersonatedSession(s) {
   return s.impersonatorEmail !== void 0 && s.impersonatorEmail !== "";
 }
 function isCookielessSession(s) {
-  return isImpersonatedSession(s) || s.cookieless === true || hasApiKey(s);
+  return isImpersonatedSession(s) || s.cookieless === true || hasApiKey(s) || hasApiKeyEnvVar(s);
 }
 function usesApiKey(s) {
-  return hasApiKey(s) && !isImpersonatedSession(s);
+  return (hasApiKey(s) || hasApiKeyEnvVar(s)) && !isImpersonatedSession(s);
 }
 var KeychainError = class extends Error {
   constructor(message, options) {
@@ -294,6 +297,16 @@ var credentialsFileSchema = z.object({
   // A user-bound API key, exchanged for `access` on demand. A file may hold
   // only this; `access` then appears after the first exchange.
   apiKey: z.string().min(1).optional(),
+  // DR-52657: the NAME of an environment variable holding the API key, for
+  // provisioners that must not put the key on disk — an agent sandbox, where
+  // the variable's in-sandbox value is an opaque vault placeholder
+  // substituted at egress, or a CI runner keeping the key in its secret env.
+  // The value is resolved at exchange time and passed verbatim; dr-cli never
+  // inspects, validates, or logs it. Mutually exclusive with `apiKey` (a
+  // refinement below): a file carrying both is ambiguous about which
+  // credential authenticates it, and silently preferring either one turns a
+  // provisioning mistake into commands running as the wrong key.
+  apiKeyEnvVar: z.string().min(1).optional(),
   // Carried verbatim, judged by `parseApiKeyExpiry` where it is read. Not
   // validated here, and not `.catch(undefined)` either: a rotation rewrites
   // the whole file from the parsed object, so a value this schema dropped
@@ -332,13 +345,19 @@ var credentialsFileSchema = z.object({
 }).passthrough().refine((c) => c.sessionId === void 0 === (c.csrfToken === void 0), {
   message: "sessionId and csrfToken must be provided together",
   path: ["sessionId"]
-}).refine((c) => c.access !== void 0 || c.apiKey !== void 0, {
-  message: "one of access or apiKey is required",
+}).refine((c) => !(c.apiKey !== void 0 && c.apiKeyEnvVar !== void 0), {
+  message: "apiKey and apiKeyEnvVar are mutually exclusive",
+  path: ["apiKeyEnvVar"]
+}).refine((c) => c.access !== void 0 || c.apiKey !== void 0 || c.apiKeyEnvVar !== void 0, {
+  message: "one of access, apiKey or apiKeyEnvVar is required",
   path: ["access"]
-}).refine((c) => c.apiKey !== void 0 || c.refresh !== void 0 || c.sessionId !== void 0, {
-  message: "refresh is required unless an apiKey or a session cookie is present",
-  path: ["refresh"]
-});
+}).refine(
+  (c) => c.apiKey !== void 0 || c.apiKeyEnvVar !== void 0 || c.refresh !== void 0 || c.sessionId !== void 0,
+  {
+    message: "refresh is required unless an apiKey, apiKeyEnvVar or a session cookie is present",
+    path: ["refresh"]
+  }
+);
 function credentialsFilePath() {
   const override = process.env[CREDENTIALS_FILE_ENV];
   return override !== void 0 && override !== "" ? override : DEFAULT_CREDENTIALS_FILE;
@@ -801,7 +820,13 @@ async function exchangeApiKey(host, apiKey, options) {
   if (key === "") {
     throw new Error("api-key exchange: the stored API key is empty");
   }
-  if (!/^[\x21-\x7e]+$/.test(key)) {
+  if (options?.opaque === true) {
+    if (/[\r\n\0]/.test(key) || !/^[\x00-\xff]+$/.test(key)) {
+      throw new Error(
+        "api-key exchange: the environment variable named by apiKeyEnvVar holds a value that cannot travel in an HTTP header (a line break, NUL, or a character above U+00FF)"
+      );
+    }
+  } else if (!/^[\x21-\x7e]+$/.test(key)) {
     throw new Error(
       "api-key exchange: dr only accepts an API key of printable ASCII with no spaces; the stored one contains whitespace, control characters, or non-ASCII characters"
     );
@@ -965,10 +990,31 @@ function mintedByApiKey(token) {
 function apiKeyFingerprint(apiKey) {
   return createHash("sha256").update(apiKey.trim()).digest("hex").slice(0, 32);
 }
+function resolveApiKeyMaterial(session) {
+  if (session.apiKey !== void 0 && session.apiKey !== "") {
+    return { key: session.apiKey, fromEnv: false };
+  }
+  const name = session.apiKeyEnvVar;
+  if (name === void 0 || name === "") {
+    throw new Error("api-key exchange: the session carries no API key");
+  }
+  const value = process.env[name];
+  if (value === void 0 || value === "") {
+    throw new Error(
+      `api-key exchange: the credential file names environment variable ${name} as the API-key carrier, but it is unset or empty in this environment`
+    );
+  }
+  return { key: value, fromEnv: true };
+}
 function mintedByStoredApiKey(session) {
   if (!mintedByApiKey(session.jwtAccess)) return false;
-  if (session.apiKey === void 0 || session.apiKey === "") return false;
-  return session.jwtApiKeyFingerprint === apiKeyFingerprint(session.apiKey);
+  let material;
+  try {
+    material = resolveApiKeyMaterial(session);
+  } catch {
+    return false;
+  }
+  return session.jwtApiKeyFingerprint === apiKeyFingerprint(material.key);
 }
 function apiKeyStaleBuffer(session, identity2, fallbackMs) {
   if (session.jwtAccess === void 0 || session.jwtAccess === "") return fallbackMs;
@@ -995,12 +1041,13 @@ function ttlOf(token) {
 function exchangeForSession(store, serverKey, email, session, host, opts) {
   const identity2 = `${serverKey}:${email}`;
   if (opts.signal?.aborted === true) return Promise.reject(opts.signal.reason);
-  const key = JSON.stringify([
-    identity2,
-    host,
-    opts.force,
-    apiKeyFingerprint(session.apiKey)
-  ]);
+  let material;
+  try {
+    material = resolveApiKeyMaterial(session);
+  } catch (err) {
+    throw new SessionExpiredError(`${identity2} (${msgOf3(err)})`);
+  }
+  const key = JSON.stringify([identity2, host, opts.force, apiKeyFingerprint(material.key)]);
   const pending = inFlightExchanges.get(key);
   if (pending !== void 0) return joinExchange(pending, opts.signal);
   const controller = new AbortController();
@@ -1015,7 +1062,7 @@ function exchangeForSession(store, serverKey, email, session, host, opts) {
     for (; ; ) {
       let tok;
       try {
-        tok = await exchangeApiKey(host, session.apiKey, { signal });
+        tok = await exchangeApiKey(host, material.key, { signal, opaque: material.fromEnv });
       } catch (err) {
         const cachedIsUsable = !opts.force && mintedByStoredApiKey(session) && !jwtExpiringSoon(session, 0);
         if (!(err instanceof ApiKeyExchangeError)) {
@@ -1054,7 +1101,7 @@ function exchangeForSession(store, serverKey, email, session, host, opts) {
         // the token did not come from. Read back by `mintedByStoredApiKey` on
         // every later command to tell this token apart from one the previous
         // key minted.
-        jwtApiKeyFingerprint: apiKeyFingerprint(session.apiKey),
+        jwtApiKeyFingerprint: apiKeyFingerprint(material.key),
         // Dropped, not carried: the exchange mints no refresh token, and the
         // refresh rung is closed to a keyed identity by contract. Clearing it
         // is what lets "keyed, and still holding a refresh token" mean "these
@@ -1065,7 +1112,7 @@ function exchangeForSession(store, serverKey, email, session, host, opts) {
       };
       try {
         const current = await store.getSession(serverKey, email);
-        if (current === void 0 || current.apiKey !== session.apiKey) {
+        if (current === void 0 || current.apiKey !== session.apiKey || current.apiKeyEnvVar !== session.apiKeyEnvVar) {
           return next;
         }
         await store.saveSession(serverKey, next);
@@ -1383,7 +1430,8 @@ var KeyringStore = class _KeyringStore {
     const impersonated = impersonatorEmail !== "";
     const cookielessFlag = parsed2.cookieless === true;
     const apiKey = await this.backend.get(SERVICE, `${sessionAccount}:apikey`);
-    const keyPresent = apiKey !== void 0 && apiKey !== "";
+    const apiKeyEnvVar = typeof parsed2.apiKeyEnvVar === "string" ? parsed2.apiKeyEnvVar : "";
+    const keyPresent = apiKey !== void 0 && apiKey !== "" || apiKeyEnvVar !== "";
     const cookieless = impersonated || cookielessFlag || keyPresent;
     const halfCookie = sessionId === "" !== (csrfToken === "");
     if (savedAtStr === "" || halfCookie || !cookieless && sessionId === "") {
@@ -1429,9 +1477,12 @@ var KeyringStore = class _KeyringStore {
     if (jwtRefresh !== void 0 && jwtRefresh !== "") {
       session.jwtRefresh = jwtRefresh;
     }
-    if (keyPresent) {
+    if (apiKey !== void 0 && apiKey !== "") {
       session.apiKey = apiKey;
     }
+    if (apiKeyEnvVar !== "") {
+      session.apiKeyEnvVar = apiKeyEnvVar;
+    }
     return session;
   }
   /**
@@ -1463,9 +1514,9 @@ var KeyringStore = class _KeyringStore {
     const impersonated = isImpersonatedSession(session);
     if (isCookielessSession(session)) {
       const hasJwt = session.jwtAccess !== void 0 && session.jwtAccess !== "";
-      if (!hasJwt && !hasApiKey(session)) {
+      if (!hasJwt && !hasApiKey(session) && !hasApiKeyEnvVar(session)) {
         throw new Error(
-          "saveSession: cookie-less session must have a jwtAccess token or an apiKey"
+          "saveSession: cookie-less session must have a jwtAccess token, an apiKey, or an apiKeyEnvVar"
         );
       }
       if (session.sessionId === "" !== (session.csrfToken === "")) {
@@ -1496,6 +1547,9 @@ var KeyringStore = class _KeyringStore {
     if (session.jwtApiKeyFingerprint !== void 0 && session.jwtApiKeyFingerprint !== "") {
       metaBlob.jwtApiKeyFingerprint = session.jwtApiKeyFingerprint;
     }
+    if (hasApiKeyEnvVar(session)) {
+      metaBlob.apiKeyEnvVar = session.apiKeyEnvVar;
+    }
     if (impersonated) {
       metaBlob.impersonatorEmail = session.impersonatorEmail;
       if (session.impersonatedUserId !== void 0) {
@@ -2599,7 +2653,9 @@ var FileKeyringBackend = class _FileKeyringBackend {
       // Named as the Session field, since the blob is what `getSession` reads.
       ...creds.accessApiKeyFingerprint !== void 0 && {
         jwtApiKeyFingerprint: creds.accessApiKeyFingerprint
-      }
+      },
+      // The env var's NAME only — the resolved key never enters any store.
+      ...creds.apiKeyEnvVar !== void 0 && { apiKeyEnvVar: creds.apiKeyEnvVar }
     });
   }
   static slotOf(creds, account) {
@@ -2627,11 +2683,16 @@ var FileKeyringBackend = class _FileKeyringBackend {
     const csrfToken = typeof parsed2.csrfToken === "string" ? parsed2.csrfToken : "";
     const apiKeyExpiresAt = typeof parsed2.apiKeyExpiresAt === "string" ? parsed2.apiKeyExpiresAt : "";
     const accessApiKeyFingerprint = typeof parsed2.jwtApiKeyFingerprint === "string" ? parsed2.jwtApiKeyFingerprint : "";
+    const apiKeyEnvVar = typeof parsed2.apiKeyEnvVar === "string" ? parsed2.apiKeyEnvVar : "";
     return {
       ...sessionId !== "" && { sessionId },
       ...csrfToken !== "" && { csrfToken },
       ...apiKeyExpiresAt !== "" && { apiKeyExpiresAt },
-      ...accessApiKeyFingerprint !== "" && { accessApiKeyFingerprint }
+      ...accessApiKeyFingerprint !== "" && { accessApiKeyFingerprint },
+      // Set-if-present, never deleted on a blob that lost it (the
+      // `apiKeyExpiresAt` rule): it is the identity's only credential pointer,
+      // and a meta rewrite must not be able to brick the file.
+      ...apiKeyEnvVar !== "" && { apiKeyEnvVar }
     };
   }
   async get(_service, account) {
@@ -2724,6 +2785,7 @@ var FileKeyringBackend = class _FileKeyringBackend {
             if (meta.apiKeyExpiresAt !== void 0) next.apiKeyExpiresAt = meta.apiKeyExpiresAt;
             if (meta.accessApiKeyFingerprint === void 0) delete next.accessApiKeyFingerprint;
             else next.accessApiKeyFingerprint = meta.accessApiKeyFingerprint;
+            if (meta.apiKeyEnvVar !== void 0) next.apiKeyEnvVar = meta.apiKeyEnvVar;
             break;
           }
         }
@@ -44947,7 +45009,7 @@ import * as nodePath2 from "path";
 var API_PREFIX = "/api/v1";
 var OPERATOR_EMAIL_HEADER = "X-Operator-Email";
 function withOperatorAttribution(client, options) {
-  const operatorEmail = isImpersonatedSession(client.session) ? client.session.impersonatorEmail : client.session.cookieless === true && !hasApiKey(client.session) && client.session.interactiveLogin !== true ? void 0 : client.email;
+  const operatorEmail = isImpersonatedSession(client.session) ? client.session.impersonatorEmail : client.session.cookieless === true && !hasApiKey(client.session) && !hasApiKeyEnvVar(client.session) && client.session.interactiveLogin !== true ? void 0 : client.email;
   if (operatorEmail === void 0) return options ?? {};
   return {
     ...options,

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.97",
+  "cliVersion": "1.6.98",
   "_contract": "Resolve a command path through `aliases` (canonical prefix + alias segment -> canonical path) before any lookup. A path listed in `pendingCommands`, or whose first segment is a key of `pending`, is UNDECIDED, not unrestricted: fail closed or skip it, and never read a path's absence from `commands` as 'no requirement'. An entry carrying `denied` is UNAVAILABLE to any AGENT-SCOPED credential — one whose `scopes` claim carries at least one `resource:action` entry; a claim that is absent, empty, capability-only or wholly unparseable is UNRESTRICTED, and this mark does not apply to it — whatever else that entry says: it is not a ceiling and it is not always-available, its `denied.reason` says why and `denied.until` names the ticket that lifts it, and the absence of `requires` on it must NEVER be read as 'no requirement'. Only an entry in `commands` with an empty `requires` means always-available.",
   "commands": {
     "login": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-cli",
-  "version": "1.6.97",
+  "version": "1.6.98",
   "description": "Datarails CLI",
   "type": "module",
   "engines": {
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@datarails-ai/dr-appspace-cli": "0.10.20",
+    "@datarails-ai/dr-appspace-cli": "0.10.21",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     "commander": "^12.1.0",