@knpkv/atlassian-common 0.2.0

package/dist/auth/OAuthResponseSchemas.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 declare const TokenResponseSchema: Schema.Struct<{
+    access_token: typeof Schema.String;
+    refresh_token: typeof Schema.String;
+    expires_in: typeof Schema.Number;
+    scope: typeof Schema.String;
+    token_type: typeof 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 declare const AccessibleResourceSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    name: typeof Schema.String;
+    url: typeof Schema.String;
+    scopes: Schema.Array$<typeof Schema.String>;
+    avatarUrl: Schema.optional<typeof 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 declare const UserInfoSchema: Schema.Struct<{
+    account_id: typeof Schema.String;
+    name: typeof Schema.String;
+    email: typeof Schema.String;
+}>;
+/**
+ * Type for user info.
+ *
+ * @category Types
+ */
+export type UserInfo = Schema.Schema.Type<typeof UserInfoSchema>;
+//# sourceMappingURL=OAuthResponseSchemas.d.ts.map

package/dist/auth/OAuthResponseSchemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthResponseSchemas.d.ts","sourceRoot":"","sources":["../../src/auth/OAuthResponseSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;EAM9B,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE1E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;EAMnC,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAEpF;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;EAIzB,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,cAAc,CAAC,CAAA"}

package/dist/auth/OAuthResponseSchemas.js

@@ -0,0 +1,47 @@
+/**
+ * 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
+});
+/**
+ * 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)
+});
+/**
+ * Schema for user info from /me endpoint.
+ *
+ * @category Schema
+ */
+export const UserInfoSchema = Schema.Struct({
+    account_id: Schema.String,
+    name: Schema.String,
+    email: Schema.String
+});
+//# sourceMappingURL=OAuthResponseSchemas.js.map

package/dist/auth/OAuthResponseSchemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthResponseSchemas.js","sourceRoot":"","sources":["../../src/auth/OAuthResponseSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C,YAAY,EAAE,MAAM,CAAC,MAAM;IAC3B,aAAa,EAAE,MAAM,CAAC,MAAM;IAC5B,UAAU,EAAE,MAAM,CAAC,MAAM;IACzB,KAAK,EAAE,MAAM,CAAC,MAAM;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM;CAC1B,CAAC,CAAA;AASF;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,CAAC;IACpD,EAAE,EAAE,MAAM,CAAC,MAAM;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,GAAG,EAAE,MAAM,CAAC,MAAM;IAClB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;CAC1C,CAAC,CAAA;AASF;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1C,UAAU,EAAE,MAAM,CAAC,MAAM;IACzB,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,KAAK,EAAE,MAAM,CAAC,MAAM;CACrB,CAAC,CAAA"}

package/dist/auth/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Barrel export for Atlassian OAuth2 auth utilities.
+ *
+ * @module
+ */
+export { AUTH_URL, buildAuthUrl, type BuildAuthUrlOptions, computeCodeChallenge, CONFLUENCE_SCOPES, generateCodeVerifier, JIRA_SCOPES, ME_URL, RESOURCES_URL, REVOKE_URL, TOKEN_URL } from "./OAuthEndpoints.js";
+export { AuthMissingError, OAuthError, OAuthNotConfiguredError, type OAuthStep } from "./OAuthErrors.js";
+export { buildOAuthToken, exchangeCodeForTokens, type ExchangeCodeOptions, getAccessibleResources, getUserInfo, refreshToken, revokeToken } from "./OAuthOperations.js";
+export { type AccessibleResource, AccessibleResourceSchema, type TokenResponse, TokenResponseSchema, type UserInfo, UserInfoSchema } from "./OAuthResponseSchemas.js";
+export { generateUUID } from "./uuid.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,QAAQ,EACR,YAAY,EACZ,KAAK,mBAAmB,EACxB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,EACX,MAAM,EACN,aAAa,EACb,UAAU,EACV,SAAS,EACV,MAAM,qBAAqB,CAAA;AAG5B,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,uBAAuB,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAGxG,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,sBAAsB,EACtB,WAAW,EACX,YAAY,EACZ,WAAW,EACZ,MAAM,sBAAsB,CAAA;AAG7B,OAAO,EACL,KAAK,kBAAkB,EACvB,wBAAwB,EACxB,KAAK,aAAa,EAClB,mBAAmB,EACnB,KAAK,QAAQ,EACb,cAAc,EACf,MAAM,2BAA2B,CAAA;AAGlC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA"}

package/dist/auth/index.js

@@ -0,0 +1,16 @@
+/**
+ * Barrel export for Atlassian OAuth2 auth utilities.
+ *
+ * @module
+ */
+// Endpoints and scopes
+export { AUTH_URL, buildAuthUrl, computeCodeChallenge, CONFLUENCE_SCOPES, generateCodeVerifier, JIRA_SCOPES, ME_URL, RESOURCES_URL, REVOKE_URL, TOKEN_URL } from "./OAuthEndpoints.js";
+// Errors
+export { AuthMissingError, OAuthError, OAuthNotConfiguredError } from "./OAuthErrors.js";
+// Operations
+export { buildOAuthToken, exchangeCodeForTokens, getAccessibleResources, getUserInfo, refreshToken, revokeToken } from "./OAuthOperations.js";
+// Response schemas
+export { AccessibleResourceSchema, TokenResponseSchema, UserInfoSchema } from "./OAuthResponseSchemas.js";
+// Utilities
+export { generateUUID } from "./uuid.js";
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,uBAAuB;AACvB,OAAO,EACL,QAAQ,EACR,YAAY,EAEZ,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,EACX,MAAM,EACN,aAAa,EACb,UAAU,EACV,SAAS,EACV,MAAM,qBAAqB,CAAA;AAE5B,SAAS;AACT,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,uBAAuB,EAAkB,MAAM,kBAAkB,CAAA;AAExG,aAAa;AACb,OAAO,EACL,eAAe,EACf,qBAAqB,EAErB,sBAAsB,EACtB,WAAW,EACX,YAAY,EACZ,WAAW,EACZ,MAAM,sBAAsB,CAAA;AAE7B,mBAAmB;AACnB,OAAO,EAEL,wBAAwB,EAExB,mBAAmB,EAEnB,cAAc,EACf,MAAM,2BAA2B,CAAA;AAElC,YAAY;AACZ,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA"}

package/dist/auth/uuid.d.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 declare const generateUUID: () => Effect.Effect<string>;
+//# sourceMappingURL=uuid.d.ts.map

package/dist/auth/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../../src/auth/uuid.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,QAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAsD,CAAA"}

package/dist/auth/uuid.js

@@ -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.sync(() => globalThis.crypto.randomUUID());
+//# sourceMappingURL=uuid.js.map

package/dist/auth/uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.js","sourceRoot":"","sources":["../../src/auth/uuid.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAA0B,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAA"}

package/dist/config/ConfigPaths.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+declare const HomeDirectoryError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "HomeDirectoryError";
+} & Readonly<A>;
+/**
+ * Error when home directory cannot be determined.
+ *
+ * @category Errors
+ */
+export declare class HomeDirectoryError extends HomeDirectoryError_base<{
+    readonly cause?: unknown;
+}> {
+    get message(): string;
+}
+/**
+ * Service for getting the home directory.
+ * Allows mocking in tests.
+ *
+ * @category Services
+ */
+export interface HomeDirectory {
+    readonly get: () => Effect.Effect<string, HomeDirectoryError>;
+}
+declare const HomeDirectoryTag_base: Context.TagClass<HomeDirectoryTag, "@knpkv/atlassian-common/HomeDirectory", HomeDirectory>;
+/**
+ * Tag for the HomeDirectory service.
+ *
+ * @category Services
+ */
+export declare class HomeDirectoryTag extends HomeDirectoryTag_base {
+}
+/**
+ * Default implementation using HOME/USERPROFILE env vars.
+ *
+ * @category Layers
+ */
+export declare const HomeDirectoryLive: Layer.Layer<HomeDirectoryTag>;
+/**
+ * XDG config directory for Atlassian tools.
+ * Returns ~/.config/atlassian by default.
+ *
+ * @category Utilities
+ */
+export declare const getConfigDir: (toolName?: string) => Effect.Effect<string, HomeDirectoryError, HomeDirectoryTag | Path.Path>;
+/**
+ * Get auth file path for a specific tool.
+ *
+ * @category Utilities
+ */
+export declare const getAuthPath: (toolName: string) => Effect.Effect<string, HomeDirectoryError, HomeDirectoryTag | Path.Path>;
+/**
+ * Get OAuth config file path for a specific tool.
+ *
+ * @category Utilities
+ */
+export declare const getOAuthConfigPath: (toolName: string) => Effect.Effect<string, HomeDirectoryError, HomeDirectoryTag | Path.Path>;
+/**
+ * Ensure config directory exists with secure permissions.
+ *
+ * @category Utilities
+ */
+export declare const ensureConfigDir: (toolName: string) => Effect.Effect<string, HomeDirectoryError | Error.PlatformError, FileSystem.FileSystem | Path.Path | HomeDirectoryTag>;
+/**
+ * Write file with secure permissions (600).
+ *
+ * @category Utilities
+ */
+export declare const writeSecureFile: (filePath: string, content: string) => Effect.Effect<void, Error.PlatformError, FileSystem.FileSystem>;
+export {};
+//# sourceMappingURL=ConfigPaths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigPaths.d.ts","sourceRoot":"","sources":["../../src/config/ConfigPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,KAAK,KAAK,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,UAAU,MAAM,6BAA6B,CAAA;AACzD,OAAO,KAAK,IAAI,MAAM,uBAAuB,CAAA;AAE7C,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;;;;AAGrC;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC;IACA,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;CAC9D;;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,qBAGnC;CAAG;AAMN;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAY3D,CAAA;AAID;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACvB,WAAW,MAAM,KAChB,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAYrE,CAAA;AAEJ;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAKrE,CAAA;AAEJ;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAKrE,CAAA;AAEJ;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CACd,MAAM,EACN,kBAAkB,GAAG,KAAK,CAAC,aAAa,EACxC,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAYlD,CAAA;AAEJ;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,MAAM,EAChB,SAAS,MAAM,KACd,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,aAAa,EAAE,UAAU,CAAC,UAAU,CAQ7D,CAAA"}

package/dist/config/ConfigPaths.js

@@ -0,0 +1,102 @@
+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") {
+    get message() {
+        return "Cannot determine home directory: HOME/USERPROFILE not set";
+    }
+}
+/**
+ * Tag for the HomeDirectory service.
+ *
+ * @category Services
+ */
+export class HomeDirectoryTag extends Context.Tag("@knpkv/atlassian-common/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.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) => 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) => 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) => 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) => 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, content) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* fs.writeFileString(filePath, content);
+    // Set secure permissions (owner only)
+    yield* fs.chmod(filePath, 0o600);
+});
+//# sourceMappingURL=ConfigPaths.js.map

package/dist/config/ConfigPaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigPaths.js","sourceRoot":"","sources":["../../src/config/ConfigPaths.ts"],"names":[],"mappings":"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"}

package/dist/config/OAuthSchemas.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 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 declare const OAuthUserSchema: Schema.Struct<{
+    /** Atlassian account ID */
+    account_id: typeof Schema.String;
+    /** Display name */
+    name: typeof Schema.String;
+    /** Email address */
+    email: typeof 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 declare const OAuthTokenSchema: Schema.Struct<{
+    /** OAuth access token */
+    access_token: typeof Schema.String;
+    /** OAuth refresh token */
+    refresh_token: typeof Schema.String;
+    /** Token expiration timestamp (Unix ms) */
+    expires_at: typeof Schema.Number;
+    /** Granted scopes */
+    scope: typeof Schema.String;
+    /** Atlassian Cloud site ID */
+    cloud_id: typeof Schema.String;
+    /** Site URL */
+    site_url: typeof Schema.String;
+    /** Cached user info */
+    user: Schema.optional<Schema.Struct<{
+        /** Atlassian account ID */
+        account_id: typeof Schema.String;
+        /** Display name */
+        name: typeof Schema.String;
+        /** Email address */
+        email: typeof Schema.String;
+    }>>;
+}>;
+/**
+ * Type for stored OAuth token.
+ *
+ * @category Types
+ */
+export type OAuthToken = Schema.Schema.Type<typeof OAuthTokenSchema>;
+/**
+ * Schema for OAuth client configuration.
+ *
+ * @category Schema
+ */
+export declare const OAuthConfigSchema: Schema.Struct<{
+    /** OAuth client ID from Atlassian Developer Console */
+    clientId: typeof Schema.String;
+    /** OAuth client secret */
+    clientSecret: typeof 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 declare const AtlassianSiteSchema: Schema.Struct<{
+    /** Cloud ID */
+    id: typeof Schema.String;
+    /** Site name */
+    name: typeof Schema.String;
+    /** Site URL */
+    url: typeof Schema.String;
+    /** Available scopes */
+    scopes: Schema.Array$<typeof Schema.String>;
+    /** Avatar URL */
+    avatarUrl: Schema.optional<typeof 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 declare const AtlassianUserSchema: Schema.Struct<{
+    /** Atlassian account ID */
+    accountId: typeof Schema.String;
+    /** Display name */
+    displayName: typeof Schema.String;
+    /** Email address (may be empty for privacy) */
+    email: Schema.optional<typeof Schema.String>;
+    /** Public name */
+    publicName: Schema.optional<typeof Schema.String>;
+}>;
+/**
+ * Type for Atlassian user profile.
+ *
+ * @category Types
+ */
+export type AtlassianUser = Schema.Schema.Type<typeof AtlassianUserSchema>;
+//# sourceMappingURL=OAuthSchemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthSchemas.d.ts","sourceRoot":"","sources":["../../src/config/OAuthSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;GAIG;AACH,eAAO,MAAM,eAAe;IAC1B,2BAA2B;;IAE3B,mBAAmB;;IAEnB,oBAAoB;;EAEpB,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,eAAe,CAAC,CAAA;AAElE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB;IAC3B,yBAAyB;;IAEzB,0BAA0B;;IAE1B,2CAA2C;;IAE3C,qBAAqB;;IAErB,8BAA8B;;IAE9B,eAAe;;IAEf,uBAAuB;;QAhDvB,2BAA2B;;QAE3B,mBAAmB;;QAEnB,oBAAoB;;;EA8CpB,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEpE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;IAC5B,uDAAuD;;IAEvD,0BAA0B;;EAE1B,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEtE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;IAC9B,eAAe;;IAEf,gBAAgB;;IAEhB,eAAe;;IAEf,uBAAuB;;IAEvB,iBAAiB;;EAEjB,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE1E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;IAC9B,2BAA2B;;IAE3B,mBAAmB;;IAEnB,+CAA+C;;IAE/C,kBAAkB;;EAElB,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

package/dist/config/OAuthSchemas.js

@@ -0,0 +1,107 @@
+/**
+ * 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
+});
+/**
+ * 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)
+});
+/**
+ * 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
+});
+/**
+ * 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)
+});
+/**
+ * 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)
+});
+//# sourceMappingURL=OAuthSchemas.js.map

package/dist/config/OAuthSchemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthSchemas.js","sourceRoot":"","sources":["../../src/config/OAuthSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3C,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC,MAAM;IACzB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC,MAAM;CACrB,CAAC,CAAA;AASF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5C,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAC,MAAM;IAC3B,0BAA0B;IAC1B,aAAa,EAAE,MAAM,CAAC,MAAM;IAC5B,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC,MAAM;IACzB,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC,MAAM;IACpB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM;IACvB,eAAe;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM;IACvB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC;CACvC,CAAC,CAAA;AASF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7C,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC,MAAM;IACvB,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC,MAAM;CAC5B,CAAC,CAAA;AASF;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C,eAAe;IACf,EAAE,EAAE,MAAM,CAAC,MAAM;IACjB,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,eAAe;IACf,GAAG,EAAE,MAAM,CAAC,MAAM;IAClB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IACnC,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;CAC1C,CAAC,CAAA;AASF;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC,MAAM;IACxB,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM;IAC1B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACrC,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;CAC3C,CAAC,CAAA"}