@knpkv/atlassian-common 0.2.0

package/src/auth/OAuthErrors.ts

@@ -0,0 +1,101 @@
+/**
+ * Tagged error types for Atlassian OAuth2 flows.
+ *
+ * **Mental model**
+ *
+ * - **Step-scoped errors**: {@link OAuthError} carries a `step` field (`"configure" | "authorize" |
+ *   "token" | "refresh" | "revoke"`) so callers can handle failures per-phase.
+ * - **Companion errors**: {@link AuthMissingError} (not logged in) and
+ *   {@link OAuthNotConfiguredError} (no client credentials) represent pre-flow failures.
+ *
+ * **Gotchas**
+ *
+ * - `OAuthError.message` is a computed getter derived from `step` + `cause` — it's not
+ *   a stored field, so don't destructure it from the constructor.
+ *
+ * @module
+ */
+import * as Data from "effect/Data"
+
+/**
+ * OAuth flow step for error context.
+ *
+ * @category Types
+ */
+export type OAuthStep = "configure" | "authorize" | "token" | "resources" | "user-info" | "refresh" | "revoke"
+
+/**
+ * Error during OAuth2 flow.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect"
+ * import { OAuthError } from "@knpkv/atlassian-common/auth"
+ *
+ * Effect.gen(function* () {
+ *   // ... oauth operation
+ * }).pipe(
+ *   Effect.catchTag("OAuthError", (error) =>
+ *     Effect.sync(() => console.error(`OAuth error at ${error.step}: ${error.message}`))
+ *   )
+ * )
+ * ```
+ *
+ * @category Errors
+ */
+export class OAuthError extends Data.TaggedError("OAuthError")<{
+  readonly step: OAuthStep
+  readonly cause?: unknown
+}> {
+  override get message(): string {
+    if (this.cause instanceof Error) {
+      return `OAuth ${this.step} failed: ${this.cause.message}`
+    }
+    if (typeof this.cause === "string") {
+      return `OAuth ${this.step} failed: ${this.cause}`
+    }
+    return `OAuth ${this.step} failed`
+  }
+}
+
+/**
+ * Error when authentication is missing.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect"
+ * import { AuthMissingError } from "@knpkv/atlassian-common/auth"
+ *
+ * Effect.gen(function* () {
+ *   // ... requires auth
+ * }).pipe(
+ *   Effect.catchTag("AuthMissingError", () =>
+ *     Effect.sync(() => console.error("Please login first"))
+ *   )
+ * )
+ * ```
+ *
+ * @category Errors
+ */
+export class AuthMissingError extends Data.TaggedError("AuthMissingError")<{
+  readonly tool?: string
+}> {
+  override get message(): string {
+    const toolPart = this.tool ? ` for ${this.tool}` : ""
+    return `Not logged in${toolPart}. Please run 'auth login' first.`
+  }
+}
+
+/**
+ * Error when OAuth is not configured.
+ *
+ * @category Errors
+ */
+export class OAuthNotConfiguredError extends Data.TaggedError("OAuthNotConfiguredError")<{
+  readonly tool?: string
+}> {
+  override get message(): string {
+    const toolPart = this.tool ? `'${this.tool} auth configure'` : "'auth configure'"
+    return `OAuth not configured. Run ${toolPart} first.`
+  }
+}

package/src/auth/OAuthOperations.ts

@@ -0,0 +1,276 @@
+/**
+ * Core OAuth2 operations against Atlassian's token and resource endpoints.
+ *
+ * **Mental model**
+ *
+ * - **Effect-native HTTP**: Every operation takes an `HttpClient` from the Effect
+ *   context and returns `Effect<A, OAuthError, HttpClient>`. Callers provide the
+ *   client via `Layer.succeed`.
+ * - **Schema-validated responses**: Token and user payloads are decoded through
+ *   Effect Schema before returning, catching API contract drift at runtime.
+ *
+ * **Common tasks**
+ *
+ * - Exchange auth code: {@link exchangeCodeForTokens}
+ * - List user sites: {@link getAccessibleResources}
+ * - Refresh expired token: {@link refreshToken}
+ * - Build storable token: {@link buildOAuthToken}
+ *
+ * @module
+ */
+import * as HttpClient from "@effect/platform/HttpClient"
+import * as HttpClientRequest from "@effect/platform/HttpClientRequest"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { type OAuthConfig, type OAuthToken } from "../config/OAuthSchemas.js"
+import { ME_URL, RESOURCES_URL, REVOKE_URL, TOKEN_URL } from "./OAuthEndpoints.js"
+import { OAuthError } from "./OAuthErrors.js"
+import {
+  type AccessibleResource,
+  AccessibleResourceSchema,
+  type TokenResponse,
+  TokenResponseSchema,
+  type UserInfo,
+  UserInfoSchema
+} from "./OAuthResponseSchemas.js"
+
+/**
+ * Options for exchanging an authorization code for tokens.
+ *
+ * @category Types
+ */
+export interface ExchangeCodeOptions {
+  /** Local callback server port (for redirect_uri) */
+  readonly port: number
+  /** PKCE code verifier (if PKCE was used in auth request) */
+  readonly codeVerifier?: string | undefined
+}
+
+/**
+ * Exchange authorization code for tokens.
+ *
+ * @category Operations
+ */
+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> = {
+      grant_type: "authorization_code",
+      client_id: config.clientId,
+      client_secret: config.clientSecret,
+      code,
+      redirect_uri: `http://localhost:${options.port}/callback`
+    }
+    if (options.codeVerifier) tokenBody.code_verifier = options.codeVerifier
+    const request = yield* HttpClientRequest.post(TOKEN_URL).pipe(
+      HttpClientRequest.setHeader("Content-Type", "application/json"),
+      HttpClientRequest.bodyJson(tokenBody)
+    )
+
+    const response = yield* httpClient.execute(request)
+
+    if (response.status >= 400) {
+      const text = yield* response.text
+      yield* Effect.logDebug(`Token exchange failed (${response.status}): ${text}`)
+      return yield* Effect.fail(
+        new OAuthError({ step: "token", cause: `HTTP ${response.status}` })
+      )
+    }
+
+    const body = yield* response.json
+
+    return yield* Schema.decodeUnknown(TokenResponseSchema)(body)
+  }).pipe(
+    Effect.mapError((cause) => new OAuthError({ step: "token", cause }))
+  )
+
+/**
+ * Get accessible resources (sites) for the authenticated user.
+ *
+ * @param accessToken - OAuth access token
+ *
+ * @category Operations
+ */
+export const getAccessibleResources = (
+  accessToken: string
+): Effect.Effect<ReadonlyArray<AccessibleResource>, OAuthError, HttpClient.HttpClient> =>
+  Effect.gen(function*() {
+    const httpClient = yield* HttpClient.HttpClient
+    const request = HttpClientRequest.get(RESOURCES_URL).pipe(
+      HttpClientRequest.setHeader("Authorization", `Bearer ${accessToken}`),
+      HttpClientRequest.setHeader("Accept", "application/json")
+    )
+
+    const response = yield* httpClient.execute(request)
+
+    if (response.status >= 400) {
+      const text = yield* response.text
+      yield* Effect.logDebug(`Accessible resources failed (${response.status}): ${text}`)
+      return yield* Effect.fail(
+        new OAuthError({ step: "resources", cause: `HTTP ${response.status}` })
+      )
+    }
+
+    const body = yield* response.json
+
+    return yield* Schema.decodeUnknown(Schema.Array(AccessibleResourceSchema))(body)
+  }).pipe(
+    Effect.mapError((cause) => new OAuthError({ step: "resources", cause }))
+  )
+
+/**
+ * Get user info from /me endpoint.
+ *
+ * @param accessToken - OAuth access token
+ *
+ * @category Operations
+ */
+export const getUserInfo = (
+  accessToken: string
+): Effect.Effect<UserInfo, OAuthError, HttpClient.HttpClient> =>
+  Effect.gen(function*() {
+    const httpClient = yield* HttpClient.HttpClient
+    const request = HttpClientRequest.get(ME_URL).pipe(
+      HttpClientRequest.setHeader("Authorization", `Bearer ${accessToken}`),
+      HttpClientRequest.setHeader("Accept", "application/json")
+    )
+
+    const response = yield* httpClient.execute(request)
+
+    if (response.status >= 400) {
+      const text = yield* response.text
+      yield* Effect.logDebug(`User info failed (${response.status}): ${text}`)
+      return yield* Effect.fail(
+        new OAuthError({ step: "user-info", cause: `HTTP ${response.status}` })
+      )
+    }
+
+    const body = yield* response.json
+
+    return yield* Schema.decodeUnknown(UserInfoSchema)(body)
+  }).pipe(
+    Effect.mapError((cause) => new OAuthError({ step: "user-info", cause }))
+  )
+
+/**
+ * Refresh an expired OAuth token.
+ *
+ * @param token - Current OAuth token (with refresh_token)
+ * @param config - OAuth client configuration
+ *
+ * @category Operations
+ */
+export const refreshToken = (
+  token: OAuthToken,
+  config: OAuthConfig
+): Effect.Effect<OAuthToken, OAuthError, HttpClient.HttpClient> =>
+  Effect.gen(function*() {
+    const httpClient = yield* HttpClient.HttpClient
+    const request = yield* HttpClientRequest.post(TOKEN_URL).pipe(
+      HttpClientRequest.setHeader("Content-Type", "application/json"),
+      HttpClientRequest.bodyJson({
+        grant_type: "refresh_token",
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        refresh_token: token.refresh_token
+      }),
+      Effect.mapError((cause) => new OAuthError({ step: "refresh", cause }))
+    )
+
+    const response = yield* httpClient.execute(request).pipe(
+      Effect.mapError((cause) => new OAuthError({ step: "refresh", cause }))
+    )
+
+    if (response.status >= 400) {
+      const text = yield* response.text.pipe(
+        Effect.mapError((cause) => new OAuthError({ step: "refresh", cause }))
+      )
+      return yield* Effect.fail(
+        new OAuthError({ step: "refresh", cause: `HTTP ${response.status}: ${text}` })
+      )
+    }
+
+    const body = yield* response.json.pipe(
+      Effect.mapError((cause) => new OAuthError({ step: "refresh", cause }))
+    )
+    const tokenResponse = yield* Schema.decodeUnknown(TokenResponseSchema)(body).pipe(
+      Effect.mapError((cause) => new OAuthError({ step: "refresh", cause }))
+    )
+
+    return {
+      ...token,
+      access_token: tokenResponse.access_token,
+      refresh_token: tokenResponse.refresh_token,
+      expires_at: Date.now() + tokenResponse.expires_in * 1000,
+      scope: tokenResponse.scope
+    }
+  })
+
+/**
+ * Revoke an OAuth token.
+ *
+ * @param token - OAuth token to revoke
+ * @param config - OAuth client configuration
+ *
+ * @category Operations
+ */
+export const revokeToken = (
+  token: OAuthToken,
+  config: OAuthConfig
+): Effect.Effect<void, OAuthError, HttpClient.HttpClient> =>
+  Effect.gen(function*() {
+    const httpClient = yield* HttpClient.HttpClient
+    const request = yield* HttpClientRequest.post(REVOKE_URL).pipe(
+      HttpClientRequest.setHeader("Content-Type", "application/json"),
+      HttpClientRequest.bodyJson({
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        token: token.refresh_token
+      }),
+      Effect.mapError((cause) => new OAuthError({ step: "revoke", cause }))
+    )
+
+    const response = yield* httpClient.execute(request).pipe(
+      Effect.mapError((cause) => new OAuthError({ step: "revoke", cause }))
+    )
+
+    if (response.status >= 400) {
+      return yield* Effect.fail(
+        new OAuthError({
+          step: "revoke",
+          cause: `Token revocation failed with status ${response.status}`
+        })
+      )
+    }
+  })
+
+/**
+ * Build OAuthToken from token response and site info.
+ *
+ * @param tokenResponse - Token response from exchange
+ * @param site - Selected accessible resource
+ * @param user - User info
+ *
+ * @category Utilities
+ */
+export const buildOAuthToken = (
+  tokenResponse: TokenResponse,
+  site: AccessibleResource,
+  user: UserInfo
+): OAuthToken => ({
+  access_token: tokenResponse.access_token,
+  refresh_token: tokenResponse.refresh_token,
+  expires_at: Date.now() + tokenResponse.expires_in * 1000,
+  scope: tokenResponse.scope,
+  cloud_id: site.id,
+  site_url: site.url,
+  user: {
+    account_id: user.account_id,
+    name: user.name,
+    email: user.email
+  }
+})

package/src/auth/OAuthResponseSchemas.ts

@@ -0,0 +1,70 @@
+/**
+ * Effect Schema definitions for Atlassian OAuth2 API response payloads.
+ *
+ * **Mental model**
+ *
+ * - **Schema = source of truth**: {@link TokenResponseSchema}, {@link AccessibleResourceSchema},
+ *   and {@link UserInfoSchema} define the wire format. Companion `type` aliases are derived
+ *   via `Schema.Schema.Type` — never hand-written.
+ *
+ * @module
+ */
+import * as Schema from "effect/Schema"
+
+/**
+ * Schema for OAuth2 token response from Atlassian.
+ *
+ * @category Schema
+ */
+export const TokenResponseSchema = Schema.Struct({
+  access_token: Schema.String,
+  refresh_token: Schema.String,
+  expires_in: Schema.Number,
+  scope: Schema.String,
+  token_type: Schema.String
+})
+
+/**
+ * Type for OAuth2 token response.
+ *
+ * @category Types
+ */
+export type TokenResponse = Schema.Schema.Type<typeof TokenResponseSchema>
+
+/**
+ * Schema for accessible resource (site) from Atlassian.
+ *
+ * @category Schema
+ */
+export const AccessibleResourceSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  url: Schema.String,
+  scopes: Schema.Array(Schema.String),
+  avatarUrl: Schema.optional(Schema.String)
+})
+
+/**
+ * Type for accessible resource.
+ *
+ * @category Types
+ */
+export type AccessibleResource = Schema.Schema.Type<typeof AccessibleResourceSchema>
+
+/**
+ * Schema for user info from /me endpoint.
+ *
+ * @category Schema
+ */
+export const UserInfoSchema = Schema.Struct({
+  account_id: Schema.String,
+  name: Schema.String,
+  email: Schema.String
+})
+
+/**
+ * Type for user info.
+ *
+ * @category Types
+ */
+export type UserInfo = Schema.Schema.Type<typeof UserInfoSchema>

package/src/auth/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Barrel export for Atlassian OAuth2 auth utilities.
+ *
+ * @module
+ */
+
+// Endpoints and scopes
+export {
+  AUTH_URL,
+  buildAuthUrl,
+  type BuildAuthUrlOptions,
+  computeCodeChallenge,
+  CONFLUENCE_SCOPES,
+  generateCodeVerifier,
+  JIRA_SCOPES,
+  ME_URL,
+  RESOURCES_URL,
+  REVOKE_URL,
+  TOKEN_URL
+} from "./OAuthEndpoints.js"
+
+// Errors
+export { AuthMissingError, OAuthError, OAuthNotConfiguredError, type OAuthStep } from "./OAuthErrors.js"
+
+// Operations
+export {
+  buildOAuthToken,
+  exchangeCodeForTokens,
+  type ExchangeCodeOptions,
+  getAccessibleResources,
+  getUserInfo,
+  refreshToken,
+  revokeToken
+} from "./OAuthOperations.js"
+
+// Response schemas
+export {
+  type AccessibleResource,
+  AccessibleResourceSchema,
+  type TokenResponse,
+  TokenResponseSchema,
+  type UserInfo,
+  UserInfoSchema
+} from "./OAuthResponseSchemas.js"
+
+// Utilities
+export { generateUUID } from "./uuid.js"

package/src/auth/uuid.ts

@@ -0,0 +1,14 @@
+/**
+ * Cryptographic UUID v4 generation via Web Crypto API.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect"
+
+/**
+ * Generate a cryptographically secure UUID v4.
+ * Uses Web Crypto API randomUUID (Node.js 19+, all modern browsers).
+ *
+ * @category Utilities
+ */
+export const generateUUID = (): Effect.Effect<string> => Effect.sync(() => globalThis.crypto.randomUUID())

package/src/config/ConfigPaths.ts

@@ -0,0 +1,179 @@
+/**
+ * XDG-compliant config path resolution and secure file I/O for Atlassian tools.
+ *
+ * **Mental model**
+ *
+ * - **Injectable home directory**: {@link HomeDirectoryTag} is an Effect service so tests
+ *   can substitute a temp dir without touching env vars. {@link HomeDirectoryLive} reads
+ *   `HOME` / `USERPROFILE` via Effect `Config`.
+ * - **XDG hierarchy**: `~/.config/atlassian/<toolName>/` — respects `XDG_CONFIG_HOME` override.
+ * - **Secure by default**: {@link ensureConfigDir} creates dirs at `0o700`;
+ *   {@link writeSecureFile} writes at `0o600`.
+ *
+ * **Common tasks**
+ *
+ * - Resolve config dir: {@link getConfigDir}
+ * - Get auth file path: {@link getAuthPath}
+ * - Write credential files: {@link writeSecureFile}
+ *
+ * @module
+ */
+import type * as Error from "@effect/platform/Error"
+import * as FileSystem from "@effect/platform/FileSystem"
+import * as Path from "@effect/platform/Path"
+import * as Config from "effect/Config"
+import * as Context from "effect/Context"
+import * as Data from "effect/Data"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+
+/**
+ * Error when home directory cannot be determined.
+ *
+ * @category Errors
+ */
+export class HomeDirectoryError extends Data.TaggedError("HomeDirectoryError")<{
+  readonly cause?: unknown
+}> {
+  override get message(): string {
+    return "Cannot determine home directory: HOME/USERPROFILE not set"
+  }
+}
+
+/**
+ * Service for getting the home directory.
+ * Allows mocking in tests.
+ *
+ * @category Services
+ */
+export interface HomeDirectory {
+  readonly get: () => Effect.Effect<string, HomeDirectoryError>
+}
+
+/**
+ * Tag for the HomeDirectory service.
+ *
+ * @category Services
+ */
+export class HomeDirectoryTag extends Context.Tag("@knpkv/atlassian-common/HomeDirectory")<
+  HomeDirectoryTag,
+  HomeDirectory
+>() {}
+
+const HomeConfig = Config.option(Config.string("HOME")).pipe(
+  Config.orElse(() => Config.option(Config.string("USERPROFILE")))
+)
+
+/**
+ * Default implementation using HOME/USERPROFILE env vars.
+ *
+ * @category Layers
+ */
+export const HomeDirectoryLive: Layer.Layer<HomeDirectoryTag> = Layer.succeed(
+  HomeDirectoryTag,
+  {
+    get: () =>
+      Effect.gen(function*() {
+        const opt = yield* Effect.orDie(HomeConfig)
+        return yield* Option.match(opt, {
+          onNone: () => Effect.fail(new HomeDirectoryError({})),
+          onSome: (home) => Effect.succeed(home)
+        })
+      })
+  }
+)
+
+const XdgConfigHome = Config.option(Config.string("XDG_CONFIG_HOME"))
+
+/**
+ * XDG config directory for Atlassian tools.
+ * Returns ~/.config/atlassian by default.
+ *
+ * @category Utilities
+ */
+export const getConfigDir = (
+  toolName?: string
+): Effect.Effect<string, HomeDirectoryError, HomeDirectoryTag | Path.Path> =>
+  Effect.gen(function*() {
+    const homeDir = yield* HomeDirectoryTag
+    const pathSvc = yield* Path.Path
+    const home = yield* homeDir.get()
+
+    // Use XDG_CONFIG_HOME if set, otherwise ~/.config
+    const xdgOpt = yield* Effect.orDie(XdgConfigHome)
+    const xdgConfig = Option.getOrElse(xdgOpt, () => pathSvc.join(home, ".config"))
+    const baseDir = pathSvc.join(xdgConfig, "atlassian")
+
+    return toolName ? pathSvc.join(baseDir, toolName) : baseDir
+  })
+
+/**
+ * Get auth file path for a specific tool.
+ *
+ * @category Utilities
+ */
+export const getAuthPath = (
+  toolName: string
+): Effect.Effect<string, HomeDirectoryError, HomeDirectoryTag | Path.Path> =>
+  Effect.gen(function*() {
+    const path = yield* Path.Path
+    const configDir = yield* getConfigDir(toolName)
+    return path.join(configDir, "auth.json")
+  })
+
+/**
+ * Get OAuth config file path for a specific tool.
+ *
+ * @category Utilities
+ */
+export const getOAuthConfigPath = (
+  toolName: string
+): Effect.Effect<string, HomeDirectoryError, HomeDirectoryTag | Path.Path> =>
+  Effect.gen(function*() {
+    const path = yield* Path.Path
+    const configDir = yield* getConfigDir(toolName)
+    return path.join(configDir, "oauth.json")
+  })
+
+/**
+ * Ensure config directory exists with secure permissions.
+ *
+ * @category Utilities
+ */
+export const ensureConfigDir = (
+  toolName: string
+): Effect.Effect<
+  string,
+  HomeDirectoryError | Error.PlatformError,
+  FileSystem.FileSystem | Path.Path | HomeDirectoryTag
+> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const configDir = yield* getConfigDir(toolName)
+
+    yield* fs.makeDirectory(configDir, { recursive: true })
+
+    // Set secure permissions (owner only)
+    yield* fs.chmod(configDir, 0o700)
+
+    return configDir
+  })
+
+/**
+ * Write file with secure permissions (600).
+ *
+ * @category Utilities
+ */
+export const writeSecureFile = (
+  filePath: string,
+  content: string
+): Effect.Effect<void, Error.PlatformError, FileSystem.FileSystem> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+
+    yield* fs.writeFileString(filePath, content)
+
+    // Set secure permissions (owner only)
+    yield* fs.chmod(filePath, 0o600)
+  })