@pachca/cli 2026.8.0 → 2026.8.1

package/dist/secret-store.js

@@ -0,0 +1,129 @@
+import { createRequire } from 'node:module';
+/**
+ * Secrets in the OS credential store: Keychain on macOS, Secret Service on
+ * Linux, Credential Manager on Windows.
+ *
+ * Why bother when the config file is already `chmod 600`: those permissions stop
+ * *other users* of the machine, not code running as you — and code running as
+ * you is the normal case now (postinstall scripts, editor extensions, agents).
+ * The npm worm of 2025 swept developer machines with TruffleHog looking for
+ * exactly this kind of file. The OS store is not a silver bullet either, but it
+ * takes the secret out of a plain file that anything can read by walking $HOME.
+ *
+ * The native module is optional on purpose. Headless Linux, containers and
+ * minimal images often have no Secret Service at all, and a CLI that refuses to
+ * log in there would be worse than one that stores a file. Every entry point
+ * below degrades to `null`/`false` instead of throwing, and the caller falls
+ * back to the config file and says so.
+ */
+const SERVICE = 'pachca-cli';
+// `undefined` = not attempted yet, `null` = attempted and unavailable.
+let keyringModule;
+/**
+ * Opt out of the OS store entirely. `--insecure-storage` covers the login, but
+ * an environment variable is what agents, containers and CI can actually set —
+ * and on a headless box every keyring call is a failed round trip.
+ */
+function disabledByEnv() {
+    return process.env.PACHCA_SECRET_STORE === 'file';
+}
+function loadKeyring() {
+    if (disabledByEnv())
+        return null;
+    if (keyringModule !== undefined)
+        return keyringModule;
+    // The package is CJS and optional; a static import would make the whole CLI
+    // fail to load on a platform without a prebuilt binary.
+    try {
+        const require = createRequire(import.meta.url);
+        keyringModule = require('@napi-rs/keyring');
+    }
+    catch {
+        keyringModule = null;
+    }
+    return keyringModule;
+}
+/**
+ * Install a stand-in for the native module.
+ *
+ * Tests need this: the module is pulled in with `createRequire`, which module
+ * mocking cannot intercept, so without a seam a test run would read and write
+ * the developer's real Keychain.
+ */
+export function setKeyringForTests(stub) {
+    keyringModule = stub;
+}
+function entryFor(profileName) {
+    const keyring = loadKeyring();
+    if (!keyring)
+        return null;
+    try {
+        return new keyring.Entry(SERVICE, profileName);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether secrets can actually be stored — checked by writing and removing a
+ * probe entry, not by loading the module.
+ *
+ * Loading proves nothing: on Linux the binary loads fine and every call then
+ * fails because no Secret Service is running. Finding that out at login time is
+ * the point — a profile marked `keyring` that cannot be read back would lock the
+ * user out of their own session.
+ */
+export function isSecretStoreAvailable() {
+    const entry = entryFor('__pachca_probe__');
+    if (!entry)
+        return false;
+    try {
+        entry.setPassword('probe');
+        const readBack = entry.getPassword();
+        entry.deleteCredential();
+        return readBack === 'probe';
+    }
+    catch {
+        return false;
+    }
+}
+export function readSecret(profileName) {
+    const entry = entryFor(profileName);
+    if (!entry)
+        return null;
+    try {
+        const raw = entry.getPassword();
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        return typeof parsed?.token === 'string' ? parsed : null;
+    }
+    catch {
+        // Missing entry, locked keyring, or something else wrote a value we cannot
+        // parse. All three mean "no usable secret here".
+        return null;
+    }
+}
+export function writeSecret(profileName, secret) {
+    const entry = entryFor(profileName);
+    if (!entry)
+        return false;
+    try {
+        entry.setPassword(JSON.stringify(secret));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function deleteSecret(profileName) {
+    const entry = entryFor(profileName);
+    if (!entry)
+        return;
+    try {
+        entry.deleteCredential();
+    }
+    catch {
+        // Nothing stored, or the store is gone. Either way there is nothing to undo.
+    }
+}

package/dist/token-refresh.js

@@ -0,0 +1,136 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getConfigDirPath, getProfile, isExpiring, isRefreshable, updateProfileTokens, expiresAtFromNow, } from './profiles.js';
+import { OAuthError, refreshAccessToken } from './oauth.js';
+const LOCK_FILENAME = 'refresh.lock';
+/** A lock older than this belonged to a process that died mid-refresh. */
+const LOCK_STALE_MS = 30_000;
+/** How long a waiting process gives the lock holder before refreshing itself. */
+const LOCK_WAIT_MS = 20_000;
+const LOCK_POLL_MS = 150;
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function lockPath() {
+    return path.join(getConfigDirPath(), LOCK_FILENAME);
+}
+function acquireLock() {
+    const file = lockPath();
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        return fs.openSync(file, 'wx');
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        // Someone holds it — unless they died and left the file behind.
+        try {
+            const age = Date.now() - fs.statSync(file).mtimeMs;
+            if (age > LOCK_STALE_MS) {
+                fs.unlinkSync(file);
+                return fs.openSync(file, 'wx');
+            }
+        }
+        catch {
+            // lost the race to another process; fall through to waiting
+        }
+        return null;
+    }
+}
+function releaseLock(fd) {
+    try {
+        fs.closeSync(fd);
+    }
+    catch {
+        // already closed
+    }
+    try {
+        fs.unlinkSync(lockPath());
+    }
+    catch {
+        // already removed
+    }
+}
+/**
+ * Refresh the profile's access token when it is about to expire.
+ *
+ * OAuth tokens live an hour, so a long agent session would otherwise lose access
+ * mid-run. Agents also run several CLI processes at once: without the lock they
+ * would all refresh with the same refresh token and invalidate each other, and
+ * the user would be logged out. One process refreshes, the rest wait and pick up
+ * the result from the config file.
+ *
+ * Returns the profile to use. Throws `OAuthError` only when the session is truly
+ * dead and the user has to log in again.
+ */
+export async function ensureFreshToken(profileName, profile) {
+    if (!isRefreshable(profile) || !isExpiring(profile))
+        return profile;
+    const fd = acquireLock();
+    if (fd === null) {
+        const waited = await waitForOtherProcess(profileName);
+        if (waited)
+            return waited;
+        // The holder gave up or is stuck — refresh ourselves rather than fail.
+        return refreshAndStore(profileName, profile);
+    }
+    try {
+        // Re-read: the previous holder may have refreshed while we queued for the lock.
+        const current = getProfile(profileName) ?? profile;
+        if (!isExpiring(current))
+            return current;
+        return await refreshAndStore(profileName, current);
+    }
+    finally {
+        releaseLock(fd);
+    }
+}
+async function waitForOtherProcess(profileName) {
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    while (Date.now() < deadline) {
+        await sleep(LOCK_POLL_MS);
+        const current = getProfile(profileName);
+        if (current && !isExpiring(current))
+            return current;
+        if (!fs.existsSync(lockPath())) {
+            // The holder finished between our read of the profile and this check. Look
+            // once more before refreshing ourselves: their new token is already on disk,
+            // and ours has just been spent.
+            const after = getProfile(profileName);
+            return after && !isExpiring(after) ? after : undefined;
+        }
+    }
+    return undefined;
+}
+async function refreshAndStore(profileName, profile) {
+    let grant;
+    try {
+        grant = await refreshAccessToken(profile.refresh_token);
+    }
+    catch (error) {
+        // A refresh token is single-use — the server revokes it the moment someone
+        // redeems it. So `invalid_grant` usually means a parallel process got there
+        // first, not that the session died: the config already holds a working token.
+        // Without this check a lost race logs the user out for no reason.
+        if (error instanceof OAuthError && error.code === 'invalid_grant') {
+            const current = getProfile(profileName);
+            if (current?.token && !isExpiring(current))
+                return current;
+        }
+        throw error;
+    }
+    const updated = updateProfileTokens(profileName, {
+        token: grant.access_token,
+        refresh_token: grant.refresh_token,
+        expires_at: grant.expires_in ? expiresAtFromNow(grant.expires_in) : undefined,
+        scopes: grant.scope ? grant.scope.split(' ').filter(Boolean) : undefined,
+    });
+    return updated ?? { ...profile, token: grant.access_token };
+}
+/** True when the failure means the session is gone for good, not a hiccup. */
+export function isSessionExpired(error) {
+    return (error instanceof OAuthError &&
+        ['invalid_grant', 'invalid_request', 'invalid_client', 'unauthorized_client'].includes(error.code));
+}