@knpkv/atlassian-common 1.5.0 → 1.7.0

package/test/cliAuth.oauthServer.test.ts

@@ -0,0 +1,276 @@
+/** @effect-diagnostics strictEffectProvide:skip-file */
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient"
+import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer"
+import { describe, expect, it } from "@effect/vitest"
+import * as Cause from "effect/Cause"
+import * as Effect from "effect/Effect"
+import * as Fiber from "effect/Fiber"
+import { HttpClient, HttpClientRequest, HttpServer, HttpServerError } from "effect/http"
+import * as Layer from "effect/Layer"
+import { NetAddress } from "effect/net"
+import * as Predicate from "effect/Predicate"
+import * as Ref from "effect/Ref"
+import { createServer } from "node:http"
+import { HttpServerFactoryLive } from "../src/cli-auth/internal/NodeLayers.js"
+import {
+  callbackServerListenOptions,
+  callbackUrl,
+  HttpServerFactoryTag,
+  makeHttpServerFactory,
+  startCallbackServer
+} from "../src/cli-auth/internal/oauthServer.js"
+
+const HttpClientLive = NodeHttpClient.layerUndici
+const EphemeralHttpServerFactoryLive = makeHttpServerFactory(
+  () => NodeHttpServer.layerServer(createServer, { port: 0 })
+)
+const fakeHttpServer = (port: number): HttpServer.HttpServer["Service"] =>
+  HttpServer.make({
+    address: NetAddress.inetAddressFromIpStringUnsafe("127.0.0.1", port),
+    serve: () => Effect.void
+  })
+
+describe("oauthServer", () => {
+  describe("startCallbackServer", () => {
+    it.effect("binds the same localhost name advertised by the callback URL", () =>
+      Effect.scoped(
+        Effect.gen(function*() {
+          const listenOptions = callbackServerListenOptions(0)
+          const factory = yield* HttpServerFactoryTag
+          const server = yield* HttpServer.HttpServer.pipe(
+            Effect.provide(factory.createServerLayer(listenOptions))
+          )
+          const advertisedUrl = new URL(callbackUrl(8585))
+          const ipv6OnlyLocalhost = (hostname: string) => (hostname === "localhost" ? "::1" : undefined)
+          expect(NetAddress.isInetAddress(server.address)).toBe(true)
+          expect(listenOptions.host).toBe(advertisedUrl.hostname)
+          expect(ipv6OnlyLocalhost(listenOptions.host)).toBe("::1")
+          expect(ipv6OnlyLocalhost(advertisedUrl.hostname)).toBe("::1")
+        }).pipe(Effect.provide(HttpServerFactoryLive))
+      ))
+
+    it.effect("starts server and returns port", () =>
+      Effect.scoped(
+        Effect.gen(function*() {
+          const expectedState = "test-state-123"
+          const result = yield* startCallbackServer(expectedState)
+
+          expect(result.port).toBeGreaterThan(0)
+          expect(Predicate.isObject(result.codePromise)).toBe(true)
+        }).pipe(Effect.provide(EphemeralHttpServerFactoryLive))
+      ))
+
+    it.effect("handles successful callback with code", () =>
+      Effect.scoped(
+        Effect.gen(function*() {
+          const expectedState = "test-state-456"
+          const { codePromise, port } = yield* startCallbackServer(expectedState)
+
+          // Make callback request in background
+          const codeReceiver = yield* Effect.forkChild(codePromise)
+
+          // Simulate OAuth callback using Effect HttpClient
+          const client = yield* HttpClient.HttpClient
+          const request = HttpClientRequest.get(`http://127.0.0.1:${port}/callback`).pipe(
+            HttpClientRequest.setUrlParam("code", "auth_code_123"),
+            HttpClientRequest.setUrlParam("state", expectedState)
+          )
+          yield* client.execute(request)
+
+          const code = yield* Fiber.join(codeReceiver)
+          expect(code).toBe("auth_code_123")
+        }).pipe(Effect.provide(Layer.mergeAll(EphemeralHttpServerFactoryLive, HttpClientLive)))
+      ))
+
+    it.effect("releases the callback port when the owning workflow fails", () =>
+      Effect.gen(function*() {
+        yield* Effect.scoped(
+          startCallbackServer("first").pipe(
+            Effect.provide(EphemeralHttpServerFactoryLive),
+            Effect.andThen(Effect.fail("browser-open-failed")),
+            Effect.flip
+          )
+        )
+
+        const port = yield* Effect.scoped(
+          startCallbackServer("second").pipe(
+            Effect.provide(EphemeralHttpServerFactoryLive),
+            Effect.map((server) => server.port)
+          )
+        )
+        expect(port).toBeGreaterThan(0)
+      }))
+
+    it.effect("starts concurrent real callback servers on distinct OS-assigned ports", () =>
+      Effect.scoped(
+        Effect.gen(function*() {
+          const [first, second] = yield* Effect.all(
+            [startCallbackServer("first"), startCallbackServer("second")],
+            { concurrency: "unbounded" }
+          )
+          expect(first.port).toBeGreaterThan(0)
+          expect(second.port).toBeGreaterThan(0)
+          expect(first.port).not.toBe(second.port)
+        }).pipe(Effect.provide(EphemeralHttpServerFactoryLive))
+      ))
+
+    it.effect("retries occupied fixed-range ports with the injected factory", () => {
+      const attempts = Ref.makeUnsafe<ReadonlyArray<number>>([])
+      const occupiedFactory = makeHttpServerFactory(({ port }) =>
+        Layer.effect(
+          HttpServer.HttpServer,
+          Ref.update(attempts, (ports) => [...ports, port]).pipe(
+            Effect.andThen(
+              port < 8587
+                ? Effect.fail(new HttpServerError.ServeError({ cause: { code: "EADDRINUSE" } }))
+                : Effect.succeed(fakeHttpServer(port))
+            )
+          )
+        )
+      )
+
+      return Effect.scoped(
+        Effect.gen(function*() {
+          const server = yield* startCallbackServer("state")
+          expect(server.port).toBe(8587)
+          expect(yield* Ref.get(attempts)).toEqual([8585, 8586, 8587])
+        }).pipe(Effect.provide(occupiedFactory))
+      )
+    })
+
+    it.effect("maps a multiply retried server failure to one OAuth error", () => {
+      const attempts = Ref.makeUnsafe<ReadonlyArray<number>>([])
+      const terminalFailure = new HttpServerError.ServeError({ cause: { code: "EACCES" } })
+      const failingFactory = makeHttpServerFactory(({ port }) =>
+        Layer.effect(
+          HttpServer.HttpServer,
+          Ref.update(attempts, (ports) => [...ports, port]).pipe(
+            Effect.andThen(
+              port < 8587
+                ? Effect.fail(new HttpServerError.ServeError({ cause: { code: "EADDRINUSE" } }))
+                : Effect.fail(terminalFailure)
+            )
+          )
+        )
+      )
+
+      return Effect.scoped(
+        Effect.gen(function*() {
+          const error = yield* startCallbackServer("state").pipe(Effect.flip)
+          expect(error.cause).toBe(terminalFailure)
+          expect(error.message.split("OAuth authorize failed:").length - 1).toBe(1)
+          expect(yield* Ref.get(attempts)).toEqual([8585, 8586, 8587])
+        }).pipe(Effect.provide(failingFactory))
+      )
+    })
+
+    it.effect("does not retry a non-address-in-use server failure", () => {
+      const attempts = Ref.makeUnsafe(0)
+      const failingFactory = makeHttpServerFactory(() =>
+        Layer.effect(
+          HttpServer.HttpServer,
+          Ref.update(attempts, (count) => count + 1).pipe(
+            Effect.andThen(Effect.fail(
+              new HttpServerError.ServeError({
+                cause: { code: "ECONNREFUSED" }
+              })
+            ))
+          )
+        )
+      )
+
+      return Effect.scoped(
+        startCallbackServer("state").pipe(
+          Effect.provide(failingFactory),
+          Effect.flip,
+          Effect.tap(() => Ref.get(attempts).pipe(Effect.map((count) => expect(count).toBe(1))))
+        )
+      )
+    })
+
+    it.effect("ignores a forged error callback before accepting the legitimate state", () =>
+      Effect.scoped(
+        Effect.gen(function*() {
+          const expectedState = "expected-state"
+          const { codePromise, port } = yield* startCallbackServer(expectedState)
+          const codeReceiver = yield* Effect.forkChild(codePromise)
+          const client = yield* HttpClient.HttpClient
+
+          const forgedResponse = yield* client.execute(
+            HttpClientRequest.get(`http://127.0.0.1:${port}/callback`).pipe(
+              HttpClientRequest.setUrlParam("error", "access_denied")
+            )
+          )
+          expect(forgedResponse.status).toBe(403)
+          yield* client.execute(
+            HttpClientRequest.get(`http://127.0.0.1:${port}/callback`).pipe(
+              HttpClientRequest.setUrlParam("code", "legitimate-code"),
+              HttpClientRequest.setUrlParam("state", expectedState)
+            )
+          )
+
+          expect(yield* Fiber.join(codeReceiver)).toBe("legitimate-code")
+        }).pipe(Effect.provide(Layer.mergeAll(EphemeralHttpServerFactoryLive, HttpClientLive)))
+      ))
+
+    it.effect("accepts a provider error only after validating state", () =>
+      Effect.scoped(
+        Effect.gen(function*() {
+          const expectedState = "expected-state"
+          const { codePromise, port } = yield* startCallbackServer(expectedState)
+          const codeReceiver = yield* Effect.forkChild(codePromise)
+          const client = yield* HttpClient.HttpClient
+
+          yield* client.execute(
+            HttpClientRequest.get(`http://127.0.0.1:${port}/callback`).pipe(
+              HttpClientRequest.setUrlParam("error", "access_denied"),
+              HttpClientRequest.setUrlParam("state", expectedState)
+            )
+          )
+
+          const error = yield* Fiber.join(codeReceiver).pipe(Effect.flip)
+          expect(String(error.cause)).toContain("access_denied")
+          expect(error.message).toBe("OAuth authorize failed: access_denied")
+        }).pipe(Effect.provide(Layer.mergeAll(EphemeralHttpServerFactoryLive, HttpClientLive)))
+      ))
+    it.effect("reports the provider error code when its description is empty", () =>
+      Effect.scoped(
+        Effect.gen(function*() {
+          const expectedState = "expected-state"
+          const { codePromise, port } = yield* startCallbackServer(expectedState)
+          const codeReceiver = yield* Effect.forkChild(codePromise)
+          const client = yield* HttpClient.HttpClient
+
+          yield* client.execute(
+            HttpClientRequest.get(`http://127.0.0.1:${port}/callback`).pipe(
+              HttpClientRequest.setUrlParam("error", "access_denied"),
+              HttpClientRequest.setUrlParam("error_description", ""),
+              HttpClientRequest.setUrlParam("state", expectedState)
+            )
+          )
+
+          const error = yield* Fiber.join(codeReceiver).pipe(Effect.flip)
+          expect(error.cause).toBe("access_denied")
+        }).pipe(Effect.provide(Layer.mergeAll(EphemeralHttpServerFactoryLive, HttpClientLive)))
+      ))
+    it.effect("fails promptly when the handler cannot be installed", () =>
+      Effect.scoped(
+        Effect.gen(function*() {
+          const exit = yield* startCallbackServer("state").pipe(
+            Effect.provide(makeHttpServerFactory(() =>
+              Layer.succeed(
+                HttpServer.HttpServer,
+                HttpServer.make({
+                  address: NetAddress.inetAddressFromIpStringUnsafe("127.0.0.1", 8585),
+                  serve: () => Effect.die("handler-install-failed")
+                })
+              )
+            )),
+            Effect.exit
+          )
+          expect(exit._tag).toBe("Failure")
+          expect(String(exit._tag === "Failure" ? Cause.squash(exit.cause) : "")).toContain("handler-install-failed")
+        })
+      ))
+  })
+})

package/test/cliAuth.openBrowser.test.ts

@@ -0,0 +1,70 @@
+/** @effect-diagnostics strictEffectProvide:skip-file */
+/**
+ * The launcher order and when it stops. A launcher that is missing or exits
+ * non-zero falls through to the next; when none succeeds the failure is typed so
+ * the caller decides whether that is fatal.
+ */
+import { describe, expect, it } from "@effect/vitest"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as PlatformError from "effect/PlatformError"
+import { ChildProcessSpawner } from "effect/process"
+import * as Sink from "effect/Sink"
+import * as Stream from "effect/Stream"
+import { openBrowser } from "../src/cli-auth/index.js"
+
+// `outcomes` maps a launcher to its exit code; a launcher not listed is missing.
+const launchers = (outcomes: Readonly<Record<string, number>>, attempts: Array<string>) =>
+  Layer.succeed(
+    ChildProcessSpawner.ChildProcessSpawner,
+    ChildProcessSpawner.make((command) => {
+      const name = command._tag === "StandardCommand" ? command.command : "piped"
+      attempts.push(name)
+      const exitCode = outcomes[name]
+      if (exitCode === undefined) {
+        return Effect.fail(PlatformError.systemError({ _tag: "NotFound", module: "ChildProcess", method: "spawn" }))
+      }
+      return Effect.succeed(ChildProcessSpawner.makeHandle({
+        all: Stream.empty,
+        exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(exitCode)),
+        getInputFd: () => Sink.drain,
+        getOutputFd: () => Stream.empty,
+        isRunning: Effect.succeed(false),
+        kill: () => Effect.void,
+        pid: ChildProcessSpawner.ProcessId(1),
+        reref: Effect.void,
+        stderr: Stream.empty,
+        stdin: Sink.drain,
+        stdout: Stream.empty,
+        unref: Effect.succeed(Effect.void)
+      }))
+    })
+  )
+
+describe("openBrowser", () => {
+  it.effect("stops at the first launcher that exits 0", () =>
+    Effect.gen(function*() {
+      const attempts: Array<string> = []
+      yield* openBrowser("https://example.test").pipe(Effect.provide(launchers({ "xdg-open": 0 }, attempts)))
+      expect(attempts).toEqual(["open", "xdg-open"])
+    }))
+
+  it.effect("falls through a launcher that exits non-zero", () =>
+    Effect.gen(function*() {
+      const attempts: Array<string> = []
+      yield* openBrowser("https://example.test").pipe(
+        Effect.provide(launchers({ open: 1, "xdg-open": 3, "rundll32.exe": 0 }, attempts))
+      )
+      expect(attempts).toEqual(["open", "xdg-open", "rundll32.exe"])
+    }))
+
+  it.effect("fails with the last launcher's exit when none succeeds", () =>
+    Effect.gen(function*() {
+      const attempts: Array<string> = []
+      const error = yield* openBrowser("https://example.test").pipe(
+        Effect.provide(launchers({ open: 1, "xdg-open": 4, "rundll32.exe": 2 }, attempts)),
+        Effect.flip
+      )
+      expect(error).toMatchObject({ _tag: "BrowserOpenError", command: "rundll32.exe", exitCode: 2 })
+    }))
+})

package/test/cliAuth.refresh.test.ts

@@ -0,0 +1,304 @@
+/** @effect-diagnostics strictEffectProvide:skip-file */
+/**
+ * What a failed token refresh is allowed to do to the stored credential.
+ *
+ * Atlassian rotates refresh tokens, so a refresh that does not complete leaves
+ * the client unable to tell whether the grant landed. Deleting the profile in
+ * that state is unrecoverable and unattended — `JiraApiConfigLive` builds on
+ * every CLI invocation, and jcf's statusline runs one every 30 seconds — so a
+ * bad network window could silently log the user out with nobody watching.
+ *
+ * The rule: discard the stored token only when Atlassian actually rejected it
+ * (a 4xx). Anything else — timeout, transport failure — keeps the credential so
+ * the next run can retry.
+ */
+import { NodeFileSystem, NodePath, NodeServices } from "@effect/platform-node"
+import { describe, expect, it } from "@effect/vitest"
+import { ConfigProvider } from "effect"
+import * as Data from "effect/Data"
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import * as Fiber from "effect/Fiber"
+import * as FileSystem from "effect/FileSystem"
+import { HttpClient, HttpClientResponse } from "effect/http"
+import * as Layer from "effect/Layer"
+import { TestClock } from "effect/testing"
+import { makeAtlassianCliAuth, NodeCliAuthLive } from "../src/cli-auth/index.js"
+import { loadActiveProfileToken, saveProfileToken } from "../src/config/AuthProfiles.js"
+import { HomeDirectoryLive } from "../src/config/ConfigPaths.js"
+import { saveOAuthConfig } from "../src/config/TokenStorage.js"
+
+const TOOL = "test-cli"
+
+class TestAuthMissing extends Data.TaggedError("TestAuthMissing") {}
+
+const authOptions = {
+  toolName: TOOL,
+  commandName: "test",
+  productName: "Test",
+  scopes: ["offline_access"],
+  authMissing: () => new TestAuthMissing()
+}
+
+const expiredToken = {
+  access_token: "expired-access",
+  refresh_token: "rotating-refresh",
+  expires_at: 0,
+  token_type: "Bearer",
+  scope: "offline_access",
+  cloud_id: "cloud-1",
+  site_url: "https://example.atlassian.net"
+}
+
+const storage = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer, HomeDirectoryLive)
+
+// The auth also needs a spawner (browser launch during login) and Crypto (PKCE).
+// Without them construction dies as a defect, which no `catchTag` would see — and
+// the assertions below would then pass without the refresh ever running.
+const getAccessTokenWith = (client: Layer.Layer<HttpClient.HttpClient>) =>
+  makeAtlassianCliAuth(authOptions).pipe(
+    Effect.flatMap((auth) => auth.getAccessToken()),
+    Effect.provide(Layer.mergeAll(client, NodeServices.layer, NodeCliAuthLive))
+  )
+
+// A client that never answers — the stall case, driven by TestClock. It reports
+// when the request has actually been issued so the test can advance the clock at
+// a point where the refresh deadline is registered; adjusting before that would
+// move past the deadline before it exists and hang.
+const stalledClient = (issued: Deferred.Deferred<void>) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make(() => Effect.flatMap(Deferred.succeed(issued, undefined), () => Effect.never))
+  )
+
+const respondingClient = (status: number, body: string) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) => Effect.succeed(HttpClientResponse.fromWeb(request, new Response(body, { status }))))
+  )
+
+// A client that answers with the one thing that does prove the token is dead.
+const rejectingClient = respondingClient(400, JSON.stringify({ error: "invalid_grant" }))
+
+// A rotation that only completes once the test says so, so interruption can be
+// aimed at the exact window between the grant and the token being persisted.
+const gatedClient = (issued: Deferred.Deferred<void>, release: Deferred.Deferred<void>) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) =>
+      Effect.gen(function*() {
+        yield* Deferred.succeed(issued, undefined)
+        yield* Deferred.await(release)
+        return HttpClientResponse.fromWeb(
+          request,
+          new Response(
+            JSON.stringify({
+              access_token: "fresh-access",
+              refresh_token: "rotated-refresh",
+              expires_in: 3600,
+              scope: "offline_access",
+              token_type: "Bearer"
+            }),
+            { status: 200, headers: { "content-type": "application/json" } }
+          )
+        )
+      })
+    )
+  )
+
+// `HomeDirectoryLive` resolves HOME through the ambient ConfigProvider, so the
+// test home can be injected rather than set on `process.env` — a global that
+// parallel tests would race each other to overwrite and restore. The directory
+// is scoped, so it is removed when the effect finishes either way.
+const withHome = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const home = yield* fs.makeTempDirectoryScoped({ prefix: "atlassian-cli-auth-" })
+    return yield* effect.pipe(
+      Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env: { HOME: home } })))
+    )
+  }).pipe(Effect.scoped, Effect.provide(NodeFileSystem.layer))
+
+const storedToken = loadActiveProfileToken(TOOL).pipe(Effect.provide(storage))
+
+// Both the token and the client config have to be on disk, or `getConfig`
+// short-circuits the refresh before any request is made and the assertions
+// below would pass without exercising anything.
+const seedExpiredToken = Effect.gen(function*() {
+  yield* saveOAuthConfig(TOOL, { clientId: "client-1", clientSecret: "secret-1" })
+  yield* saveProfileToken(TOOL, expiredToken)
+}).pipe(Effect.provide(storage))
+
+describe("Atlassian CLI token refresh", () => {
+  it.effect("keeps the stored credential when the refresh never answers", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedExpiredToken
+
+      const issued = yield* Deferred.make<void>()
+      const attempt = getAccessTokenWith(stalledClient(issued)).pipe(
+        Effect.exit
+      )
+      const fiber = yield* attempt.pipe(Effect.forkChild({ startImmediately: true }))
+
+      yield* Deferred.await(issued)
+      yield* TestClock.adjust("31 seconds")
+      const exit = yield* Fiber.join(fiber)
+
+      expect(exit._tag).toBe("Failure")
+      // The point of the test: a stall is not evidence, so the token survives.
+      const after = yield* storedToken
+      expect(after?.refresh_token).toBe("rotating-refresh")
+    })))
+
+  // Rate limiting is the case this most needs to survive: several `jira`/`jcf`
+  // processes on one expired token hit the endpoint together, one wins the
+  // rotation and the rest get 429. Treating that as a verdict on the token
+  // would log the user out precisely when things are busiest.
+  it.effect("keeps the stored credential when the provider rate-limits", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedExpiredToken
+
+      const exit = yield* getAccessTokenWith(respondingClient(429, "Too Many Requests")).pipe(
+        Effect.exit
+      )
+
+      expect(exit._tag).toBe("Failure")
+      const after = yield* storedToken
+      expect(after?.refresh_token).toBe("rotating-refresh")
+    })))
+
+  // `refreshToken` sends the client credentials in the body, so a wrong or
+  // rotated secret comes back as `400 invalid_client` — a config problem, not a
+  // dead token. Deleting here would destroy a working credential and force a
+  // re-login that fails identically until `jira auth configure` is run.
+  it.effect("keeps the stored credential when the client credentials are rejected", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedExpiredToken
+
+      const exit = yield* getAccessTokenWith(respondingClient(400, JSON.stringify({ error: "invalid_client" }))).pipe(
+        Effect.exit
+      )
+
+      expect(exit._tag).toBe("Failure")
+      const after = yield* storedToken
+      expect(after?.refresh_token).toBe("rotating-refresh")
+    })))
+
+  // A bare 403 is as likely to be a proxy or WAF as Atlassian revoking
+  // anything, so the code has to say so explicitly.
+  it.effect("keeps the stored credential on a 403 that does not say invalid_grant", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedExpiredToken
+
+      const exit = yield* getAccessTokenWith(respondingClient(403, "<html>Forbidden</html>")).pipe(
+        Effect.exit
+      )
+
+      expect(exit._tag).toBe("Failure")
+      const after = yield* storedToken
+      expect(after?.refresh_token).toBe("rotating-refresh")
+    })))
+
+  it.effect("discards the stored credential on a 403 revocation", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedExpiredToken
+
+      const exit = yield* getAccessTokenWith(respondingClient(403, JSON.stringify({ error: "invalid_grant" }))).pipe(
+        Effect.exit
+      )
+
+      expect(exit._tag).toBe("Failure")
+      const after = yield* storedToken
+      expect(after).toBeNull()
+    })))
+
+  // An unparseable body is no verdict at all, so the conservative reading wins.
+  it.effect("keeps the stored credential when the error body is unparseable", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedExpiredToken
+
+      const exit = yield* getAccessTokenWith(respondingClient(400, "not json at all")).pipe(
+        Effect.exit
+      )
+
+      expect(exit._tag).toBe("Failure")
+      const after = yield* storedToken
+      expect(after?.refresh_token).toBe("rotating-refresh")
+    })))
+
+  // The atomicity half: once the grant is out, the replacement must reach disk
+  // even though the caller has already given up on the fiber.
+  it.effect("persists the rotated token even when interrupted mid-rotation", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedExpiredToken
+      const issued = yield* Deferred.make<void>()
+      const release = yield* Deferred.make<void>()
+
+      const fiber = yield* getAccessTokenWith(gatedClient(issued, release)).pipe(
+        Effect.exit,
+        Effect.forkChild({ startImmediately: true })
+      )
+
+      yield* Deferred.await(issued) // the grant is in flight
+      const interrupting = yield* Fiber.interrupt(fiber).pipe(Effect.forkChild({ startImmediately: true }))
+      yield* Deferred.succeed(release, undefined) // now let it answer
+      yield* Fiber.join(interrupting)
+
+      // The interrupt could not tear the rotation in half, so the replacement
+      // is on disk rather than lost with the token it consumed.
+      const after = yield* storedToken
+      expect(after?.refresh_token).toBe("rotated-refresh")
+    })))
+
+  // A second caller that arrives mid-refresh waits on the first caller's
+  // result. If the first caller is interrupted, the waiter must still settle
+  // instead of blocking forever on a result nobody will publish.
+  it.live("settles a waiting caller when the refreshing caller is interrupted", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedExpiredToken
+      const issued = yield* Deferred.make<void>()
+      const release = yield* Deferred.make<void>()
+      const auth = yield* makeAtlassianCliAuth(authOptions).pipe(
+        Effect.provide(Layer.mergeAll(gatedClient(issued, release), NodeServices.layer, NodeCliAuthLive))
+      )
+
+      const owner = yield* auth.getAccessToken().pipe(Effect.forkChild({ startImmediately: true }))
+      yield* Deferred.await(issued) // the owner holds the refresh lock, grant in flight
+      const waiter = yield* auth.getAccessToken().pipe(Effect.exit, Effect.forkChild({ startImmediately: true }))
+      const interrupting = yield* Fiber.interrupt(owner).pipe(Effect.forkChild({ startImmediately: true }))
+      yield* Deferred.succeed(release, undefined)
+      yield* Fiber.join(interrupting)
+
+      const settled = yield* Fiber.join(waiter).pipe(Effect.timeoutOption("2 seconds"))
+      expect(settled._tag).toBe("Some")
+    })))
+
+  it.effect("discards the stored credential only when the provider rejects it", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedExpiredToken
+
+      const exit = yield* getAccessTokenWith(rejectingClient).pipe(
+        Effect.exit
+      )
+
+      expect(exit._tag).toBe("Failure")
+      const after = yield* storedToken
+      expect(after).toBeNull()
+    })))
+
+  it.effect("names the CLI's own login command when the token is spent", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedExpiredToken
+
+      const error = yield* getAccessTokenWith(rejectingClient).pipe(Effect.flip)
+
+      expect(error).toMatchObject({ _tag: "OAuthError", step: "refresh", status: 400, errorCode: "invalid_grant" })
+      expect(error.message).toContain("Please run 'test auth login'")
+    })))
+
+  it.effect("fails with the CLI's own error when nobody is logged in", () =>
+    withHome(Effect.gen(function*() {
+      const error = yield* getAccessTokenWith(rejectingClient).pipe(Effect.flip)
+      expect(error._tag).toBe("TestAuthMissing")
+    })))
+})