@knpkv/atlassian-common 1.1.0 → 1.3.0

package/dist/config/index.d.ts

@@ -5,7 +5,7 @@
  */
 export { ensureConfigDir, getAuthPath, getConfigDir, getOAuthConfigPath, getProfilesPath, type HomeDirectory, HomeDirectoryError, HomeDirectoryLive, HomeDirectoryTag, writeSecureFile } from "./ConfigPaths.js";
 export { type AtlassianSite, AtlassianSiteSchema, type AtlassianUser, AtlassianUserSchema, type OAuthConfig, OAuthConfigSchema, type OAuthToken, OAuthTokenSchema, type OAuthUser, OAuthUserSchema } from "./OAuthSchemas.js";
-export { deleteToken, FileSystemError, isTokenExpired, loadOAuthConfig, loadToken, saveOAuthConfig, saveToken } from "./TokenStorage.js";
+export { deleteToken, FileSystemError, isTokenExpired, isTokenExpiredAt, loadOAuthConfig, loadToken, saveOAuthConfig, saveToken } from "./TokenStorage.js";
 export { type AuthProfile, AuthProfileSchema, type AuthProfilesFile, AuthProfilesFileSchema, deleteActiveProfile, deleteProfile, deleteProfileBySelector, findProfile, loadActiveProfile, loadActiveProfileToken, loadProfiles, profileFromToken, profileIdFromToken, profileNameFromToken, saveProfiles, saveProfileToken, setActiveProfile, setActiveProfileBySelector } from "./AuthProfiles.js";
-export { ATLASSIAN_TOOLS, type AtlassianToolDefinition, CONFLUENCE_REQUIRED_SCOPES, inspectAllToolProfiles, inspectToolProfiles, JIRA_REQUIRED_SCOPES, migrateLegacyProfiles, MissingOAuthConfigError, missingScopes, ProfileNotFoundError, type ProfileTokenStatus, refreshActiveProfiles, tokenScopes, type ToolProfileStatus, useProfileForAllTools } from "./ProfileManager.js";
+export { ATLASSIAN_TOOLS, type AtlassianToolDefinition, CONFLUENCE_REQUIRED_SCOPES, inspectAllToolProfiles, inspectToolProfiles, JIRA_PROPOSAL_REQUIRED_SCOPES, JIRA_REQUIRED_SCOPES, migrateLegacyProfiles, MissingOAuthConfigError, missingScopes, ProfileNotFoundError, type ProfileTokenStatus, refreshActiveProfiles, tokenScopes, type ToolProfileStatus, useProfileForAllTools } from "./ProfileManager.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,eAAe,EACf,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,KAAK,aAAa,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EAChB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EACL,KAAK,aAAa,EAClB,mBAAmB,EACnB,KAAK,aAAa,EAClB,mBAAmB,EACnB,KAAK,WAAW,EAChB,iBAAiB,EACjB,KAAK,UAAU,EACf,gBAAgB,EAChB,KAAK,SAAS,EACd,eAAe,EAChB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EACL,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,EACf,SAAS,EACT,eAAe,EACf,SAAS,EACV,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EACL,KAAK,WAAW,EAChB,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,uBAAuB,EACvB,WAAW,EACX,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,0BAA0B,EAC3B,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EACL,eAAe,EACf,KAAK,uBAAuB,EAC5B,0BAA0B,EAC1B,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,qBAAqB,EACrB,WAAW,EACX,KAAK,iBAAiB,EACtB,qBAAqB,EACtB,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,eAAe,EACf,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,KAAK,aAAa,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EAChB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EACL,KAAK,aAAa,EAClB,mBAAmB,EACnB,KAAK,aAAa,EAClB,mBAAmB,EACnB,KAAK,WAAW,EAChB,iBAAiB,EACjB,KAAK,UAAU,EACf,gBAAgB,EAChB,KAAK,SAAS,EACd,eAAe,EAChB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EACL,WAAW,EACX,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,eAAe,EACf,SAAS,EACV,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EACL,KAAK,WAAW,EAChB,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,uBAAuB,EACvB,WAAW,EACX,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,0BAA0B,EAC3B,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EACL,eAAe,EACf,KAAK,uBAAuB,EAC5B,0BAA0B,EAC1B,sBAAsB,EACtB,mBAAmB,EACnB,6BAA6B,EAC7B,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,qBAAqB,EACrB,WAAW,EACX,KAAK,iBAAiB,EACtB,qBAAqB,EACtB,MAAM,qBAAqB,CAAA"}

package/dist/config/index.js

@@ -8,9 +8,9 @@ export { ensureConfigDir, getAuthPath, getConfigDir, getOAuthConfigPath, getProf
 // OAuth schemas
 export { AtlassianSiteSchema, AtlassianUserSchema, OAuthConfigSchema, OAuthTokenSchema, OAuthUserSchema } from "./OAuthSchemas.js";
 // Token storage
-export { deleteToken, FileSystemError, isTokenExpired, loadOAuthConfig, loadToken, saveOAuthConfig, saveToken } from "./TokenStorage.js";
+export { deleteToken, FileSystemError, isTokenExpired, isTokenExpiredAt, loadOAuthConfig, loadToken, saveOAuthConfig, saveToken } from "./TokenStorage.js";
 // Auth profiles
 export { AuthProfileSchema, AuthProfilesFileSchema, deleteActiveProfile, deleteProfile, deleteProfileBySelector, findProfile, loadActiveProfile, loadActiveProfileToken, loadProfiles, profileFromToken, profileIdFromToken, profileNameFromToken, saveProfiles, saveProfileToken, setActiveProfile, setActiveProfileBySelector } from "./AuthProfiles.js";
 // Unified profile manager
-export { ATLASSIAN_TOOLS, CONFLUENCE_REQUIRED_SCOPES, inspectAllToolProfiles, inspectToolProfiles, JIRA_REQUIRED_SCOPES, migrateLegacyProfiles, MissingOAuthConfigError, missingScopes, ProfileNotFoundError, refreshActiveProfiles, tokenScopes, useProfileForAllTools } from "./ProfileManager.js";
+export { ATLASSIAN_TOOLS, CONFLUENCE_REQUIRED_SCOPES, inspectAllToolProfiles, inspectToolProfiles, JIRA_PROPOSAL_REQUIRED_SCOPES, JIRA_REQUIRED_SCOPES, migrateLegacyProfiles, MissingOAuthConfigError, missingScopes, ProfileNotFoundError, refreshActiveProfiles, tokenScopes, useProfileForAllTools } from "./ProfileManager.js";
 //# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAe;AACf,OAAO,EACL,eAAe,EACf,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,eAAe,EAEf,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EAChB,MAAM,kBAAkB,CAAA;AAEzB,gBAAgB;AAChB,OAAO,EAEL,mBAAmB,EAEnB,mBAAmB,EAEnB,iBAAiB,EAEjB,gBAAgB,EAEhB,eAAe,EAChB,MAAM,mBAAmB,CAAA;AAE1B,gBAAgB;AAChB,OAAO,EACL,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,EACf,SAAS,EACT,eAAe,EACf,SAAS,EACV,MAAM,mBAAmB,CAAA;AAE1B,gBAAgB;AAChB,OAAO,EAEL,iBAAiB,EAEjB,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,uBAAuB,EACvB,WAAW,EACX,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,0BAA0B,EAC3B,MAAM,mBAAmB,CAAA;AAE1B,0BAA0B;AAC1B,OAAO,EACL,eAAe,EAEf,0BAA0B,EAC1B,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,oBAAoB,EAEpB,qBAAqB,EACrB,WAAW,EAEX,qBAAqB,EACtB,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAe;AACf,OAAO,EACL,eAAe,EACf,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,eAAe,EAEf,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EAChB,MAAM,kBAAkB,CAAA;AAEzB,gBAAgB;AAChB,OAAO,EAEL,mBAAmB,EAEnB,mBAAmB,EAEnB,iBAAiB,EAEjB,gBAAgB,EAEhB,eAAe,EAChB,MAAM,mBAAmB,CAAA;AAE1B,gBAAgB;AAChB,OAAO,EACL,WAAW,EACX,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,eAAe,EACf,SAAS,EACV,MAAM,mBAAmB,CAAA;AAE1B,gBAAgB;AAChB,OAAO,EAEL,iBAAiB,EAEjB,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,uBAAuB,EACvB,WAAW,EACX,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,0BAA0B,EAC3B,MAAM,mBAAmB,CAAA;AAE1B,0BAA0B;AAC1B,OAAO,EACL,eAAe,EAEf,0BAA0B,EAC1B,sBAAsB,EACtB,mBAAmB,EACnB,6BAA6B,EAC7B,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,oBAAoB,EAEpB,qBAAqB,EACrB,WAAW,EAEX,qBAAqB,EACtB,MAAM,qBAAqB,CAAA"}

package/dist/internal/legacyWallClock.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare const unsafeCurrentTimeMillis: () => number;
+//# sourceMappingURL=legacyWallClock.d.ts.map

package/dist/internal/legacyWallClock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacyWallClock.d.ts","sourceRoot":"","sources":["../../src/internal/legacyWallClock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,QAAO,MAAoB,CAAA"}

package/dist/internal/legacyWallClock.js

@@ -0,0 +1,11 @@
+/**
+ * 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 = () => Date.now();
+//# sourceMappingURL=legacyWallClock.js.map

package/dist/internal/legacyWallClock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacyWallClock.js","sourceRoot":"","sources":["../../src/internal/legacyWallClock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knpkv/atlassian-common",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Shared utilities for Atlassian tools (AST, serializers, auth, config)",
   "license": "MIT",
   "author": "knpkv",
@@ -49,28 +49,32 @@
     "./profile-manager": {
       "import": "./dist/config/ProfileManager.js",
       "types": "./dist/config/ProfileManager.d.ts"
+    },
+    "./profile-storage": {
+      "import": "./dist/config/ProfileStorage.js",
+      "types": "./dist/config/ProfileStorage.d.ts"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
-    "effect": "4.0.0-beta.93"
+    "effect": "4.0.0-beta.98"
   },
   "dependencies": {
-    "@effect/platform-node": "4.0.0-beta.93",
+    "@effect/platform-node": "4.0.0-beta.98",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",
     "unified": "^11.0.5"
   },
   "devDependencies": {
-    "@effect/platform-node": "4.0.0-beta.93",
-    "@effect/vitest": "4.0.0-beta.93",
+    "@effect/platform-node": "4.0.0-beta.98",
+    "@effect/vitest": "4.0.0-beta.98",
     "@types/node": "latest",
-    "effect": "4.0.0-beta.93",
+    "effect": "4.0.0-beta.98",
     "typescript": "~6.0.3",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   },
   "keywords": [
     "effect",

package/src/auth/OAuthEndpoints.ts

@@ -82,6 +82,22 @@ export const JIRA_SCOPES = [
   "offline_access"
 ]
 
+/**
+ * Legacy proposal-only Jira scopes retained for public API compatibility.
+ *
+ * Control Center owns a separate least-privilege release-publication scope set;
+ * {@link JIRA_SCOPES} remains the legacy write-capable set for other consumers,
+ * while proposal-only integrations may continue using this read-only set.
+ *
+ * @category Scopes
+ */
+export const JIRA_PROPOSAL_SCOPES = [
+  "read:jira-work",
+  "read:jira-user",
+  "read:me",
+  "offline_access"
+]
+
 /**
  * Options for building OAuth2 authorization URL.
  *
@@ -94,6 +110,8 @@ export interface BuildAuthUrlOptions {
   readonly state: string
   /** Local callback server port */
   readonly port: number
+  /** Exact callback URL for an existing application server. */
+  readonly redirectUri?: string | undefined
   /** OAuth2 scopes */
   readonly scopes: ReadonlyArray<string>
   /** PKCE code_challenge (S256). Omit to skip PKCE. */
@@ -110,7 +128,7 @@ export const buildAuthUrl = (options: BuildAuthUrlOptions): string => {
     audience: "api.atlassian.com",
     client_id: options.clientId,
     scope: options.scopes.join(" "),
-    redirect_uri: `http://localhost:${options.port}/callback`,
+    redirect_uri: options.redirectUri ?? `http://localhost:${options.port}/callback`,
     state: options.state,
     response_type: "code",
     prompt: "consent"

package/src/auth/OAuthOperations.ts

@@ -23,6 +23,7 @@ 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 {
@@ -42,6 +43,8 @@ import {
 export interface ExchangeCodeOptions {
   /** Local callback server port (for redirect_uri) */
   readonly port: number
+  /** Exact callback URL used by the authorization request. */
+  readonly redirectUri?: string | undefined
   /** PKCE code verifier (if PKCE was used in auth request) */
   readonly codeVerifier?: string | undefined
 }
@@ -63,7 +66,7 @@ export const exchangeCodeForTokens = (
       client_id: config.clientId,
       client_secret: config.clientSecret,
       code,
-      redirect_uri: `http://localhost:${options.port}/callback`
+      redirect_uri: options.redirectUri ?? `http://localhost:${options.port}/callback`
     }
     if (options.codeVerifier) tokenBody.code_verifier = options.codeVerifier
     const request = yield* HttpClientRequest.post(TOKEN_URL).pipe(
@@ -258,14 +261,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,
@@ -275,3 +279,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/index.ts

@@ -4,7 +4,9 @@
  * @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,
@@ -12,6 +14,7 @@ export {
   computeCodeChallenge,
   CONFLUENCE_SCOPES,
   generateCodeVerifier,
+  JIRA_PROPOSAL_SCOPES,
   JIRA_SCOPES,
   ME_URL,
   RESOURCES_URL,
@@ -25,6 +28,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,12 +99,9 @@ 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
     )

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"
@@ -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,14 @@ 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"
+]
+
 export const CONFLUENCE_REQUIRED_SCOPES: ReadonlyArray<string> = [
   "read:page:confluence",
   "write:page:confluence",
@@ -135,7 +144,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 +175,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
     }
@@ -268,7 +280,8 @@ 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 }))

package/src/config/ProfileStorage.ts

@@ -0,0 +1,5 @@
+/** Filesystem-only Atlassian profile storage used by local service integrations. @module */
+
+export { type AuthProfile, loadProfiles } from "./AuthProfiles.js"
+export { HomeDirectoryError, HomeDirectoryLive, HomeDirectoryTag } from "./ConfigPaths.js"
+export { FileSystemError, isTokenExpired } from "./TokenStorage.js"

package/src/config/TokenStorage.ts

@@ -23,6 +23,7 @@ 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"
@@ -70,7 +71,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 +88,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 +137,7 @@ export const deleteToken = (
     const tokenPath = yield* getAuthPath(toolName)
 
     yield* fs.remove(tokenPath).pipe(
-      Effect.catchCause(() => Effect.void)
+      Effect.catch(() => Effect.void)
     )
   })
 
@@ -160,7 +161,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 +178,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 +221,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/OAuthEndpoints.test.ts

@@ -90,6 +90,20 @@ describe("OAuthEndpoints", () => {
       expect(parsed.searchParams.get("prompt")).toBe("consent")
     })
 
+    it("uses an application callback URL when supplied", () => {
+      const url = buildAuthUrl({
+        clientId: "cid",
+        state: "state-123",
+        port: 4173,
+        redirectUri: "http://127.0.0.1:4173/services/oauth/atlassian/callback",
+        scopes: ["read:me"]
+      })
+
+      expect(new URL(url).searchParams.get("redirect_uri")).toBe(
+        "http://127.0.0.1:4173/services/oauth/atlassian/callback"
+      )
+    })
+
     // PKCE is optional — omitting codeChallenge must not add params (backwards compat)
     it("omits PKCE params when codeChallenge not provided", () => {
       const url = buildAuthUrl({

package/test/OAuthOperations.test.ts

@@ -127,6 +127,22 @@ describe("OAuthOperations", () => {
         expect(body.code_verifier).toBe("my-verifier")
       }))
 
+    it.effect("uses the same application callback URL during exchange", () =>
+      Effect.gen(function*() {
+        const { capturedRequests, mockClient } = createMockHttpClient([{ status: 200, body: validTokenBody }])
+        const redirectUri = "http://127.0.0.1:4173/services/oauth/atlassian/callback"
+
+        yield* exchangeCodeForTokens("auth-code", oauthConfig, { port: 4173, redirectUri }).pipe(
+          provide(mockClient)
+        )
+
+        const request = capturedRequests[0]!
+        const body = yield* request.body._tag === "Uint8Array"
+          ? Effect.succeed(JSON.parse(new TextDecoder().decode(request.body.body)))
+          : Effect.succeed({})
+        expect(body.redirect_uri).toBe(redirectUri)
+      }))
+
     // Token exchange failures (invalid code, expired code) must surface as OAuthError with step="token"
     it.effect("returns OAuthError with step=token on HTTP 400", () =>
       Effect.gen(function*() {

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

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "incremental": true,
+    "tsBuildInfoFile": "node_modules/.cache/tsconfig.build.tsbuildinfo"
+  }
+}