{"record":{"id":"caf5fa22518608de","repo":"ruvnet/ruflo","slug":"could-not-reach-the-cognitum-auth-service-ruflo-c","errorCode":null,"errorMessage":"Could not reach the Cognitum auth service. ruflo core functionality is unaffected — sign-in is not required for local use.","messagePattern":"Could not reach the Cognitum auth service\\. ruflo core functionality is unaffected — sign-in is not required for local use\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"v3/@claude-flow/cli/src/auth/client.ts","lineNumber":216,"sourceCode":"  };\n  return { tokens, method: 'token-stdin' };\n}\n\n/**\n * Refreshes an access token. Classifies failure into network-unreachable\n * vs. a reachable-but-erroring server so callers can print an honest\n * message instead of collapsing both into \"offline\" (ADR-308 failure\n * policy: local ruflo functionality is never affected by auth being\n * unavailable, but the diagnostic should say WHY it's unavailable).\n */\nexport async function refreshAccessToken(refreshTokenValue: string): Promise<OAuthTokenResponse> {\n  const sec = await loadSecurityOAuth();\n  try {\n    return await sec.refreshToken(refreshTokenValue);\n  } catch (e) {\n    if (e instanceof sec.OAuthError) {\n      if (e.code === 'network') {\n        throw new Error(\n          'Could not reach the Cognitum auth service. ruflo core functionality is unaffected — ' +\n            'sign-in is not required for local use.',\n        );\n      }\n      throw new Error(`Cognitum auth service returned an unexpected response: ${e.message}`);\n    }\n    throw e;\n  }\n}\n\n/**\n * Returns an access token suitable for an authenticated call.\n *\n * Fast path: a process-memory token with more than one minute remaining.\n * Slow path: load the profile's refresh token from the OS keychain, perform\n * one refresh, persist a rotated refresh token BEFORE exposing the new access\n * token, then update metadata and the process cache. Refresh is deliberately\n * demand-driven: offline-safe commands such as plain `auth status` never call","sourceCodeStart":198,"sourceCodeEnd":234,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/auth/client.ts#L198-L234","documentation":"refreshAccessToken() maps an OAuthError with code 'network' from @claude-flow/security's refreshToken() into this offline diagnostic. Per ADR-308's failure policy it distinguishes \"network unreachable\" from \"reachable but erroring\": the message deliberately states that local ruflo functionality is unaffected and sign-in is not required for local use. There is no built-in retry loop; refresh is demand-driven.","triggerScenarios":"Any call to getValidAccessToken()/refreshAccessToken() while auth.cognitum.one is unreachable: no internet, DNS resolution failure, connection refused/timeout, firewall or corporate proxy blocking the host, or a TLS-intercepting middlebox dropping the connection.","commonSituations":"Air-gapped or hotel/offline development; CI runners behind restrictive egress allow-lists that whitelist npm but not the auth domain; VPN split-tunneling dropping the auth host; transient ISP/DNS outages during a long-lived session attempting a token refresh.","solutions":["Treat it as non-fatal: continue with local ruflo commands — auth is optional for local use per ADR-308","Check basic connectivity to the auth host: curl -sS https://auth.cognitum.one or check DNS/proxy env vars (HTTPS_PROXY, HTTP_PROXY, NO_PROXY)","If behind a corporate proxy, configure it so node's fetch reaches auth.cognitum.one, then retry the command that needed auth","Retry later once network is restored; the next authenticated command will refresh on demand"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Pre-flight reachability check before demanding auth\nasync function authReachable(): Promise<boolean> {\n  try {\n    await fetch('https://auth.cognitum.one', { method: 'HEAD', signal: AbortSignal.timeout(3000) });\n    return true;\n  } catch { return false; }\n}","typeGuard":"function isAuthUnreachableError(e: unknown): boolean {\n  return e instanceof Error && e.message.startsWith('Could not reach the Cognitum auth service');\n}","tryCatchPattern":"try {\n  token = await getValidAccessToken(profile);\n} catch (e) {\n  if (isAuthUnreachableError(e)) {\n    // ADR-308: degrade to local-only mode, never retry-loop\n    return runWithoutAuth();\n  }\n  throw e;\n}","preventionTips":["Design commands to work offline unless an authenticated capability is explicitly needed","Don't wrap this in an automatic retry loop — refresh is demand-driven by design","Surface the diagnostic as-is; it already explains that local use is unaffected"],"tags":["auth","oauth","network","offline","diagnostic"],"backgroundTag":"auth-service-unreachable","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}