@knpkv/atlassian-common 0.2.0

package/src/config/OAuthSchemas.ts

@@ -0,0 +1,146 @@
+/**
+ * Shared Effect Schema definitions for persisted OAuth credentials and site metadata.
+ *
+ * **Mental model**
+ *
+ * - **Storage schemas**: {@link OAuthTokenSchema} and {@link OAuthConfigSchema} define the
+ *   JSON shape written to `auth.json` / `oauth.json` on disk. They are the single source
+ *   of truth for token and config structure.
+ * - **Type derivation**: All companion types (`OAuthToken`, `OAuthConfig`, etc.) are derived
+ *   from schemas — never duplicated.
+ *
+ * @module
+ */
+import * as Schema from "effect/Schema"
+
+/**
+ * Schema for OAuth user info from Atlassian.
+ *
+ * @category Schema
+ */
+export const OAuthUserSchema = Schema.Struct({
+  /** Atlassian account ID */
+  account_id: Schema.String,
+  /** Display name */
+  name: Schema.String,
+  /** Email address */
+  email: Schema.String
+})
+
+/**
+ * Type for OAuth user info.
+ *
+ * @category Types
+ */
+export type OAuthUser = Schema.Schema.Type<typeof OAuthUserSchema>
+
+/**
+ * Schema for stored OAuth token.
+ *
+ * @example
+ * ```typescript
+ * import { OAuthTokenSchema } from "@knpkv/atlassian-common/config"
+ * import * as Schema from "effect/Schema"
+ *
+ * const token = Schema.decodeUnknownSync(OAuthTokenSchema)({
+ *   access_token: "eyJ...",
+ *   refresh_token: "eyJ...",
+ *   expires_at: Date.now() + 3600000,
+ *   scope: "read:confluence-content.all",
+ *   cloud_id: "abc123",
+ *   site_url: "https://mysite.atlassian.net"
+ * })
+ * ```
+ *
+ * @category Schema
+ */
+export const OAuthTokenSchema = Schema.Struct({
+  /** OAuth access token */
+  access_token: Schema.String,
+  /** OAuth refresh token */
+  refresh_token: Schema.String,
+  /** Token expiration timestamp (Unix ms) */
+  expires_at: Schema.Number,
+  /** Granted scopes */
+  scope: Schema.String,
+  /** Atlassian Cloud site ID */
+  cloud_id: Schema.String,
+  /** Site URL */
+  site_url: Schema.String,
+  /** Cached user info */
+  user: Schema.optional(OAuthUserSchema)
+})
+
+/**
+ * Type for stored OAuth token.
+ *
+ * @category Types
+ */
+export type OAuthToken = Schema.Schema.Type<typeof OAuthTokenSchema>
+
+/**
+ * Schema for OAuth client configuration.
+ *
+ * @category Schema
+ */
+export const OAuthConfigSchema = Schema.Struct({
+  /** OAuth client ID from Atlassian Developer Console */
+  clientId: Schema.String,
+  /** OAuth client secret */
+  clientSecret: Schema.String
+})
+
+/**
+ * Type for OAuth client configuration.
+ *
+ * @category Types
+ */
+export type OAuthConfig = Schema.Schema.Type<typeof OAuthConfigSchema>
+
+/**
+ * Schema for Atlassian Cloud site info.
+ *
+ * @category Schema
+ */
+export const AtlassianSiteSchema = Schema.Struct({
+  /** Cloud ID */
+  id: Schema.String,
+  /** Site name */
+  name: Schema.String,
+  /** Site URL */
+  url: Schema.String,
+  /** Available scopes */
+  scopes: Schema.Array(Schema.String),
+  /** Avatar URL */
+  avatarUrl: Schema.optional(Schema.String)
+})
+
+/**
+ * Type for Atlassian Cloud site.
+ *
+ * @category Types
+ */
+export type AtlassianSite = Schema.Schema.Type<typeof AtlassianSiteSchema>
+
+/**
+ * Schema for Atlassian user profile.
+ *
+ * @category Schema
+ */
+export const AtlassianUserSchema = Schema.Struct({
+  /** Atlassian account ID */
+  accountId: Schema.String,
+  /** Display name */
+  displayName: Schema.String,
+  /** Email address (may be empty for privacy) */
+  email: Schema.optional(Schema.String),
+  /** Public name */
+  publicName: Schema.optional(Schema.String)
+})
+
+/**
+ * Type for Atlassian user profile.
+ *
+ * @category Types
+ */
+export type AtlassianUser = Schema.Schema.Type<typeof AtlassianUserSchema>

package/src/config/TokenStorage.ts

@@ -0,0 +1,228 @@
+/**
+ * Persistent token and OAuth config storage with schema validation and secure file I/O.
+ *
+ * **Mental model**
+ *
+ * - **Load returns null, not error**: {@link loadToken} and {@link loadOAuthConfig} return
+ *   `null` for missing/corrupt files — callers decide whether absence is an error.
+ * - **Save is atomic**: Writes go through {@link writeSecureFile} with `0o600` permissions.
+ * - **Schema-gated reads**: JSON is parsed then validated via `Schema.decodeUnknown` —
+ *   corrupt data is treated as absent rather than crashing.
+ *
+ * **Common tasks**
+ *
+ * - Load stored token: {@link loadToken}
+ * - Persist after refresh: {@link saveToken}
+ * - Check expiration: {@link isTokenExpired}
+ *
+ * @module
+ */
+import type * as Error from "@effect/platform/Error"
+import * as FileSystem from "@effect/platform/FileSystem"
+import type * as Path from "@effect/platform/Path"
+import * as Data from "effect/Data"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+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"
+
+/**
+ * Error during file system operations.
+ *
+ * @category Errors
+ */
+export class FileSystemError extends Data.TaggedError("FileSystemError")<{
+  readonly operation: string
+  readonly path: string
+  readonly cause?: unknown
+}> {
+  override get message(): string {
+    return `Failed to ${this.operation} file at ${this.path}`
+  }
+}
+
+/**
+ * Load stored OAuth token from disk.
+ *
+ * @param toolName - The tool name (e.g., "confluence", "jira")
+ * @returns The stored token or null if not found/invalid
+ *
+ * @category Token Storage
+ */
+export const loadToken = (
+  toolName: string
+): Effect.Effect<
+  OAuthToken | null,
+  FileSystemError | HomeDirectoryError,
+  FileSystem.FileSystem | Path.Path | HomeDirectoryTag
+> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const tokenPath = yield* getAuthPath(toolName)
+
+    const exists = yield* fs.exists(tokenPath).pipe(
+      Effect.catchAll(() => Effect.succeed(false))
+    )
+    if (!exists) {
+      return null
+    }
+
+    const content = yield* fs.readFileString(tokenPath).pipe(
+      Effect.mapError((cause) => new FileSystemError({ operation: "read", path: tokenPath, cause }))
+    )
+
+    const parsed = yield* Effect.sync(() => {
+      try {
+        return JSON.parse(content) as unknown
+      } catch {
+        return null
+      }
+    })
+    if (parsed === null) {
+      yield* Effect.logWarning(`Corrupted auth.json at ${tokenPath} — could not parse JSON`)
+      return null
+    }
+
+    return yield* Schema.decodeUnknown(OAuthTokenSchema)(parsed).pipe(
+      Effect.catchAll((e) =>
+        Effect.logWarning(`Invalid token schema in ${tokenPath}: ${e}`).pipe(
+          Effect.map(() => null)
+        )
+      )
+    )
+  })
+
+/**
+ * Save OAuth token to disk with secure permissions.
+ *
+ * @param toolName - The tool name (e.g., "confluence", "jira")
+ * @param token - The token to save
+ *
+ * @category Token Storage
+ */
+export const saveToken = (
+  toolName: string,
+  token: OAuthToken
+): Effect.Effect<
+  void,
+  FileSystemError | HomeDirectoryError | Error.PlatformError,
+  FileSystem.FileSystem | Path.Path | HomeDirectoryTag
+> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    yield* ensureConfigDir(toolName)
+    const tokenPath = yield* getAuthPath(toolName)
+
+    yield* writeSecureFile(tokenPath, JSON.stringify(token, null, 2)).pipe(
+      Effect.provideService(FileSystem.FileSystem, fs)
+    )
+  })
+
+/**
+ * Delete stored OAuth token.
+ *
+ * @param toolName - The tool name (e.g., "confluence", "jira")
+ *
+ * @category Token Storage
+ */
+export const deleteToken = (
+  toolName: string
+): Effect.Effect<void, FileSystemError | HomeDirectoryError, FileSystem.FileSystem | Path.Path | HomeDirectoryTag> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const tokenPath = yield* getAuthPath(toolName)
+
+    yield* fs.remove(tokenPath).pipe(
+      Effect.catchAll(() => Effect.void)
+    )
+  })
+
+/**
+ * Load OAuth client configuration from disk.
+ *
+ * @param toolName - The tool name (e.g., "confluence", "jira")
+ * @returns The stored config or null if not found/invalid
+ *
+ * @category OAuth Config
+ */
+export const loadOAuthConfig = (
+  toolName: string
+): Effect.Effect<
+  OAuthConfig | null,
+  FileSystemError | HomeDirectoryError,
+  FileSystem.FileSystem | Path.Path | HomeDirectoryTag
+> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const configPath = yield* getOAuthConfigPath(toolName)
+
+    const exists = yield* fs.exists(configPath).pipe(
+      Effect.catchAll(() => Effect.succeed(false))
+    )
+    if (!exists) {
+      return null
+    }
+
+    const content = yield* fs.readFileString(configPath).pipe(
+      Effect.mapError((cause) => new FileSystemError({ operation: "read", path: configPath, cause }))
+    )
+
+    const parsed = yield* Effect.sync(() => {
+      try {
+        return JSON.parse(content) as unknown
+      } catch {
+        return null
+      }
+    })
+    if (parsed === null) {
+      yield* Effect.logWarning(`Corrupted oauth config at ${configPath} — could not parse JSON`)
+      return null
+    }
+
+    return yield* Schema.decodeUnknown(OAuthConfigSchema)(parsed).pipe(
+      Effect.catchAll((e) =>
+        Effect.logWarning(`Invalid OAuth config schema in ${configPath}: ${e}`).pipe(
+          Effect.map(() => null)
+        )
+      )
+    )
+  })
+
+/**
+ * Save OAuth client configuration to disk with secure permissions.
+ *
+ * @param toolName - The tool name (e.g., "confluence", "jira")
+ * @param config - The config to save
+ *
+ * @category OAuth Config
+ */
+export const saveOAuthConfig = (
+  toolName: string,
+  config: OAuthConfig
+): Effect.Effect<
+  void,
+  FileSystemError | HomeDirectoryError | Error.PlatformError,
+  FileSystem.FileSystem | Path.Path | HomeDirectoryTag
+> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    yield* ensureConfigDir(toolName)
+    const configPath = yield* getOAuthConfigPath(toolName)
+
+    yield* writeSecureFile(configPath, JSON.stringify(config, null, 2)).pipe(
+      Effect.provideService(FileSystem.FileSystem, fs)
+    )
+  })
+
+/**
+ * Check if token is expired or about to expire.
+ *
+ * @param token - The token to check
+ * @param bufferMs - Buffer time in ms before expiration (default: 5 minutes)
+ * @returns True if token is expired or will expire within buffer time
+ *
+ * @category Utilities
+ */
+export const isTokenExpired = (token: OAuthToken, bufferMs: number = 5 * 60 * 1000): boolean =>
+  Date.now() >= token.expires_at - bufferMs

package/src/config/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Barrel export for config path utilities, schemas, and token storage.
+ *
+ * @module
+ */
+
+// Config paths
+export {
+  ensureConfigDir,
+  getAuthPath,
+  getConfigDir,
+  getOAuthConfigPath,
+  type HomeDirectory,
+  HomeDirectoryError,
+  HomeDirectoryLive,
+  HomeDirectoryTag,
+  writeSecureFile
+} from "./ConfigPaths.js"
+
+// OAuth schemas
+export {
+  type AtlassianSite,
+  AtlassianSiteSchema,
+  type AtlassianUser,
+  AtlassianUserSchema,
+  type OAuthConfig,
+  OAuthConfigSchema,
+  type OAuthToken,
+  OAuthTokenSchema,
+  type OAuthUser,
+  OAuthUserSchema
+} from "./OAuthSchemas.js"
+
+// Token storage
+export {
+  deleteToken,
+  FileSystemError,
+  isTokenExpired,
+  loadOAuthConfig,
+  loadToken,
+  saveOAuthConfig,
+  saveToken
+} from "./TokenStorage.js"

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Root barrel export for `@knpkv/atlassian-common` — AST nodes, auth, config, serializers.
+ *
+ * @module
+ */
+
+// AST types
+export * from "./ast/index.js"
+
+// Brand utilities
+export {
+  ContentHash,
+  IssueKey,
+  makeBrandedNonEmptyString,
+  makeBrandedString,
+  PageId,
+  ProjectKey,
+  SpaceKey
+} from "./Brand.js"
+
+// Hash utilities
+export { hashBuffer, hashContent, hashContentSync, hashEquals } from "./Hash.js"
+
+// Error types
+export { ParseError, SerializeError } from "./SerializeError.js"
+
+// Serializers
+export { serializeInlineNodes, type SerializeOptions, serializeToMarkdown } from "./serializers/index.js"
+
+// Config utilities
+export * from "./config/index.js"
+
+// Auth utilities
+export * from "./auth/index.js"

package/src/parsers/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Barrel export for content parsers (placeholder — not yet implemented).
+ *
+ * @module
+ */
+
+// TODO: Extract MarkdownParser from confluence-to-markdown
+export {}