@37signals/basecamp 0.2.0

package/dist/oauth/interactive-login.js

@@ -0,0 +1,106 @@
+/**
+ * Interactive OAuth login flow for CLI and desktop applications.
+ *
+ * Orchestrates the full OAuth 2.0 authorization code flow:
+ * discovery, PKCE, local callback server, browser launch, code exchange.
+ */
+import { discover, discoverLaunchpad } from "./discovery.js";
+import { generateState, generatePKCE } from "./pkce.js";
+import { buildAuthorizationUrl } from "./authorize.js";
+import { startCallbackServer } from "./callback-server.js";
+import { exchangeCode } from "./exchange.js";
+import { BasecampError } from "../errors.js";
+/**
+ * Performs the full interactive OAuth login flow.
+ *
+ * Steps:
+ * 1. Discover OAuth endpoints
+ * 2. Generate PKCE and state parameters
+ * 3. Start local callback server
+ * 4. Build authorization URL and open browser
+ * 5. Wait for callback with authorization code
+ * 6. Exchange code for tokens
+ * 7. Save token to store
+ *
+ * @param options - Login flow configuration
+ * @returns The resulting OAuth token
+ * @throws BasecampError on any flow failure
+ *
+ * @example
+ * ```ts
+ * import open from "open"; // or use child_process
+ *
+ * const token = await performInteractiveLogin({
+ *   clientId: process.env.BASECAMP_CLIENT_ID!,
+ *   clientSecret: process.env.BASECAMP_CLIENT_SECRET!,
+ *   store: new FileTokenStore("~/.config/basecamp/tokens.json"),
+ *   openBrowser: (url) => open(url),
+ *   onStatus: (msg) => console.log(msg),
+ * });
+ * ```
+ */
+export async function performInteractiveLogin(options) {
+    const { clientId, clientSecret, store, baseUrl, useLegacyFormat = true, callbackPort, openBrowser, promptForManualVisit, onStatus, } = options;
+    // 1. Discover OAuth endpoints
+    onStatus?.("Discovering OAuth endpoints...");
+    const config = baseUrl ? await discover(baseUrl) : await discoverLaunchpad();
+    // 2. Generate PKCE and state
+    const state = generateState();
+    const pkce = await generatePKCE();
+    // 3. Start callback server
+    onStatus?.("Starting callback server...");
+    const { url: redirectUri, waitForCallback, close } = await startCallbackServer({
+        port: callbackPort,
+        expectedState: state,
+    });
+    try {
+        // 4. Build authorization URL
+        const authUrl = buildAuthorizationUrl({
+            authorizationEndpoint: config.authorizationEndpoint,
+            clientId,
+            redirectUri,
+            state,
+            pkce,
+        });
+        // 5. Open browser
+        onStatus?.("Opening browser for authorization...");
+        let browserOpened = false;
+        try {
+            await openBrowser(authUrl.toString());
+            browserOpened = true;
+        }
+        catch {
+            // Browser launch failed
+        }
+        if (!browserOpened) {
+            if (promptForManualVisit) {
+                await promptForManualVisit(authUrl.toString());
+            }
+            else {
+                throw new BasecampError("auth", "Failed to open browser and no manual visit prompt configured");
+            }
+        }
+        // 6. Wait for callback
+        onStatus?.("Waiting for authorization...");
+        const { code } = await waitForCallback();
+        // 7. Exchange code for tokens
+        onStatus?.("Exchanging authorization code for tokens...");
+        const token = await exchangeCode({
+            tokenEndpoint: config.tokenEndpoint,
+            code,
+            redirectUri,
+            clientId,
+            clientSecret,
+            codeVerifier: pkce.verifier,
+            useLegacyFormat,
+        });
+        // 8. Save token
+        await store.save(token);
+        onStatus?.("Authorization complete.");
+        return token;
+    }
+    finally {
+        close();
+    }
+}
+//# sourceMappingURL=interactive-login.js.map

package/dist/oauth/interactive-login.js.map

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

package/dist/oauth/pkce.d.ts

@@ -0,0 +1,68 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0.
+ *
+ * Provides cryptographically secure code verifier and challenge generation
+ * to protect against authorization code interception attacks.
+ */
+/**
+ * PKCE parameters for OAuth 2.0 authorization code flow with PKCE.
+ */
+export interface PKCE {
+    /** The code_verifier to send during token exchange */
+    verifier: string;
+    /** The code_challenge (SHA256 hash of verifier) to send during authorization */
+    challenge: string;
+}
+/**
+ * Generates a cryptographically secure PKCE code verifier and challenge.
+ *
+ * The verifier is 43 characters (32 random bytes, base64url-encoded).
+ * The challenge is the base64url-encoded SHA256 hash of the verifier.
+ *
+ * Use code_challenge_method=S256 with the challenge in the authorization request.
+ *
+ * @example
+ * ```ts
+ * const pkce = await generatePKCE();
+ *
+ * // In authorization request:
+ * const authUrl = new URL(authEndpoint);
+ * authUrl.searchParams.set("code_challenge", pkce.challenge);
+ * authUrl.searchParams.set("code_challenge_method", "S256");
+ *
+ * // Later, in token exchange:
+ * const token = await exchangeCode({
+ *   code,
+ *   codeVerifier: pkce.verifier,
+ *   // ...
+ * });
+ * ```
+ */
+export declare function generatePKCE(): Promise<PKCE>;
+/**
+ * Generates a cryptographically secure OAuth state parameter.
+ *
+ * The state is 22 characters (16 random bytes, base64url-encoded).
+ * Use this to prevent CSRF attacks on the OAuth flow.
+ *
+ * @example
+ * ```ts
+ * const state = generateState();
+ *
+ * // Store state before redirect:
+ * sessionStorage.setItem("oauth_state", state);
+ *
+ * // In authorization request:
+ * const authUrl = new URL(authEndpoint);
+ * authUrl.searchParams.set("state", state);
+ *
+ * // In callback handler:
+ * const returnedState = new URL(window.location.href).searchParams.get("state");
+ * const savedState = sessionStorage.getItem("oauth_state");
+ * if (returnedState !== savedState) {
+ *   throw new Error("State mismatch - possible CSRF attack");
+ * }
+ * ```
+ */
+export declare function generateState(): string;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/oauth/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/oauth/pkce.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;CACnB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAWlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAGtC"}

package/dist/oauth/pkce.js

@@ -0,0 +1,80 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0.
+ *
+ * Provides cryptographically secure code verifier and challenge generation
+ * to protect against authorization code interception attacks.
+ */
+/**
+ * Base64url encodes a Uint8Array without padding.
+ */
+function base64UrlEncode(bytes) {
+    // Convert to base64
+    const base64 = btoa(String.fromCharCode(...bytes));
+    // Convert to base64url (replace + with -, / with _, remove padding)
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+/**
+ * Generates a cryptographically secure PKCE code verifier and challenge.
+ *
+ * The verifier is 43 characters (32 random bytes, base64url-encoded).
+ * The challenge is the base64url-encoded SHA256 hash of the verifier.
+ *
+ * Use code_challenge_method=S256 with the challenge in the authorization request.
+ *
+ * @example
+ * ```ts
+ * const pkce = await generatePKCE();
+ *
+ * // In authorization request:
+ * const authUrl = new URL(authEndpoint);
+ * authUrl.searchParams.set("code_challenge", pkce.challenge);
+ * authUrl.searchParams.set("code_challenge_method", "S256");
+ *
+ * // Later, in token exchange:
+ * const token = await exchangeCode({
+ *   code,
+ *   codeVerifier: pkce.verifier,
+ *   // ...
+ * });
+ * ```
+ */
+export async function generatePKCE() {
+    // Generate 32 random bytes
+    const bytes = crypto.getRandomValues(new Uint8Array(32));
+    const verifier = base64UrlEncode(bytes);
+    // Compute SHA256 hash of the verifier
+    const encoder = new TextEncoder();
+    const hashBuffer = await crypto.subtle.digest("SHA-256", encoder.encode(verifier));
+    const challenge = base64UrlEncode(new Uint8Array(hashBuffer));
+    return { verifier, challenge };
+}
+/**
+ * Generates a cryptographically secure OAuth state parameter.
+ *
+ * The state is 22 characters (16 random bytes, base64url-encoded).
+ * Use this to prevent CSRF attacks on the OAuth flow.
+ *
+ * @example
+ * ```ts
+ * const state = generateState();
+ *
+ * // Store state before redirect:
+ * sessionStorage.setItem("oauth_state", state);
+ *
+ * // In authorization request:
+ * const authUrl = new URL(authEndpoint);
+ * authUrl.searchParams.set("state", state);
+ *
+ * // In callback handler:
+ * const returnedState = new URL(window.location.href).searchParams.get("state");
+ * const savedState = sessionStorage.getItem("oauth_state");
+ * if (returnedState !== savedState) {
+ *   throw new Error("State mismatch - possible CSRF attack");
+ * }
+ * ```
+ */
+export function generateState() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    return base64UrlEncode(bytes);
+}
+//# sourceMappingURL=pkce.js.map

package/dist/oauth/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../src/oauth/pkce.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH;;GAEG;AACH,SAAS,eAAe,CAAC,KAAiB;IACxC,oBAAoB;IACpB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IACnD,oEAAoE;IACpE,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,2BAA2B;IAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAExC,sCAAsC;IACtC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IACnF,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;IAE9D,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IACzD,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC"}

package/dist/oauth/token-manager.d.ts

@@ -0,0 +1,92 @@
+/**
+ * OAuth 2.0 token lifecycle management.
+ *
+ * Handles automatic token refresh, expiry detection, and refresh deduplication.
+ */
+import type { TokenStore } from "./token-store.js";
+import type { RefreshRequest, OAuthToken } from "./types.js";
+/**
+ * Options for creating a TokenManager.
+ */
+export interface TokenManagerOptions {
+    /** Token persistence store */
+    store: TokenStore;
+    /** Function to perform the token refresh HTTP call */
+    refreshToken: (req: RefreshRequest) => Promise<OAuthToken>;
+    /** URL of the token endpoint */
+    tokenEndpoint: string;
+    /** The client identifier (optional) */
+    clientId?: string;
+    /** The client secret (optional) */
+    clientSecret?: string;
+    /** Use Launchpad's non-standard token format (optional) */
+    useLegacyFormat?: boolean;
+    /** Seconds before expiry to trigger refresh (default: 120) */
+    bufferSeconds?: number;
+}
+/**
+ * Manages OAuth token lifecycle with automatic refresh and persistence.
+ *
+ * Loads tokens from a store on first access, refreshes when expired,
+ * and deduplicates concurrent refresh requests.
+ *
+ * @example
+ * ```ts
+ * const manager = new TokenManager({
+ *   store: new FileTokenStore("~/.config/basecamp/tokens.json"),
+ *   refreshToken,
+ *   tokenEndpoint: config.tokenEndpoint,
+ *   clientId: "my_client_id",
+ *   clientSecret: "my_client_secret",
+ *   useLegacyFormat: true,
+ * });
+ *
+ * // Use as a TokenProvider
+ * const client = createBasecampClient({
+ *   accountId: "12345",
+ *   accessToken: () => manager.getToken(),
+ * });
+ * ```
+ */
+export declare class TokenManager {
+    private readonly store;
+    private readonly doRefresh;
+    private readonly tokenEndpoint;
+    private readonly clientId?;
+    private readonly clientSecret?;
+    private readonly useLegacyFormat?;
+    private readonly bufferSeconds;
+    private token;
+    private loaded;
+    private refreshPromise;
+    constructor(options: TokenManagerOptions);
+    /**
+     * Returns a valid access token string, refreshing if necessary.
+     *
+     * On first call, loads from store. If expired, refreshes and saves.
+     * Concurrent calls during refresh share the same promise.
+     *
+     * @throws if no token is available and refresh fails
+     */
+    getToken(): Promise<string>;
+    /**
+     * Forces a token refresh regardless of expiry.
+     *
+     * Concurrent calls share the same in-flight request.
+     *
+     * @throws if no refresh token is available or refresh fails
+     */
+    forceRefresh(): Promise<OAuthToken>;
+    /**
+     * Checks if the current token is expired.
+     *
+     * Returns true if no token is loaded or the token has expired.
+     */
+    isExpired(): boolean;
+    /**
+     * The currently loaded token, or null if none.
+     */
+    get currentToken(): OAuthToken | null;
+    private executeRefresh;
+}
+//# sourceMappingURL=token-manager.d.ts.map

package/dist/oauth/token-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../../src/oauth/token-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,8BAA8B;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,sDAAsD;IACtD,YAAY,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3D,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+C;IACzE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAU;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAoC;gBAE9C,OAAO,EAAE,mBAAmB;IAUxC;;;;;;;OAOG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAcjC;;;;;;OAMG;IACG,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC;IAczC;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAKpB;;OAEG;IACH,IAAI,YAAY,IAAI,UAAU,GAAG,IAAI,CAEpC;YAEa,cAAc;CAuB7B"}

package/dist/oauth/token-manager.js

@@ -0,0 +1,126 @@
+/**
+ * OAuth 2.0 token lifecycle management.
+ *
+ * Handles automatic token refresh, expiry detection, and refresh deduplication.
+ */
+import { isTokenExpired } from "./exchange.js";
+/**
+ * Manages OAuth token lifecycle with automatic refresh and persistence.
+ *
+ * Loads tokens from a store on first access, refreshes when expired,
+ * and deduplicates concurrent refresh requests.
+ *
+ * @example
+ * ```ts
+ * const manager = new TokenManager({
+ *   store: new FileTokenStore("~/.config/basecamp/tokens.json"),
+ *   refreshToken,
+ *   tokenEndpoint: config.tokenEndpoint,
+ *   clientId: "my_client_id",
+ *   clientSecret: "my_client_secret",
+ *   useLegacyFormat: true,
+ * });
+ *
+ * // Use as a TokenProvider
+ * const client = createBasecampClient({
+ *   accountId: "12345",
+ *   accessToken: () => manager.getToken(),
+ * });
+ * ```
+ */
+export class TokenManager {
+    store;
+    doRefresh;
+    tokenEndpoint;
+    clientId;
+    clientSecret;
+    useLegacyFormat;
+    bufferSeconds;
+    token = null;
+    loaded = false;
+    refreshPromise = null;
+    constructor(options) {
+        this.store = options.store;
+        this.doRefresh = options.refreshToken;
+        this.tokenEndpoint = options.tokenEndpoint;
+        this.clientId = options.clientId;
+        this.clientSecret = options.clientSecret;
+        this.useLegacyFormat = options.useLegacyFormat;
+        this.bufferSeconds = options.bufferSeconds ?? 120;
+    }
+    /**
+     * Returns a valid access token string, refreshing if necessary.
+     *
+     * On first call, loads from store. If expired, refreshes and saves.
+     * Concurrent calls during refresh share the same promise.
+     *
+     * @throws if no token is available and refresh fails
+     */
+    async getToken() {
+        if (!this.loaded) {
+            this.token = await this.store.load();
+            this.loaded = true;
+        }
+        if (this.token && !isTokenExpired(this.token, this.bufferSeconds)) {
+            return this.token.accessToken;
+        }
+        const refreshed = await this.forceRefresh();
+        return refreshed.accessToken;
+    }
+    /**
+     * Forces a token refresh regardless of expiry.
+     *
+     * Concurrent calls share the same in-flight request.
+     *
+     * @throws if no refresh token is available or refresh fails
+     */
+    async forceRefresh() {
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = this.executeRefresh();
+        try {
+            return await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    /**
+     * Checks if the current token is expired.
+     *
+     * Returns true if no token is loaded or the token has expired.
+     */
+    isExpired() {
+        if (!this.token)
+            return true;
+        return isTokenExpired(this.token, this.bufferSeconds);
+    }
+    /**
+     * The currently loaded token, or null if none.
+     */
+    get currentToken() {
+        return this.token;
+    }
+    async executeRefresh() {
+        const refreshTokenValue = this.token?.refreshToken;
+        if (!refreshTokenValue) {
+            throw new Error("No refresh token available");
+        }
+        const newToken = await this.doRefresh({
+            tokenEndpoint: this.tokenEndpoint,
+            refreshToken: refreshTokenValue,
+            clientId: this.clientId,
+            clientSecret: this.clientSecret,
+            useLegacyFormat: this.useLegacyFormat,
+        });
+        // Preserve the previous refresh token when the server omits one
+        const merged = newToken.refreshToken
+            ? newToken
+            : { ...newToken, refreshToken: refreshTokenValue };
+        this.token = merged;
+        await this.store.save(merged);
+        return merged;
+    }
+}
+//# sourceMappingURL=token-manager.js.map

package/dist/oauth/token-manager.js.map

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

package/dist/oauth/token-store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Token persistence for OAuth 2.0 tokens.
+ *
+ * Provides a file-based token store with atomic writes and secure permissions.
+ */
+import type { OAuthToken } from "./types.js";
+/**
+ * Interface for persisting OAuth tokens.
+ */
+export interface TokenStore {
+    /** Load a previously saved token, or null if none exists */
+    load(): Promise<OAuthToken | null>;
+    /** Save a token for later retrieval */
+    save(token: OAuthToken): Promise<void>;
+    /** Remove the stored token */
+    clear(): Promise<void>;
+}
+/**
+ * File-based token store with atomic writes and secure permissions.
+ *
+ * Tokens are stored as JSON with 0o600 permissions (owner read/write only).
+ * Writes are atomic: data is written to a temporary file then renamed.
+ *
+ * @example
+ * ```ts
+ * const store = new FileTokenStore("~/.config/basecamp/tokens.json");
+ *
+ * // Save a token
+ * await store.save(token);
+ *
+ * // Load it back
+ * const loaded = await store.load();
+ *
+ * // Clear when done
+ * await store.clear();
+ * ```
+ */
+export declare class FileTokenStore implements TokenStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    load(): Promise<OAuthToken | null>;
+    save(token: OAuthToken): Promise<void>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=token-store.d.ts.map

package/dist/oauth/token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../../src/oauth/token-store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,IAAI,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnC,uCAAuC;IACvC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,8BAA8B;IAC9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA2BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAe,YAAW,UAAU;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,EAAE,MAAM;IAItB,IAAI,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAuBlC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAU7B"}

package/dist/oauth/token-store.js

@@ -0,0 +1,105 @@
+/**
+ * Token persistence for OAuth 2.0 tokens.
+ *
+ * Provides a file-based token store with atomic writes and secure permissions.
+ */
+import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { homedir } from "node:os";
+/**
+ * Resolves ~ to the user's home directory.
+ */
+function expandHome(filePath) {
+    if (filePath.startsWith("~/")) {
+        return filePath.replace("~", homedir());
+    }
+    if (filePath === "~") {
+        return homedir();
+    }
+    return filePath;
+}
+/**
+ * File-based token store with atomic writes and secure permissions.
+ *
+ * Tokens are stored as JSON with 0o600 permissions (owner read/write only).
+ * Writes are atomic: data is written to a temporary file then renamed.
+ *
+ * @example
+ * ```ts
+ * const store = new FileTokenStore("~/.config/basecamp/tokens.json");
+ *
+ * // Save a token
+ * await store.save(token);
+ *
+ * // Load it back
+ * const loaded = await store.load();
+ *
+ * // Clear when done
+ * await store.clear();
+ * ```
+ */
+export class FileTokenStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = expandHome(filePath);
+    }
+    async load() {
+        let raw;
+        try {
+            raw = await readFile(this.filePath, "utf-8");
+        }
+        catch (err) {
+            if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+                return null;
+            }
+            throw err;
+        }
+        const data = JSON.parse(raw);
+        return {
+            accessToken: data.accessToken,
+            refreshToken: data.refreshToken,
+            tokenType: data.tokenType,
+            expiresIn: data.expiresIn,
+            expiresAt: data.expiresAt ? new Date(data.expiresAt) : undefined,
+            scope: data.scope,
+        };
+    }
+    async save(token) {
+        const serialized = {
+            accessToken: token.accessToken,
+            refreshToken: token.refreshToken,
+            tokenType: token.tokenType,
+            expiresIn: token.expiresIn,
+            expiresAt: token.expiresAt?.toISOString(),
+            scope: token.scope,
+        };
+        const json = JSON.stringify(serialized, null, 2) + "\n";
+        const tmpPath = this.filePath + ".tmp";
+        // Ensure directory exists
+        await mkdir(dirname(this.filePath), { recursive: true });
+        // Remove stale tmp file so writeFile creates a fresh one with 0o600
+        try {
+            await unlink(tmpPath);
+        }
+        catch (err) {
+            if (!(err instanceof Error && "code" in err && err.code === "ENOENT")) {
+                throw err;
+            }
+        }
+        // Atomic write: write to tmp, then rename
+        await writeFile(tmpPath, json, { mode: 0o600 });
+        await rename(tmpPath, this.filePath);
+    }
+    async clear() {
+        try {
+            await unlink(this.filePath);
+        }
+        catch (err) {
+            if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+                return; // Already gone
+            }
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=token-store.js.map

package/dist/oauth/token-store.js.map

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