@capgo/cli/dist/src/auth/session.d.ts

A CLI to upload to capgo servers

/**
 * Shared, UI-free authentication core.
 *
 * `cli/src/login.ts` (the interactive `capgo login` command) and the MCP login
 * tools (`capgo_login` / `capgo_whoami` / `capgo_logout`) all funnel through these
 * helpers so there is a single validate / persist / introspect path — no forked
 * security logic. The user-facing message builders live here too (pure functions)
 * so the tool wording is covered by unit tests rather than only the integration
 * smoke test.
 */
export type KeySource = 'env' | 'global' | 'local';
export interface LoginState {
    loggedIn: boolean;
    /** Resolved user id — only populated when `validate` succeeded. */
    userId?: string;
    /** Where the resolved key came from, if any (also set when a present key fails validation). */
    source?: KeySource;
    /**
     * Only meaningful when `validate` was requested. `true` = confirmed valid this
     * call; `false` = a key is present but could NOT be verified (network/server
     * error), so it is reported as still-logged-in-but-unverified rather than as a
     * definitive sign-out. Undefined when no validation was attempted.
     */
    verified?: boolean;
}
export interface SaveKeyOptions {
    /** Persist to `./.capgo` (project-local) instead of `~/.capgo` (global). */
    local?: boolean;
    supaHost?: string;
    supaAnon?: string;
}
/**
 * Validate an API key against Capgo and, if valid, persist it (0o600).
 * Returns the resolved user id. Throws on a missing/invalid key or a disallowed
 * local write (local requires a git repository, mirroring `capgo login --local`).
 *
 * Nothing is written when validation fails.
 */
export declare function validateAndSaveKey(apikey: string, options?: SaveKeyOptions): Promise<{
    userId: string;
}>;
/**
 * Report whether a saved key exists.
 *
 * Presence-only by default (no network) so it is cheap enough to gate every tool
 * call. Pass `{ validate: true }` (used by `capgo_whoami`) to additionally confirm
 * the key still authenticates and resolve the user id.
 */
export declare function getLoginState(options?: {
    validate?: boolean;
}): Promise<LoginState>;
/**
 * Remove the saved key. Clears the global key (`~/.capgo`) by default, or the
 * project-local key (`./.capgo`) when `local` is set. Never touches `CAPGO_TOKEN`
 * (an env var is not ours to unset). Returns whether a file was actually removed.
 */
export declare function clearSavedKey(options?: {
    local?: boolean;
}): Promise<{
    cleared: boolean;
}>;
/** Success text for capgo_login. */
export declare function loginSuccessMessage(userId: string, local: boolean): string;
/** Status text for capgo_whoami, covering verified / unverified / invalid / signed-out. */
export declare function whoamiMessage(state: LoginState): string;
/**
 * Honest text for capgo_logout. `remaining` is the post-clear login state: if a
 * credential is still reachable (CAPGO_TOKEN, or the other on-disk scope) we say
 * so explicitly instead of falsely claiming the session is signed out.
 */
export declare function logoutMessage(cleared: boolean, removedLocal: boolean, remaining: LoginState): string;