@skrr-ai/auth-core 0.1.2

package/dist/esm/loginWithLocalhost.js

@@ -0,0 +1,353 @@
+/**
+ * loginWithLocalhost.ts — Phase H.0 orchestrator.
+ *
+ * @deprecated Tier-1.1 (2026-04-29). This module talks to the older
+ * `/api/auth/cli-init` + `/api/auth/cli-token-exchange` endpoints; the
+ * canonical PKCE+localhost orchestrator is now
+ * `daemon/src/cli/oauthLogin.ts:runOAuthLogin`, which uses the standard
+ * `/api/oauth/token` endpoint and additionally arms a manual-paste
+ * fallback arm. Retained until `--legacy` is removed (gated on Tier-2.2
+ * telemetry showing <1% usage). New code MUST NOT call this — the only
+ * remaining caller is the daemon's `loginInteractive` legacy fallback at
+ * `daemon/src/auth.ts:loginWithLocalhostFlow`. See
+ * `docs/daemon-auth-production-readiness-2026-04-29.md` Tier 1.1 for the
+ * removal plan.
+ *
+ * Ties PKCE primitives + local 127.0.0.1 callback server + server-side
+ * /cli-init / /cli-token-exchange endpoints into a single function the
+ * CLI/daemon can call. Returns daemon-style tokens (same shape as the
+ * device-code completion path) so the persistence layer in
+ * `daemon/src/auth.ts:saveToken()` doesn't change.
+ *
+ * Flow:
+ *
+ *   1. generate code_verifier + state
+ *   2. compute S256 code_challenge
+ *   3. start local 127.0.0.1 callback server (handle.redirectUri ready)
+ *   4. POST /api/auth/cli-init { code_challenge, redirect_uri, state,
+ *                                 device_name, scope }
+ *      → { requestId, authUrl }
+ *   5. open authUrl in user's browser (caller-injected opener)
+ *   6. user approves on app.oversky.ai/auth/cli?req=<requestId>
+ *   7. server 302s browser → http://127.0.0.1:<port>/callback?code&state
+ *   8. handle.waitForCallback() resolves with { code }
+ *   9. POST /api/auth/cli-token-exchange { code, code_verifier,
+ *                                          redirect_uri }
+ *      → { token, expiresAt, refreshToken?, refreshExpiresAt? }
+ *  10. return the token bundle (caller persists via saveToken())
+ *
+ * Design boundaries:
+ *
+ *   - Browser opener is caller-injected (auth-core stays platform-
+ *     agnostic; daemon passes its `execFile('open' | 'xdg-open' |
+ *     'rundll32', …)` wrapper).
+ *   - fetch is caller-overridable for tests; defaults to globalThis.fetch
+ *     (Node 20+).
+ *   - SSH / headless / OVERSKY_FORCE_DEVICE_CODE detection is the
+ *     CALLER's job — this orchestrator just runs the flow. The caller
+ *     decides whether localhost callback is appropriate before calling.
+ *   - No retries. The auth code is single-use and short-lived; if a
+ *     network blip drops the token-exchange request, the user just
+ *     reruns the login command. Adding retries here muddies error
+ *     semantics for callers that want clean fallback signals.
+ *
+ * Error handling:
+ *
+ *   The orchestrator throws structured errors so callers can branch:
+ *
+ *     LocalCallbackBindError       — port unavailable; caller may retry
+ *     LocalCallbackTimeoutError    — user never approved; fall back
+ *     LocalCallbackStateMismatchError — likely attack; fail loudly
+ *     LocalCallbackDeniedError     — user clicked deny; surface clearly
+ *     LocalCallbackMalformedError  — server bug; surface for diagnosis
+ *     LoginInitError               — /cli-init HTTP failure
+ *                                   (code='FEATURE_DISABLED' for 404 →
+ *                                    caller falls back to device-code)
+ *     LoginExchangeError           — /cli-token-exchange HTTP failure
+ *
+ * Cleanup invariant: the local server is ALWAYS torn down before this
+ * function returns or throws — any failure path runs through the
+ * `try / finally(handle.close())` wrapper. A future caller cannot leak
+ * a listening socket by catching the wrong error.
+ */
+import { generateState, generateVerifier, challenge as pkceChallenge } from './pkce.js';
+import { startLocalCallback } from './loginLocalhost.js';
+import { getAuthLogger } from './runtime.js';
+/** Default scope for new daemon installs. */
+const DEFAULT_SCOPE = 'daemon';
+// ---------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------
+/**
+ * /cli-init failed. `code` distinguishes the failure mode so the
+ * caller can branch (FEATURE_DISABLED → fall back to device-code; the
+ * rest → surface to user).
+ */
+export class LoginInitError extends Error {
+    code; // 200 but body shape unexpected
+    status;
+    responseBody;
+    constructor(code, message, status, body) {
+        super(message);
+        this.name = 'LoginInitError';
+        this.code = code;
+        this.status = status;
+        this.responseBody = body;
+    }
+}
+/** /cli-token-exchange failed. */
+export class LoginExchangeError extends Error {
+    code; // 200 but body shape unexpected
+    status;
+    responseBody;
+    constructor(code, message, status, body) {
+        super(message);
+        this.name = 'LoginExchangeError';
+        this.code = code;
+        this.status = status;
+        this.responseBody = body;
+    }
+}
+// ---------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------
+/**
+ * Run the full PKCE-via-localhost login flow. See file header for the
+ * step-by-step. Throws structured errors on every failure path. The
+ * local callback server is always torn down before this function
+ * returns or throws.
+ */
+export async function loginWithLocalhost(opts) {
+    const log = getAuthLogger();
+    const fetchFn = opts.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchFn !== 'function') {
+        throw new TypeError('loginWithLocalhost: globalThis.fetch is missing — pass fetchImpl or run under Node ≥ 20');
+    }
+    const scope = opts.scope ?? DEFAULT_SCOPE;
+    const serverUrl = opts.serverUrl.replace(/\/+$/, '');
+    // Step 1+2: PKCE primitives. The verifier never leaves this
+    // function's local scope until step 9.
+    const codeVerifier = generateVerifier();
+    const codeChallenge = pkceChallenge(codeVerifier, 'S256');
+    const state = generateState();
+    // Step 3: bind the local callback server. Bind error here is fatal —
+    // caller decides whether to retry on a different port.
+    const handle = await startLocalCallback({
+        state,
+        port: opts.port,
+        host: opts.host,
+        bindAddr: opts.bindAddr,
+        timeoutMs: opts.timeoutMs,
+    });
+    try {
+        // Step 4: POST /cli-init.
+        const initBody = {
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+            redirect_uri: handle.redirectUri,
+            state,
+            device_name: opts.deviceName,
+            daemon_id: opts.daemonId,
+            scope,
+        };
+        let initRes;
+        try {
+            initRes = await fetchFn(`${serverUrl}/api/auth/cli-init`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(initBody),
+            });
+        }
+        catch (err) {
+            throw new LoginInitError('NETWORK_ERROR', `POST /api/auth/cli-init failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (initRes.status === 404) {
+            // Server doesn't expose this endpoint — feature flag off, or
+            // older server build that pre-dates Phase H.0. Caller should
+            // fall back to device-code.
+            throw new LoginInitError('FEATURE_DISABLED', 'Server does not support PKCE localhost login (feature flag off or older build). ' +
+                'Fall back to device-code.', 404);
+        }
+        if (initRes.status === 429) {
+            throw new LoginInitError('RATE_LIMITED', 'Server rate-limited the login init request. Wait a moment and retry.', 429, await safeReadBody(initRes));
+        }
+        if (initRes.status >= 500) {
+            throw new LoginInitError('SERVER_ERROR', `Server returned ${initRes.status} on /cli-init.`, initRes.status, await safeReadBody(initRes));
+        }
+        if (!initRes.ok) {
+            throw new LoginInitError('BAD_REQUEST', `Server returned ${initRes.status} on /cli-init.`, initRes.status, await safeReadBody(initRes));
+        }
+        let initJson;
+        try {
+            initJson = await initRes.json();
+        }
+        catch (err) {
+            throw new LoginInitError('MALFORMED_RESPONSE', `Could not parse /cli-init response as JSON: ${err instanceof Error ? err.message : String(err)}`, initRes.status);
+        }
+        const init = parseInitResponse(initJson);
+        if (!init) {
+            throw new LoginInitError('MALFORMED_RESPONSE', '/cli-init response missing requestId or authUrl', initRes.status);
+        }
+        // Step 5: hand the auth URL to the caller (so they can print it
+        // before / instead of opening the browser) then open it. Both are
+        // best-effort — the user can copy/paste the URL.
+        if (opts.onAuthUrl) {
+            try {
+                opts.onAuthUrl(init.authUrl);
+            }
+            catch (err) {
+                log.warn(`[loginWithLocalhost] onAuthUrl callback threw (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        try {
+            await opts.openBrowser(init.authUrl);
+        }
+        catch (err) {
+            log.warn(`[loginWithLocalhost] openBrowser failed (non-fatal — user can paste URL): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Step 6–8: wait for the callback. Errors here are the structured
+        // LocalCallback* set; they propagate as-is so the caller branches
+        // on instanceof.
+        const callback = await handle.waitForCallback();
+        // Step 9: POST /cli-token-exchange.
+        const exchangeBody = {
+            code: callback.code,
+            code_verifier: codeVerifier,
+            redirect_uri: handle.redirectUri,
+        };
+        let exchangeRes;
+        try {
+            exchangeRes = await fetchFn(`${serverUrl}/api/auth/cli-token-exchange`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(exchangeBody),
+            });
+        }
+        catch (err) {
+            throw new LoginExchangeError('NETWORK_ERROR', `POST /api/auth/cli-token-exchange failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (exchangeRes.status === 400) {
+            throw new LoginExchangeError('INVALID_GRANT', 'Server rejected the PKCE code exchange (verifier mismatch, expired code, or already redeemed).', 400, await safeReadBody(exchangeRes));
+        }
+        if (exchangeRes.status >= 500) {
+            throw new LoginExchangeError('SERVER_ERROR', `Server returned ${exchangeRes.status} on /cli-token-exchange.`, exchangeRes.status, await safeReadBody(exchangeRes));
+        }
+        if (!exchangeRes.ok) {
+            throw new LoginExchangeError('BAD_REQUEST', `Server returned ${exchangeRes.status} on /cli-token-exchange.`, exchangeRes.status, await safeReadBody(exchangeRes));
+        }
+        let exchangeJson;
+        try {
+            exchangeJson = await exchangeRes.json();
+        }
+        catch (err) {
+            throw new LoginExchangeError('MALFORMED_RESPONSE', `Could not parse /cli-token-exchange response as JSON: ${err instanceof Error ? err.message : String(err)}`, exchangeRes.status);
+        }
+        const result = parseExchangeResponse(exchangeJson);
+        if (!result) {
+            throw new LoginExchangeError('MALFORMED_RESPONSE', '/cli-token-exchange response missing token or has bad shape', exchangeRes.status);
+        }
+        log.info(`[loginWithLocalhost] login successful (scope=${result.scope ?? scope}` +
+            (result.daemonId ? ` daemonId=${result.daemonId}` : '') +
+            ')');
+        return result;
+    }
+    finally {
+        // Cleanup invariant: server torn down on every exit path.
+        //
+        // Subtlety: when /cli-init fails (404, network, etc.) we throw
+        // BEFORE reaching `await handle.waitForCallback()`, so the
+        // callback Promise has no .catch attached. `handle.close()` will
+        // reject that Promise with CANCELLED → an unhandledRejection
+        // event the test runner correctly flags. Attach a no-op .catch
+        // first so the artifact-of-cleanup rejection is observed.
+        // Harmless on the happy path: the try-block's await already
+        // attached its own handler, and multiple .catches on the same
+        // Promise all observe the same outcome.
+        void handle.waitForCallback().catch(() => undefined);
+        handle.close();
+    }
+}
+function parseInitResponse(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    const requestId = typeof obj.requestId === 'string' ? obj.requestId : null;
+    const authUrl = typeof obj.authUrl === 'string' ? obj.authUrl : null;
+    if (!requestId || !authUrl)
+        return null;
+    // Defense in depth: refuse to open URLs that aren't http/https.
+    // Prevents a hostile/buggy server response steering the caller's
+    // browser at javascript: / file: / data: URIs.
+    try {
+        const u = new URL(authUrl);
+        if (u.protocol !== 'http:' && u.protocol !== 'https:')
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { requestId, authUrl };
+}
+function parseExchangeResponse(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    const token = typeof obj.token === 'string' && obj.token.length > 0 ? obj.token : undefined;
+    const expiresAt = parseEpochMs(obj.expiresAt);
+    const refreshToken = typeof obj.refreshToken === 'string' && obj.refreshToken.length > 0
+        ? obj.refreshToken
+        : undefined;
+    const refreshExpiresAt = parseEpochMs(obj.refreshExpiresAt);
+    const daemonId = typeof obj.daemonId === 'string' && obj.daemonId.length > 0 ? obj.daemonId : undefined;
+    const scope = parseScope(obj.scope);
+    // Stage-E #1 — opaque `osk_dmn_*` co-issued for daemon-scope mints
+    // (server-side: routes/cliAuth.js sends it in the response payload).
+    // Treat any non-string/empty as absent — login responses don't have
+    // the "explicitly clear" null semantic that refresh responses do.
+    const opaqueAccessToken = typeof obj.opaqueAccessToken === 'string' && obj.opaqueAccessToken.length > 0
+        ? obj.opaqueAccessToken
+        : undefined;
+    // Stage-E #1 step 4 — daemon-scope login responses omit `token`
+    // because the daemon-JWT substrate is retired. Accept the response
+    // as long as the server returned at least one credential class.
+    // Pre-step-4 responses (token only / token + opaque) and post-step-4
+    // responses (opaque only) both pass.
+    if (!token && !opaqueAccessToken)
+        return null;
+    // Match the device-code defensive path in daemon/src/auth.ts: if the
+    // server claimed to issue a refresh token but the expiry is
+    // unparseable, drop both rather than persist a refresh that reads
+    // back as "valid forever" via Date.now() > NaN.
+    const safeRefresh = refreshToken !== undefined && refreshExpiresAt !== undefined
+        ? { refreshToken, refreshExpiresAt }
+        : undefined;
+    return {
+        ...(token ? { token } : {}),
+        ...(expiresAt !== undefined ? { expiresAt } : {}),
+        ...(safeRefresh ?? {}),
+        ...(daemonId ? { daemonId } : {}),
+        ...(scope ? { scope } : {}),
+        ...(opaqueAccessToken ? { opaqueAccessToken } : {}),
+    };
+}
+function parseEpochMs(v) {
+    if (typeof v !== 'string' && typeof v !== 'number')
+        return undefined;
+    const ms = new Date(v).getTime();
+    return Number.isFinite(ms) ? ms : undefined;
+}
+function parseScope(v) {
+    if (v === 'daemon' || v === 'cli' || v === 'web')
+        return v;
+    return undefined;
+}
+async function safeReadBody(res) {
+    try {
+        const txt = await res.text();
+        // Truncate so a massive 5xx HTML page doesn't bloat error objects.
+        return txt.length > 500 ? txt.slice(0, 500) + '… [truncated]' : txt;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/esm/machineId.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Return the stable machine-scoped daemon UUID. On first call, reads
+ * `<configDir>/daemon.id` if present; otherwise mints a UUIDv7 and
+ * persists it atomically at 0600. Cached for the process lifetime.
+ *
+ * On filesystem failure (locked home dir, read-only FS, ENOSPC) returns
+ * a deterministic `fallback-<machineUuid>` string so the caller still
+ * has something to emit. The `fallback-` prefix makes telemetry
+ * trivially bucketable and prevents the fallback from being confused
+ * with a real UUIDv7 downstream.
+ *
+ * The caller may pass `machineUuidFallback` to override the default
+ * hostname+platform fingerprint with a richer detector (e.g. the
+ * daemon's `getMachineUuid()` from `registry.ts`).
+ */
+export declare function ensureMachineDaemonId(machineUuidFallback?: () => string): string;
+/**
+ * Scan `<configDir>/profiles/<profile>/daemon.id` for pre-unification
+ * per-profile identity files. Any daemon that shipped before the
+ * machine-scoped layout landed may have minted a UUID under the
+ * profile directory; emitting those on every register lets the server
+ * fold the stale `DaemonRefreshSession` + `Daemon` rows into the
+ * canonical machine identity without data loss.
+ *
+ * Returns deduped lowercase UUIDs only. Silent on individual read
+ * failures — unreadable / malformed / non-UUID entries are omitted.
+ * Never throws. Returns `[]` on clean installs.
+ */
+export declare function legacyDaemonUuids(): string[];
+/**
+ * @internal test seam — clears the in-process cache so a test can
+ * exercise the full `ensureMachineDaemonId` flow against a fresh
+ * filesystem without rebuilding the module.
+ */
+export declare function __resetCachedDaemonIdForTest(): void;

package/dist/esm/machineId.js

@@ -0,0 +1,231 @@
+/**
+ * machineId.ts — stable machine-scoped daemon identity (auth-core).
+ *
+ * Lifted from `daemon/src/machineIdentity.ts` so the CLI and daemon can
+ * share a single per-machine UUIDv7 stored at `<configDir>/daemon.id`.
+ *
+ * Why this exists alongside platform-derived machine UUIDs:
+ *
+ *   - OS-derived ids (IOPlatformUUID / /etc/machine-id / MachineGuid) are
+ *     stable per-machine, but they CHANGE on OS reinstall — at which
+ *     point the server can't recognize "this is the same physical
+ *     machine after a reinstall."
+ *   - `ensureMachineDaemonId()` persists a UUID we mint ourselves in a
+ *     per-user dotfile. It survives OS reinstalls (as long as the home
+ *     directory survives), and a user whose machineUuid changes can
+ *     still be re-anchored via the legacy-id list.
+ *
+ * Auth-core does NOT know about platform-level OS UUIDs (those still
+ * live in `daemon/src/registry.ts::getMachineUuid()`). The fallback is
+ * supplied by the consumer via the `machineUuidFallback` parameter so
+ * a daemon can pass its richer detector while a CLI uses a hostname
+ * fingerprint.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getAuthMachineConfigDir, getAuthLogger } from './runtime.js';
+/** File name for the stable machine daemon id. Never changes. */
+const DAEMON_ID_FILENAME = 'daemon.id';
+/** Profile subdirectory — scanned for legacy per-profile identity files. */
+const PROFILES_DIRNAME = 'profiles';
+/** UUID canonical form — 8-4-4-4-12 lowercase hex. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+let cachedStableDaemonId = null;
+function machineHomeDir() {
+    // MACHINE-scoped root — deliberately NOT the profile-scoped configDir.
+    // See OSK-1478: the daemon's configDir is `~/.skrr/profiles/<profile>`,
+    // which made this "stable per-machine id" drift per-profile.
+    return getAuthMachineConfigDir();
+}
+function stableDaemonIdPath() {
+    return path.join(machineHomeDir(), DAEMON_ID_FILENAME);
+}
+/**
+ * Generate a UUIDv7 (RFC 9562 §5.7). 48 bits big-endian unix-millis
+ * timestamp, 4 bits version, 12 bits random, 2 bits variant, 62 bits
+ * random. Implemented inline because Node 20's `crypto.randomUUID()` is
+ * v4 only; pulling a dep for 15 lines is not worth the supply-chain
+ * surface area.
+ */
+function generateUuidV7() {
+    const bytes = crypto.randomBytes(16);
+    const ts = BigInt(Date.now());
+    bytes[0] = Number((ts >> 40n) & 0xffn);
+    bytes[1] = Number((ts >> 32n) & 0xffn);
+    bytes[2] = Number((ts >> 24n) & 0xffn);
+    bytes[3] = Number((ts >> 16n) & 0xffn);
+    bytes[4] = Number((ts >> 8n) & 0xffn);
+    bytes[5] = Number(ts & 0xffn);
+    // Version 7 → top 4 bits of byte 6.
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    // RFC 4122 variant (10xx) → top 2 bits of byte 8.
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString('hex');
+    return (hex.slice(0, 8) +
+        '-' +
+        hex.slice(8, 12) +
+        '-' +
+        hex.slice(12, 16) +
+        '-' +
+        hex.slice(16, 20) +
+        '-' +
+        hex.slice(20));
+}
+function isUuidLike(raw) {
+    return UUID_RE.test(raw.trim());
+}
+/**
+ * Atomic write with 0600 mode. Tmp file in the same directory so the
+ * final rename is intra-filesystem. Concurrent processes racing the
+ * first-ever write both produce valid UUIDs; the kernel serializes
+ * the rename and the loser's file becomes unreachable — harmless.
+ */
+function writeDaemonIdFile(target, id) {
+    const dir = path.dirname(target);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${target}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
+    fs.writeFileSync(tmp, id + '\n', { encoding: 'utf-8', mode: 0o600 });
+    try {
+        fs.chmodSync(tmp, 0o600);
+    }
+    catch {
+        /* best-effort — writeFileSync already set mode */
+    }
+    fs.renameSync(tmp, target);
+}
+/**
+ * Default fallback when a consumer doesn't supply one. Synthesizes a
+ * SHA-256 of `os.hostname()` + `os.platform()` — better than just
+ * hostname (includes platform) but worse than a true hardware UUID.
+ *
+ * The daemon overrides this with its richer detector
+ * (`registry.ts::getMachineUuid()`) when available. The CLI today has
+ * no native deps for OS UUIDs and so accepts this default.
+ */
+function defaultMachineUuidFallback() {
+    const host = os.hostname() || 'unknown-host';
+    const platform = os.platform() || 'unknown-platform';
+    return crypto.createHash('sha256').update(`auth-core:${platform}:${host}`).digest('hex');
+}
+/**
+ * Return the stable machine-scoped daemon UUID. On first call, reads
+ * `<configDir>/daemon.id` if present; otherwise mints a UUIDv7 and
+ * persists it atomically at 0600. Cached for the process lifetime.
+ *
+ * On filesystem failure (locked home dir, read-only FS, ENOSPC) returns
+ * a deterministic `fallback-<machineUuid>` string so the caller still
+ * has something to emit. The `fallback-` prefix makes telemetry
+ * trivially bucketable and prevents the fallback from being confused
+ * with a real UUIDv7 downstream.
+ *
+ * The caller may pass `machineUuidFallback` to override the default
+ * hostname+platform fingerprint with a richer detector (e.g. the
+ * daemon's `getMachineUuid()` from `registry.ts`).
+ */
+export function ensureMachineDaemonId(machineUuidFallback) {
+    if (cachedStableDaemonId !== null)
+        return cachedStableDaemonId;
+    const target = stableDaemonIdPath();
+    const fallbackFn = machineUuidFallback ?? defaultMachineUuidFallback;
+    const log = getAuthLogger();
+    // Fast path: the file exists and its contents parse as a UUID.
+    try {
+        const raw = fs.readFileSync(target, 'utf-8').trim();
+        if (isUuidLike(raw)) {
+            cachedStableDaemonId = raw.toLowerCase();
+            return cachedStableDaemonId;
+        }
+        // File exists but content is not a UUID. Overwrite — the file is
+        // machine-local and this binary is its only reader. Losing the
+        // garbled content is acceptable.
+        log.warn(`[machineIdentity] ${target} exists but does not contain a valid UUID — regenerating`);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'ENOENT') {
+            log.warn(`[machineIdentity] read ${target} failed (${code ?? 'unknown'}): ${err.message}`);
+        }
+    }
+    // OSK-1478 migration — before minting a brand-new id (which the server has
+    // never seen), adopt an existing pre-unification per-profile `daemon.id` if
+    // one is present. This promotes a previously-used identity to the canonical
+    // machine-root location so the daemon's `stableDaemonId` doesn't needlessly
+    // flip to a value with no server-side history. The remaining profile ids are
+    // still surfaced by `legacyDaemonUuids()` for the register-time fold, so no
+    // identity is lost either way. Deterministic pick (sorted) so racing
+    // processes converge on the same adoption.
+    const adoptable = legacyDaemonUuids().sort();
+    if (adoptable.length > 0) {
+        const adopted = adoptable[0];
+        try {
+            writeDaemonIdFile(target, adopted);
+            log.info(`[machineIdentity] adopted pre-unification per-profile id as machine-scoped canonical: ${adopted}`);
+            cachedStableDaemonId = adopted;
+            return adopted;
+        }
+        catch (err) {
+            // Fall through to a fresh mint on write failure — the legacy fold still
+            // re-anchors the server row, so correctness does not depend on adoption.
+            log.warn(`[machineIdentity] adopt ${adopted} failed: ${err.message} — minting fresh`);
+        }
+    }
+    const fresh = generateUuidV7();
+    try {
+        writeDaemonIdFile(target, fresh);
+        cachedStableDaemonId = fresh;
+        return fresh;
+    }
+    catch (err) {
+        log.warn(`[machineIdentity] persist ${target} failed: ${err.message} — using fallback`);
+        const fallback = `fallback-${fallbackFn()}`;
+        cachedStableDaemonId = fallback;
+        return fallback;
+    }
+}
+/**
+ * Scan `<configDir>/profiles/<profile>/daemon.id` for pre-unification
+ * per-profile identity files. Any daemon that shipped before the
+ * machine-scoped layout landed may have minted a UUID under the
+ * profile directory; emitting those on every register lets the server
+ * fold the stale `DaemonRefreshSession` + `Daemon` rows into the
+ * canonical machine identity without data loss.
+ *
+ * Returns deduped lowercase UUIDs only. Silent on individual read
+ * failures — unreadable / malformed / non-UUID entries are omitted.
+ * Never throws. Returns `[]` on clean installs.
+ */
+export function legacyDaemonUuids() {
+    const profilesDir = path.join(machineHomeDir(), PROFILES_DIRNAME);
+    let entries;
+    try {
+        entries = fs.readdirSync(profilesDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const seen = new Set();
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const candidate = path.join(profilesDir, entry.name, DAEMON_ID_FILENAME);
+        try {
+            const raw = fs.readFileSync(candidate, 'utf-8').trim();
+            if (isUuidLike(raw))
+                seen.add(raw.toLowerCase());
+        }
+        catch {
+            /* omit */
+        }
+    }
+    return [...seen];
+}
+/**
+ * @internal test seam — clears the in-process cache so a test can
+ * exercise the full `ensureMachineDaemonId` flow against a fresh
+ * filesystem without rebuilding the module.
+ */
+export function __resetCachedDaemonIdForTest() {
+    cachedStableDaemonId = null;
+}

package/dist/esm/messages.d.ts

@@ -0,0 +1,9 @@
+export type AuthFailureReason = 'REFRESH_INVALID' | 'REFRESH_REUSED' | 'REFRESH_EXPIRED' | 'SESSION_REVOKED' | 'TOKEN_EXPIRED' | 'TOKEN_INVALID' | 'UNKNOWN_401' | 'UNKNOWN';
+export declare function formatReauthMessage(reason: AuthFailureReason | string): string;
+/**
+ * Exit code for "permanent auth failure during initial connect" — picked to
+ * match the BSD/Unix sysexits.h convention (EX_TEMPFAIL = 75) so process
+ * supervisors (launchd, systemd, pm2) can be configured to NOT auto-restart
+ * on this code (the user must manually re-auth, retrying won't help).
+ */
+export declare const EXIT_NEEDS_REAUTH = 75;

package/dist/esm/messages.js

@@ -0,0 +1,40 @@
+/**
+ * User-facing messages for auth state transitions.
+ *
+ * Centralized so every surface (daemon CLI, sky CLI, Electron tray, future
+ * mobile companion) emits consistent copy. The binary name in the suggested
+ * recovery command is parameterized via `configureAuthCore({ binaryName })`
+ * so each consumer's reauth banner matches the binary the user just typed.
+ */
+import { getAuthBinaryName } from './runtime.js';
+const REASON_HUMAN = {
+    REFRESH_INVALID: 'Your saved credentials are no longer valid.',
+    REFRESH_REUSED: 'Your session was ended for security reasons (token replay detected).',
+    REFRESH_EXPIRED: 'Your session has expired.',
+    SESSION_REVOKED: 'Your session was ended (you signed out elsewhere or your password changed).',
+    TOKEN_EXPIRED: 'Your access token has expired.',
+    TOKEN_INVALID: 'Your saved credentials are no longer valid.',
+    UNKNOWN_401: 'OverSky needs you to sign in again.',
+    UNKNOWN: 'OverSky needs you to sign in again.',
+};
+export function formatReauthMessage(reason) {
+    const norm = REASON_HUMAN[reason] || REASON_HUMAN.UNKNOWN;
+    const isHeadless = !process.stdout.isTTY;
+    const bin = getAuthBinaryName();
+    const cmd = isHeadless ? `${bin} login --device` : `${bin} login`;
+    return [
+        '',
+        'OverSky cannot connect — re-authentication required.',
+        `  Reason: ${norm}`,
+        '',
+        `  To continue, run:  ${cmd}`,
+        '',
+    ].join('\n');
+}
+/**
+ * Exit code for "permanent auth failure during initial connect" — picked to
+ * match the BSD/Unix sysexits.h convention (EX_TEMPFAIL = 75) so process
+ * supervisors (launchd, systemd, pm2) can be configured to NOT auto-restart
+ * on this code (the user must manually re-auth, retrying won't help).
+ */
+export const EXIT_NEEDS_REAUTH = 75;