sidekick-shared 0.27.5 → 0.28.0

package/dist/esm/claudeCredentials.js

@@ -0,0 +1,111 @@
+/**
+ * Pure helpers over the Claude Code credential blob (`claudeAiOauth`). No I/O.
+ */
+import { createHash } from 'crypto';
+/** Lifetime of a Claude Code access token. */
+export const CLAUDE_ACCESS_TOKEN_LIFETIME_MS = 8 * 60 * 60 * 1000;
+/**
+ * Refresh-token lifetime observed on Claude Code 2.1.x. Used only to estimate
+ * the refresh expiry of snapshots captured before the CLI recorded it.
+ */
+export const CLAUDE_REFRESH_TOKEN_LIFETIME_ESTIMATE_MS = 21 * 24 * 60 * 60 * 1000;
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/** Parse the stored blob, tolerating the `mcpOAuth` sibling and unknown keys. */
+export function parseClaudeCredentialBlob(blob) {
+    if (!blob || typeof blob !== 'object')
+        return null;
+    const oauth = blob.claudeAiOauth;
+    if (!oauth || typeof oauth !== 'object')
+        return null;
+    const record = oauth;
+    if (typeof record.accessToken !== 'string' || !record.accessToken)
+        return null;
+    return {
+        accessToken: record.accessToken,
+        refreshToken: typeof record.refreshToken === 'string' ? record.refreshToken : undefined,
+        expiresAt: finiteNumber(record.expiresAt),
+        refreshTokenExpiresAt: finiteNumber(record.refreshTokenExpiresAt),
+        scopes: Array.isArray(record.scopes)
+            ? record.scopes.filter((scope) => typeof scope === 'string')
+            : undefined,
+        subscriptionType: typeof record.subscriptionType === 'string' ? record.subscriptionType : undefined,
+        rateLimitTier: typeof record.rateLimitTier === 'string' ? record.rateLimitTier : undefined,
+    };
+}
+/**
+ * Monotonic freshness clock: every refresh issues a new access token with a
+ * later `expiresAt`, so the larger value is the newer credential.
+ */
+export function claudeCredentialFreshness(credentials) {
+    if (!credentials)
+        return 0;
+    return credentials.expiresAt ?? credentials.refreshTokenExpiresAt ?? 0;
+}
+/** True when `candidate` is strictly newer than `existing`. */
+export function isNewerClaudeCredential(candidate, existing) {
+    return claudeCredentialFreshness(candidate) > claudeCredentialFreshness(existing);
+}
+/**
+ * When the refresh-token expiry was recorded, use it; otherwise estimate it
+ * from the access-token issue time. Returns `estimated: true` for the latter.
+ */
+export function resolveClaudeRefreshExpiry(credentials) {
+    if (!credentials)
+        return null;
+    if (credentials.refreshTokenExpiresAt !== undefined) {
+        return { refreshExpiresAt: credentials.refreshTokenExpiresAt, estimated: false };
+    }
+    if (credentials.expiresAt !== undefined) {
+        const issuedAt = credentials.expiresAt - CLAUDE_ACCESS_TOKEN_LIFETIME_MS;
+        return {
+            refreshExpiresAt: issuedAt + CLAUDE_REFRESH_TOKEN_LIFETIME_ESTIMATE_MS,
+            estimated: true,
+        };
+    }
+    return null;
+}
+/**
+ * Short, non-reversible fingerprint of the refresh token. Claude Code rotates
+ * the refresh token on every refresh, so equal fingerprints mean two stores
+ * hold the same link of one chain. Safe to persist and log; tokens never are.
+ */
+export function claudeRefreshFingerprint(credentials) {
+    const token = credentials?.refreshToken;
+    return token ? createHash('sha256').update(token).digest('hex').slice(0, 16) : null;
+}
+function recordOrUndefined(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * The part of a blob a profile home keeps: the Claude login only. MCP OAuth
+ * tokens (`mcpOAuth`) rotate too and follow the live store, so a profile copy
+ * never duplicates one of their chains (and stays far below the Keychain
+ * line limit).
+ */
+export function claudeLoginOnly(blob) {
+    const oauth = recordOrUndefined(recordOrUndefined(blob)?.claudeAiOauth);
+    return oauth ? { claudeAiOauth: oauth } : null;
+}
+/**
+ * The blob to install into the live store when `candidate`'s login replaces
+ * the live one: everything live holds (its MCP tokens are the freshest links
+ * of their chains) with the candidate's `claudeAiOauth`, plus any MCP server
+ * only the candidate knows. Mirrors what Claude Code's own `/login` keeps.
+ */
+export function mergeClaudeLoginIntoLive(live, candidate) {
+    const liveRecord = recordOrUndefined(live) ?? {};
+    const candidateRecord = recordOrUndefined(candidate) ?? {};
+    const merged = {
+        ...liveRecord,
+        claudeAiOauth: candidateRecord.claudeAiOauth,
+    };
+    const liveMcp = recordOrUndefined(liveRecord.mcpOAuth);
+    const candidateMcp = recordOrUndefined(candidateRecord.mcpOAuth);
+    if (liveMcp || candidateMcp)
+        merged.mcpOAuth = { ...candidateMcp, ...liveMcp };
+    return merged;
+}

package/dist/esm/claudeLiveGuard.js

@@ -0,0 +1,43 @@
+/**
+ * The decision every write into the live Claude credential store must pass.
+ * Pure: callers read the stores, this decides.
+ *
+ * Claude Code rotates the refresh token on every refresh, so the live store
+ * always holds the newest link of its chain. Writing an older link over it
+ * destroys a working login, and installing another account without saving the
+ * live one first loses that account's chain. The rules:
+ *
+ * - `switch`: another account replaces live. Allowed only after the outgoing
+ *   live credential was captured (whenever live holds one), and never with a
+ *   candidate that is the same refresh-token link as live.
+ * - `relogin` / `repair`: the same account's credential replaces live. Allowed
+ *   only when the candidate is strictly fresher (a different refresh token
+ *   with a later expiry); otherwise live is kept.
+ * - `rollback`: restore what a failed switch displaced. Allowed only while the
+ *   live store still holds exactly what that switch wrote (or is empty or
+ *   unparseable); a write Claude Code made in between is never clobbered.
+ * - An unreadable live store (`error`: timeout, locked Keychain) refuses all.
+ */
+import { decideLiveCredentialWrite } from './liveCredentialGuard';
+import { claudeCredentialFreshness, claudeRefreshFingerprint, parseClaudeCredentialBlob, } from './claudeCredentials';
+export function decideLiveClaudeWrite(request) {
+    const candidate = parseClaudeCredentialBlob(request.candidate);
+    const live = request.live.status === 'ok' ? parseClaudeCredentialBlob(request.live.blob) : null;
+    const liveFp = claudeRefreshFingerprint(live);
+    return decideLiveCredentialWrite({
+        provider: 'Claude',
+        intent: request.intent,
+        liveStatus: request.live.status,
+        candidateValid: candidate !== null,
+        liveHasCredential: live !== null,
+        liveAccountId: request.liveAccountUuid,
+        candidateAccountId: request.candidateAccountUuid,
+        sameLink: liveFp !== null && liveFp === claudeRefreshFingerprint(candidate),
+        strictlyNewer: claudeCredentialFreshness(candidate) > claudeCredentialFreshness(live),
+        capturedOutgoing: request.capturedOutgoing,
+        matchesWritten: request.live.status === 'ok' &&
+            JSON.stringify(request.live.blob) === JSON.stringify(request.written),
+        allowNonOkRollback: true,
+        requireDifferentLinkForAdvance: true,
+    });
+}

package/dist/esm/claudePaths.js

@@ -0,0 +1,22 @@
+import * as os from 'os';
+import * as path from 'path';
+export function getDefaultClaudeHome() {
+    return path.join(os.homedir(), '.claude');
+}
+/** True when this process runs against the default `~/.claude` home. */
+export function isDefaultClaudeHome() {
+    return !process.env.CLAUDE_CONFIG_DIR?.trim();
+}
+/**
+ * The home the `claude` CLI reads and writes for this process: `CLAUDE_CONFIG_DIR`
+ * when set, else `~/.claude`. Every "live" credential or identity read goes
+ * through this so sidekick follows the same home the CLI does.
+ */
+export function getLiveClaudeHome() {
+    const explicit = process.env.CLAUDE_CONFIG_DIR?.trim();
+    return explicit ? explicit : getDefaultClaudeHome();
+}
+/** Where the `claude` CLI writes session transcripts for this process. */
+export function getClaudeProjectsDir() {
+    return path.join(getLiveClaudeHome(), 'projects');
+}

package/dist/esm/claudeProfiles.js

@@ -0,0 +1,142 @@
+import { execFileSync } from 'child_process';
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { getAccountsDir } from './accountRegistry';
+import { getDefaultClaudeHome, getLiveClaudeHome, isDefaultClaudeHome } from './claudePaths';
+export { getDefaultClaudeHome, getLiveClaudeHome, isDefaultClaudeHome };
+const DEFAULT_CLAUDE_KEYCHAIN_SERVICE = 'Claude Code-credentials';
+const KEYCHAIN_ACCOUNT_PATTERN = /^[a-zA-Z0-9._-]+$/;
+const KEYCHAIN_FALLBACK_ACCOUNT = 'claude-code-user';
+/**
+ * Claude Code honours this variable ahead of `CLAUDE_CONFIG_DIR` when it
+ * derives the keychain item name. Any `claude` child sidekick spawns must not
+ * inherit it, or the login would land in an item nobody else reads.
+ */
+export const CLAUDE_SECURESTORAGE_CONFIG_DIR_ENV = 'CLAUDE_SECURESTORAGE_CONFIG_DIR';
+export function getClaudeProfilesDir() {
+    return path.join(getAccountsDir(), 'claude', 'profiles');
+}
+/**
+ * True when the live home is one of sidekick's own profile homes: a shell
+ * that eval'd `sidekick accounts env` or runs inside `sidekick accounts shell`.
+ * That profile's store then reads as the live store, so sync, re-login, and
+ * switching must not treat it as live: they would delete the shell's only
+ * usable copy and re-point the active account at it.
+ */
+export function isLiveClaudeHomeSidekickProfile() {
+    const liveHome = path.resolve(getLiveClaudeHome());
+    const profilesDir = path.resolve(getClaudeProfilesDir());
+    return liveHome === profilesDir || liveHome.startsWith(profilesDir + path.sep);
+}
+export function getClaudeProfileDir(uuid) {
+    return path.join(getClaudeProfilesDir(), uuid);
+}
+export function getClaudeProfileHome(uuid) {
+    return path.join(getClaudeProfileDir(uuid), 'home');
+}
+/**
+ * Sidekick's private backup of a profile's credential. Claude Code never reads
+ * it, so it is not a CLI-usable copy: this is where the live account's
+ * credential is mirrored while its profile home stays empty.
+ */
+export function getClaudeCredentialBackupPath(uuid) {
+    return path.join(getAccountsDir(), 'credentials', `${uuid}.credentials.json`);
+}
+export function ensureClaudeProfileDirs(uuid) {
+    fs.mkdirSync(getClaudeProfileHome(uuid), { recursive: true, mode: 0o700 });
+}
+/**
+ * Claude Code hashes the NFC-normalised config directory; macOS hands paths
+ * back decomposed (NFD), so a home directory with a non-ASCII name would
+ * otherwise hash differently from the item the CLI wrote.
+ */
+export function claudeKeychainSuffix(configDir) {
+    return createHash('sha256').update(configDir.normalize('NFC')).digest('hex').slice(0, 8);
+}
+/**
+ * Keychain service name for a config directory. Claude Code drops the suffix
+ * when `CLAUDE_CONFIG_DIR` is unset — not when the path merely equals
+ * `~/.claude` — so the no-argument form follows the process environment.
+ */
+export function claudeKeychainService(configDir) {
+    const dir = configDir ?? (isDefaultClaudeHome() ? undefined : getLiveClaudeHome());
+    return dir
+        ? `${DEFAULT_CLAUDE_KEYCHAIN_SERVICE}-${claudeKeychainSuffix(dir)}`
+        : DEFAULT_CLAUDE_KEYCHAIN_SERVICE;
+}
+/** The keychain account name Claude Code uses: the unix username, sanitised. */
+export function claudeKeychainAccountName() {
+    let name;
+    try {
+        name = process.env.USER || os.userInfo().username;
+    }
+    catch {
+        name = undefined;
+    }
+    return name && KEYCHAIN_ACCOUNT_PATTERN.test(name) ? name : KEYCHAIN_FALLBACK_ACCOUNT;
+}
+/** Environment for spawning `claude` against a specific home. */
+export function buildClaudeChildEnv(home, baseEnv = process.env) {
+    const env = { ...baseEnv, CLAUDE_CONFIG_DIR: home };
+    delete env[CLAUDE_SECURESTORAGE_CONFIG_DIR_ENV];
+    return env;
+}
+function readOauthAccount(configPath) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        return raw?.oauthAccount && typeof raw.oauthAccount === 'object' ? raw.oauthAccount : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Where the identity (`oauthAccount`) of a Claude home lives. Recent Claude
+ * Code versions keep it in `<home>/.claude.json`; older ones (and the default
+ * home on this machine's history) use `~/.claude.json`. Prefer the in-home file
+ * when it carries an identity, otherwise fall back to the legacy location for
+ * the default home only.
+ */
+export function getClaudeConfigPath(home = getLiveClaudeHome()) {
+    const primary = path.join(home, '.claude.json');
+    if (readOauthAccount(primary))
+        return primary;
+    if (path.resolve(home) === path.resolve(getDefaultClaudeHome())) {
+        return path.join(os.homedir(), '.claude.json');
+    }
+    return primary;
+}
+function identityFromOauthAccount(oauthAccount) {
+    const email = oauthAccount?.emailAddress;
+    const uuid = oauthAccount?.accountUuid;
+    return typeof email === 'string' && typeof uuid === 'string' ? { email, uuid } : null;
+}
+/** Identity of the account currently logged in to a Claude home (default: the live home). */
+export function readLiveClaudeIdentity(home = getLiveClaudeHome()) {
+    return identityFromOauthAccount(readOauthAccount(getClaudeConfigPath(home)));
+}
+export function readClaudeProfileIdentity(home) {
+    return identityFromOauthAccount(readOauthAccount(path.join(home, '.claude.json')));
+}
+export function keychainServiceExists(service) {
+    try {
+        execFileSync('security', ['find-generic-password', '-s', service], {
+            stdio: ['ignore', 'ignore', 'ignore'],
+            timeout: 4000,
+            killSignal: 'SIGKILL',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isClaudeProfileAuthenticated(home) {
+    const hasCredentials = process.platform === 'darwin'
+        ? keychainServiceExists(claudeKeychainService(home)) ||
+            fs.existsSync(path.join(home, '.credentials.json'))
+        : fs.existsSync(path.join(home, '.credentials.json'));
+    return hasCredentials && readClaudeProfileIdentity(home) !== null;
+}

package/dist/esm/claudeRefreshLock.js

@@ -0,0 +1,106 @@
+/**
+ * Borrow Claude Code's own token-refresh lock while Sidekick reads and
+ * replaces a home's credential.
+ *
+ * Claude Code 2.1.x serialises refreshes per config directory with a
+ * proper-lockfile directory lock at `<configDir>/.oauth_refresh.lock` (stale
+ * after 60 s) plus a legacy `<realpath(configDir)>.lock`. Under that lock it
+ * re-reads the store before refreshing and adopts a token someone else wrote,
+ * so holding both locks keeps a refresh (which rotates the refresh token) out
+ * of the window between Sidekick's read and its write.
+ *
+ * Best effort by construction: this layers on Claude Code internals. If they
+ * change we lose only the exclusion; the callers' fingerprint re-checks still
+ * catch a store that moved. Held briefly (a few `security` calls), well under
+ * the 60 s stale window, and released on every exit.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/** Claude Code treats a lock older than this as abandoned (proper-lockfile `stale`). */
+export const CLAUDE_REFRESH_LOCK_STALE_MS = 60_000;
+const DEFAULT_WAIT_MS = 5_000;
+const POLL_MS = 50;
+const sleepView = new Int32Array(new SharedArrayBuffer(4));
+/** Claude Code is refreshing a login in one of the homes; retry shortly. */
+export class ClaudeRefreshLockBusyError extends Error {
+    constructor(lockPath) {
+        super(`Claude Code is refreshing a login (${lockPath} is held); try again in a few seconds.`);
+        this.name = 'ClaudeRefreshLockBusyError';
+    }
+}
+export function claudeRefreshLockPaths(home) {
+    let real = path.resolve(home);
+    try {
+        real = fs.realpathSync(home);
+    }
+    catch {
+        /* keep the resolved path */
+    }
+    return [path.join(home, '.oauth_refresh.lock'), `${real}.lock`];
+}
+function tryAcquire(lockPath, now) {
+    try {
+        fs.mkdirSync(lockPath);
+        return true;
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    try {
+        const stat = fs.statSync(lockPath);
+        if (now - stat.mtimeMs > CLAUDE_REFRESH_LOCK_STALE_MS) {
+            // proper-lockfile's own recovery: an abandoned lock is removed and retaken.
+            fs.rmSync(lockPath, { recursive: true, force: true });
+            fs.mkdirSync(lockPath);
+            return true;
+        }
+    }
+    catch {
+        /* released or retaken between checks; poll again */
+    }
+    return false;
+}
+/**
+ * Run `operation` holding the refresh locks of every existing home (a home
+ * that does not exist has no CLI using it). Throws
+ * {@link ClaudeRefreshLockBusyError} when a lock stays held past `waitMs`.
+ */
+export function withClaudeRefreshLocksSync(homes, operation, options = {}) {
+    const waitMs = options.waitMs ?? DEFAULT_WAIT_MS;
+    const lockPaths = [
+        ...new Set(homes
+            .filter((home) => {
+            try {
+                return fs.statSync(home).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        })
+            .flatMap(claudeRefreshLockPaths)),
+    ];
+    const held = [];
+    try {
+        const deadline = Date.now() + waitMs;
+        for (const lockPath of lockPaths) {
+            while (!tryAcquire(lockPath, Date.now())) {
+                if (Date.now() >= deadline)
+                    throw new ClaudeRefreshLockBusyError(lockPath);
+                Atomics.wait(sleepView, 0, 0, POLL_MS);
+            }
+            held.push(lockPath);
+        }
+        return operation();
+    }
+    finally {
+        for (const lockPath of held.reverse()) {
+            try {
+                fs.rmSync(lockPath, { recursive: true, force: true });
+            }
+            catch {
+                /* Claude Code recovers a stale lock after 60 s */
+            }
+        }
+    }
+}

package/dist/esm/codexAuth.js

@@ -0,0 +1,101 @@
+/**
+ * Pure helpers over the Codex CLI `auth.json` payload. No filesystem access
+ * beyond an optional mtime fallback, no child processes.
+ */
+import * as fs from 'fs';
+import { createHash } from 'crypto';
+// Codex refreshes OAuth tokens at most every 8 days; a stored refresh token
+// older than that may already be rejected by the auth server.
+export const STALE_AUTH_THRESHOLD_MS = 8 * 24 * 60 * 60 * 1000;
+export function parseJwtPayload(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length < 2)
+        return null;
+    try {
+        const payload = Buffer.from(parts[1], 'base64url').toString('utf8');
+        return JSON.parse(payload);
+    }
+    catch {
+        return null;
+    }
+}
+export function parseAuthJson(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readAuthIdentityFromRaw(raw) {
+    const parsed = parseAuthJson(raw);
+    if (!parsed)
+        return null;
+    const idToken = parsed.tokens?.id_token;
+    const claims = idToken ? parseJwtPayload(idToken) : null;
+    const profileClaims = claims?.['https://api.openai.com/profile'];
+    const authClaims = claims?.['https://api.openai.com/auth'];
+    const email = typeof claims?.email === 'string'
+        ? claims.email
+        : typeof profileClaims?.email === 'string'
+            ? profileClaims.email
+            : undefined;
+    const workspaceId = typeof authClaims?.chatgpt_account_id === 'string'
+        ? authClaims.chatgpt_account_id
+        : parsed.tokens?.account_id;
+    const planType = typeof authClaims?.chatgpt_plan_type === 'string' ? authClaims.chatgpt_plan_type : undefined;
+    const authMode = parsed.OPENAI_API_KEY || parsed.auth_mode === 'api_key' ? 'api-key' : 'chatgpt';
+    return { email, workspaceId, planType, authMode };
+}
+export function readLastRefresh(raw, fallbackPath) {
+    const parsed = parseAuthJson(raw);
+    if (parsed?.last_refresh) {
+        const ts = Date.parse(parsed.last_refresh);
+        if (!Number.isNaN(ts))
+            return ts;
+    }
+    if (fallbackPath) {
+        try {
+            return fs.statSync(fallbackPath).mtimeMs;
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return null;
+}
+/** Expiry (ms since epoch) of the access token JWT, when it carries `exp`. */
+export function readAccessTokenExpiry(raw) {
+    const parsed = parseAuthJson(raw);
+    const accessToken = parsed?.tokens?.access_token;
+    if (!accessToken)
+        return null;
+    const claims = parseJwtPayload(accessToken);
+    return typeof claims?.exp === 'number' && Number.isFinite(claims.exp) ? claims.exp * 1000 : null;
+}
+/** Workspace id first (a ChatGPT workspace is one seat), then email. */
+export function identitiesMatch(a, b) {
+    if (!a || !b)
+        return false;
+    if (a.workspaceId && b.workspaceId)
+        return a.workspaceId === b.workspaceId;
+    return Boolean(a.email && b.email && a.email === b.email);
+}
+/** Non-secret chain-link identifier; raw token values never belong in diagnostics. */
+export function codexRefreshFingerprint(raw) {
+    const token = parseAuthJson(raw)?.tokens?.refresh_token;
+    return typeof token === 'string' && token
+        ? createHash('sha256').update(token).digest('hex').slice(0, 16)
+        : null;
+}
+/** Compare evidence, never filesystem timestamps. Incomparable credentials tie. */
+export function compareCodexAuthFreshness(a, b) {
+    const ar = readLastRefresh(a), br = readLastRefresh(b);
+    if (ar !== null && br !== null && ar !== br)
+        return ar > br ? 1 : -1;
+    const ae = readAccessTokenExpiry(a), be = readAccessTokenExpiry(b);
+    return ae !== null && be !== null && ae !== be ? (ae > be ? 1 : -1) : 0;
+}