@layr-labs/benchmaxx-arena-mcp 0.1.0

package/dist/config.js

@@ -0,0 +1,47 @@
+/**
+ * Configuration for the benchmaxx-arena MCP server.
+ *
+ * The only knob is the base-URL origin. `BENCHMAXX_ARENA_URL` overrides it;
+ * only the origin (scheme, host, port) is used, any path is dropped. The
+ * default is production. A bearer key travels on this transport, so the scheme
+ * must be `https`, with the single exception of `http://localhost` and
+ * `http://127.0.0.1` for local development.
+ */
+export const PRODUCTION_ORIGIN = 'https://harnessarena.xyz';
+export const ARENA_URL_ENV = 'BENCHMAXX_ARENA_URL';
+/** A loopback host may use plain http; every other host must use https. */
+function isLoopbackHost(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+/**
+ * Normalize a raw URL string to its origin. Throws on a malformed URL or a
+ * scheme that would send a credential in cleartext to a non-loopback host.
+ */
+export function normalizeOrigin(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new Error(`${ARENA_URL_ENV} is not a valid URL: ${raw}. Use a full origin such as https://harnessarena.xyz.`);
+    }
+    if (parsed.protocol === 'https:') {
+        return parsed.origin;
+    }
+    if (parsed.protocol === 'http:' && isLoopbackHost(parsed.hostname)) {
+        return parsed.origin;
+    }
+    throw new Error(`${ARENA_URL_ENV} must use https (http is allowed only for localhost): ${raw}.`);
+}
+/**
+ * Resolve the configuration from an environment map. Defaults to production
+ * when the override is absent or empty.
+ */
+export function loadConfig(env = process.env) {
+    const raw = env[ARENA_URL_ENV];
+    if (raw === undefined || raw.trim() === '') {
+        return { origin: PRODUCTION_ORIGIN };
+    }
+    return { origin: normalizeOrigin(raw.trim()) };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,0BAA0B,CAAA;AAE3D,MAAM,CAAC,MAAM,aAAa,GAAG,qBAAqB,CAAA;AAElD,2EAA2E;AAC3E,SAAS,cAAc,CAAC,QAAgB;IACtC,OAAO,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,OAAO,CAAA;AACrF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,IAAI,MAAW,CAAA;IACf,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,GAAG,aAAa,wBAAwB,GAAG,uDAAuD,CACnG,CAAA;IACH,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,OAAO,MAAM,CAAC,MAAM,CAAA;IACtB,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnE,OAAO,MAAM,CAAC,MAAM,CAAA;IACtB,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,GAAG,aAAa,yDAAyD,GAAG,GAAG,CAAC,CAAA;AAClG,CAAC;AAOD;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,GAAG,GAAG,GAAG,CAAC,aAAa,CAAC,CAAA;IAC9B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3C,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAA;IACtC,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAA;AAChD,CAAC"}

package/dist/credentialStore.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Durable, secure storage for the minted API key.
+ *
+ * The store writes `~/.benchmaxx/credentials.json`: versioned JSON keyed by the
+ * base-URL origin, so one file holds many deployments. The directory is `0700`
+ * and the file is `0600`. Those modes are enforced on every write, and a
+ * pre-existing loose mode is repaired on read, because a `mode` on an open of
+ * an already-existing file is a no-op — the file could predate this code with a
+ * looser mode. A symlink at either path is refused.
+ *
+ * The filesystem and the home directory are injected so the store is
+ * unit-testable without touching a real home directory. The token is never
+ * logged.
+ */
+export declare const CREDENTIALS_VERSION = 1;
+/** One stored credential: the non-secret identity plus the secret token. */
+export interface StoredCredential {
+    token: string;
+    keyId: string;
+    keyPrefix: string;
+    username: string;
+}
+/** The on-disk shape: versioned, keyed by origin. */
+export interface CredentialsFile {
+    version: number;
+    credentials: Record<string, StoredCredential>;
+}
+/** The subset of node:fs/promises the store needs, injected for testing. */
+export interface FsLike {
+    mkdir(path: string, options: {
+        recursive: boolean;
+        mode: number;
+    }): Promise<unknown>;
+    chmod(path: string, mode: number): Promise<void>;
+    readFile(path: string, encoding: 'utf8'): Promise<string>;
+    writeFile(path: string, data: string, options: {
+        mode: number;
+        flag?: string;
+    }): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    rm(path: string, options: {
+        force: boolean;
+    }): Promise<void>;
+    lstat(path: string): Promise<{
+        isSymbolicLink(): boolean;
+        mode: number;
+    }>;
+}
+/** A malformed or unreadable credentials file that the user must fix. */
+export declare class CredentialsFileError extends Error {
+    constructor(message: string);
+}
+export interface CredentialStoreOptions {
+    fs: FsLike;
+    homeDir: string;
+    /** Path join, injected so tests need no node:path. Defaults to posix join. */
+    join?: (...parts: string[]) => string;
+    /**
+     * Suffix for the temp file each write owns. Injected so a test can assert the
+     * exact temp path. Defaults to the pid plus random bytes.
+     */
+    uniqueSuffix?: () => string;
+}
+export declare class CredentialStore {
+    private readonly fs;
+    private readonly dir;
+    private readonly file;
+    private readonly join;
+    private readonly uniqueSuffix;
+    constructor(options: CredentialStoreOptions);
+    /** Read the credential for one origin, or undefined when not authenticated. */
+    get(origin: string): Promise<StoredCredential | undefined>;
+    /** Store the credential for one origin, replacing any prior value. */
+    set(origin: string, credential: StoredCredential): Promise<void>;
+    /** Delete the credential for one origin. Returns true when one was removed. */
+    delete(origin: string): Promise<boolean>;
+    /**
+     * Read and parse the file. A missing file is "not authenticated" (an empty
+     * store). A present-but-unreadable or invalid-JSON file is a hard error the
+     * user must fix or delete. Repairs a loose file mode and refuses a symlink.
+     */
+    private read;
+    /**
+     * Write atomically. Refuse a symlinked directory (following it would drop the
+     * 0600 credential at an attacker-chosen target and defeat the 0700
+     * containment). Create the 0700 dir, then write a temp file with the
+     * exclusive `wx` flag so an attacker-planted temp symlink fails the open
+     * rather than being followed. chmod it (the open mode is a no-op on an
+     * existing file), then rename it into place and re-chmod.
+     *
+     * The temp name is unique per write. A single fixed `credentials.json.tmp`
+     * made concurrent writers collide: two servers (or a retried login) sharing
+     * one home directory would have the second `wx` open fail on the first's temp,
+     * or — worse, once the stale temp was force-removed — race on the same path
+     * and interleave. A unique name means each writer owns its temp and the
+     * rename is the only contended step, which is atomic. The temp is removed if
+     * anything after the open fails, so a crashed write leaves no 0600 litter.
+     */
+    private write;
+    private assertNotSymlink;
+    /** Tighten a pre-existing group/world-accessible path back to the target mode. */
+    private repairMode;
+}

package/dist/credentialStore.js

@@ -0,0 +1,168 @@
+/**
+ * Durable, secure storage for the minted API key.
+ *
+ * The store writes `~/.benchmaxx/credentials.json`: versioned JSON keyed by the
+ * base-URL origin, so one file holds many deployments. The directory is `0700`
+ * and the file is `0600`. Those modes are enforced on every write, and a
+ * pre-existing loose mode is repaired on read, because a `mode` on an open of
+ * an already-existing file is a no-op — the file could predate this code with a
+ * looser mode. A symlink at either path is refused.
+ *
+ * The filesystem and the home directory are injected so the store is
+ * unit-testable without touching a real home directory. The token is never
+ * logged.
+ */
+import { randomBytes } from 'node:crypto';
+export const CREDENTIALS_VERSION = 1;
+/** A malformed or unreadable credentials file that the user must fix. */
+export class CredentialsFileError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CredentialsFileError';
+    }
+}
+function isNotFound(error) {
+    return error?.code === 'ENOENT';
+}
+const defaultJoin = (...parts) => parts.join('/');
+const defaultUniqueSuffix = () => `${process.pid}.${randomBytes(6).toString('hex')}`;
+export class CredentialStore {
+    fs;
+    dir;
+    file;
+    join;
+    uniqueSuffix;
+    constructor(options) {
+        this.fs = options.fs;
+        this.join = options.join ?? defaultJoin;
+        this.uniqueSuffix = options.uniqueSuffix ?? defaultUniqueSuffix;
+        this.dir = this.join(options.homeDir, '.benchmaxx');
+        this.file = this.join(this.dir, 'credentials.json');
+    }
+    /** Read the credential for one origin, or undefined when not authenticated. */
+    async get(origin) {
+        const file = await this.read();
+        return file.credentials[origin];
+    }
+    /** Store the credential for one origin, replacing any prior value. */
+    async set(origin, credential) {
+        const file = await this.read();
+        file.credentials[origin] = credential;
+        await this.write(file);
+    }
+    /** Delete the credential for one origin. Returns true when one was removed. */
+    async delete(origin) {
+        const file = await this.read();
+        if (!(origin in file.credentials)) {
+            return false;
+        }
+        delete file.credentials[origin];
+        await this.write(file);
+        return true;
+    }
+    /**
+     * Read and parse the file. A missing file is "not authenticated" (an empty
+     * store). A present-but-unreadable or invalid-JSON file is a hard error the
+     * user must fix or delete. Repairs a loose file mode and refuses a symlink.
+     */
+    async read() {
+        let raw;
+        try {
+            await this.assertNotSymlink(this.dir);
+            await this.assertNotSymlink(this.file);
+            raw = await this.fs.readFile(this.file, 'utf8');
+        }
+        catch (error) {
+            if (isNotFound(error)) {
+                return { version: CREDENTIALS_VERSION, credentials: {} };
+            }
+            if (error instanceof CredentialsFileError) {
+                throw error;
+            }
+            throw new CredentialsFileError(`cannot read ${this.file}. Fix its permissions or delete it, then run the login tool again.`);
+        }
+        await this.repairMode(this.dir, 0o700);
+        await this.repairMode(this.file, 0o600);
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new CredentialsFileError(`${this.file} is not valid JSON. Delete it, then run the login tool again.`);
+        }
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            typeof parsed.credentials !== 'object' ||
+            parsed.credentials === null) {
+            throw new CredentialsFileError(`${this.file} has an unexpected shape. Delete it, then run the login tool again.`);
+        }
+        const file = parsed;
+        return { version: file.version ?? CREDENTIALS_VERSION, credentials: file.credentials };
+    }
+    /**
+     * Write atomically. Refuse a symlinked directory (following it would drop the
+     * 0600 credential at an attacker-chosen target and defeat the 0700
+     * containment). Create the 0700 dir, then write a temp file with the
+     * exclusive `wx` flag so an attacker-planted temp symlink fails the open
+     * rather than being followed. chmod it (the open mode is a no-op on an
+     * existing file), then rename it into place and re-chmod.
+     *
+     * The temp name is unique per write. A single fixed `credentials.json.tmp`
+     * made concurrent writers collide: two servers (or a retried login) sharing
+     * one home directory would have the second `wx` open fail on the first's temp,
+     * or — worse, once the stale temp was force-removed — race on the same path
+     * and interleave. A unique name means each writer owns its temp and the
+     * rename is the only contended step, which is atomic. The temp is removed if
+     * anything after the open fails, so a crashed write leaves no 0600 litter.
+     */
+    async write(file) {
+        await this.assertNotSymlink(this.dir);
+        await this.fs.mkdir(this.dir, { recursive: true, mode: 0o700 });
+        await this.fs.chmod(this.dir, 0o700);
+        const tmp = `${this.file}.${this.uniqueSuffix()}.tmp`;
+        const data = JSON.stringify({ version: CREDENTIALS_VERSION, credentials: file.credentials }, null, 2);
+        await this.fs.writeFile(tmp, data, { mode: 0o600, flag: 'wx' });
+        try {
+            await this.fs.chmod(tmp, 0o600);
+            await this.fs.rename(tmp, this.file);
+        }
+        catch (error) {
+            // The temp still holds the token; do not leave it behind on failure.
+            await this.fs.rm(tmp, { force: true }).catch(() => { });
+            throw error;
+        }
+        await this.fs.chmod(this.file, 0o600);
+    }
+    async assertNotSymlink(path) {
+        let stat;
+        try {
+            stat = await this.fs.lstat(path);
+        }
+        catch (error) {
+            if (isNotFound(error)) {
+                return;
+            }
+            throw error;
+        }
+        if (stat.isSymbolicLink()) {
+            throw new CredentialsFileError(`${path} is a symlink, which is refused for a credential file. Delete it, then run the login tool again.`);
+        }
+    }
+    /** Tighten a pre-existing group/world-accessible path back to the target mode. */
+    async repairMode(path, targetMode) {
+        try {
+            const stat = await this.fs.lstat(path);
+            const looseBits = stat.mode & 0o077;
+            if (looseBits !== 0) {
+                await this.fs.chmod(path, targetMode);
+            }
+        }
+        catch (error) {
+            if (isNotFound(error)) {
+                return;
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=credentialStore.js.map

package/dist/credentialStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentialStore.js","sourceRoot":"","sources":["../src/credentialStore.ts"],"names":[],"mappings":"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"}

package/dist/device.d.ts

@@ -0,0 +1,87 @@
+/**
+ * GitHub device-flow poll loop.
+ *
+ * The primitives (`nextPollDelay`, `devicePollDeadline`, `assertBeforeDevicePoll`)
+ * are ported from frontend/src/workbench/device.ts so the two clients honor the
+ * same PENDING/SLOW_DOWN/expiry rules. `runDevicePoll` drives them with an
+ * injected clock, sleep, and poll function, so the loop is unit-testable with no
+ * wall-clock and no network.
+ */
+export declare const DEVICE_STATUS: {
+    readonly UNSPECIFIED: "DEVICE_AUTHORIZATION_STATUS_UNSPECIFIED";
+    readonly PENDING: "DEVICE_AUTHORIZATION_STATUS_PENDING";
+    readonly SLOW_DOWN: "DEVICE_AUTHORIZATION_STATUS_SLOW_DOWN";
+    readonly EXPIRED: "DEVICE_AUTHORIZATION_STATUS_EXPIRED";
+    readonly DENIED: "DEVICE_AUTHORIZATION_STATUS_DENIED";
+    readonly SUCCESS: "DEVICE_AUTHORIZATION_STATUS_SUCCESS";
+};
+/** Minted credentials returned on a successful poll. */
+export interface DeviceCredentials {
+    token: string;
+    id: string;
+    prefix: string;
+}
+/**
+ * One poll outcome, the fields of PollDeviceResponse this loop reads.
+ *
+ * `credentials` is a message field and the gateway sets EmitUnpopulated, so a
+ * pending poll carries an explicit `null` rather than omitting the key. The
+ * SUCCESS branch's falsy check covers both.
+ */
+export interface DeviceOutcome {
+    status?: string;
+    pending?: boolean;
+    retryAfterSeconds?: number;
+    errorCode?: string;
+    credentials?: DeviceCredentials | null;
+    username?: string;
+}
+/**
+ * The next poll delay in seconds for a non-terminal outcome, or undefined when
+ * the outcome is terminal. Honors the server's retry hint but never goes below
+ * the previous delay (GitHub's cumulative slow_down behavior).
+ */
+export declare function nextPollDelay(previousSeconds: number, outcome: DeviceOutcome): number | undefined;
+/** Absolute deadline (ms epoch) after which polling must stop. */
+export declare function devicePollDeadline(expiresInSeconds: number, now: number): number;
+/** Throw when the deadline has passed. */
+export declare function assertBeforeDevicePoll(deadline: number, now: number): void;
+/** Raised when the caller cancels the login. */
+export declare class DeviceLoginCancelled extends Error {
+    constructor();
+}
+export interface DevicePollDeps {
+    /** Sleep for a number of milliseconds. */
+    sleep: (ms: number) => Promise<void>;
+    /** Current time in ms epoch. */
+    now: () => number;
+    /** Perform one poll of the device-token endpoint. */
+    poll: (pollIntervalSeconds: number) => Promise<DeviceOutcome>;
+    /**
+     * Cancellation from the caller. Checked at both loop boundaries, so an
+     * abandoned login stops polling instead of running to the device deadline.
+     */
+    signal?: AbortSignal;
+    /**
+     * Called before each wait. Used to emit progress so an MCP host sees liveness
+     * and does not time the tool out while the human is approving.
+     */
+    onWait?: () => Promise<void> | void;
+}
+export interface DevicePollParams {
+    /** Initial poll interval from DeviceAuthorizationResponse.interval. */
+    intervalSeconds: number;
+    /** Device authorization lifetime from DeviceAuthorizationResponse.expiresIn. */
+    expiresInSeconds: number;
+}
+/** The identity produced by a successful device flow. */
+export interface DeviceLoginResult {
+    credentials: DeviceCredentials;
+    username: string;
+}
+/**
+ * Poll until the device authorization is approved, denied, or expired. Returns
+ * the credentials on SUCCESS. Throws a clear, actionable error on DENIED,
+ * EXPIRED, or the deadline.
+ */
+export declare function runDevicePoll(deps: DevicePollDeps, params: DevicePollParams): Promise<DeviceLoginResult>;

package/dist/device.js

@@ -0,0 +1,92 @@
+/**
+ * GitHub device-flow poll loop.
+ *
+ * The primitives (`nextPollDelay`, `devicePollDeadline`, `assertBeforeDevicePoll`)
+ * are ported from frontend/src/workbench/device.ts so the two clients honor the
+ * same PENDING/SLOW_DOWN/expiry rules. `runDevicePoll` drives them with an
+ * injected clock, sleep, and poll function, so the loop is unit-testable with no
+ * wall-clock and no network.
+ */
+export const DEVICE_STATUS = {
+    UNSPECIFIED: 'DEVICE_AUTHORIZATION_STATUS_UNSPECIFIED',
+    PENDING: 'DEVICE_AUTHORIZATION_STATUS_PENDING',
+    SLOW_DOWN: 'DEVICE_AUTHORIZATION_STATUS_SLOW_DOWN',
+    EXPIRED: 'DEVICE_AUTHORIZATION_STATUS_EXPIRED',
+    DENIED: 'DEVICE_AUTHORIZATION_STATUS_DENIED',
+    SUCCESS: 'DEVICE_AUTHORIZATION_STATUS_SUCCESS',
+};
+/**
+ * The next poll delay in seconds for a non-terminal outcome, or undefined when
+ * the outcome is terminal. Honors the server's retry hint but never goes below
+ * the previous delay (GitHub's cumulative slow_down behavior).
+ */
+export function nextPollDelay(previousSeconds, outcome) {
+    if (outcome.status === DEVICE_STATUS.PENDING || outcome.status === DEVICE_STATUS.SLOW_DOWN) {
+        return Math.max(previousSeconds, outcome.retryAfterSeconds ?? previousSeconds);
+    }
+    return undefined;
+}
+/** Absolute deadline (ms epoch) after which polling must stop. */
+export function devicePollDeadline(expiresInSeconds, now) {
+    if (!Number.isFinite(expiresInSeconds) || expiresInSeconds <= 0) {
+        throw new Error('device authorization expiry is invalid');
+    }
+    return now + expiresInSeconds * 1000;
+}
+/** Throw when the deadline has passed. */
+export function assertBeforeDevicePoll(deadline, now) {
+    if (now >= deadline) {
+        throw new Error('device authorization expired before you approved it — run the login tool again.');
+    }
+}
+/** Raised when the caller cancels the login. */
+export class DeviceLoginCancelled extends Error {
+    constructor() {
+        super('the login was cancelled.');
+        this.name = 'DeviceLoginCancelled';
+    }
+}
+function assertNotCancelled(signal) {
+    if (signal?.aborted) {
+        throw new DeviceLoginCancelled();
+    }
+}
+/**
+ * Poll until the device authorization is approved, denied, or expired. Returns
+ * the credentials on SUCCESS. Throws a clear, actionable error on DENIED,
+ * EXPIRED, or the deadline.
+ */
+export async function runDevicePoll(deps, params) {
+    const deadline = devicePollDeadline(params.expiresInSeconds, deps.now());
+    let delaySeconds = Math.max(1, params.intervalSeconds);
+    for (;;) {
+        assertNotCancelled(deps.signal);
+        assertBeforeDevicePoll(deadline, deps.now());
+        await deps.onWait?.();
+        await deps.sleep(delaySeconds * 1000);
+        // Recheck after the wait: cancellation almost always lands during it.
+        assertNotCancelled(deps.signal);
+        assertBeforeDevicePoll(deadline, deps.now());
+        const outcome = await deps.poll(delaySeconds);
+        if (outcome.status === DEVICE_STATUS.SUCCESS) {
+            if (!outcome.credentials || !outcome.username) {
+                throw new Error('the arena approved the login but returned no credentials — try again.');
+            }
+            return { credentials: outcome.credentials, username: outcome.username };
+        }
+        if (outcome.status === DEVICE_STATUS.DENIED) {
+            throw new Error('the login request was denied on GitHub — run the login tool again to retry.');
+        }
+        if (outcome.status === DEVICE_STATUS.EXPIRED) {
+            throw new Error('device authorization expired before you approved it — run the login tool again.');
+        }
+        const next = nextPollDelay(delaySeconds, outcome);
+        if (next === undefined) {
+            // Unknown or unspecified status: treat as an unrecoverable failure rather
+            // than looping forever.
+            throw new Error('the login could not complete — run the login tool again.');
+        }
+        delaySeconds = next;
+    }
+}
+//# sourceMappingURL=device.js.map

package/dist/device.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.js","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Error types and the mapping from an API failure to one actionable message.
+ *
+ * Two failure kinds reach a tool:
+ *  - `ApiError`: a non-2xx HTTP response. It carries the status and the
+ *    server's `rpcStatus.message` (mirrors frontend/src/api/http.ts).
+ *  - `NetworkError`: the fetch itself rejected (DNS, connection refused, TLS).
+ *
+ * `toActionableMessage` turns either into a single message per issue #166 §5.4.
+ * It never includes a stack trace, a raw response body, or the bearer token.
+ */
+/** A failed HTTP call. `message` is the server's message; `status` is the code. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** The fetch rejected before any HTTP status was seen. */
+export declare class NetworkError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when the caller cancels a login.
+ *
+ * This lives here rather than in the flow that throws it, so both the client and
+ * the loopback listener raise the one type `toActionableMessage` recognizes. A
+ * plain `Error` would fall through to the generic copy and lose the friendly
+ * message.
+ */
+export declare class LoginCancelled extends Error {
+    constructor();
+}
+/** Raised when the loopback listener's deadline passes before a code arrives. */
+export declare class LoginTimedOut extends Error {
+    constructor();
+}
+/**
+ * Raised when POST /v1/auth/cli/redeem rejects the code or the verifier.
+ *
+ * A redeem 401 is NOT a revoked stored key — no stored key is involved — so it
+ * must not reach the generic 401 mapping, which would tell the user to log in
+ * again with no hint that their code is simply spent.
+ */
+export declare class CliRedeemFailed extends Error {
+    constructor();
+}
+/**
+ * Map any thrown failure to one actionable message. Leaks no internals: an
+ * unknown error becomes a generic message, never a raw string or stack.
+ */
+export declare function toActionableMessage(error: unknown): string;