@skrr-ai/auth-core 0.1.2

package/dist/esm/legacyStatePreflight.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Detect state left by the pre-rename product on this machine.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * §5.5 of the rename scope doc states the invariant plainly: the same machine
+ * must never have an old and a new runtime live at once. §10 names the failure
+ * it prevents — "dual daemon race", two binaries under two different service
+ * labels, each believing it holds the single-instance lock because neither can
+ * see the other's label.
+ *
+ * A rename cannot prevent that on its own. Changing `~/.oversky` to `~/.skrr`
+ * does not remove the old directory or unregister the old service; it just
+ * stops looking at them. So the new runtime has to LOOK, and refuse.
+ *
+ * DETECT AND REFUSE, NEVER MIGRATE AND NEVER DELETE
+ * -------------------------------------------------
+ * §0.1 was confirmed on 2026-08-31: there are no external users, and the team
+ * accepts re-login and reinstall. §3.2 therefore makes RESET the documented
+ * default, so this deliberately does not read, copy or repair old state:
+ *
+ *   - Copying it forward would contradict the clean break, and §7.2 forbids
+ *     copying a refresh token into a new location at all.
+ *   - Deleting it would be worse. §8.4: never delete local state, Keychain
+ *     entries or feeds to force a migration. The operator decides, from the
+ *     cutover runbook, after taking the backup that runbook specifies.
+ *
+ * The only correct behaviour is to say precisely what was found and stop.
+ *
+ * BEST EFFORT BY CONSTRUCTION
+ * ---------------------------
+ * An unreadable home directory, a permissions error or an exotic platform must
+ * never be the reason an install cannot proceed — a preflight that blocks a
+ * clean machine is worse than one that misses a dirty one. Every probe is
+ * wrapped, and anything it cannot determine reads as "not found".
+ */
+export interface LegacyStateFinding {
+    /** Absolute path that still exists. */
+    readonly path: string;
+    /** The directory name that identified it, e.g. `.oversky`. */
+    readonly root: string;
+    /** True when the directory holds a profile tree, i.e. a runtime actually ran. */
+    readonly hasProfiles: boolean;
+}
+export interface LegacyStateReport {
+    readonly findings: readonly LegacyStateFinding[];
+    /** True when anything was found. Callers refuse on this. */
+    readonly hasLegacyState: boolean;
+}
+/**
+ * Look for pre-rename state roots under `home`.
+ *
+ * `home` is injectable so the test suite can point it at a fixture rather than
+ * at the developer's actual home directory — a preflight test that reads the
+ * real `~` passes or fails based on who runs it.
+ */
+export declare function findLegacyLocalState(home?: string): LegacyStateReport;
+/**
+ * The message shown when preflight refuses.
+ *
+ * Written for someone who has just been stopped and wants to know why and what
+ * to do — so it names the exact paths, says explicitly that nothing was touched,
+ * and points at the runbook rather than improvising a fix. It does NOT offer a
+ * `--force`: the operator's next step is the backup the runbook specifies, and
+ * a flag that skips a safety check is the flag everyone learns to paste.
+ */
+export declare function describeLegacyState(report: LegacyStateReport, binaryName: string): string;

package/dist/esm/legacyStatePreflight.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { LEGACY_CONFIG_DIR_NAMES } from './localIdentity.js';
+function safeExists(p) {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+function safeHasProfiles(dir) {
+    try {
+        const profiles = path.join(dir, 'profiles');
+        return fs.existsSync(profiles) && fs.readdirSync(profiles).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Look for pre-rename state roots under `home`.
+ *
+ * `home` is injectable so the test suite can point it at a fixture rather than
+ * at the developer's actual home directory — a preflight test that reads the
+ * real `~` passes or fails based on who runs it.
+ */
+export function findLegacyLocalState(home = os.homedir()) {
+    const findings = [];
+    // No guard against a legacy name equalling the CURRENT root: `CONFIG_DIR_NAME`
+    // and `LEGACY_CONFIG_DIR_NAMES` are both literal-typed, so TypeScript proves
+    // they cannot overlap and rejects the comparison as unreachable. A runtime
+    // check here would be dead code pretending to be a safety net. The
+    // disjointness is asserted in the test instead, where it can catch a future
+    // edit to the constants.
+    for (const root of LEGACY_CONFIG_DIR_NAMES) {
+        const dir = path.join(home, root);
+        if (!safeExists(dir))
+            continue;
+        findings.push({ path: dir, root, hasProfiles: safeHasProfiles(dir) });
+    }
+    return { findings, hasLegacyState: findings.length > 0 };
+}
+/**
+ * The message shown when preflight refuses.
+ *
+ * Written for someone who has just been stopped and wants to know why and what
+ * to do — so it names the exact paths, says explicitly that nothing was touched,
+ * and points at the runbook rather than improvising a fix. It does NOT offer a
+ * `--force`: the operator's next step is the backup the runbook specifies, and
+ * a flag that skips a safety check is the flag everyone learns to paste.
+ */
+export function describeLegacyState(report, binaryName) {
+    const lines = [];
+    lines.push('Found state from the previous product identity on this machine:');
+    lines.push('');
+    for (const f of report.findings) {
+        lines.push(`  ${f.path}${f.hasProfiles ? '   (a runtime has run from here)' : ''}`);
+    }
+    lines.push('');
+    lines.push('Installing beside it risks two runtimes holding two different service');
+    lines.push('labels, each believing it owns the single-instance lock.');
+    lines.push('');
+    lines.push('Nothing above has been read, copied or removed. Follow the team cutover');
+    lines.push('runbook — it takes a backup first — and then run this again:');
+    lines.push('');
+    lines.push(`  ${binaryName} uninstall     # stop and deregister the old service`);
+    lines.push('  # then remove the directories listed above, per the runbook');
+    return lines.join('\n');
+}

package/dist/esm/localIdentity.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The names this product uses for state it leaves on a machine.
+ *
+ * WHY THESE LIVE IN ONE PLACE NOW
+ * ------------------------------
+ * Before the OverSky → skrr rename, `'.oversky'` was written as a literal in 47
+ * places across `auth-core`, `cli`, `daemon` and `desktop`, and the Keychain
+ * service prefix in about as many. Nothing related them, so nothing could tell
+ * you whether a given path was the machine root, a profile directory, or a
+ * coincidence — and changing the value meant finding all 47 and hoping.
+ *
+ * `auth-core` is the right home because it is the one module all three runtimes
+ * already import: the CLI (42 files), the daemon (35) and Desktop (5).
+ *
+ * WHAT MAKES THESE DIFFERENT FROM COPY
+ * ------------------------------------
+ * A name here ADDRESSES state that already exists on a real machine. Changing
+ * `CONFIG_DIR_NAME` does not move `~/.oversky` to `~/.skrr` — it makes the old
+ * directory unreachable and starts a new, empty one. The same is true of the
+ * Keychain service: an item is addressed BY service name, so a rename orphans
+ * the wrapped credential rather than migrating it.
+ *
+ * That is the intended behaviour under the pre-launch clean break (§0.1
+ * confirmed 2026-08-31: no external users, and the team accepts re-login). It is
+ * only safe because of the LEGACY_ values below, which exist so install
+ * preflight can NAME the old state in order to detect and refuse it. Preflight
+ * cannot refuse what it cannot name.
+ */
+/** Machine-scoped state root, relative to the user's home directory. */
+export declare const CONFIG_DIR_NAME = ".skrr";
+/**
+ * Roots this product used before, newest first.
+ *
+ * NOT a compatibility path — nothing reads state from these. They exist so
+ * install preflight and the team cutover runbook can detect a machine that
+ * still carries old state and refuse to run beside it (§5.5: the same machine
+ * must never have an old and a new runtime live at once).
+ *
+ * `.sky` predates `.oversky` and was already handled as a legacy path before
+ * this rename, so it is carried forward rather than forgotten.
+ */
+export declare const LEGACY_CONFIG_DIR_NAMES: readonly [".oversky", ".sky"];
+/** Prefix for OS service labels and Keychain services (`ai.skrr.daemon`, …). */
+export declare const NATIVE_ID_PREFIX = "ai.skrr";
+/**
+ * The previous native prefix, for the same detect-and-refuse reason.
+ *
+ * Note the KEK identifier used `com.oversky.daemon.kek` while everything else
+ * used `ai.oversky.*`. Both are listed, because preflight has to recognise a
+ * machine carrying either.
+ */
+export declare const LEGACY_NATIVE_ID_PREFIXES: readonly ["ai.oversky", "com.oversky"];
+/** The user-facing binary name used in reauth messages. Overridden per runtime. */
+export declare const DEFAULT_BINARY_NAME = "skrrd";

package/dist/esm/localIdentity.js

@@ -0,0 +1,54 @@
+/**
+ * The names this product uses for state it leaves on a machine.
+ *
+ * WHY THESE LIVE IN ONE PLACE NOW
+ * ------------------------------
+ * Before the OverSky → skrr rename, `'.oversky'` was written as a literal in 47
+ * places across `auth-core`, `cli`, `daemon` and `desktop`, and the Keychain
+ * service prefix in about as many. Nothing related them, so nothing could tell
+ * you whether a given path was the machine root, a profile directory, or a
+ * coincidence — and changing the value meant finding all 47 and hoping.
+ *
+ * `auth-core` is the right home because it is the one module all three runtimes
+ * already import: the CLI (42 files), the daemon (35) and Desktop (5).
+ *
+ * WHAT MAKES THESE DIFFERENT FROM COPY
+ * ------------------------------------
+ * A name here ADDRESSES state that already exists on a real machine. Changing
+ * `CONFIG_DIR_NAME` does not move `~/.oversky` to `~/.skrr` — it makes the old
+ * directory unreachable and starts a new, empty one. The same is true of the
+ * Keychain service: an item is addressed BY service name, so a rename orphans
+ * the wrapped credential rather than migrating it.
+ *
+ * That is the intended behaviour under the pre-launch clean break (§0.1
+ * confirmed 2026-08-31: no external users, and the team accepts re-login). It is
+ * only safe because of the LEGACY_ values below, which exist so install
+ * preflight can NAME the old state in order to detect and refuse it. Preflight
+ * cannot refuse what it cannot name.
+ */
+/** Machine-scoped state root, relative to the user's home directory. */
+export const CONFIG_DIR_NAME = '.skrr';
+/**
+ * Roots this product used before, newest first.
+ *
+ * NOT a compatibility path — nothing reads state from these. They exist so
+ * install preflight and the team cutover runbook can detect a machine that
+ * still carries old state and refuse to run beside it (§5.5: the same machine
+ * must never have an old and a new runtime live at once).
+ *
+ * `.sky` predates `.oversky` and was already handled as a legacy path before
+ * this rename, so it is carried forward rather than forgotten.
+ */
+export const LEGACY_CONFIG_DIR_NAMES = ['.oversky', '.sky'];
+/** Prefix for OS service labels and Keychain services (`ai.skrr.daemon`, …). */
+export const NATIVE_ID_PREFIX = 'ai.skrr';
+/**
+ * The previous native prefix, for the same detect-and-refuse reason.
+ *
+ * Note the KEK identifier used `com.oversky.daemon.kek` while everything else
+ * used `ai.oversky.*`. Both are listed, because preflight has to recognise a
+ * machine carrying either.
+ */
+export const LEGACY_NATIVE_ID_PREFIXES = ['ai.oversky', 'com.oversky'];
+/** The user-facing binary name used in reauth messages. Overridden per runtime. */
+export const DEFAULT_BINARY_NAME = 'skrrd';

package/dist/esm/loginLocalhost.d.ts

@@ -0,0 +1,115 @@
+/** Default total wait (ms) for the callback. Matches consent-page UX. */
+export declare const DEFAULT_LOGIN_TIMEOUT_MS: number;
+export interface StartLocalCallbackOptions {
+    /**
+     * PKCE state parameter — must match the value sent to the consent
+     * page in `/api/auth/cli-init`. Generate via `pkce.generateState()`.
+     */
+    state: string;
+    /**
+     * Port to bind. 0 (default) requests an ephemeral kernel-assigned
+     * port. Pin a port (via `--port` or `OVERSKY_LOGIN_PORT`) when the
+     * user is in a firewall-allowlisted environment that pre-opened a
+     * single localhost port for OAuth flows.
+     */
+    port?: number;
+    /**
+     * Total time the server waits for a callback before timing out.
+     * Default 2 minutes. After this elapses the server closes and the
+     * callback promise rejects with `LocalCallbackTimeoutError`.
+     */
+    timeoutMs?: number;
+    /**
+     * Multica-convergence (P1 #5) — override the host that appears in
+     * `redirectUri` AND the listen address. Defaults to `'127.0.0.1'`
+     * and SHOULD stay that way for every local-browser flow.
+     *
+     * The override exists for one legitimate case: the CLI is on a
+     * different machine than the browser (e.g. a LAN-only dev box a
+     * teammate's browser needs to reach). In that scenario the user
+     * passes `--callback-host <lan-ip>` and the server binds on that
+     * interface so the browser can reach it.
+     *
+     * Binding a non-loopback host widens the blast radius — any device
+     * on that network segment can race the browser to the callback.
+     * Callers SHOULD only enable this after confirming with the user
+     * that the LAN is trusted. A warning is emitted on non-loopback
+     * binds.
+     *
+     * SSH port-forward users DO NOT need this — forwarding
+     * `-L 1455:127.0.0.1:1455` makes the remote's 127.0.0.1 reachable
+     * from the local browser without touching `host`.
+     */
+    host?: string;
+    /**
+     * Optional split between bind address and URL host. When provided,
+     * the server listens on `bindAddr` and the `redirectUri` is built
+     * from `host`. Use sparingly — e.g. `bindAddr='0.0.0.0'` with
+     * `host='10.0.0.5'` lets a browser on a teammate's machine reach
+     * a CLI on the LAN without hardcoding the LAN IP into the bind.
+     *
+     * Defaults to `host` when omitted.
+     */
+    bindAddr?: string;
+}
+export interface LocalCallbackResult {
+    /** Authorization code returned by the server (single-use). */
+    code: string;
+    /** State echoed back, post-validation. */
+    state: string;
+    /**
+     * The redirect URI this server bound to. Caller MUST pass this same
+     * string to /cli-init AND /cli-token-exchange (RFC 6749 §4.1.3
+     * redirect_uri-binding requirement).
+     */
+    redirectUri: string;
+}
+export interface LocalCallbackHandle {
+    /**
+     * Bound redirect URI in the form `http://127.0.0.1:<port>/callback`.
+     * Available synchronously after `startLocalCallback()` resolves.
+     */
+    redirectUri: string;
+    /**
+     * Resolves with the callback result on the first valid callback.
+     * Rejects on timeout, denial, state mismatch, malformed callback,
+     * post-bind server error, or caller cancellation. Safe to call
+     * multiple times — returns the same promise.
+     */
+    waitForCallback(): Promise<LocalCallbackResult>;
+    /** Cancel the wait and tear down the server. Idempotent. */
+    close(): void;
+}
+export declare class LocalCallbackError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class LocalCallbackBindError extends LocalCallbackError {
+    readonly port: number;
+    readonly cause?: Error;
+    constructor(port: number, cause?: Error);
+}
+export declare class LocalCallbackTimeoutError extends LocalCallbackError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+export declare class LocalCallbackStateMismatchError extends LocalCallbackError {
+    constructor();
+}
+export declare class LocalCallbackDeniedError extends LocalCallbackError {
+    readonly serverError: string;
+    constructor(serverError: string, description?: string);
+}
+export declare class LocalCallbackMalformedError extends LocalCallbackError {
+    constructor(reason: string);
+}
+/**
+ * Start the local 127.0.0.1 callback server. Binds synchronously
+ * (await'd via the listen handshake) and returns a handle whose
+ * `redirectUri` is immediately usable. The caller drives the rest of
+ * the flow and awaits `waitForCallback()` when ready.
+ *
+ * Throws `LocalCallbackBindError` if the bind fails (caller decides
+ * whether to retry on a different port or fall back to device-code).
+ */
+export declare function startLocalCallback(opts: StartLocalCallbackOptions): Promise<LocalCallbackHandle>;