@knpkv/atlassian-common 1.2.0 → 1.4.1

package/src/auth/OAuthOperations.ts

@@ -23,11 +23,13 @@ import * as Effect from "effect/Effect"
 import * as Schema from "effect/Schema"
 import { HttpClient, HttpClientRequest } from "effect/unstable/http"
 import { type OAuthConfig, type OAuthToken } from "../config/OAuthSchemas.js"
+import { unsafeCurrentTimeMillis } from "../internal/legacyWallClock.js"
 import { ME_URL, RESOURCES_URL, REVOKE_URL, TOKEN_URL } from "./OAuthEndpoints.js"
 import { OAuthError } from "./OAuthErrors.js"
 import {
   type AccessibleResource,
   AccessibleResourceSchema,
+  TokenErrorSchema,
   type TokenResponse,
   TokenResponseSchema,
   type UserInfo,
@@ -48,6 +50,15 @@ export interface ExchangeCodeOptions {
   readonly codeVerifier?: string | undefined
 }
 
+interface AuthorizationCodeTokenBody {
+  readonly grant_type: string
+  readonly client_id: string
+  readonly client_secret: string
+  readonly code: string
+  readonly redirect_uri: string
+  code_verifier?: string
+}
+
 /**
  * Exchange authorization code for tokens.
  *
@@ -57,10 +68,10 @@ export const exchangeCodeForTokens = (
   code: string,
   config: OAuthConfig,
   options: ExchangeCodeOptions
-): Effect.Effect<TokenResponse, OAuthError, HttpClient.HttpClient> =>
+) =>
   Effect.gen(function*() {
     const httpClient = yield* HttpClient.HttpClient
-    const tokenBody: Record<string, string> = {
+    const tokenBody: AuthorizationCodeTokenBody = {
       grant_type: "authorization_code",
       client_id: config.clientId,
       client_secret: config.clientSecret,
@@ -191,8 +202,21 @@ export const refreshToken = (
       const text = yield* response.text.pipe(
         Effect.mapError((cause) => new OAuthError({ step: "refresh", cause }))
       )
+      // The OAuth `error` code is what distinguishes "this grant is spent" from
+      // "your request was malformed", and callers key credential deletion off
+      // it. A body that is not JSON, or not shaped like an OAuth error, simply
+      // leaves it absent — which callers read as "no verdict", not "rejected".
+      const errorCode = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(TokenErrorSchema))(text).pipe(
+        Effect.map((decoded) => decoded.error),
+        Effect.catch(() => Effect.succeed(undefined))
+      )
       return yield* Effect.fail(
-        new OAuthError({ step: "refresh", cause: `HTTP ${response.status}: ${text}` })
+        new OAuthError({
+          step: "refresh",
+          cause: `HTTP ${response.status}: ${text}`,
+          status: response.status,
+          ...(!(errorCode === undefined) && { errorCode })
+        })
       )
     }
 
@@ -260,14 +284,15 @@ export const revokeToken = (
  *
  * @category Utilities
  */
-export const buildOAuthToken = (
+export const buildOAuthTokenAt = (
   tokenResponse: TokenResponse,
   site: AccessibleResource,
-  user: UserInfo
+  user: UserInfo,
+  nowMs: number
 ): OAuthToken => ({
   access_token: tokenResponse.access_token,
   refresh_token: tokenResponse.refresh_token,
-  expires_at: Date.now() + tokenResponse.expires_in * 1000,
+  expires_at: nowMs + tokenResponse.expires_in * 1000,
   scope: tokenResponse.scope,
   cloud_id: site.id,
   site_url: site.url,
@@ -277,3 +302,16 @@ export const buildOAuthToken = (
     email: user.email
   }
 })
+
+/**
+ * Build an OAuth token using the host clock.
+ *
+ * @deprecated Effect workflows should call {@link buildOAuthTokenAt} with
+ * `Clock.currentTimeMillis`. This wrapper preserves the existing synchronous
+ * public API until the next major release.
+ */
+export const buildOAuthToken = (
+  tokenResponse: TokenResponse,
+  site: AccessibleResource,
+  user: UserInfo
+): OAuthToken => buildOAuthTokenAt(tokenResponse, site, user, unsafeCurrentTimeMillis())

package/src/auth/OAuthResponseSchemas.ts

@@ -11,6 +11,18 @@
  */
 import * as Schema from "effect/Schema"
 
+/**
+ * OAuth 2.0 error response body (RFC 6749 §5.2).
+ *
+ * Only `error` is required; providers vary on the rest, so nothing else is
+ * modelled — the code is the part callers act on.
+ *
+ * @category Schema
+ */
+export const TokenErrorSchema = Schema.Struct({
+  error: Schema.String
+})
+
 /**
  * Schema for OAuth2 token response from Atlassian.
  *

package/src/auth/index.ts

@@ -4,14 +4,18 @@
  * @module
  */
 
-// Endpoints and scopes
+// Endpoints and legacy public scope sets. Control Center owns a separate
+// least-privilege release-publication set; proposal-only consumers can use
+// JIRA_PROPOSAL_SCOPES and other write-capable consumers can use JIRA_SCOPES.
 export {
   AUTH_URL,
   buildAuthUrl,
   type BuildAuthUrlOptions,
   computeCodeChallenge,
+  CONFLUENCE_FOLDER_SCOPES,
   CONFLUENCE_SCOPES,
   generateCodeVerifier,
+  JIRA_PROPOSAL_SCOPES,
   JIRA_SCOPES,
   ME_URL,
   RESOURCES_URL,
@@ -25,6 +29,7 @@ export { AuthMissingError, OAuthError, OAuthNotConfiguredError, type OAuthStep }
 // Operations
 export {
   buildOAuthToken,
+  buildOAuthTokenAt,
   exchangeCodeForTokens,
   type ExchangeCodeOptions,
   getAccessibleResources,

package/src/bin.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { NodeFileSystem, NodeHttpClient, NodePath, NodeRuntime, NodeServices, NodeStdio } from "@effect/platform-node"
+import { NodeHttpClient, NodeRuntime, NodeServices } from "@effect/platform-node"
 import * as Console from "effect/Console"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
@@ -99,17 +99,16 @@ const program = Effect.gen(function*() {
   const args = yield* stdio.args
   return yield* cli(args)
 }).pipe(
-  Effect.provide(NodeStdio.layer),
   Effect.provide(
     Layer.mergeAll(
       NodeServices.layer,
-      NodeFileSystem.layer,
-      NodePath.layer,
       NodeHttpClient.layerFetch,
       HomeDirectoryLive
     )
   ),
-  Effect.catch((error: unknown) => Console.error(String(error)).pipe(Effect.andThen(Effect.fail(error))))
+  Effect.catch(<UnparsedInput>(error: UnparsedInput) =>
+    Console.error(String(error)).pipe(Effect.andThen(Effect.fail(error)))
+  )
 )
 
 NodeRuntime.runMain(program, { disableErrorReporting: true })

package/src/config/AuthProfiles.ts

@@ -71,9 +71,11 @@ export type AuthProfilesFile = Schema.Schema.Type<typeof AuthProfilesFileSchema>
 
 const emptyProfiles = (): AuthProfilesFile => ({ profiles: [] })
 
-const parseJsonOrNull = (content: string): unknown | null => {
+const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Json))
+
+const parseJsonOrNull = (content: string): Schema.Json | null => {
   try {
-    return JSON.parse(content)
+    return decodeJson(content)
   } catch {
     return null
   }

package/src/config/ProfileManager.ts

@@ -3,6 +3,7 @@
  *
  * @module
  */
+import * as Clock from "effect/Clock"
 import * as Data from "effect/Data"
 import * as Effect from "effect/Effect"
 import * as FileSystem from "effect/FileSystem"
@@ -10,7 +11,7 @@ import * as Path from "effect/Path"
 import type * as PlatformError from "effect/PlatformError"
 import * as Schema from "effect/Schema"
 import type { HttpClient } from "effect/unstable/http"
-import type { OAuthError } from "../auth/OAuthErrors.js"
+import { OAuthError } from "../auth/OAuthErrors.js"
 import { refreshToken } from "../auth/OAuthOperations.js"
 import {
   type AuthProfile,
@@ -22,7 +23,7 @@ import {
 } from "./AuthProfiles.js"
 import { getProfilesPath, type HomeDirectoryError, HomeDirectoryTag } from "./ConfigPaths.js"
 import { type OAuthToken, OAuthTokenSchema } from "./OAuthSchemas.js"
-import { FileSystemError, isTokenExpired, loadOAuthConfig } from "./TokenStorage.js"
+import { FileSystemError, isTokenExpiredAt, loadOAuthConfig } from "./TokenStorage.js"
 
 export interface AtlassianToolDefinition {
   readonly toolName: string
@@ -42,6 +43,25 @@ export const JIRA_REQUIRED_SCOPES: ReadonlyArray<string> = [
   "offline_access"
 ]
 
+/** Legacy read-only Jira requirements retained for proposal-only consumers. */
+export const JIRA_PROPOSAL_REQUIRED_SCOPES: ReadonlyArray<string> = [
+  "read:jira-work",
+  "read:jira-user",
+  "read:me",
+  "offline_access"
+]
+
+/**
+ * Scopes a Confluence profile must hold to be considered valid.
+ *
+ * Deliberately page-only. The CLI also requests the folder and CQL-search scopes
+ * (`CONFLUENCE_FOLDER_SCOPES`), but they are not listed here: this constant also
+ * gates control-center's per-site scope check, and a profile that can read and
+ * write pages is legitimately valid for everything except `folder`/`search`.
+ * The cost is that `atlassian profiles doctor` reports a pre-folder profile as
+ * valid and those two commands then fail with 401/403 until the OAuth app is
+ * updated and the user logs in again — see the confluence-to-markdown README.
+ */
 export const CONFLUENCE_REQUIRED_SCOPES: ReadonlyArray<string> = [
   "read:page:confluence",
   "write:page:confluence",
@@ -135,7 +155,7 @@ const loadLegacyToken = (
     )
     const parsed = yield* Effect.try({
       try: () => JSON.parse(content),
-      catch: (cause) => cause
+      catch: (): "invalid-json" => "invalid-json"
     }).pipe(Effect.catch(() => Effect.succeed(null)))
     if (parsed === null) return null
     return yield* Schema.decodeUnknownEffect(OAuthTokenSchema)(parsed).pipe(
@@ -166,12 +186,15 @@ export const inspectToolProfiles = (
     const [store, config] = yield* Effect.all([loadProfiles(storeName), loadOAuthConfig(storeName)])
     const activeProfile = store.profiles.find((profile) => profile.id === store.activeProfileId) ?? store.profiles[0] ??
       null
+    const nowMs = yield* Clock.currentTimeMillis
     return {
       tool,
       authStoreName: storeName,
       activeProfile,
       profiles: store.profiles,
-      tokenStatus: activeProfile === null ? "missing" : isTokenExpired(activeProfile.token, 0) ? "expired" : "valid",
+      tokenStatus: activeProfile === null ? "missing" : isTokenExpiredAt(activeProfile.token, nowMs, 0)
+        ? "expired"
+        : "valid",
       missingScopes: activeProfile === null ? [] : missingScopes(activeProfile.token, tool.requiredScopes),
       oauthConfigured: config !== null
     }
@@ -248,6 +271,9 @@ export const migrateLegacyProfiles = (
     return yield* inspectAllToolProfiles(tools)
   })
 
+/** Matches `JiraAuth`'s refresh deadline; see the rotation comment below. */
+const REFRESH_TIMEOUT = "30 seconds"
+
 /**
  * Refresh expired active profiles.
  *
@@ -268,13 +294,36 @@ export const refreshActiveProfiles = (
         const store = yield* loadProfiles(storeName)
         const active = store.profiles.find((profile) => profile.id === store.activeProfileId) ?? store.profiles[0] ??
           null
-        if (!active || !isTokenExpired(active.token, 0)) return
+        const nowMs = yield* Clock.currentTimeMillis
+        if (!active || !isTokenExpiredAt(active.token, nowMs, 0)) return
         const config = yield* loadOAuthConfig(storeName)
         if (!config) {
           return yield* Effect.fail(new MissingOAuthConfigError({ authStoreName: storeName, profileId: active.id }))
         }
-        const refreshed = yield* refreshToken(active.token, config)
-        yield* saveProfileToken(storeName, refreshed)
+        // Rotating refresh tokens: the grant consumes the stored token
+        // server-side and the response carries its replacement, so an interrupt
+        // between the two spends the credential without persisting what
+        // replaced it — the next refresh 4xxs and the user is silently logged
+        // out. Keep the grant and the persist atomic, as `JiraAuth` does.
+        // The deadline is inside the region on purpose: an uninterruptible
+        // region with no bound of its own absorbs SIGINT/SIGTERM entirely
+        // (`runMain`'s handlers only interrupt the main fiber), so `atlassian
+        // auth refresh` would stop answering Ctrl-C against a stalled token
+        // endpoint. A deadline forked inside the region is still interruptible,
+        // so it does bound this. Failing here leaves the stored token in place
+        // — a refresh that never answered says nothing about its validity.
+        yield* Effect.uninterruptible(
+          Effect.gen(function*() {
+            const refreshed = yield* refreshToken(active.token, config).pipe(
+              Effect.timeout(REFRESH_TIMEOUT),
+              Effect.catchTag(
+                "TimeoutError",
+                () => Effect.fail(new OAuthError({ step: "refresh", cause: `no response within ${REFRESH_TIMEOUT}` }))
+              )
+            )
+            yield* saveProfileToken(storeName, refreshed)
+          })
+        )
       }))
     return yield* inspectAllToolProfiles(tools)
   })

package/src/config/TokenStorage.ts

@@ -23,13 +23,16 @@ import * as FileSystem from "effect/FileSystem"
 import type * as Path from "effect/Path"
 import type * as PlatformError from "effect/PlatformError"
 import * as Schema from "effect/Schema"
+import { unsafeCurrentTimeMillis } from "../internal/legacyWallClock.js"
 import { type HomeDirectoryError, type HomeDirectoryTag } from "./ConfigPaths.js"
 import { ensureConfigDir, getAuthPath, getOAuthConfigPath, writeSecureFile } from "./ConfigPaths.js"
 import { type OAuthConfig, OAuthConfigSchema, type OAuthToken, OAuthTokenSchema } from "./OAuthSchemas.js"
 
-const parseJsonOrNull = (content: string): unknown | null => {
+const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Json))
+
+const parseJsonOrNull = (content: string): Schema.Json | null => {
   try {
-    return JSON.parse(content)
+    return decodeJson(content)
   } catch {
     return null
   }
@@ -70,7 +73,7 @@ export const loadToken = (
     const tokenPath = yield* getAuthPath(toolName)
 
     const exists = yield* fs.exists(tokenPath).pipe(
-      Effect.catchCause(() => Effect.succeed(false))
+      Effect.catch(() => Effect.succeed(false))
     )
     if (!exists) {
       return null
@@ -87,7 +90,7 @@ export const loadToken = (
     }
 
     return yield* Schema.decodeUnknownEffect(OAuthTokenSchema)(parsed).pipe(
-      Effect.catchCause((e) =>
+      Effect.catch((e) =>
         Effect.logWarning(`Invalid token schema in ${tokenPath}: ${e}`).pipe(
           Effect.map(() => null)
         )
@@ -136,7 +139,7 @@ export const deleteToken = (
     const tokenPath = yield* getAuthPath(toolName)
 
     yield* fs.remove(tokenPath).pipe(
-      Effect.catchCause(() => Effect.void)
+      Effect.catch(() => Effect.void)
     )
   })
 
@@ -160,7 +163,7 @@ export const loadOAuthConfig = (
     const configPath = yield* getOAuthConfigPath(toolName)
 
     const exists = yield* fs.exists(configPath).pipe(
-      Effect.catchCause(() => Effect.succeed(false))
+      Effect.catch(() => Effect.succeed(false))
     )
     if (!exists) {
       return null
@@ -177,7 +180,7 @@ export const loadOAuthConfig = (
     }
 
     return yield* Schema.decodeUnknownEffect(OAuthConfigSchema)(parsed).pipe(
-      Effect.catchCause((e) =>
+      Effect.catch((e) =>
         Effect.logWarning(`Invalid OAuth config schema in ${configPath}: ${e}`).pipe(
           Effect.map(() => null)
         )
@@ -220,5 +223,18 @@ export const saveOAuthConfig = (
  *
  * @category Utilities
  */
+export const isTokenExpiredAt = (
+  token: OAuthToken,
+  nowMs: number,
+  bufferMs: number = 5 * 60 * 1000
+): boolean => nowMs >= token.expires_at - bufferMs
+
+/**
+ * Check token expiration using the host clock.
+ *
+ * @deprecated Effect workflows should call {@link isTokenExpiredAt} with
+ * `Clock.currentTimeMillis`. This wrapper preserves the existing synchronous
+ * public API until the next major release.
+ */
 export const isTokenExpired = (token: OAuthToken, bufferMs: number = 5 * 60 * 1000): boolean =>
-  Date.now() >= token.expires_at - bufferMs
+  isTokenExpiredAt(token, unsafeCurrentTimeMillis(), bufferMs)

package/src/config/index.ts

@@ -37,6 +37,7 @@ export {
   deleteToken,
   FileSystemError,
   isTokenExpired,
+  isTokenExpiredAt,
   loadOAuthConfig,
   loadToken,
   saveOAuthConfig,
@@ -72,6 +73,7 @@ export {
   CONFLUENCE_REQUIRED_SCOPES,
   inspectAllToolProfiles,
   inspectToolProfiles,
+  JIRA_PROPOSAL_REQUIRED_SCOPES,
   JIRA_REQUIRED_SCOPES,
   migrateLegacyProfiles,
   MissingOAuthConfigError,

package/src/internal/legacyWallClock.ts

@@ -0,0 +1,10 @@
+/**
+ * Compatibility boundary for legacy synchronous OAuth helpers.
+ *
+ * New Effect workflows must obtain time from `Clock.currentTimeMillis` and call
+ * the corresponding `*At` helper. This host-clock read remains only so the
+ * existing synchronous public API does not change without a major release.
+ *
+ * @internal
+ */
+export const unsafeCurrentTimeMillis = (): number => Date.now()

package/test/ApiUpdateWorkflows.test.ts

@@ -0,0 +1,80 @@
+import * as NodeServices from "@effect/platform-node/NodeServices"
+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 * as Predicate from "effect/Predicate"
+import type * as Schema from "effect/Schema"
+import { parse } from "yaml"
+
+const isRecord = <UnparsedInput>(value: UnparsedInput): value is UnparsedInput & Record<string, Schema.Json> =>
+  Predicate.isObjectOrArray(value) && value !== null && !Array.isArray(value)
+
+const buildCommands = (source: string): ReadonlyArray<string> => {
+  const workflow: unknown = parse(source)
+  if (!isRecord(workflow) || !isRecord(workflow.jobs)) return []
+
+  return Object.values(workflow.jobs).flatMap((job) => {
+    if (!isRecord(job) || !Array.isArray(job.steps)) return []
+    return job.steps.flatMap((step) => {
+      if (!isRecord(step) || !Predicate.isString(step.name) || !step.name.startsWith("Build ")) return []
+      return Predicate.isString(step.run) ? [step.run] : []
+    })
+  })
+}
+
+const dependencyClosureDiagnostics = (
+  source: string,
+  expectedConsumers: ReadonlyArray<string>
+): ReadonlyArray<string> => {
+  const commands = buildCommands(source)
+  return expectedConsumers.flatMap((consumer) => {
+    const dependencyClosedFilter = `--filter ${consumer}...`
+    return commands.some((command) => command.includes(dependencyClosedFilter) && /\bbuild\b/u.test(command))
+      ? []
+      : [`API update workflow must build ${consumer} with its workspace dependency closure`]
+  })
+}
+
+const loadWorkflow = (name: string) =>
+  Effect.gen(function*() {
+    const fileSystem = yield* FileSystem.FileSystem
+    const path = yield* Path.Path
+    const workflowPath = yield* path.fromFileUrl(new URL(`../../../.github/workflows/${name}`, import.meta.url))
+    return yield* fileSystem.readFileString(workflowPath)
+  }).pipe(Effect.provide(NodeServices.layer))
+
+describe("API update workflow build closure", () => {
+  it("rejects a bare consumer build and accepts a dependency-closed build", () => {
+    const invalid = `
+jobs:
+  update:
+    steps:
+      - name: Build generated client and consumer
+        run: pnpm --filter @knpkv/confluence-to-markdown build
+`
+    const valid = `
+jobs:
+  update:
+    steps:
+      - name: Build generated client and consumer
+        run: pnpm --filter @knpkv/confluence-to-markdown... build
+`
+
+    expect(dependencyClosureDiagnostics(invalid, ["@knpkv/confluence-to-markdown"])).toEqual([
+      "API update workflow must build @knpkv/confluence-to-markdown with its workspace dependency closure"
+    ])
+    expect(dependencyClosureDiagnostics(valid, ["@knpkv/confluence-to-markdown"])).toEqual([])
+  })
+
+  it.effect("builds every API consumer with its workspace dependencies", () =>
+    Effect.gen(function*() {
+      const confluence = yield* loadWorkflow("confluence-api-update.yml")
+      const jira = yield* loadWorkflow("jira-api-update.yml")
+      const clockify = yield* loadWorkflow("clockify-api-update.yml")
+
+      expect(dependencyClosureDiagnostics(confluence, ["@knpkv/confluence-to-markdown"])).toEqual([])
+      expect(dependencyClosureDiagnostics(jira, ["@knpkv/jira-cli", "@knpkv/jira-clockify"])).toEqual([])
+      expect(dependencyClosureDiagnostics(clockify, ["@knpkv/jira-clockify"])).toEqual([])
+    }))
+})

package/test/OAuthEndpoints.test.ts

@@ -6,6 +6,7 @@ import {
   AUTH_URL,
   buildAuthUrl,
   computeCodeChallenge,
+  CONFLUENCE_FOLDER_SCOPES,
   CONFLUENCE_SCOPES,
   generateCodeVerifier
 } from "../src/auth/OAuthEndpoints.js"
@@ -18,6 +19,28 @@ describe("OAuthEndpoints", () => {
       expect(CONFLUENCE_SCOPES).toContain("read:attachment:confluence")
       expect(CONFLUENCE_SCOPES).toContain("write:attachment:confluence")
     })
+
+    // Control Center feeds this constant straight into its own authorize
+    // request, so folder authority must not leak in here — it would widen every
+    // Control Center sign-in to a scope its documented OAuth app never enables.
+    it("carries no folder or search authority", () => {
+      for (const scope of CONFLUENCE_FOLDER_SCOPES) {
+        expect(CONFLUENCE_SCOPES).not.toContain(scope)
+      }
+    })
+  })
+
+  describe("CONFLUENCE_FOLDER_SCOPES", () => {
+    // Exact strings: Atlassian rejects the whole authorize request for one
+    // unrecognized scope, and a typo surfaces only on a real consent screen.
+    it("names the scopes the folder and CQL-search endpoints require", () => {
+      expect([...CONFLUENCE_FOLDER_SCOPES].sort()).toEqual([
+        "read:content-details:confluence",
+        "read:folder:confluence",
+        "read:hierarchical-content:confluence",
+        "write:folder:confluence"
+      ])
+    })
   })
 
   // ---- PKCE ----

package/test/ProfileManager.test.ts

@@ -1,8 +1,12 @@
 import { describe, expect, it } from "@effect/vitest"
 import { ConfigProvider, Effect, Layer } from "effect"
+import * as Clock from "effect/Clock"
+import * as Deferred from "effect/Deferred"
+import * as Fiber from "effect/Fiber"
 import * as FileSystem from "effect/FileSystem"
 import * as Path from "effect/Path"
 import { SystemError } from "effect/PlatformError"
+import { HttpClient, HttpClientResponse } from "effect/unstable/http"
 import {
   type AtlassianToolDefinition,
   HomeDirectoryLive,
@@ -13,6 +17,7 @@ import {
   type OAuthToken,
   ProfileNotFoundError,
   refreshActiveProfiles,
+  saveOAuthConfig,
   saveProfileToken,
   useProfileForAllTools
 } from "../src/config/index.js"
@@ -175,6 +180,62 @@ describe("ProfileManager", () => {
     ).rejects.toBeInstanceOf(ProfileNotFoundError)
   })
 
+  // Atlassian rotates refresh tokens, so the grant consumes the stored one and
+  // the response carries its replacement. If an interrupt can land between the
+  // two, the credential is spent with nothing saved and the profile is silently
+  // logged out — hence the uninterruptible region around grant-and-persist.
+  it("persists the rotated token even when interrupted mid-rotation", async () => {
+    const mock = makeMockFS()
+    const program = Effect.gen(function*() {
+      yield* saveOAuthConfig("tool-a", { clientId: "client-1", clientSecret: "secret-1" })
+      const nowMs = yield* Clock.currentTimeMillis
+      yield* saveProfileToken("tool-a", makeToken(1, "read:me offline_access", nowMs - 1_000))
+
+      const issued = yield* Deferred.make<void>()
+      const release = yield* Deferred.make<void>()
+      const client = 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: "read:me offline_access",
+                  token_type: "Bearer"
+                }),
+                { status: 200, headers: { "content-type": "application/json" } }
+              )
+            )
+          })
+        )
+      )
+
+      const fiber = yield* refreshActiveProfiles([tools[0]!]).pipe(
+        Effect.provide(client),
+        Effect.exit,
+        Effect.forkChild({ startImmediately: true })
+      )
+      yield* Deferred.await(issued)
+      const interrupting = yield* Fiber.interrupt(fiber).pipe(Effect.forkChild({ startImmediately: true }))
+      yield* Deferred.succeed(release, undefined)
+      yield* Fiber.join(interrupting)
+    })
+
+    await Effect.runPromise(
+      program.pipe(
+        Effect.provide(Layer.mergeAll(mock.layer, Path.layer, HomeDirectoryLive, ConfigProviderLive))
+      )
+    )
+
+    expect(JSON.stringify(mock.store)).toContain("rotated-refresh")
+  })
+
   it("fails expired-token refresh when OAuth config is missing", async () => {
     await expect(
       run(

package/test/PublicExports.test.ts

@@ -0,0 +1,16 @@
+import { JIRA_PROPOSAL_SCOPES, JIRA_SCOPES } from "../src/auth/index.js"
+import { JIRA_PROPOSAL_REQUIRED_SCOPES, JIRA_REQUIRED_SCOPES } from "../src/config/index.js"
+
+describe("public compatibility exports", () => {
+  it("retains proposal-only Jira scopes beside the write-capable release scopes", () => {
+    expect(JIRA_PROPOSAL_SCOPES).toEqual([
+      "read:jira-work",
+      "read:jira-user",
+      "read:me",
+      "offline_access"
+    ])
+    expect(JIRA_PROPOSAL_REQUIRED_SCOPES).toEqual(JIRA_PROPOSAL_SCOPES)
+    expect(JIRA_SCOPES).toContain("manage:jira-configuration")
+    expect(JIRA_REQUIRED_SCOPES).toContain("manage:jira-project")
+  })
+})