{"record":{"id":"c5c4d7fac021ea66","repo":"JuliusBrussee/caveman","slug":"name-must-be-an-absolute-http-s-url-without-cr","errorCode":null,"errorMessage":"${name} must be an absolute http(s) URL without credentials","messagePattern":"(.+?) must be an absolute http\\(s\\) URL without credentials","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/sdk/typescript/src/index.ts","lineNumber":344,"sourceCode":"  spanId: string;\n  parentSpanId: string;\n  kind: number;\n  startTimeNs: number;\n  endTimeNs: number;\n  statusCode: number; // 0=unset, 1=ok, 2=error\n  attributes: Record<string, string | number | boolean>;\n};\n\nfunction normalizedServiceURL(value: string, name: \"baseURL\" | \"controlURL\"): string {\n  if (value.trim() !== value) throw new Error(`${name} must not contain surrounding whitespace`);\n  let parsed: URL;\n  try {\n    parsed = new URL(value);\n  } catch {\n    throw new Error(`${name} must be an absolute http(s) URL`);\n  }\n  if ((parsed.protocol !== \"http:\" && parsed.protocol !== \"https:\") || !parsed.hostname || parsed.username || parsed.password) {\n    throw new Error(`${name} must be an absolute http(s) URL without credentials`);\n  }\n  if (parsed.search || parsed.hash) throw new Error(`${name} must not contain a query or fragment`);\n  return value.replace(/\\/+$/, \"\");\n}\n\nexport class Cave {\n  readonly options: CaveOptions;\n\n  constructor(options: CaveOptions) {\n    if (!options.apiKey || !options.baseURL || !options.agent) throw new Error(\"apiKey, baseURL, and agent are required\");\n    if (options.timeoutMs !== undefined && (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0)) {\n      throw new Error(\"timeoutMs must be a positive integer\");\n    }\n    // CAVE_WORKFLOW lets a wrapper (`cave wrap --workflow x`) label every request\n    // from an SDK app without a code change. An explicit option always wins.\n    // globalThis lookup keeps the SDK browser-neutral (no node type dependency).\n    // The env value is normalized to the gateway's label rule (lowercase\n    // [a-z0-9_-], max 96) — an invalid ambient value is ignored rather than","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/sdk/typescript/src/index.ts#L326-L362","documentation":"This is the second-layer URL check: the value parses as a URL but is rejected because it is not http/https, has no hostname, or embeds user/password credentials. The SDK refuses URLs with inline credentials both for security (leaking creds into requests/logs) and correctness of gateway routing.","triggerScenarios":"baseURL: \"ftp://example.com\" or \"https://user:pass@api.example.com\" or \"https:///path\" (empty hostname) passed to Cave options via normalized().","commonSituations":"Copy-pasting a URL with basic-auth credentials (common from curl examples or other SDKs that accept auth-in-URL); using a non-http scheme; misassembled URL where host part was lost.","solutions":["Remove credentials from the URL and pass them separately (the SDK takes apiKey as its own option).","Use an http: or https: scheme; switch ftp:// or custom schemes to https://.","Ensure the URL includes a hostname (e.g. https://api.example.com, not https:///path)."],"exampleFix":"// before\nnew Cave({ apiKey, baseURL: \"https://user:secret@api.example.com\", agent: \"x\" });\n\n// after\nnew Cave({ apiKey, baseURL: \"https://api.example.com\", agent: \"x\" });","handlingStrategy":"validation","validationCode":"function assertCleanHttpURL(v: string, name: string): URL {\n  const u = new URL(v);\n  if ((u.protocol !== \"http:\" && u.protocol !== \"https:\") || !u.hostname || u.username || u.password)\n    throw new Error(`${name} must be an http(s) URL without credentials`);\n  return u;\n}","typeGuard":"const isCredentialFreeHttpURL = (v: string): boolean => {\n  try { const u = new URL(v); return (u.protocol === \"http:\" || u.protocol === \"https:\") && !!u.hostname && !u.username && !u.password; } catch { return false; }\n};","tryCatchPattern":"try {\n  const cave = new Cave({ apiKey, baseURL, agent });\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"without credentials\")) {\n    const u = new URL(baseURL);\n    baseURL = u.origin + u.pathname;\n    // retry construction\n  } else throw e;\n}","preventionTips":["Never embed user:password in URLs; pass secrets via the SDK's apiKey option.","Audit config from curl examples or legacy SDKs that accepted auth-in-URL.","Scan config files for the '://' credential pattern (user@ in host) in CI."],"tags":["validation","url","security","credentials"],"backgroundTag":"invalid-url-format","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}