@zapier/zapier-sdk-cli 0.42.1 → 0.43.0

package/dist/src/login/filesystem-cache.js

@@ -0,0 +1,195 @@
+/**
+ * Default filesystem + OS keychain cache adapter for the SDK.
+ *
+ * Conforms to the generic ZapierCache interface that the SDK defines.
+ * Secrets go to the OS keychain via cross-keychain; non-secret values
+ * and the identity metadata (expires_at, secret flag) go to the
+ * existing zapier-sdk-cli Conf file. A proper-lockfile lock wraps the
+ * exchange/persist critical section so N concurrent CLI invocations
+ * collapse to a single network exchange.
+ *
+ * The SDK treats this (like any ZapierCache) as a cache — values may
+ * disappear, and the caller must always be able to recreate them.
+ */
+import { createHash } from "crypto";
+import { dirname } from "path";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { getPassword, setPassword, deletePassword } from "cross-keychain";
+import * as lockfile from "proper-lockfile";
+import { getConfig } from "./index";
+import { enqueue, getBackendInfo } from "./keychain";
+const SERVICE = "zapier-sdk-cache";
+const CONFIG_KEY = "cache";
+const LOCK_UPDATE_MS = 5000;
+const LOCK_STALE_MS = 10000;
+const LOCK_RETRY_WAIT_MS = 100;
+const LOCK_RETRY_MAX_WAIT_MS = 1000;
+const LOCK_RETRY_COUNT = 120; // ~2 min worst-case wait under heavy contention
+/**
+ * cross-keychain's native macOS backend restricts account names to
+ * alphanumeric + . _ @ -. Hash arbitrary SDK keys to a hex digest to
+ * stay inside that alphabet.
+ */
+function keychainAccount(key) {
+    return createHash("sha256").update(key).digest("hex");
+}
+function readConfigMap() {
+    const cfg = getConfig();
+    const stored = cfg.get(CONFIG_KEY);
+    if (stored && typeof stored === "object") {
+        return stored;
+    }
+    return {};
+}
+function writeConfigMap(map) {
+    getConfig().set(CONFIG_KEY, map);
+}
+function entryIsExpired(entry) {
+    return entry.expires_at !== undefined && entry.expires_at <= Date.now();
+}
+export function createCache() {
+    return {
+        async get(key) {
+            const entry = readConfigMap()[key];
+            if (!entry)
+                return undefined;
+            if (entryIsExpired(entry))
+                return undefined;
+            if (entry.secret) {
+                const stored = await enqueue(async () => {
+                    await getBackendInfo();
+                    return getPassword(SERVICE, keychainAccount(key));
+                });
+                if (!stored) {
+                    // Config claims a secret exists but keychain doesn't have it.
+                    // Treat as a miss so the caller re-produces the value.
+                    return undefined;
+                }
+                return { value: stored, expiresAt: entry.expires_at };
+            }
+            if (entry.value === undefined)
+                return undefined;
+            return { value: entry.value, expiresAt: entry.expires_at };
+        },
+        async set(key, value, options) {
+            const secret = options?.secret ?? false;
+            const expiresAt = options?.ttl
+                ? Date.now() + options.ttl * 1000
+                : undefined;
+            if (secret) {
+                // Keychain first so a failed keychain write doesn't leave a
+                // dangling config pointer to a non-existent secret.
+                try {
+                    await enqueue(async () => {
+                        await getBackendInfo();
+                        await setPassword(SERVICE, keychainAccount(key), value);
+                    });
+                }
+                catch {
+                    // No keychain available (headless CI, sandboxed env). Skip
+                    // the config write too so subsequent reads cleanly miss.
+                    return;
+                }
+                const map = readConfigMap();
+                map[key] = { secret: true, expires_at: expiresAt };
+                try {
+                    writeConfigMap(map);
+                }
+                catch {
+                    // Config is read-only; orphan the keychain entry. Reads find
+                    // no config pointer and treat as a miss — self-healing on the
+                    // next successful write.
+                }
+            }
+            else {
+                const map = readConfigMap();
+                map[key] = { secret: false, value, expires_at: expiresAt };
+                try {
+                    writeConfigMap(map);
+                }
+                catch {
+                    // Nothing we can do; next write for this key is the next
+                    // chance to persist.
+                }
+            }
+        },
+        async delete(key) {
+            // Config first: an orphan keychain entry with no config pointer
+            // is unreachable via `get`, which is better than a stuck stale
+            // value if the keychain delete succeeds but config write fails.
+            const map = readConfigMap();
+            const entry = map[key];
+            if (entry) {
+                delete map[key];
+                try {
+                    writeConfigMap(map);
+                }
+                catch {
+                    // ignore
+                }
+            }
+            if (entry?.secret) {
+                try {
+                    await enqueue(async () => {
+                        await getBackendInfo();
+                        await deletePassword(SERVICE, keychainAccount(key));
+                    });
+                }
+                catch {
+                    // Best-effort
+                }
+            }
+        },
+        async withLock(_key, fn) {
+            // Global lock on the Conf file: Conf writes the whole file
+            // atomically, so a per-key lock wouldn't prevent sibling keys
+            // from clobbering each other. Fleet-wide serialization is fine
+            // at CLI scale (<1 request/second sustained per machine).
+            const cfg = getConfig();
+            const lockTarget = `${cfg.path}.cache-lock`;
+            try {
+                mkdirSync(dirname(lockTarget), { recursive: true });
+                if (!existsSync(lockTarget)) {
+                    writeFileSync(lockTarget, "");
+                }
+            }
+            catch {
+                // Can't create the lock file (read-only fs, no HOME, etc.).
+                // Proceed unsynchronized — correctness is maintained at the
+                // cost of possibly N exchanges in the worst case, same as
+                // before this MR.
+                return fn();
+            }
+            let release = null;
+            try {
+                release = await lockfile.lock(lockTarget, {
+                    stale: LOCK_STALE_MS,
+                    update: LOCK_UPDATE_MS,
+                    retries: {
+                        retries: LOCK_RETRY_COUNT,
+                        factor: 1.2,
+                        minTimeout: LOCK_RETRY_WAIT_MS,
+                        maxTimeout: LOCK_RETRY_MAX_WAIT_MS,
+                    },
+                });
+            }
+            catch {
+                // Lock is genuinely unavailable. Same graceful-degrade as above.
+                return fn();
+            }
+            try {
+                return await fn();
+            }
+            finally {
+                try {
+                    await release();
+                }
+                catch {
+                    // If release fails (e.g. the lockfile was reclaimed as stale
+                    // while we held it), there's nothing useful to do — the next
+                    // acquirer will handle it.
+                }
+            }
+        },
+    };
+}

package/dist/src/login/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Zapier SDK CLI Login Package
+ *
+ * Handles login, logout, token cache and refresh for Zapier SDK CLI.
+ * Provides getToken function that can be optionally imported by zapier-sdk.
+ */
+import Conf from "conf";
+export { createCache } from "./filesystem-cache";
+/**
+ * Authentication error for token refresh failures.
+ * This is a standalone clone of ZapierAuthenticationError from the SDK.
+ * We can't import from SDK because cli-login must remain a standalone package
+ * with no SDK dependencies. The SDK recognizes this error by name.
+ */
+export declare class ZapierAuthenticationError extends Error {
+    constructor(message: string);
+}
+export interface PkceCredentials {
+    type: "pkce";
+    clientId: string;
+    baseUrl?: string;
+    scope?: string;
+}
+export interface AuthOptions {
+    onEvent?: (event: {
+        type: string;
+        payload: Record<string, unknown>;
+        timestamp: number;
+    }) => void;
+    fetch?: typeof globalThis.fetch;
+    /** Credentials object from SDK. Contains clientId and resolved auth baseUrl. */
+    credentials?: PkceCredentials;
+    /** Enable debug logging for fetch requests and config operations. */
+    debug?: boolean;
+}
+export interface LoginData {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+}
+export declare const AUTH_MODE_HEADER = "X-Auth";
+/**
+ * Gets the OAuth token endpoint URL.
+ * baseUrl should be the auth base URL (e.g., https://zapier.com), already resolved by SDK.
+ */
+export declare function getAuthTokenUrl(options?: {
+    baseUrl?: string;
+}): string;
+/**
+ * Gets the OAuth authorization endpoint URL.
+ * baseUrl should be the auth base URL (e.g., https://zapier.com), already resolved by SDK.
+ */
+export declare function getAuthAuthorizeUrl(options?: {
+    baseUrl?: string;
+}): string;
+/**
+ * Configuration needed for PKCE login flow.
+ */
+export interface PkceLoginConfig {
+    clientId: string;
+    tokenUrl: string;
+    authorizeUrl: string;
+}
+/**
+ * Gets all configuration needed for the PKCE login flow.
+ * Credentials should have baseUrl already resolved by SDK.
+ */
+export declare function getPkceLoginConfig(options?: {
+    credentials?: PkceCredentials;
+}): PkceLoginConfig;
+export type LoginStorageMode = "keychain" | "config";
+export declare function getConfig(): Conf;
+/**
+ * Drops the cached Conf instance so the next getConfig() call re-initializes
+ * from disk (including re-running the pre-existing file detection).
+ */
+export declare function unloadConfig(): void;
+export declare function updateLogin(loginData: LoginData, options?: {
+    storage?: LoginStorageMode;
+    debug?: boolean;
+}): Promise<void>;
+/**
+ * Main function exported for zapier-sdk to optionally use.
+ * Returns the stored token from CLI configuration (with auto-refresh).
+ *
+ * Note: Environment variable handling (ZAPIER_CREDENTIALS, ZAPIER_TOKEN)
+ * is done by the SDK before calling this function.
+ *
+ * Returns undefined if no valid token is found.
+ */
+export declare function getToken(options?: AuthOptions): Promise<string | undefined>;
+/**
+ * Gets the logged-in user information from JWT token.
+ * Automatically refreshes token if expired.
+ */
+export declare function getLoggedInUser(options?: AuthOptions): Promise<{
+    accountId: number;
+    customUserId: number;
+    email: string;
+}>;
+/**
+ * Checks config to determine current cache mode without reading keychain.
+ * Credential keys in config are ground truth — if login_jwt exists, we're in
+ * config mode regardless of the marker. The marker only matters when no
+ * credential keys are present (e.g. after logout or when using keychain).
+ */
+export declare function getLoginStorageMode(): LoginStorageMode;
+/**
+ * Clears stored login information.
+ */
+export declare function logout(options?: Pick<AuthOptions, "onEvent">): Promise<void>;
+/**
+ * Gets the path to the configuration file.
+ */
+export declare function getConfigPath(): string;