@skrr-ai/cli 0.1.51 → 0.1.53

package/dist/lib/auth-storage.js

@@ -37,6 +37,7 @@ exports.backends = void 0;
 exports.readFromFile = readFromFile;
 exports.deleteFileBackend = deleteFileBackend;
 exports.readFromBackend = readFromBackend;
+exports.describeForeignCredential = describeForeignCredential;
 exports.writeToBackend = writeToBackend;
 exports.clearAllBackends = clearAllBackends;
 exports.normalizeServerOrigin = normalizeServerOrigin;
@@ -71,6 +72,21 @@ exports.__authFilePathForTest = __authFilePathForTest;
  * interactive) and delegates the keychain/file slots to `readFromBackend()`
  * here. We own token persistence; the resolver owns precedence.
  *
+ * Every bundle is also bound to the CONFIG that owns it (OSK-12135). The
+ * login Keychain is shared by every skrr setup of this macOS user, while the
+ * CLI identity (`cliId`) lives in the config root, so another setup with the
+ * same profile name could write this profile's slot and the next refresh
+ * presented a token bound to its `cliId`. Now:
+ *
+ *   - a bundle carries its owner `{configRoot, cliId}` (Keychain `cli-owner`
+ *     slot, or `owner` in the file), and the server-bound identity is also read
+ *     from the access token's `did` claim, which an older writer cannot omit;
+ *   - a read REFUSES a bundle whose owner is another root or another cliId,
+ *     with the owner named (`ownerStatus: 'foreign'`), and never deletes it;
+ *   - storage is namespaced by config root (see `keychain.ts`; the file lives
+ *     under the config root), and a slot another root may own is only ever a
+ *     read-side migration source, adopted on POSITIVE evidence of ownership.
+ *
  * Cross-process coordination: every write path should run inside
  * `withAuthLock()` from @skrr-ai/auth-core so the daemon, Electron main,
  * and a sibling `skrr` can't race us on a rotation. Callers are responsible
@@ -84,17 +100,127 @@ const auth_core_1 = require("@skrr-ai/auth-core");
 const keychain = __importStar(require("./keychain"));
 const cred_envelope_1 = require("./cred-envelope");
 const config_1 = require("./config");
+const cli_id_1 = require("./cli-id");
 /** Filename for the non-darwin file backend. Parallel to the daemon's
  *  `auth.json`, deliberately distinct so the two binaries never clobber
  *  each other's tokens (CLI holds scope=cli, daemon holds scope=daemon). */
 const AUTH_FILENAME = 'cli-auth.json';
-/** Config root shared with the daemon (so auth.lock coordinates). */
+/**
+ * The config root — the same one `cli-config.json` (and so `cliId`) lives in.
+ *
+ * This was `$HOME/.skrr` regardless of `SKRR_CONFIG_DIR`, so two configs that
+ * shared a HOME shared one credential file while each held its own `cliId`.
+ * Unchanged for anyone who has not relocated the root.
+ */
 function authDir() {
-    return path.join(os.homedir(), '.skrr');
+    return (0, config_1.configRoot)();
 }
 function authFilePath() {
     return path.join(authDir(), AUTH_FILENAME);
 }
+/**
+ * Where the file lived before it followed the config root. Only differs from
+ * `authFilePath()` under a root override, and is then a migration SOURCE: read
+ * only when its bundle positively belongs to this config, never written.
+ */
+function legacyAuthFilePath() {
+    return path.join(os.homedir(), '.skrr', AUTH_FILENAME);
+}
+// ---------------------------------------------------------------------
+// Ownership
+// ---------------------------------------------------------------------
+/** Who this process is: its resolved config root and the cliId it presents. */
+function currentOwner() {
+    let cliId;
+    try {
+        // The id this profile PRESENTS — its own when it was issued one (OSK-12156).
+        const value = (0, cli_id_1.resolveCliId)((0, config_1.loadConfig)());
+        if (value)
+            cliId = value;
+    }
+    catch {
+        // A corrupt config cannot tell us who we are; ownership then rests on the
+        // config root alone, which is still enough to refuse another root's bundle.
+    }
+    return { configRoot: path.resolve((0, config_1.configRoot)()), ...(cliId ? { cliId } : {}) };
+}
+/**
+ * The CLI identity the SERVER bound this credential to. CLI access tokens carry
+ * it as `did` (the refresh row's `daemonId`), so this answers for bundles written
+ * by any version — including an older binary that never stored an owner record.
+ *
+ * Unverified decode, which `jwtUtils` permits for routing and not for trust.
+ * This is routing: it picks which LOCAL slot this config may present from. The
+ * server still verifies the token and refuses a rotation against another cliId;
+ * reading the claim first only stops us presenting a credential that cannot be
+ * ours, and anyone able to forge the slot's contents can already write them.
+ */
+function boundCliId(token) {
+    const payload = (0, auth_core_1.decodeJwtPayload)(token);
+    return payload && typeof payload.did === 'string' && payload.did.length > 0
+        ? payload.did
+        : undefined;
+}
+function parseOwner(raw) {
+    let value = raw;
+    if (typeof value === 'string') {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const { configRoot: root, cliId } = value;
+    const owner = {};
+    if (typeof root === 'string' && root.length > 0)
+        owner.configRoot = root;
+    if (typeof cliId === 'string' && cliId.length > 0)
+        owner.cliId = cliId;
+    return owner.configRoot || owner.cliId ? owner : undefined;
+}
+function ownerFor(bundle) {
+    const me = currentOwner();
+    const cliId = boundCliId(bundle.token) ?? me.cliId;
+    return { configRoot: me.configRoot, ...(cliId ? { cliId } : {}) };
+}
+/**
+ * Does this bundle belong to this config?
+ *
+ * `ownSlot` is whether the bundle came from the slot this root owns. There,
+ * the bundle is ours unless there is evidence it is not. From a slot another
+ * root may own (a migration source), it is ours only on POSITIVE evidence —
+ * a matching cliId or root — or, per the legacy rule, when it names nobody and
+ * this is the account's default root.
+ *
+ * The token's `did` outranks the stored owner record: an older binary writes
+ * the token but not `cli-owner`, so a record that disagrees with the token it
+ * sits beside is stale and says nothing about the token.
+ */
+function judgeOwnership(bundle, me, ownSlot) {
+    const did = boundCliId(bundle.token);
+    const record = bundle.owner;
+    const recordValid = record && (!did || !record.cliId || record.cliId === did);
+    const storedRoot = recordValid && record.configRoot ? path.resolve(record.configRoot) : undefined;
+    const storedCliId = did ?? (recordValid ? record.cliId : undefined);
+    const stored = {
+        ...(storedRoot ? { configRoot: storedRoot } : {}),
+        ...(storedCliId ? { cliId: storedCliId } : {}),
+    };
+    if (storedRoot && storedRoot !== me.configRoot)
+        return { ours: false, stored };
+    if (storedCliId && me.cliId && storedCliId !== me.cliId)
+        return { ours: false, stored };
+    if (ownSlot)
+        return { ours: true, stored };
+    const positive = (storedCliId !== undefined && storedCliId === me.cliId) || storedRoot === me.configRoot;
+    if (positive)
+        return { ours: true, stored };
+    const namesNobody = !storedCliId && !storedRoot;
+    return { ours: namesNobody && keychain.isDefaultConfigRoot(me.configRoot), stored };
+}
 // ---------------------------------------------------------------------
 // File backend
 // ---------------------------------------------------------------------
@@ -106,7 +232,40 @@ function authFilePath() {
  * retiring it. Everything else should keep using `readFromBackend()`.
  */
 function readFromFile() {
-    const p = authFilePath();
+    return readFileAssessed().bundle;
+}
+/**
+ * This root's file, refused when it belongs to another config; else, under a
+ * root override, the pre-override `$HOME/.skrr` file when it is positively ours.
+ */
+function readFileAssessed() {
+    const me = currentOwner();
+    const own = readFileAt(authFilePath(), true);
+    if (own) {
+        const judged = judgeOwnership(own, me, true);
+        return judged.ours ? { bundle: own } : { bundle: null, foreign: judged.stored };
+    }
+    const legacy = legacyAuthFilePath();
+    if (path.resolve(legacy) === path.resolve(authFilePath()))
+        return { bundle: null };
+    const adopted = readFileAt(legacy, false);
+    if (adopted && judgeOwnership(adopted, me, false).ours)
+        return { bundle: adopted };
+    return { bundle: null };
+}
+/** Is the pre-override file present AND positively this config's? */
+function legacyFileIsOurs() {
+    const legacy = legacyAuthFilePath();
+    if (path.resolve(legacy) === path.resolve(authFilePath()))
+        return false;
+    const bundle = readFileAt(legacy, false);
+    return Boolean(bundle && judgeOwnership(bundle, currentOwner(), false).ours);
+}
+/**
+ * Parse one credential file. `upgradeInPlace` lets the envelope migration
+ * rewrite it — true only for this root's own file, never a migration source.
+ */
+function readFileAt(p, upgradeInPlace) {
     if (!fs.existsSync(p))
         return null;
     let raw;
@@ -129,7 +288,12 @@ function readFromFile() {
     // L12 — route the secret string fields through the envelope. Mixed
     // bundles (e.g., legacy plaintext token + freshly-rotated wrapped
     // refresh) decrypt independently so partial migrations stay safe.
-    const tokenResult = (0, cred_envelope_1.maybeDecryptOnRead)(parsed.token);
+    // Read the (plaintext) owner first, so a value another config root sealed
+    // under its own key fails with a sentence that says so (OSK-12135).
+    const owner = parseOwner(parsed.owner);
+    const ownerRoot = owner?.configRoot ? path.resolve(owner.configRoot) : undefined;
+    const decryptOptions = ownerRoot && ownerRoot !== path.resolve((0, config_1.configRoot)()) ? { foreignOwnerRoot: ownerRoot } : {};
+    const tokenResult = (0, cred_envelope_1.maybeDecryptOnRead)(parsed.token, decryptOptions);
     if (tokenResult.plaintext === null) {
         // Envelope on disk but no DEK to unwrap → treat as missing so the
         // caller falls through to a clean `skrr login`.
@@ -141,7 +305,7 @@ function readFromFile() {
         bundle.expiresAt = parsed.expiresAt;
     }
     if (typeof parsed.refreshToken === 'string' && parsed.refreshToken.length > 0) {
-        const refreshResult = (0, cred_envelope_1.maybeDecryptOnRead)(parsed.refreshToken);
+        const refreshResult = (0, cred_envelope_1.maybeDecryptOnRead)(parsed.refreshToken, decryptOptions);
         if (refreshResult.plaintext !== null) {
             bundle.refreshToken = refreshResult.plaintext;
             if (refreshResult.needsMigration)
@@ -157,6 +321,8 @@ function readFromFile() {
     if (typeof parsed.serverOrigin === 'string' && parsed.serverOrigin.length > 0) {
         bundle.serverOrigin = parsed.serverOrigin;
     }
+    if (owner)
+        bundle.owner = owner;
     // Best-effort upgrade: re-write the bundle so legacy plaintext fields
     // become wrapped on the next read. A failure here doesn't break the
     // read path — the caller already has the plaintext bundle.
@@ -186,7 +352,7 @@ function readFromFile() {
     //      in-process "lock held" guard (AsyncLocalStorage) — but atomic
     //      rename already prevents corruption, so the escalation target is
     //      IO efficiency only.
-    if (needsMigration) {
+    if (needsMigration && upgradeInPlace) {
         try {
             writeToFile(bundle);
         }
@@ -218,6 +384,9 @@ function writeToFile(bundle) {
     if (bundle.serverOrigin) {
         wireBundle.serverOrigin = bundle.serverOrigin;
     }
+    // Rewrites of an existing bundle (the envelope upgrade) keep its recorded
+    // owner; everything else is stamped with this config.
+    wireBundle.owner = bundle.owner ?? ownerFor(bundle);
     // tmp + rename so no racing reader ever sees a partial file; chmod 0600
     // on the final file so the same-UID blast-radius is as narrow as the
     // file backend can offer.
@@ -251,6 +420,17 @@ function writeToFile(bundle) {
  */
 function deleteFileBackend() {
     const p = authFilePath();
+    // This root's own file — unless it holds another config's credential, which
+    // is not ours to destroy (an older binary of another config can write here).
+    const own = readFileAt(p, false);
+    if (!own || judgeOwnership(own, currentOwner(), true).ours)
+        unlinkQuietly(p);
+    // The pre-override migration source, only when it is positively ours:
+    // otherwise a sign-out would leave it to be adopted again on the next read.
+    if (legacyFileIsOurs())
+        unlinkQuietly(legacyAuthFilePath());
+}
+function unlinkQuietly(p) {
     try {
         if (fs.existsSync(p))
             fs.unlinkSync(p);
@@ -285,11 +465,95 @@ function readFromKeychain() {
     const serverOrigin = keychain.readServerOrigin();
     if (serverOrigin)
         bundle.serverOrigin = serverOrigin;
+    const owner = parseOwner(keychain.readOwner());
+    if (owner)
+        bundle.owner = owner;
+    return bundle;
+}
+function bundleFromSlots(slots) {
+    const bundle = { token: slots.token.token };
+    if (slots.token.expiresAt !== undefined)
+        bundle.expiresAt = slots.token.expiresAt;
+    if (slots.refresh) {
+        bundle.refreshToken = slots.refresh.token;
+        if (slots.refresh.expiresAt !== undefined)
+            bundle.refreshExpiresAt = slots.refresh.expiresAt;
+    }
+    if (slots.serverOrigin)
+        bundle.serverOrigin = slots.serverOrigin;
+    const owner = parseOwner(slots.owner);
+    if (owner)
+        bundle.owner = owner;
     return bundle;
 }
+/**
+ * Slots this root may adopt from, in order: the legacy profile-only slot, then
+ * the slot the default root displaced this config's credential into.
+ */
+function migrationSlots(me) {
+    if (keychain.isLegacySlotCurrent())
+        return [];
+    return [
+        { kind: 'legacy' },
+        ...(me.cliId ? [{ kind: 'displaced', cliId: me.cliId }] : []),
+    ];
+}
+/**
+ * This root's own slot, refused when it belongs to another config; else a
+ * migration slot that positively belongs to this config.
+ *
+ * The migration is READ-ONLY, deliberately. Copying the bundle into our slot
+ * here would be a write outside the auth lock, and a copy that lands after a
+ * concurrent rotation puts a spent refresh token back — which the server treats
+ * as theft and answers by revoking the family. The next locked write (a refresh
+ * or a login) lands in our own slot, and from then on it wins.
+ */
+function readKeychainAssessed() {
+    if (!keychain.isAvailable())
+        return { bundle: null };
+    const me = currentOwner();
+    const own = readFromKeychain();
+    if (own) {
+        const judged = judgeOwnership(own, me, true);
+        return judged.ours ? { bundle: own } : { bundle: null, foreign: judged.stored };
+    }
+    for (const slot of migrationSlots(me)) {
+        const slots = keychain.readBundleAt(slot);
+        if (!slots)
+            continue;
+        const bundle = bundleFromSlots(slots);
+        if (judgeOwnership(bundle, me, false).ours)
+            return { bundle };
+    }
+    return { bundle: null };
+}
+/**
+ * Before the default root overwrites its own slot, move a credential another
+ * config's older binary wrote there to that config's displaced slot, keyed by
+ * the cliId the server bound it to. A login here must not destroy it: once
+ * that config runs a current binary it adopts it from there.
+ */
+function rescueForeignCredential(me) {
+    if (!keychain.isLegacySlotCurrent())
+        return;
+    const token = keychain.readToken();
+    if (!token)
+        return;
+    const quick = boundCliId(token.token);
+    if (quick && quick === me.cliId)
+        return; // the common case: it is ours
+    const slots = keychain.readBundleAt({ kind: 'legacy' });
+    if (!slots)
+        return;
+    const judged = judgeOwnership(bundleFromSlots(slots), me, true);
+    if (judged.ours || !judged.stored.cliId)
+        return;
+    keychain.copyBundle({ kind: 'legacy' }, { kind: 'displaced', cliId: judged.stored.cliId });
+}
 function writeToKeychain(bundle) {
     if (!keychain.isAvailable())
         return false;
+    rescueForeignCredential(currentOwner());
     const ok = keychain.writeToken(bundle.token, bundle.expiresAt);
     if (!ok)
         return false;
@@ -311,11 +575,34 @@ function writeToKeychain(bundle) {
         // token pair. Origin-aware readers will fail closed until the next login.
         keychain.deleteServerOrigin();
     }
+    // Written last, so the token it describes is already in place.
+    if (!keychain.writeOwner(JSON.stringify(bundle.owner ?? ownerFor(bundle))))
+        return false;
     return true;
 }
+/** This root's own slot, after a failed partial write. */
 function deleteKeychainBackend() {
     keychain.deleteAll();
 }
+/**
+ * Sign-out for the Keychain: this root's own slot unless it holds another
+ * config's credential, plus any migration slot that is positively ours —
+ * otherwise a sign-out would leave a bundle the next read adopts again.
+ */
+function clearKeychainBackend() {
+    if (!keychain.isAvailable())
+        return;
+    const me = currentOwner();
+    const own = readFromKeychain();
+    if (!own || judgeOwnership(own, me, true).ours)
+        keychain.deleteAll();
+    for (const slot of migrationSlots(me)) {
+        const slots = keychain.readBundleAt(slot);
+        if (slots && judgeOwnership(bundleFromSlots(slots), me, false).ours) {
+            keychain.deleteAllAt(slot);
+        }
+    }
+}
 // ---------------------------------------------------------------------
 // Public API — backend-selection logic lives here
 // ---------------------------------------------------------------------
@@ -331,14 +618,21 @@ function deleteKeychainBackend() {
  * function returns whatever is persisted.
  */
 function readFromBackend(expectedServerOrigin) {
-    const fromKeychain = readFromKeychain();
-    const keychainResult = assessBundleOrigin(fromKeychain, 'keychain', expectedServerOrigin);
+    const fromKeychain = readKeychainAssessed();
+    const keychainResult = assessBundleOrigin(fromKeychain.bundle, 'keychain', expectedServerOrigin);
     if (keychainResult.bundle)
         return keychainResult;
-    const fromFile = readFromFile();
-    const fileResult = assessBundleOrigin(fromFile, 'file', expectedServerOrigin);
+    const fromFile = readFileAssessed();
+    const fileResult = assessBundleOrigin(fromFile.bundle, 'file', expectedServerOrigin);
     if (fileResult.bundle)
         return fileResult;
+    // A bundle that belongs to another skrr config outranks every other
+    // diagnostic: it is why this config has no usable credential, and it is the
+    // one case where "run login" would otherwise look like it came from nowhere.
+    if (fromKeychain.foreign)
+        return foreignResult('keychain', fromKeychain.foreign);
+    if (fromFile.foreign)
+        return foreignResult('file', fromFile.foreign);
     // Prefer the first concrete rejection for diagnostics. A partially-failed
     // Keychain write may leave an unbound token while a valid file fallback is
     // absent; surfacing the status lets BaseCommand explain why it ignored it.
@@ -359,6 +653,43 @@ function readFromBackend(expectedServerOrigin) {
             : {}),
     };
 }
+function foreignResult(backend, storedOwner) {
+    const me = currentOwner();
+    return {
+        bundle: null,
+        backend,
+        originStatus: 'none',
+        ownerStatus: 'foreign',
+        storedOwner,
+        expectedOwner: me,
+    };
+}
+/**
+ * One sentence naming whose credential was refused and why, for the surfaces
+ * that explain an absent sign-in (BaseCommand, `skrr doctor`).
+ */
+function describeForeignCredential(result) {
+    if (result.ownerStatus !== 'foreign')
+        return null;
+    const stored = result.storedOwner ?? {};
+    const mine = result.expectedOwner ?? {};
+    const where = result.backend === 'file' ? 'credential file' : 'Keychain slot';
+    const theirs = [
+        stored.cliId ? `CLI identity ${stored.cliId}` : null,
+        stored.configRoot ? `config root ${stored.configRoot}` : null,
+    ]
+        .filter(Boolean)
+        .join(', ');
+    const ours = [
+        mine.cliId ? `CLI identity ${mine.cliId}` : null,
+        mine.configRoot ? `config root ${mine.configRoot}` : null,
+    ]
+        .filter(Boolean)
+        .join(', ');
+    return (`The credential in this profile's ${where} belongs to another skrr configuration on this ` +
+        `machine (${theirs || 'unknown owner'}), not this one (${ours || 'unknown'}). It was not ` +
+        `used and has not been deleted.`);
+}
 /**
  * Persist a token bundle to the preferred backend.
  *
@@ -412,6 +743,9 @@ function writeToBackend(bundle, options = {}) {
         }
         persistedBundle = { ...bundle, serverOrigin: normalized };
     }
+    // Always stamp THIS config as the owner — a bundle read back and re-written
+    // (e.g. `pair`) must not carry a record forward from wherever it came from.
+    persistedBundle = { ...persistedBundle, owner: ownerFor(persistedBundle) };
     let backend;
     if (keychain.isAvailable()) {
         if (writeToKeychain(persistedBundle)) {
@@ -444,7 +778,7 @@ function writeToBackend(bundle, options = {}) {
  * auth-failure cleanup). Idempotent.
  */
 function clearAllBackends() {
-    deleteKeychainBackend();
+    clearKeychainBackend();
     deleteFileBackend();
 }
 /**
@@ -468,11 +802,12 @@ function clearAllBackends() {
  */
 exports.backends = {
     readKeychainToken(expectedServerOrigin) {
-        const result = assessBundleOrigin(readFromKeychain(), 'keychain', expectedServerOrigin);
+        const read = readKeychainAssessed();
+        const result = assessBundleOrigin(read.bundle, 'keychain', expectedServerOrigin);
         return result.bundle?.token ?? null;
     },
     readFileToken(expectedServerOrigin) {
-        const result = assessBundleOrigin(readFromFile(), 'file', expectedServerOrigin);
+        const result = assessBundleOrigin(readFileAssessed().bundle, 'file', expectedServerOrigin);
         return result.bundle?.token ?? null;
     },
 };

package/dist/lib/cli-id.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The operator's `OVERSKY_CLI_ID` / `SKRR_CLI_ID`, when set. The legacy spelling
+ * wins when both are set, as it does for every other overlay variable
+ * (`config.ts`, `envOverlayValue`); the config overlay reads THIS function.
+ */
+export declare function envCliIdOverride(env?: NodeJS.ProcessEnv): string | undefined;
+/** True when this process runs a named profile rather than the default one. */
+export declare function isNamedProfile(): boolean;
+/**
+ * Precedence:
+ *
+ *   1. `OVERSKY_CLI_ID` / `SKRR_CLI_ID` — the operator said so;
+ *   2. `profileCliId` — this named profile was issued its own identity;
+ *   3. `cliId` — the machine identity, which the default profile and every
+ *      profile whose session predates profile identities keep presenting.
+ *
+ * Never mints: a read must not change who this config is.
+ */
+export declare function resolveCliId(cfg: {
+    cliId?: string;
+    profileCliId?: string;
+}): string | undefined;

package/dist/lib/cli-id.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envCliIdOverride = envCliIdOverride;
+exports.isNamedProfile = isNamedProfile;
+exports.resolveCliId = resolveCliId;
+/**
+ * cli-id.ts — THE cliId this process presents (OSK-12156).
+ *
+ * The one resolver for the identity presented to the server at login, at
+ * refresh, to the daemon broker, and as the owner a stored credential is judged
+ * against (`auth-storage.ts`). It used to be read as `cfg.cliId` at a dozen call
+ * sites and regenerated in three, which is what made it impossible to give one
+ * profile its own id without some reader still presenting the machine one.
+ *
+ * Deliberately depends on nothing but the active profile: it is read by
+ * `config.ts` and `auth-storage.ts` alike, so it must not import either.
+ * Issuing an id is a separate act, owned by `cli-identity.ts`.
+ */
+const keychain_1 = require("./keychain");
+/**
+ * The operator's `OVERSKY_CLI_ID` / `SKRR_CLI_ID`, when set. The legacy spelling
+ * wins when both are set, as it does for every other overlay variable
+ * (`config.ts`, `envOverlayValue`); the config overlay reads THIS function.
+ */
+function envCliIdOverride(env = process.env) {
+    const legacy = env.OVERSKY_CLI_ID?.trim();
+    if (legacy)
+        return legacy;
+    const renamed = env.SKRR_CLI_ID?.trim();
+    return renamed ? renamed : undefined;
+}
+/** True when this process runs a named profile rather than the default one. */
+function isNamedProfile() {
+    const profile = (0, keychain_1.getActiveProfile)();
+    return Boolean(profile) && profile !== keychain_1.DEFAULT_PROFILE;
+}
+/**
+ * Precedence:
+ *
+ *   1. `OVERSKY_CLI_ID` / `SKRR_CLI_ID` — the operator said so;
+ *   2. `profileCliId` — this named profile was issued its own identity;
+ *   3. `cliId` — the machine identity, which the default profile and every
+ *      profile whose session predates profile identities keep presenting.
+ *
+ * Never mints: a read must not change who this config is.
+ */
+function resolveCliId(cfg) {
+    const env = envCliIdOverride();
+    if (env)
+        return env;
+    const profileScoped = cfg.profileCliId?.trim();
+    if (profileScoped)
+        return profileScoped;
+    const machine = cfg.cliId?.trim();
+    return machine ? machine : undefined;
+}

package/dist/lib/cli-identity.d.ts

@@ -0,0 +1,49 @@
+import { type CliConfig } from './config';
+/**
+ * A named profile's own identity. Deterministic in (host, user, config root,
+ * profile), so a profile that loses its config file and signs in again is
+ * issued the same id rather than scattering families, and two profiles — or the
+ * same profile name under two config roots — never share one. Same `cli_<12hex>`
+ * shape as the machine id: the server requires the `cli_` namespace.
+ */
+export declare function profileScopedCliId(profile?: string, root?: string): string;
+/**
+ * Does this profile hold a credential it would present? Its own backend slot
+ * (ownership-checked, any origin) or a pre-migration token still in the config.
+ *
+ * A read that FAILS answers true: "keep the id you already present" is the
+ * outcome that cannot log anyone out, so doubt falls on that side.
+ */
+export declare function hasStoredCredential(cfg: CliConfig): boolean;
+export interface LoginCliIdPlan {
+    /** The id this login presents. */
+    cliId: string;
+    /**
+     * `env`: the operator's override. `profile`: an id this profile was issued
+     * earlier. `issued`: issued now, to a named profile holding no credential.
+     * `machine`: the machine id (the default profile, or a profile whose session
+     * was minted under it).
+     */
+    source: 'env' | 'profile' | 'issued' | 'machine';
+    /** Present when the plan chose an id that is not yet on disk; persist it. */
+    updatedConfig?: CliConfig;
+}
+/**
+ * Decide the id a login is about to present. Pure apart from the credential
+ * read; the caller persists `updatedConfig` (see `cliIdForLogin`).
+ */
+export declare function planLoginCliId(cfg: CliConfig, deps?: {
+    hasStoredCredential?: (cfg: CliConfig) => boolean;
+}): LoginCliIdPlan;
+/**
+ * The id an interactive login presents, persisted BEFORE the exchange so a
+ * retry — or a sibling process — presents the same one.
+ */
+export declare function cliIdForLogin(cfg?: CliConfig): string;
+/**
+ * Record that this profile now presents `cliId` — a restored (refresh token,
+ * cliId) pair. A named profile records it as its own identity; writing the
+ * machine field from a named profile would re-identify the default profile and
+ * every profile still on the machine id, whose next refresh would be refused.
+ */
+export declare function persistPresentedCliId(cfg: CliConfig, cliId: string): void;