fix: harden multi-header auth — reject CRLF, warn on empty $VAR

- parseHeaderFlag now rejects CR/LF in name/value (RFC 7230 header injection)
  and enforces RFC-valid token chars in header names.
- resolveEnvVar warns to stderr when $VAR resolves to unset or empty —
  silent empty headers produce confusing 401s ("auth wrong" when it's "env unset").
- index.ts parseHeaderArgs now delegates to parseHeaderFlag so CLI-time
  argv parsing shares the same validation as `auth login`.
- .gitignore: ignore .claude/ harness state.

Addresses code-review feedback on PR #21.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lucianfialho

.gitignore

@@ -3,3 +3,4 @@ dist/
 *.tgz
 .env
 .DS_Store
+.claude/

src/auth/auth.test.ts

@@ -192,6 +192,18 @@ describe("parseHeaderFlag", () => {
   it("returns null for empty name", () => {
     expect(parseHeaderFlag(": value")).toBeNull();
   });
+
+  it("rejects CR/LF in value (header injection)", () => {
+    expect(parseHeaderFlag("X-Key: bad\r\nEvil: yes")).toBeNull();
+    expect(parseHeaderFlag("X-Key: bad\nEvil: yes")).toBeNull();
+    expect(parseHeaderFlag("X-Key: bad\rEvil: yes")).toBeNull();
+  });
+
+  it("rejects invalid characters in header name", () => {
+    expect(parseHeaderFlag("X Key: v")).toBeNull();
+    expect(parseHeaderFlag("X\tKey: v")).toBeNull();
+    expect(parseHeaderFlag("X:Key: v")).toEqual({ name: "X", value: "Key: v" });
+  });
 });
 
 describe("detectApiKeyHeaders", () => {
@@ -271,6 +283,32 @@ describe("resolveAuth with multi-header", () => {
     expect(auth.type).toBe("bearer");
     expect(auth.value).toBe("sk-1");
   });
+
+  it("warns to stderr when $VAR in header resolves to empty", async () => {
+    const stderr = vi.spyOn(console, "error").mockImplementation(() => {});
+    const auth = await resolveAuth(
+      { headers: { "X-VTEX-API-AppKey": "$MISSING_VAR" } },
+      specDualHeader,
+      {}
+    );
+    expect(auth.headers?.["X-VTEX-API-AppKey"]).toBe("");
+    const logged = stderr.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(logged).toMatch(/Warning.*MISSING_VAR.*unset/);
+    expect(logged).toContain("X-VTEX-API-AppKey");
+    stderr.mockRestore();
+  });
+
+  it("warns when $VAR resolves to empty string", async () => {
+    const stderr = vi.spyOn(console, "error").mockImplementation(() => {});
+    await resolveAuth(
+      { headers: { "X-Key": "$EMPTY_VAR" } },
+      specDualHeader,
+      { EMPTY_VAR: "" }
+    );
+    const logged = stderr.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(logged).toMatch(/Warning.*EMPTY_VAR.*empty/);
+    stderr.mockRestore();
+  });
 });
 
 describe("maskToken", () => {

src/auth/flags.ts

@@ -22,25 +22,25 @@ export async function resolveAuth(
   if (flags.headers && Object.keys(flags.headers).length > 0) {
     const resolved: Record<string, string> = {};
     for (const [k, v] of Object.entries(flags.headers)) {
-      resolved[k] = resolveEnvVar(v, env);
+      resolved[k] = resolveEnvVar(v, env, `--header "${k}"`);
     }
     return { type: "headers", value: "", headers: resolved };
   }
   if (flags.token) {
-    return { type: "bearer", value: resolveEnvVar(flags.token, env) };
+    return { type: "bearer", value: resolveEnvVar(flags.token, env, "--token") };
   }
   if (flags.apiKey) {
     const headerName = detectApiKeyHeader(spec) ?? "X-API-Key";
-    return { type: "apiKey", value: resolveEnvVar(flags.apiKey, env), headerName };
+    return { type: "apiKey", value: resolveEnvVar(flags.apiKey, env, "--api-key"), headerName };
   }
   if (flags.authHeader) {
-    return { type: "bearer", value: resolveEnvVar(flags.authHeader, env) };
+    return { type: "bearer", value: resolveEnvVar(flags.authHeader, env, "--auth-header") };
   }
 
   // Priority 2: .toclirc auth config
   if (flags.rcAuthToken) {
     const type = (flags.rcAuthType as AuthConfig["type"]) ?? "bearer";
-    return { type, value: resolveEnvVar(flags.rcAuthToken, env) };
+    return { type, value: resolveEnvVar(flags.rcAuthToken, env, ".toclirc auth.token") };
   }
   if (flags.rcAuthEnvVar) {
     const envVal = env[flags.rcAuthEnvVar];
@@ -69,13 +69,13 @@ export async function resolveAuth(
     if (profile.type === "headers" && profile.headers) {
       const resolved: Record<string, string> = {};
       for (const [k, v] of Object.entries(profile.headers)) {
-        resolved[k] = resolveEnvVar(v, env);
+        resolved[k] = resolveEnvVar(v, env, `profile '${profileName}' header "${k}"`);
       }
       return { type: "headers", value: "", headers: resolved };
     }
     return {
       type: profile.type,
-      value: resolveEnvVar(profile.value, env),
+      value: resolveEnvVar(profile.value, env, `profile '${profileName}'`),
       headerName: profile.headerName,
     };
   }
@@ -115,11 +115,19 @@ function detectApiKeyHeader(spec: OpenAPISpec): string | undefined {
   return undefined;
 }
 
-function resolveEnvVar(value: string, env: NodeJS.ProcessEnv): string {
-  // Replace $VAR or ${VAR} with env values
+function resolveEnvVar(value: string, env: NodeJS.ProcessEnv, context?: string): string {
+  // Replace $VAR or ${VAR} with env values. Warn when a reference resolves to empty —
+  // silent empty headers confuse downstream 401s ("auth wrong" when it's "env unset").
   return value.replace(/\$\{([^}]+)\}|\$([A-Z_][A-Z0-9_]*)/g, (_, braced, plain) => {
     const name = braced ?? plain;
-    return env[name] ?? "";
+    const resolved = env[name];
+    if (resolved === undefined || resolved === "") {
+      console.error(
+        `Warning: env var $${name} is ${resolved === undefined ? "unset" : "empty"}${context ? ` (used in ${context})` : ""}.`
+      );
+      return "";
+    }
+    return resolved;
   });
 }
 

src/auth/headers.ts

@@ -14,5 +14,9 @@ export function parseHeaderFlag(raw: string): ParsedHeader | null {
   const name = raw.slice(0, idx).trim();
   const value = raw.slice(idx + 1).trim();
   if (!name) return null;
+  // Reject CR/LF — header injection (RFC 7230 §3.2.4 forbids them in values/names)
+  if (/[\r\n]/.test(name) || /[\r\n]/.test(value)) return null;
+  // Header names per RFC 7230: token chars only (no whitespace, no control chars)
+  if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name)) return null;
   return { name, value };
 }

src/index.ts

@@ -7,6 +7,7 @@ import { executeRequest } from "./executor/http.js";
 import { formatOutput } from "./output/formatters.js";
 import { registerAuthCommands } from "./auth/commands.js";
 import { resolveAuth as resolveAuthFromFlags } from "./auth/flags.js";
+import { parseHeaderFlag } from "./auth/headers.js";
 import { registerInitCommand } from "./config/init.js";
 import { registerUseCommand } from "./templates/commands.js";
 import { loadConfig, resolveConfig } from "./config/rc.js";
@@ -409,18 +410,12 @@ function parseHeaderArgs(args: string[]): Record<string, string> | undefined {
   if (raws.length === 0) return undefined;
   const headers: Record<string, string> = {};
   for (const raw of raws) {
-    const idx = raw.indexOf(":");
-    if (idx === -1) {
-      console.error(`Error: invalid --header '${raw}'. Expected "Name: Value".`);
+    const parsed = parseHeaderFlag(raw);
+    if (!parsed) {
+      console.error(`Error: invalid --header '${raw}'. Expected "Name: Value" with RFC-valid name and no CR/LF.`);
       process.exit(1);
     }
-    const name = raw.slice(0, idx).trim();
-    const value = raw.slice(idx + 1).trim();
-    if (!name) {
-      console.error(`Error: invalid --header '${raw}'. Missing name.`);
-      process.exit(1);
-    }
-    headers[name] = value;
+    headers[parsed.name] = parsed.value;
   }
   return headers;
 }