@knpkv/atlassian-common 1.4.1 → 1.6.0

package/test/cliAuth.guardrails.test.ts

@@ -0,0 +1,76 @@
+/** @effect-diagnostics strictEffectProvide:skip-file */
+import { NodeServices } from "@effect/platform-node"
+import { describe, expect, it } from "@effect/vitest"
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import * as Path from "effect/Path"
+import { ChildProcess, ChildProcessSpawner } from "effect/process"
+import * as Schema from "effect/Schema"
+import * as Stream from "effect/Stream"
+import confluenceIntegration from "../../confluence-to-markdown/vitest.config.integration.js"
+import confluence from "../../confluence-to-markdown/vitest.config.js"
+import jiraIntegration from "../../jira-cli/vitest.config.integration.js"
+import jira from "../../jira-cli/vitest.config.js"
+import clockify from "../../jira-clockify/vitest.config.js"
+
+const configs = { jira, jiraIntegration, confluence, confluenceIntegration, clockify }
+const Findings = Schema.fromJsonString(Schema.Array(Schema.Struct({ file: Schema.String })))
+
+describe("CLI auth guardrails", () => {
+  for (const [name, config] of Object.entries(configs)) {
+    it(`${name} resolves CLI auth from source rather than stale build output`, () => {
+      expect(config.resolve?.alias).toHaveProperty(
+        "@knpkv/atlassian-common/cli-auth",
+        new URL("../src/cli-auth/index.ts", import.meta.url).pathname
+      )
+    })
+  }
+
+  it.effect("limits the reimplementation guard to the Jira and Confluence CLIs", () =>
+    Effect.gen(function*() {
+      const fs = yield* FileSystem.FileSystem
+      const path = yield* Path.Path
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+      const root = yield* path.fromFileUrl(new URL("../../../", import.meta.url))
+      const fixture = yield* fs.makeTempDirectoryScoped({ prefix: "cli-auth-guard-" })
+      yield* fs.writeFileString(
+        path.join(fixture, "sgconfig.yml"),
+        "ruleDirs: []\nlanguageGlobs:\n  tsx:\n    - \"**/*.ts\"\n"
+      )
+      // The same callback-server name and endpoint namespace are legitimate in
+      // another integration. Only the two delegated CLI implementations are banned.
+      const source = [
+        "import * as Auth from \"@knpkv/atlassian-common/auth\"",
+        "import { refreshToken } from \"@knpkv/atlassian-common/auth\"",
+        "const authUrl = Auth.buildAuthUrl({ clientId: \"client\" })",
+        "function startCallbackServer(state: string) { return state }"
+      ].join("\n")
+      for (const name of ["jira-cli", "confluence-to-markdown", "other-oauth"]) {
+        const directory = path.join(fixture, "packages", name, "src")
+        yield* fs.makeDirectory(directory, { recursive: true })
+        yield* fs.writeFileString(path.join(directory, "auth.ts"), source)
+      }
+      const handle = yield* spawner.spawn(ChildProcess.make(
+        path.join(root, "node_modules", ".bin", "ast-grep"),
+        [
+          "scan",
+          "--rule",
+          path.join(root, "ast-grep", "rules", "packaging", "no-atlassian-cli-auth-reimplementation.yml"),
+          "--json=compact",
+          "packages"
+        ],
+        { cwd: fixture }
+      ))
+      const { exitCode, stderr, stdout } = yield* Effect.all({
+        exitCode: handle.exitCode,
+        stdout: Stream.decodeText(handle.stdout).pipe(Stream.mkString),
+        stderr: Stream.decodeText(handle.stderr).pipe(Stream.mkString)
+      }, { concurrency: "unbounded" })
+      expect(exitCode, `${fixture}: ${stdout} ${stderr}`).toBe(1)
+      const findings = yield* Schema.decodeUnknownEffect(Findings)(stdout)
+      expect(findings.map(({ file }) => file).sort()).toEqual([
+        ...Array<string>(3).fill("packages/confluence-to-markdown/src/auth.ts"),
+        ...Array<string>(3).fill("packages/jira-cli/src/auth.ts")
+      ])
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)))
+})

package/test/cliAuth.login.test.ts

@@ -0,0 +1,319 @@
+/** @effect-diagnostics strictEffectProvide:skip-file */
+/**
+ * Browser login through the shared Atlassian CLI auth.
+ *
+ * The login prints the authorization URL before it tries to open a browser, so
+ * a browser that will not open must not end the login: the user can still visit
+ * the URL. A callback server that cannot bind, on the other hand, must end it
+ * before any URL is advertised, and the server must stop whenever the login's
+ * scope closes.
+ */
+import { NodeFileSystem, NodePath, NodeServices } from "@effect/platform-node"
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient"
+import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer"
+import { describe, expect, it } from "@effect/vitest"
+import { ConfigProvider } from "effect"
+import * as Console from "effect/Console"
+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, HttpClientRequest, HttpClientResponse, HttpServer, HttpServerError } from "effect/http"
+import * as Layer from "effect/Layer"
+import { ChildProcessSpawner } from "effect/process"
+import * as Ref from "effect/Ref"
+import type * as Schema from "effect/Schema"
+import * as Sink from "effect/Sink"
+import * as Stream from "effect/Stream"
+import { TestClock } from "effect/testing"
+import { createServer } from "node:http"
+import { makeAtlassianCliAuth, makeHttpServerFactory } from "../src/cli-auth/index.js"
+import { loadActiveProfileToken } 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: ["read:me", "offline_access"],
+  authMissing: () => new TestAuthMissing()
+}
+
+const storage = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer, HomeDirectoryLive)
+
+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-login-" })
+    return yield* effect.pipe(
+      Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env: { HOME: home } })))
+    )
+  }).pipe(Effect.scoped, Effect.provide(NodeFileSystem.layer))
+
+const seedConfig = saveOAuthConfig(TOOL, { clientId: "client-1", clientSecret: "secret-1" }).pipe(
+  Effect.provide(storage)
+)
+
+const json = (request: HttpClientRequest.HttpClientRequest, body: Schema.Json) =>
+  HttpClientResponse.fromWeb(
+    request,
+    new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json" } })
+  )
+
+// Atlassian's side of a successful login: token exchange, one site, the user.
+interface FakeSite {
+  readonly id: string
+  readonly name: string
+  readonly url: string
+}
+
+const firstSite: FakeSite = { id: "cloud-1", name: "Site", url: "https://site.atlassian.net" }
+const secondSite: FakeSite = { id: "cloud-2", name: "Other", url: "https://other.atlassian.net" }
+
+const atlassianClientWith = (sites: ReadonlyArray<FakeSite>) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) => {
+      if (request.url.endsWith("/oauth/token")) {
+        return Effect.succeed(json(request, {
+          access_token: "access-1",
+          refresh_token: "refresh-1",
+          expires_in: 3600,
+          scope: "read:me offline_access",
+          token_type: "Bearer"
+        }))
+      }
+      if (request.url.endsWith("/accessible-resources")) {
+        return Effect.succeed(json(request, sites.map((site) => ({ ...site, scopes: [] }))))
+      }
+      return Effect.succeed(json(request, { account_id: "acc-1", name: "Ada", email: "ada@example.com" }))
+    })
+  )
+
+const atlassianClient = atlassianClientWith([firstSite])
+
+// Every launcher runs and reports failure — merged after NodeServices so it
+// replaces the real spawner rather than being replaced by it, the way `xdg-open` does on a host
+// with no browser. The first launch hands its URL to the test.
+const failingLaunchers = (launched: Deferred.Deferred<string>, attempts: Ref.Ref<ReadonlyArray<string>>) =>
+  Layer.succeed(
+    ChildProcessSpawner.ChildProcessSpawner,
+    ChildProcessSpawner.make((command) =>
+      Effect.gen(function*() {
+        if (command._tag === "StandardCommand") {
+          yield* Ref.update(attempts, (all) => [...all, command.command])
+          yield* Deferred.succeed(launched, command.args[command.args.length - 1] ?? "")
+        }
+        return ChildProcessSpawner.makeHandle({
+          all: Stream.empty,
+          exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(1)),
+          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)
+        })
+      })
+    )
+  )
+
+// An ephemeral real server whose shutdown the test can observe.
+const observedServerFactory = (stopped: Ref.Ref<boolean>) =>
+  makeHttpServerFactory(() =>
+    Layer.merge(
+      NodeHttpServer.layerServer(createServer, { port: 0 }),
+      Layer.effectDiscard(Effect.addFinalizer(() => Ref.set(stopped, true)))
+    )
+  )
+
+const captureConsole = (lines: Array<string>): Console.Console =>
+  Object.assign(Object.create(console), {
+    log: (...args: ReadonlyArray<unknown>) => lines.push(args.join(" ")),
+    error: (...args: ReadonlyArray<unknown>) => lines.push(`stderr: ${args.join(" ")}`)
+  })
+
+const deliverCallback = (authUrl: string) =>
+  Effect.gen(function*() {
+    const url = new URL(authUrl)
+    const redirect = url.searchParams.get("redirect_uri") ?? ""
+    const state = url.searchParams.get("state") ?? ""
+    const port = new URL(redirect).port
+    const client = yield* HttpClient.HttpClient
+    yield* client.execute(
+      HttpClientRequest.get(`http://127.0.0.1:${port}/callback`).pipe(
+        HttpClientRequest.setUrlParam("code", "code-1"),
+        HttpClientRequest.setUrlParam("state", state)
+      )
+    )
+  }).pipe(Effect.provide(NodeHttpClient.layerUndici))
+
+describe("Atlassian CLI login", () => {
+  it.live("keeps waiting for the callback when no browser launcher succeeds", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedConfig
+      const launched = yield* Deferred.make<string>()
+      const attempts = yield* Ref.make<ReadonlyArray<string>>([])
+      const lines: Array<string> = []
+      const stopped = yield* Ref.make(false)
+
+      const login = yield* makeAtlassianCliAuth(authOptions).pipe(
+        Effect.flatMap((auth) => auth.login()),
+        Effect.provide(Layer.mergeAll(
+          NodeServices.layer,
+          HomeDirectoryLive,
+          atlassianClient,
+          failingLaunchers(launched, attempts),
+          observedServerFactory(stopped)
+        )),
+        Effect.provideService(Console.Console, captureConsole(lines)),
+        Effect.forkChild({ startImmediately: true })
+      )
+
+      const authUrl = yield* Deferred.await(launched)
+      yield* deliverCallback(authUrl)
+      const result = yield* Fiber.join(login)
+
+      expect(result).toBeUndefined()
+      expect(yield* Ref.get(attempts)).toEqual(["open", "xdg-open", "rundll32.exe"])
+      const printed = lines
+      expect(printed.some((line) => line.includes(`visit: ${authUrl}`))).toBe(true)
+      expect(printed).toContain("stderr: Could not open a browser (rundll32.exe exited 1); visit the URL above.")
+      expect(printed).toContain("Logged in as Ada (ada@example.com)")
+      expect(yield* Ref.get(stopped)).toBe(true)
+      const stored = yield* loadActiveProfileToken(TOOL).pipe(Effect.provide(storage))
+      expect(stored?.cloud_id).toBe("cloud-1")
+    })))
+
+  it.effect("fails before advertising a URL when the callback server cannot bind", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedConfig
+      const launched = yield* Deferred.make<string>()
+      const attempts = yield* Ref.make<ReadonlyArray<string>>([])
+      const lines: Array<string> = []
+      const refused = makeHttpServerFactory(() =>
+        Layer.effect(
+          HttpServer.HttpServer,
+          Effect.fail(new HttpServerError.ServeError({ cause: { code: "EACCES" } }))
+        )
+      )
+
+      const error = yield* makeAtlassianCliAuth(authOptions).pipe(
+        Effect.flatMap((auth) => auth.login()),
+        Effect.provide(
+          Layer.mergeAll(
+            NodeServices.layer,
+            HomeDirectoryLive,
+            atlassianClient,
+            failingLaunchers(launched, attempts),
+            refused
+          )
+        ),
+        Effect.provideService(Console.Console, captureConsole(lines)),
+        Effect.flip
+      )
+
+      expect(error._tag).toBe("OAuthError")
+      expect(yield* Ref.get(attempts)).toEqual([])
+      expect(lines).toEqual([])
+    })))
+
+  it.effect("stops the callback server when authorization times out", () =>
+    withHome(Effect.gen(function*() {
+      yield* seedConfig
+      const launched = yield* Deferred.make<string>()
+      const attempts = yield* Ref.make<ReadonlyArray<string>>([])
+      const lines: Array<string> = []
+      const stopped = yield* Ref.make(false)
+
+      const login = yield* makeAtlassianCliAuth(authOptions).pipe(
+        Effect.flatMap((auth) => auth.login()),
+        Effect.provide(Layer.mergeAll(
+          NodeServices.layer,
+          HomeDirectoryLive,
+          atlassianClient,
+          failingLaunchers(launched, attempts),
+          observedServerFactory(stopped)
+        )),
+        Effect.provideService(Console.Console, captureConsole(lines)),
+        Effect.flip,
+        Effect.forkChild({ startImmediately: true })
+      )
+
+      yield* Deferred.await(launched)
+      // The deadline is registered just after the launch; step the clock past it
+      // in increments so it fires wherever in that window it was set.
+      for (let minute = 0; minute < 10; minute++) {
+        yield* TestClock.adjust("1 minute")
+        yield* Effect.yieldNow
+      }
+      const error = yield* Fiber.join(login)
+
+      expect(error._tag).toBe("OAuthError")
+      expect(String(error.cause)).toBe("Authorization timed out")
+      expect(yield* Ref.get(stopped)).toBe(true)
+    })))
+  // With several sites, the login either lists them for the user to pick from
+  // or uses the one named by --site; an unknown --site fails and lists them.
+  const loginWithSites = (siteUrl: string | undefined) =>
+    Effect.gen(function*() {
+      yield* seedConfig
+      const launched = yield* Deferred.make<string>()
+      const attempts = yield* Ref.make<ReadonlyArray<string>>([])
+      const stopped = yield* Ref.make(false)
+      const lines: Array<string> = []
+      const login = yield* makeAtlassianCliAuth(authOptions).pipe(
+        Effect.flatMap((auth) => auth.login(siteUrl === undefined ? undefined : { siteUrl })),
+        Effect.provide(Layer.mergeAll(
+          NodeServices.layer,
+          HomeDirectoryLive,
+          atlassianClientWith([firstSite, secondSite]),
+          failingLaunchers(launched, attempts),
+          observedServerFactory(stopped)
+        )),
+        Effect.provideService(Console.Console, captureConsole(lines)),
+        Effect.result,
+        Effect.forkChild({ startImmediately: true })
+      )
+      yield* deliverCallback(yield* Deferred.await(launched))
+      const result = yield* Fiber.join(login)
+      const stored = yield* loadActiveProfileToken(TOOL).pipe(Effect.provide(storage))
+      return { result, stored }
+    })
+
+  it.live("lists the sites when several are available and none was chosen", () =>
+    withHome(Effect.gen(function*() {
+      const { result, stored } = yield* loginWithSites(undefined)
+      expect(result).toMatchObject({
+        success: [
+          { id: "cloud-1", name: "Site", url: "https://site.atlassian.net" },
+          { id: "cloud-2", name: "Other", url: "https://other.atlassian.net" }
+        ]
+      })
+      expect(stored).toBeNull()
+    })))
+
+  it.live("logs into the site chosen with --site", () =>
+    withHome(Effect.gen(function*() {
+      const { stored } = yield* loginWithSites("https://other.atlassian.net")
+      expect(stored?.cloud_id).toBe("cloud-2")
+    })))
+
+  it.live("fails and lists the sites when --site names none of them", () =>
+    withHome(Effect.gen(function*() {
+      const { result, stored } = yield* loginWithSites("https://missing.atlassian.net")
+      expect(result).toMatchObject({ failure: { _tag: "OAuthError", step: "authorize" } })
+      expect(String(result._tag === "Failure" ? result.failure.cause : "")).toContain("https://other.atlassian.net")
+      expect(stored).toBeNull()
+    })))
+})

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")
+        })
+      ))
+  })
+})