voratiq 0.1.0-beta.26 → 0.1.0-beta.27

package/dist/app-session/api-client.d.ts

@@ -0,0 +1,42 @@
+import type { AppSessionPayload } from "./session.js";
+export declare const DEFAULT_CLI_SESSION_REFRESH_WINDOW_MS = 60000;
+export declare class AppApiError extends Error {
+    readonly code: string | null;
+    readonly statusCode: number;
+    constructor(message: string, code: string | null, statusCode: number);
+}
+export declare class AppSessionRefreshResponseError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface CreateCliLoginAttemptResult {
+    attemptId: string;
+    authorizeUrl: string;
+    expiresAt: string;
+}
+export interface RefreshCliSessionOptions {
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    now?: () => Date;
+    signal?: AbortSignal;
+}
+export declare function resolveVoratiqApiOrigin(env?: NodeJS.ProcessEnv): string;
+export declare function resolveVoratiqAppOrigin(env?: NodeJS.ProcessEnv): string;
+export declare function buildAppApiUrl(path: string, options?: {
+    env?: NodeJS.ProcessEnv;
+}): URL;
+export declare function readAppApiError(response: Response): Promise<AppApiError>;
+export declare function isAbortError(error: unknown): boolean;
+export declare function throwIfAppApiRequestAborted(signal?: AbortSignal): void;
+export declare function createCliLoginAttempt(input: {
+    installationId: string;
+    callbackUrl: string;
+    callbackState: string;
+}, env?: NodeJS.ProcessEnv): Promise<CreateCliLoginAttemptResult>;
+export declare function exchangeCliLoginCode(input: {
+    code: string;
+}, env?: NodeJS.ProcessEnv): Promise<AppSessionPayload>;
+export declare function refreshCliSession(input: {
+    refreshToken: string;
+}, options?: RefreshCliSessionOptions): Promise<AppSessionPayload>;

package/dist/app-session/api-client.js

@@ -0,0 +1,143 @@
+import { parseAppSessionPayloadFromUnknown } from "./state.js";
+const DEFAULT_API_ORIGIN = "https://voratiq-api.fly.dev";
+const DEFAULT_APP_ORIGIN = "https://voratiq.com";
+export const DEFAULT_CLI_SESSION_REFRESH_WINDOW_MS = 60_000;
+export class AppApiError extends Error {
+    code;
+    statusCode;
+    constructor(message, code, statusCode) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.name = "AppApiError";
+    }
+}
+export class AppSessionRefreshResponseError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "AppSessionRefreshResponseError";
+    }
+}
+export function resolveVoratiqApiOrigin(env = process.env) {
+    return env.VORATIQ_API_ORIGIN?.trim() || DEFAULT_API_ORIGIN;
+}
+export function resolveVoratiqAppOrigin(env = process.env) {
+    return env.VORATIQ_SITE_URL?.trim() || DEFAULT_APP_ORIGIN;
+}
+export function buildAppApiUrl(path, options = {}) {
+    const origin = resolveVoratiqApiOrigin(options.env ?? process.env);
+    return new URL(path, new URL("/api/v1/", origin));
+}
+export async function readAppApiError(response) {
+    try {
+        const payload = (await response.json());
+        return new AppApiError(payload.error?.message ?? `${response.status} ${response.statusText}`, payload.error?.code ?? null, response.status);
+    }
+    catch {
+        return new AppApiError(`${response.status} ${response.statusText}`, null, response.status);
+    }
+}
+export function isAbortError(error) {
+    return (hasErrorName(error) &&
+        (error.name === "AbortError" || error.name === "TimeoutError"));
+}
+export function throwIfAppApiRequestAborted(signal) {
+    if (!signal?.aborted) {
+        return;
+    }
+    signal.throwIfAborted();
+}
+export async function createCliLoginAttempt(input, env = process.env) {
+    const response = await fetch(buildAppApiUrl("auth/cli/attempts", { env }), {
+        method: "POST",
+        headers: {
+            accept: "application/json",
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({
+            ...input,
+            appOrigin: resolveVoratiqAppOrigin(env),
+        }),
+    });
+    if (!response.ok) {
+        throw await readAppApiError(response);
+    }
+    return (await response.json());
+}
+export async function exchangeCliLoginCode(input, env = process.env) {
+    const response = await fetch(buildAppApiUrl("auth/cli/exchange", { env }), {
+        method: "POST",
+        headers: {
+            accept: "application/json",
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(input),
+    });
+    if (!response.ok) {
+        throw await readAppApiError(response);
+    }
+    const payload = (await response.json());
+    return parseAppSessionPayloadFromUnknown(payload, "Voratiq App exchange response");
+}
+export async function refreshCliSession(input, options = {}) {
+    const env = options.env ?? process.env;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const now = options.now ?? (() => new Date());
+    const response = await fetchImpl(buildAppApiUrl("auth/cli/refresh", {
+        env,
+    }), {
+        method: "POST",
+        headers: {
+            accept: "application/json",
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({
+            refreshToken: input.refreshToken,
+        }),
+        signal: options.signal,
+    });
+    if (!response.ok) {
+        throw await readAppApiError(response);
+    }
+    let payload;
+    try {
+        payload = (await response.json());
+    }
+    catch (error) {
+        throw new AppSessionRefreshResponseError("Invalid Voratiq App refresh response: expected JSON.", {
+            cause: error,
+        });
+    }
+    let refreshedSession;
+    try {
+        refreshedSession = parseAppSessionPayloadFromUnknown(payload, "Voratiq App refresh response");
+    }
+    catch (error) {
+        throw new AppSessionRefreshResponseError("Invalid Voratiq App refresh response: expected a complete CLI session payload.", {
+            cause: error,
+        });
+    }
+    validateRefreshedSessionPayload(refreshedSession, now());
+    return refreshedSession;
+}
+function hasErrorName(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "name" in error &&
+        typeof error.name === "string");
+}
+function validateRefreshedSessionPayload(payload, now) {
+    const nowMs = now.getTime();
+    const accessTokenExpiresAt = Date.parse(payload.session.accessTokenExpiresAt);
+    const refreshTokenExpiresAt = Date.parse(payload.session.refreshTokenExpiresAt);
+    if (!Number.isFinite(accessTokenExpiresAt) || accessTokenExpiresAt <= nowMs) {
+        throw new AppSessionRefreshResponseError("Invalid Voratiq App refresh response: access token expiry is unusable.");
+    }
+    if (!Number.isFinite(refreshTokenExpiresAt) ||
+        refreshTokenExpiresAt <= nowMs) {
+        throw new AppSessionRefreshResponseError("Invalid Voratiq App refresh response: refresh token expiry is unusable.");
+    }
+    if (refreshTokenExpiresAt <= accessTokenExpiresAt) {
+        throw new AppSessionRefreshResponseError("Invalid Voratiq App refresh response: refresh token expires too early.");
+    }
+}

package/dist/app-session/authenticated-api.d.ts

@@ -0,0 +1,31 @@
+import { refreshCliSession } from "./api-client.js";
+import type { AppSessionPayload } from "./session.js";
+import { writeAppSessionState } from "./session.js";
+import { readAppSessionState } from "./state.js";
+export type AppSessionAuthErrorCode = "session_missing" | "session_expired" | "session_read_failed" | "session_write_failed" | "refresh_failed" | "invalid_refresh_response";
+export declare class AppSessionAuthError extends Error {
+    readonly code: AppSessionAuthErrorCode;
+    constructor(message: string, code: AppSessionAuthErrorCode, options?: {
+        cause?: unknown;
+    });
+}
+export interface AuthenticatedAppSessionRequestContext {
+    session: AppSessionPayload;
+    accessToken: string;
+    signal?: AbortSignal;
+}
+export interface RunWithAuthenticatedAppSessionOptions<Result> {
+    run: (context: AuthenticatedAppSessionRequestContext) => Promise<Result>;
+    env?: NodeJS.ProcessEnv;
+    refreshWindowMs?: number;
+    signal?: AbortSignal;
+    isAuthenticationFailure?: (error: unknown) => boolean;
+}
+interface RunWithAuthenticatedAppSessionDependencies {
+    readAppSessionState: typeof readAppSessionState;
+    writeAppSessionState: typeof writeAppSessionState;
+    refreshCliSession: typeof refreshCliSession;
+    now: () => Date;
+}
+export declare function runWithAuthenticatedAppSession<Result>(options: RunWithAuthenticatedAppSessionOptions<Result>, dependencies?: Partial<RunWithAuthenticatedAppSessionDependencies>): Promise<Result>;
+export {};

package/dist/app-session/authenticated-api.js

@@ -0,0 +1,143 @@
+import { AppApiError, AppSessionRefreshResponseError, DEFAULT_CLI_SESSION_REFRESH_WINDOW_MS, isAbortError, refreshCliSession, throwIfAppApiRequestAborted, } from "./api-client.js";
+import { writeAppSessionState } from "./session.js";
+import { readAppSessionState } from "./state.js";
+export class AppSessionAuthError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "AppSessionAuthError";
+    }
+}
+export async function runWithAuthenticatedAppSession(options, dependencies = {}) {
+    const env = options.env ?? process.env;
+    const refreshWindowMs = normalizeRefreshWindowMs(options.refreshWindowMs);
+    const isAuthenticationFailure = options.isAuthenticationFailure ?? isAuthenticationFailureByDefault;
+    const deps = {
+        readAppSessionState,
+        writeAppSessionState,
+        refreshCliSession,
+        now: () => new Date(),
+        ...dependencies,
+    };
+    throwIfAppApiRequestAborted(options.signal);
+    let session = await readStoredSessionOrThrow({
+        env,
+        readAppSessionState: deps.readAppSessionState,
+    });
+    if (hasExpired(session.session.refreshTokenExpiresAt, deps.now())) {
+        throw buildSessionExpiredError();
+    }
+    let refreshedForRequest = false;
+    if (shouldRefreshAccessToken(session.session.accessTokenExpiresAt, deps.now(), refreshWindowMs)) {
+        session = await refreshAndPersistSession({
+            session,
+            env,
+            signal: options.signal,
+            dependencies: deps,
+        });
+        refreshedForRequest = true;
+    }
+    throwIfAppApiRequestAborted(options.signal);
+    try {
+        return await options.run({
+            session,
+            accessToken: session.session.accessToken,
+            signal: options.signal,
+        });
+    }
+    catch (error) {
+        if (!isAuthenticationFailure(error) || refreshedForRequest) {
+            throw error;
+        }
+        if (hasExpired(session.session.refreshTokenExpiresAt, deps.now())) {
+            throw buildSessionExpiredError();
+        }
+        throwIfAppApiRequestAborted(options.signal);
+        session = await refreshAndPersistSession({
+            session,
+            env,
+            signal: options.signal,
+            dependencies: deps,
+        });
+        throwIfAppApiRequestAborted(options.signal);
+        return await options.run({
+            session,
+            accessToken: session.session.accessToken,
+            signal: options.signal,
+        });
+    }
+}
+async function readStoredSessionOrThrow(options) {
+    try {
+        const state = await options.readAppSessionState(options.env);
+        if (!state.raw) {
+            throw new AppSessionAuthError("Voratiq App login is required. Run `voratiq login`.", "session_missing");
+        }
+        return state.raw;
+    }
+    catch (error) {
+        if (error instanceof AppSessionAuthError) {
+            throw error;
+        }
+        throw new AppSessionAuthError("Could not read saved Voratiq App sign-in state.", "session_read_failed", { cause: error });
+    }
+}
+async function refreshAndPersistSession(options) {
+    if (hasExpired(options.session.session.refreshTokenExpiresAt, options.dependencies.now())) {
+        throw buildSessionExpiredError();
+    }
+    let refreshed;
+    try {
+        throwIfAppApiRequestAborted(options.signal);
+        refreshed = await options.dependencies.refreshCliSession({
+            refreshToken: options.session.session.refreshToken,
+        }, {
+            env: options.env,
+            now: options.dependencies.now,
+            signal: options.signal,
+        });
+    }
+    catch (error) {
+        if (isAbortForSignal(error, options.signal)) {
+            throw error;
+        }
+        if (error instanceof AppSessionRefreshResponseError) {
+            throw new AppSessionAuthError("Invalid Voratiq App session refresh response.", "invalid_refresh_response", { cause: error });
+        }
+        throw new AppSessionAuthError("Voratiq App session refresh failed. Run `voratiq login` again.", "refresh_failed", { cause: error });
+    }
+    try {
+        await options.dependencies.writeAppSessionState(refreshed, options.env);
+    }
+    catch (error) {
+        throw new AppSessionAuthError("Could not update saved Voratiq App sign-in state.", "session_write_failed", {
+            cause: error,
+        });
+    }
+    return refreshed;
+}
+function isAbortForSignal(error, signal) {
+    return (signal?.aborted === true || (signal !== undefined && isAbortError(error)));
+}
+function isAuthenticationFailureByDefault(error) {
+    return (error instanceof AppApiError &&
+        (error.statusCode === 401 || error.statusCode === 403));
+}
+function shouldRefreshAccessToken(accessTokenExpiresAt, now, refreshWindowMs) {
+    return Date.parse(accessTokenExpiresAt) - now.getTime() <= refreshWindowMs;
+}
+function hasExpired(timestamp, now) {
+    return Date.parse(timestamp) <= now.getTime();
+}
+function normalizeRefreshWindowMs(refreshWindowMs) {
+    if (typeof refreshWindowMs !== "number" ||
+        !Number.isFinite(refreshWindowMs) ||
+        refreshWindowMs < 0) {
+        return DEFAULT_CLI_SESSION_REFRESH_WINDOW_MS;
+    }
+    return refreshWindowMs;
+}
+function buildSessionExpiredError() {
+    return new AppSessionAuthError("Voratiq App session expired. Run `voratiq login` again.", "session_expired");
+}

package/dist/app-session/browser.d.ts

@@ -0,0 +1 @@
+export declare function openExternalUrl(url: string): Promise<boolean>;

package/dist/app-session/browser.js

@@ -0,0 +1,43 @@
+import { spawn } from "node:child_process";
+function resolveOpenCommand(url) {
+    switch (process.platform) {
+        case "darwin":
+            return { command: "open", args: [url] };
+        case "win32":
+            return { command: "cmd", args: ["/c", "start", "", url] };
+        default:
+            return { command: "xdg-open", args: [url] };
+    }
+}
+export function openExternalUrl(url) {
+    if (process.env.VORATIQ_DISABLE_BROWSER_OPEN === "1") {
+        return Promise.resolve(false);
+    }
+    const { command, args } = resolveOpenCommand(url);
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (opened) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve(opened);
+        };
+        try {
+            const child = spawn(command, args, {
+                detached: true,
+                stdio: "ignore",
+            });
+            child.once("spawn", () => {
+                settle(true);
+            });
+            child.once("error", () => {
+                settle(false);
+            });
+            child.unref();
+        }
+        catch {
+            settle(false);
+        }
+    });
+}

package/dist/app-session/callback.d.ts

@@ -0,0 +1,19 @@
+export declare class AppSignInCallbackError extends Error {
+    readonly code: "bind_failed" | "timed_out" | "state_mismatch" | "malformed_callback";
+    constructor(code: "bind_failed" | "timed_out" | "state_mismatch" | "malformed_callback", message: string);
+}
+export interface AppSignInCallbackResult {
+    code: string;
+}
+export interface AppSignInCallbackServer {
+    callbackUrl: string;
+    waitForResult(timeoutMs: number): Promise<AppSignInCallbackResult>;
+    close(): Promise<void>;
+}
+export declare function startAppSignInCallbackServer(options: {
+    expectedState: string;
+    completionUrl: string;
+    host?: string;
+    pathname?: string;
+    port?: number;
+}): Promise<AppSignInCallbackServer>;

package/dist/app-session/callback.js

@@ -0,0 +1,126 @@
+import { createServer, } from "node:http";
+export class AppSignInCallbackError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "AppSignInCallbackError";
+    }
+}
+function redirectResponse(response, location) {
+    response.statusCode = 303;
+    response.setHeader("connection", "close");
+    response.setHeader("location", location);
+    response.end();
+}
+function buildCompletionUrl(completionUrl, status, reason) {
+    const url = new URL(completionUrl);
+    if (status !== "success") {
+        url.searchParams.set("status", status);
+    }
+    if (reason) {
+        url.searchParams.set("reason", reason);
+    }
+    return url.toString();
+}
+async function closeServer(server) {
+    await new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+}
+export async function startAppSignInCallbackServer(options) {
+    const host = options.host ?? "127.0.0.1";
+    const pathname = options.pathname ?? "/callback";
+    const port = options.port ?? 0;
+    let resolved = false;
+    let resolveResult = null;
+    let rejectResult = null;
+    const resultPromise = new Promise((resolve, reject) => {
+        resolveResult = resolve;
+        rejectResult = reject;
+    });
+    async function settleWithError(error) {
+        if (resolved) {
+            return;
+        }
+        resolved = true;
+        await closeServer(server).catch(() => { });
+        rejectResult?.(error);
+    }
+    async function settleWithResult(result) {
+        if (resolved) {
+            return;
+        }
+        resolved = true;
+        await closeServer(server).catch(() => { });
+        resolveResult?.(result);
+    }
+    const server = createServer((request, response) => {
+        const url = new URL(request.url ?? pathname, `http://${host}`);
+        if (url.pathname !== pathname) {
+            redirectResponse(response, buildCompletionUrl(options.completionUrl, "failed", "not_found"));
+            return;
+        }
+        const state = url.searchParams.get("state");
+        const code = url.searchParams.get("code");
+        if (state !== options.expectedState) {
+            redirectResponse(response, buildCompletionUrl(options.completionUrl, "failed", "state_mismatch"));
+            void settleWithError(new AppSignInCallbackError("state_mismatch", "The browser callback state did not match the active login request."));
+            return;
+        }
+        if (!code) {
+            redirectResponse(response, buildCompletionUrl(options.completionUrl, "failed", "malformed_callback"));
+            void settleWithError(new AppSignInCallbackError("malformed_callback", "The browser callback did not include a usable exchange code."));
+            return;
+        }
+        redirectResponse(response, buildCompletionUrl(options.completionUrl, "success"));
+        void settleWithResult({ code });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", (error) => {
+            reject(new AppSignInCallbackError("bind_failed", error instanceof Error
+                ? error.message
+                : "Failed to bind the localhost callback server."));
+        });
+        server.listen(port, host, () => {
+            server.removeAllListeners("error");
+            resolve();
+        });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        await closeServer(server);
+        throw new AppSignInCallbackError("bind_failed", "Failed to resolve the localhost callback address.");
+    }
+    return {
+        callbackUrl: `http://${host}:${address.port}${pathname}`,
+        async waitForResult(timeoutMs) {
+            let timeoutHandle;
+            try {
+                return await Promise.race([
+                    resultPromise,
+                    new Promise((_, reject) => {
+                        timeoutHandle = setTimeout(() => {
+                            reject(new AppSignInCallbackError("timed_out", "Timed out waiting for the browser to finish login approval."));
+                            void closeServer(server).catch(() => { });
+                        }, timeoutMs);
+                    }),
+                ]);
+            }
+            finally {
+                if (timeoutHandle) {
+                    clearTimeout(timeoutHandle);
+                }
+            }
+        },
+        async close() {
+            await closeServer(server);
+        },
+    };
+}

package/dist/app-session/login.d.ts

@@ -0,0 +1,27 @@
+import { randomUUID } from "node:crypto";
+import type { CommandOutputWriter } from "../cli/output.js";
+import { createCliLoginAttempt, exchangeCliLoginCode } from "./api-client.js";
+import { openExternalUrl } from "./browser.js";
+import { startAppSignInCallbackServer } from "./callback.js";
+import { type AppSessionPayload, writeAppSessionState } from "./session.js";
+import { readAppSessionState } from "./state.js";
+export interface AppSignInDependencies {
+    createLoginAttempt: typeof createCliLoginAttempt;
+    exchangeLoginCode: typeof exchangeCliLoginCode;
+    openExternalUrl: typeof openExternalUrl;
+    readAppSessionState: typeof readAppSessionState;
+    startCallbackServer: typeof startAppSignInCallbackServer;
+    writeAppSessionState: typeof writeAppSessionState;
+    randomUUID: typeof randomUUID;
+    now: () => Date;
+}
+export interface AppSignInResult {
+    body: string;
+    statePath: string;
+    session: AppSessionPayload;
+}
+export declare function performAppSignIn(options?: {
+    writeOutput?: CommandOutputWriter;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}, dependencies?: Partial<AppSignInDependencies>): Promise<AppSignInResult>;

package/dist/app-session/login.js

@@ -0,0 +1,107 @@
+import { randomUUID } from "node:crypto";
+import { CliError } from "../cli/errors.js";
+import { colorize } from "../utils/colors.js";
+import { AppApiError, createCliLoginAttempt, exchangeCliLoginCode, resolveVoratiqAppOrigin, } from "./api-client.js";
+import { openExternalUrl } from "./browser.js";
+import { AppSignInCallbackError, startAppSignInCallbackServer, } from "./callback.js";
+import { writeAppSessionState } from "./session.js";
+import { readAppSessionState } from "./state.js";
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+const COMPLETE_PATH = "/auth/cli/complete";
+function emitInfo(writeOutput, message, options = {}) {
+    writeOutput?.({
+        body: message,
+        formatBody: {
+            leadingNewline: options.leadingNewline ?? false,
+            trailingNewline: false,
+        },
+    });
+}
+function toLoginCliError(error) {
+    if (error instanceof AppSignInCallbackError) {
+        switch (error.code) {
+            case "bind_failed":
+                return new CliError("Could not start the local sign-in callback.", [], [
+                    "Allow loopback (127.0.0.1) binding for this shell, then run `voratiq login` again.",
+                ]);
+            case "timed_out":
+                return new CliError("Timed out waiting for approval.", [], ["Run `voratiq login` again to retry."]);
+            case "state_mismatch":
+            case "malformed_callback":
+                return new CliError("The sign-in callback was invalid.", [], ["Close the browser tab and run `voratiq login` again."]);
+        }
+    }
+    if (error instanceof AppApiError) {
+        if (error.code === "cancelled_exchange") {
+            return new CliError("Sign-in was cancelled in the browser.", [], ["Run `voratiq login` again when you're ready."]);
+        }
+        return new CliError("Could not complete sign-in.", [], ["Check your Voratiq app and API configuration, then try again."]);
+    }
+    return error instanceof CliError
+        ? error
+        : new CliError(error instanceof Error ? error.message : "Login failed.");
+}
+function renderLoginSuccess(session) {
+    const signedInAs = session.actor.email ?? session.actor.id;
+    return `${colorize("Success:", "green")} Signed in to Voratiq App as ${signedInAs}`;
+}
+export async function performAppSignIn(options = {}, dependencies = {}) {
+    const env = options.env ?? process.env;
+    const writeOutput = options.writeOutput;
+    const deps = {
+        createLoginAttempt: createCliLoginAttempt,
+        exchangeLoginCode: exchangeCliLoginCode,
+        openExternalUrl,
+        readAppSessionState,
+        startCallbackServer: startAppSignInCallbackServer,
+        writeAppSessionState,
+        randomUUID,
+        now: () => new Date(),
+        ...dependencies,
+    };
+    const existingState = await deps.readAppSessionState(env);
+    const existingInstallationId = typeof existingState.raw?.installation.id === "string"
+        ? existingState.raw.installation.id
+        : null;
+    const installationId = existingInstallationId ?? deps.randomUUID();
+    const callbackState = deps.randomUUID();
+    let callbackServer = null;
+    try {
+        callbackServer = await deps.startCallbackServer({
+            expectedState: callbackState,
+            completionUrl: new URL(COMPLETE_PATH, resolveVoratiqAppOrigin(env)).toString(),
+        });
+        const attempt = await deps.createLoginAttempt({
+            installationId,
+            callbackUrl: callbackServer.callbackUrl,
+            callbackState,
+        }, env);
+        emitInfo(writeOutput, "Opening browser to sign in...", {
+            leadingNewline: true,
+        });
+        const opened = await deps.openExternalUrl(attempt.authorizeUrl);
+        if (!opened) {
+            emitInfo(writeOutput, "Browser didn't open. Open this URL to continue:");
+            emitInfo(writeOutput, attempt.authorizeUrl);
+        }
+        emitInfo(writeOutput, "Waiting for approval in your browser...", {
+            leadingNewline: !opened,
+        });
+        const callback = await callbackServer.waitForResult(options.timeoutMs ?? LOGIN_TIMEOUT_MS);
+        const session = await deps.exchangeLoginCode({ code: callback.code }, env);
+        const statePath = await deps.writeAppSessionState(session, env);
+        return {
+            body: renderLoginSuccess(session),
+            statePath,
+            session,
+        };
+    }
+    catch (error) {
+        throw toLoginCliError(error);
+    }
+    finally {
+        if (callbackServer) {
+            await callbackServer.close().catch(() => { });
+        }
+    }
+}