@tapi-dev/sdk 0.1.3 → 0.1.5

package/README.md

@@ -14,50 +14,84 @@ This package is ESM-first and works in runtimes with `fetch`, including modern N
 
 Tapi Studio is the desktop app used to author and test local Tapi integrations. Install the SDK first, then use the bundled CLI:
 
-```bash
-npm install @tapi-dev/sdk
-npx tapi studio install --channel pilot
-npx tapi studio open
-```
-
-You can also run the CLI directly from npm without adding the package first:
-
-```bash
-npx @tapi-dev/sdk studio install --channel pilot
-```
-
-The CLI reads the release manifest from:
-
-```text
-https://d4xaf52nfwiok.cloudfront.net/studio/channels/pilot/latest.json
-```
-
-It downloads the Windows installer, verifies the manifest SHA256, caches the installer locally, and runs it. The installer cache defaults to:
+```bash
+npm install @tapi-dev/sdk
+npx tapi studio install --channel pilot
+npx tapi studio open
+```
+
+`studio install` opens a browser sign-in before any Studio EXE download. The
+CLI exchanges the browser credential for Firebase auth, requests a short-lived
+Studio install token from the Tapi API, then fetches a protected manifest and
+installer download URL. If the signed-in user is not yet approved, the server
+submits an approval request and sends the existing email approval links to the
+admin. After approval, rerun the same command.
+
+You can also run the CLI directly from npm without adding the package first:
+
+```bash
+npx @tapi-dev/sdk studio install --channel pilot
+```
+
+The install flow talks to the Tapi API host first:
+
+```text
+POST /api/sdk/v1/studio/install-token
+GET  /api/sdk/v1/studio/releases/<channel>
+```
+
+It then downloads the Windows installer, verifies the manifest SHA256, caches
+the installer locally, and runs it. The installer cache defaults to:
 
 ```text
-%LOCALAPPDATA%\Tapi\Studio\downloads
-```
-
-Useful commands:
-
-```bash
-npx tapi studio install --channel pilot
-npx tapi studio install --channel pilot --download-only
-npx tapi studio install --manifest https://d4xaf52nfwiok.cloudfront.net/studio/channels/pilot/latest.json
-npx tapi studio open
-npx tapi studio doctor
-```
-
-Environment overrides:
-
-```env
-TAPI_STUDIO_CHANNEL=pilot
-TAPI_STUDIO_MANIFEST_URL=https://d4xaf52nfwiok.cloudfront.net/studio/channels/pilot/latest.json
-TAPI_DOWNLOADS_BASE_URL=https://d4xaf52nfwiok.cloudfront.net
-TAPI_STUDIO_EXE=C:\Users\you\AppData\Local\Tapi Studio\Tapi Studio.exe
-```
-
-Tapi Studio desktop releases are currently published for Windows x64.
+%LOCALAPPDATA%\Tapi\Studio\downloads
+```
+
+Tapi Studio includes the matching Tapi Service build. When the installer runs,
+it installs or replaces the local `tapi-service` Windows service with the
+version declared in the Studio manifest. Developers do not pick a service
+version separately; updating Studio updates the service version used by that
+project and by apps generated from that project.
+
+Useful commands:
+
+```bash
+npx tapi studio install --channel pilot
+npx tapi studio install --channel pilot --download-only
+npx tapi studio install --api-base-url https://api.example.com
+npx tapi studio install --install-token tsi_your_preissued_token
+npx tapi studio open
+npx tapi studio doctor
+```
+
+Environment overrides:
+
+```env
+TAPI_BASE_URL=https://your-tapi-api-host
+TAPI_STUDIO_API_BASE_URL=https://your-tapi-api-host
+TAPI_STUDIO_CHANNEL=pilot
+TAPI_STUDIO_MANIFEST_URL=https://d4xaf52nfwiok.cloudfront.net/studio/channels/pilot/latest.json
+TAPI_STUDIO_INSTALL_TOKEN=tsi_your_preissued_token
+TAPI_STUDIO_AUTH_HTML_URL=https://rsarlong-1f92fd.gitlab.io/auth.html
+TAPI_FIREBASE_API_KEY=AIzaSyCDZR8lWyVQcWYfFdNZa4vuL4IWEC0h6gE
+TAPI_STUDIO_EXE=C:\Users\you\AppData\Local\Tapi Studio\Tapi Studio.exe
+```
+
+`TAPI_STUDIO_MANIFEST_URL` remains useful for `studio doctor`. Direct manifest
+overrides are not used by the protected installer path.
+
+Server-side protected install delivery also requires:
+
+```env
+STUDIO_INSTALL_TOKEN_SECRET=replace-me
+S3_BUCKET=your-private-release-bucket
+AWS_REGION=us-east-1
+```
+
+If the Studio installer objects remain publicly downloadable, users can bypass
+the approval gate by skipping the CLI entirely.
+
+Tapi Studio desktop releases are currently published for Windows x64.
 
 ## Quick Start
 

package/dist/cli.d.ts

@@ -15,18 +15,40 @@ export interface StudioReleaseManifest {
     commitShort?: string;
     ref?: string;
     installerKind?: string;
+    bundledService?: {
+        product?: string;
+        version?: string;
+        source?: string;
+        manifestUrl?: string;
+    };
 }
 interface StudioCliOptions {
     channel: StudioChannel;
+    apiBaseUrl: string;
     manifestUrl: string;
+    manifestUrlOverride?: string;
     cacheDir: string;
     downloadOnly: boolean;
     silent: boolean;
     exePath?: string;
+    installToken?: string;
 }
 export declare function runCli(argv?: string[]): Promise<number>;
 export declare function parseStudioOptions(args: string[]): StudioCliOptions;
 export declare function getDefaultStudioCacheDir(): string;
+export declare class CliWideEvent {
+    private readonly filePath;
+    private readonly startedAt;
+    private readonly data;
+    private readonly phases;
+    private constructor();
+    static create(eventName: string, initialFields?: Record<string, unknown>): Promise<CliWideEvent>;
+    phase(phase: string, fields?: Record<string, unknown>): Promise<void>;
+    finish(success: boolean, fields?: Record<string, unknown>): Promise<void>;
+    private write;
+}
+export declare function createCliWideEvent(eventName: string, initialFields?: Record<string, unknown>): Promise<CliWideEvent>;
+export declare function getCliWideEventRoot(): string;
 export declare function getStudioExecutableCandidates(): string[];
 export declare function validateStudioManifest(input: unknown): StudioReleaseManifest;
 export declare function compareVersions(left: string, right: string): number;

package/dist/cli.js

@@ -1,16 +1,33 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createServer } from "node:http";
+import { createHash, randomUUID } from "node:crypto";
 import { createReadStream, createWriteStream, existsSync, readFileSync } from "node:fs";
-import { mkdir, rename, unlink } from "node:fs/promises";
+import { mkdir, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
 const DEFAULT_DOWNLOADS_BASE_URL = "https://d4xaf52nfwiok.cloudfront.net";
+const DEFAULT_STUDIO_API_BASE_URL = "https://determined-motivation-production.up.railway.app";
+const DEFAULT_STUDIO_AUTH_HTML_URL = "https://rsarlong-1f92fd.gitlab.io/auth.html";
+const DEFAULT_FIREBASE_API_KEY = "AIzaSyCDZR8lWyVQcWYfFdNZa4vuL4IWEC0h6gE";
 const DEFAULT_CHANNEL = "pilot";
 const SUPPORTED_STUDIO_PLATFORM = "windows-x86_64";
+const DEFAULT_INSTALL_AUTH_TIMEOUT_MS = 120_000;
+const MAX_WIDE_EVENT_PROCESS_ROOTS = 5;
+class StudioInstallApprovalError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "StudioInstallApprovalError";
+    }
+}
 const sdkVersion = readSdkVersion();
 export async function runCli(argv = process.argv.slice(2)) {
     const [command, subcommand, ...rest] = argv;
@@ -72,11 +89,31 @@ export function parseStudioOptions(args) {
             continue;
         }
         if (arg === "--manifest") {
-            raw.manifestUrl = requireOptionValue(args, ++index, "--manifest");
+            raw.manifestUrlOverride = requireOptionValue(args, ++index, "--manifest");
             continue;
         }
         if (arg.startsWith("--manifest=")) {
-            raw.manifestUrl = arg.slice("--manifest=".length);
+            raw.manifestUrlOverride = arg.slice("--manifest=".length);
+            continue;
+        }
+        if (arg === "--api-base-url" || arg === "--server") {
+            raw.apiBaseUrl = requireOptionValue(args, ++index, arg);
+            continue;
+        }
+        if (arg.startsWith("--api-base-url=")) {
+            raw.apiBaseUrl = arg.slice("--api-base-url=".length);
+            continue;
+        }
+        if (arg.startsWith("--server=")) {
+            raw.apiBaseUrl = arg.slice("--server=".length);
+            continue;
+        }
+        if (arg === "--install-token") {
+            raw.installToken = requireOptionValue(args, ++index, "--install-token");
+            continue;
+        }
+        if (arg.startsWith("--install-token=")) {
+            raw.installToken = arg.slice("--install-token=".length);
             continue;
         }
         if (arg === "--cache-dir") {
@@ -109,18 +146,26 @@ export function parseStudioOptions(args) {
         throw new Error(`Unknown option: ${arg}`);
     }
     const channel = raw.channel ?? parseChannel(envString("TAPI_STUDIO_CHANNEL") ?? DEFAULT_CHANNEL);
+    const apiBaseUrl = normalizeHttpUrl(raw.apiBaseUrl
+        ?? envString("TAPI_STUDIO_API_BASE_URL")
+        ?? envString("TAPI_BASE_URL")
+        ?? envString("TAPI_STUDIO_SERVER_URL")
+        ?? DEFAULT_STUDIO_API_BASE_URL, "Studio API base URL");
     const downloadsBaseUrl = normalizeHttpUrl(envString("TAPI_DOWNLOADS_BASE_URL") ?? DEFAULT_DOWNLOADS_BASE_URL, "TAPI_DOWNLOADS_BASE_URL");
-    const explicitManifestUrl = raw.manifestUrl ?? envString("TAPI_STUDIO_MANIFEST_URL");
+    const explicitManifestUrl = raw.manifestUrlOverride ?? envString("TAPI_STUDIO_MANIFEST_URL");
     const manifestUrl = explicitManifestUrl
         ? normalizeHttpUrl(explicitManifestUrl, "Studio manifest URL")
         : `${downloadsBaseUrl.replace(/\/+$/, "")}/studio/channels/${channel}/latest.json`;
     return {
         channel,
+        apiBaseUrl,
         manifestUrl,
+        manifestUrlOverride: explicitManifestUrl ? normalizeHttpUrl(explicitManifestUrl, "Studio manifest URL") : undefined,
         cacheDir: raw.cacheDir ?? getDefaultStudioCacheDir(),
         downloadOnly: raw.downloadOnly ?? false,
         silent: raw.silent ?? false,
         exePath: raw.exePath ?? envString("TAPI_STUDIO_EXE"),
+        installToken: raw.installToken ?? envString("TAPI_STUDIO_INSTALL_TOKEN"),
     };
 }
 export function getDefaultStudioCacheDir() {
@@ -131,6 +176,141 @@ export function getDefaultStudioCacheDir() {
     }
     return join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "tapi", "studio");
 }
+export class CliWideEvent {
+    filePath;
+    startedAt = performance.now();
+    data;
+    phases = [];
+    constructor(filePath, eventName, initialFields) {
+        this.filePath = filePath;
+        this.data = {
+            event: eventName,
+            seq: 1,
+            timestamp: new Date().toISOString(),
+            trace_id: `cli_${randomUUID().replace(/-/g, "").slice(0, 12)}`,
+            actor: {
+                mode: "tapi_cli",
+                pid: process.pid,
+                cwd: process.cwd(),
+                node: process.version,
+                platform: process.platform,
+                arch: process.arch,
+            },
+            phases: this.phases,
+            ...initialFields,
+        };
+    }
+    static async create(eventName, initialFields = {}) {
+        try {
+            const root = getCliWideEventRoot();
+            await mkdir(root, { recursive: true });
+            const sessionDir = join(root, sessionDirName("tapi_cli"));
+            await mkdir(sessionDir, { recursive: true });
+            await pruneCliWideEventProcessRoots(root);
+            const filePath = join(sessionDir, `${safeEventFilename(eventName)}_${timeFilename(new Date())}.json`);
+            const event = new CliWideEvent(filePath, eventName, initialFields);
+            await event.phase("start");
+            return event;
+        }
+        catch {
+            return new CliWideEvent(undefined, eventName, initialFields);
+        }
+    }
+    async phase(phase, fields = {}) {
+        this.phases.push({
+            phase,
+            timestamp: new Date().toISOString(),
+            fields: sanitizeEventFields(fields),
+        });
+        this.data.phase = phase;
+        await this.write();
+    }
+    async finish(success, fields = {}) {
+        const durationMs = Math.round((performance.now() - this.startedAt) * 10) / 10;
+        this.data.duration_ms = durationMs;
+        this.data.outcome = success ? "success" : "error";
+        await this.phase(success ? "finish.success" : "finish.error", fields);
+    }
+    async write() {
+        if (!this.filePath) {
+            return;
+        }
+        try {
+            await writeFile(this.filePath, JSON.stringify(this.data, null, 2), "utf8");
+        }
+        catch {
+            // Diagnostics must never make the installer path fail.
+        }
+    }
+}
+export async function createCliWideEvent(eventName, initialFields = {}) {
+    return CliWideEvent.create(eventName, initialFields);
+}
+export function getCliWideEventRoot() {
+    const override = envString("TAPI_EVENTS_ROOT");
+    if (override) {
+        return override;
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA ??
+            (process.env.USERPROFILE ? join(process.env.USERPROFILE, "AppData", "Local") : join(homedir(), "AppData", "Local"));
+        return join(localAppData, "Tapi", "logs", "events");
+    }
+    return join(process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state"), "tapi", "logs", "events");
+}
+async function pruneCliWideEventProcessRoots(root) {
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        const directories = await Promise.all(entries
+            .filter((entry) => entry.isDirectory())
+            .map(async (entry) => {
+            const path = join(root, entry.name);
+            try {
+                return { path, mtimeMs: (await stat(path)).mtimeMs };
+            }
+            catch {
+                return { path, mtimeMs: 0 };
+            }
+        }));
+        if (directories.length <= MAX_WIDE_EVENT_PROCESS_ROOTS) {
+            return;
+        }
+        directories.sort((left, right) => right.mtimeMs - left.mtimeMs || right.path.localeCompare(left.path));
+        await Promise.all(directories
+            .slice(MAX_WIDE_EVENT_PROCESS_ROOTS)
+            .map((entry) => rm(entry.path, { recursive: true, force: true })));
+    }
+    catch {
+        // Best-effort retention only.
+    }
+}
+function sessionDirName(role) {
+    const now = new Date();
+    const stamp = now
+        .toISOString()
+        .replace("T", "_")
+        .replace(/\.\d+Z$/, "")
+        .replace(/:/g, "-");
+    return `${stamp}_${role}_pid${process.pid}`;
+}
+function timeFilename(date) {
+    return date
+        .toISOString()
+        .split("T")[1]
+        .replace("Z", "")
+        .replace(/:/g, "-");
+}
+function safeEventFilename(eventName) {
+    return `001_${eventName.replace(/[^A-Za-z0-9._-]/g, "_").replace(/\./g, "_")}`;
+}
+function sanitizeEventFields(fields) {
+    return JSON.parse(JSON.stringify(fields, (_key, value) => {
+        if (value instanceof Error) {
+            return errorDetails(value);
+        }
+        return value;
+    }));
+}
 export function getStudioExecutableCandidates() {
     const candidates = [
         process.env.TAPI_STUDIO_EXE,
@@ -185,29 +365,150 @@ export function compareVersions(left, right) {
     return 0;
 }
 async function installStudio(options) {
-    ensureWindowsHost();
-    console.log(`Fetching Tapi Studio ${options.channel} manifest...`);
-    const manifest = await fetchStudioManifest(options.manifestUrl);
-    ensureCompatibleManifest(manifest);
-    await mkdir(options.cacheDir, { recursive: true });
-    const installerPath = join(options.cacheDir, cachedInstallerName(manifest));
-    const verified = await hasVerifiedCachedInstaller(installerPath, manifest.sha256);
-    if (verified) {
-        console.log(`Using cached installer: ${installerPath}`);
+    const event = await createCliWideEvent("tapi_cli.studio_install", {
+        sdk_version: sdkVersion,
+        options: installEventOptions(options),
+    });
+    try {
+        await event.phase("host.check", {
+            platform: process.platform,
+            arch: process.arch,
+        });
+        ensureWindowsHost();
+        if (options.manifestUrlOverride) {
+            throw new Error("Direct Studio manifest overrides are no longer supported for install. "
+                + "Use --channel with the protected install flow instead.");
+        }
+        let installToken = options.installToken?.trim();
+        if (installToken) {
+            await event.phase("auth.install_token.provided", {
+                apiBaseUrl: options.apiBaseUrl,
+                channel: options.channel,
+            });
+        }
+        else {
+            console.log("Checking Studio install approval...");
+            await event.phase("auth.install_token.request.start", {
+                apiBaseUrl: options.apiBaseUrl,
+                channel: options.channel,
+            });
+            installToken = await obtainStudioInstallToken(options, event);
+            await event.phase("auth.install_token.request.success", {
+                apiBaseUrl: options.apiBaseUrl,
+                channel: options.channel,
+            });
+        }
+        console.log(`Fetching Tapi Studio ${options.channel} manifest...`);
+        await event.phase("manifest.fetch.start", {
+            apiBaseUrl: options.apiBaseUrl,
+            channel: options.channel,
+        });
+        const manifest = await fetchProtectedStudioManifest(options.apiBaseUrl, options.channel, installToken);
+        await event.phase("manifest.fetch.success", {
+            manifest: manifestEventSummary(manifest),
+        });
+        ensureCompatibleManifest(manifest);
+        await event.phase("manifest.compatible", {
+            sdkVersion,
+            minSdkVersion: manifest.minSdkVersion,
+            platform: manifest.platform,
+        });
+        await mkdir(options.cacheDir, { recursive: true });
+        const installerPath = join(options.cacheDir, cachedInstallerName(manifest));
+        await event.phase("cache.check.start", {
+            cacheDir: options.cacheDir,
+            installerPath,
+        });
+        const verified = await hasVerifiedCachedInstaller(installerPath, manifest.sha256);
+        if (verified) {
+            console.log(`Using cached installer: ${installerPath}`);
+            await event.phase("cache.hit", { installerPath });
+        }
+        else {
+            await event.phase("cache.miss", { installerPath });
+            console.log(`Downloading Tapi Studio ${manifest.version}...`);
+            await event.phase("download.start", {
+                url: manifest.url,
+                destination: installerPath,
+                expectedSha256: manifest.sha256,
+            });
+            await downloadAndVerify(manifest.url, installerPath, manifest.sha256);
+            await event.phase("download.verified", {
+                installerPath,
+                expectedSha256: manifest.sha256,
+            });
+        }
+        if (options.downloadOnly) {
+            console.log(`Downloaded installer: ${installerPath}`);
+            await event.finish(true, {
+                installerPath,
+                downloadOnly: true,
+            });
+            return 0;
+        }
+        const installerArgs = options.silent ? ["/S"] : [];
+        console.log(`Starting Tapi Studio installer: ${installerPath}`);
+        await event.phase("installer.start", {
+            installerPath,
+            args: installerArgs,
+        });
+        await runProcess(installerPath, installerArgs);
+        console.log("Tapi Studio installer finished.");
+        await event.finish(true, {
+            installerPath,
+            downloadOnly: false,
+        });
+        return 0;
+    }
+    catch (error) {
+        await event.finish(false, {
+            error: errorDetails(error),
+        });
+        throw error;
+    }
+}
+async function obtainStudioInstallToken(options, event) {
+    const cachedCreds = await refreshCachedFirebaseCredentials();
+    if (cachedCreds) {
+        await event.phase("auth.cache.refresh.success", {
+            uid: cachedCreds.uid,
+            authCachePath: getStudioAuthCachePath(),
+        });
+        await writeStudioAuthCache(cachedCreds);
+        try {
+            const issued = await requestStudioInstallToken(options.apiBaseUrl, options.channel, cachedCreds.idToken);
+            return issued.installToken;
+        }
+        catch (error) {
+            if (isApprovalTerminalError(error)) {
+                throw error;
+            }
+            await event.phase("auth.cache.install_token.retry_interactive", {
+                error: errorDetails(error),
+            });
+        }
     }
     else {
-        console.log(`Downloading Tapi Studio ${manifest.version}...`);
-        await downloadAndVerify(manifest.url, installerPath, manifest.sha256);
+        await event.phase("auth.cache.refresh.miss", {
+            authCachePath: getStudioAuthCachePath(),
+        });
     }
-    if (options.downloadOnly) {
-        console.log(`Downloaded installer: ${installerPath}`);
-        return 0;
+    const browserAuth = await browserGoogleSignIn();
+    await event.phase("auth.browser.callback.received", {
+        googleIdTokenPresent: Boolean(browserAuth.idToken),
+        googleAccessTokenPresent: Boolean(browserAuth.accessToken),
+    });
+    if (!browserAuth.idToken) {
+        throw new Error(browserAuth.error || browserAuth.detail || "Browser sign-in did not return a Google ID token.");
     }
-    const installerArgs = options.silent ? ["/S"] : [];
-    console.log(`Starting Tapi Studio installer: ${installerPath}`);
-    await runProcess(installerPath, installerArgs);
-    console.log("Tapi Studio installer finished.");
-    return 0;
+    const firebaseCreds = await exchangeGoogleToFirebase(browserAuth.idToken, browserAuth.accessToken);
+    await writeStudioAuthCache(firebaseCreds);
+    await event.phase("auth.firebase.exchange.success", {
+        uid: firebaseCreds.uid,
+        authCachePath: getStudioAuthCachePath(),
+    });
+    const issued = await requestStudioInstallToken(options.apiBaseUrl, options.channel, firebaseCreds.idToken);
+    return issued.installToken;
 }
 async function openStudio(options) {
     ensureWindowsHost();
@@ -230,6 +531,7 @@ async function runDoctor(options) {
     console.log(`Tapi SDK: ${sdkVersion}`);
     console.log(`Node: ${process.version}`);
     console.log(`Platform: ${process.platform}/${process.arch}`);
+    console.log(`Studio API: ${options.apiBaseUrl}`);
     console.log(`Studio channel: ${options.channel}`);
     console.log(`Studio manifest: ${options.manifestUrl}`);
     console.log(`Studio cache: ${options.cacheDir}`);
@@ -246,6 +548,18 @@ async function runDoctor(options) {
     }
     return 0;
 }
+async function fetchProtectedStudioManifest(apiBaseUrl, channel, installToken, fetchImpl = fetch) {
+    const response = await fetchImpl(`${apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/studio/releases/${channel}`, {
+        headers: {
+            Accept: "application/json",
+            Authorization: `Bearer ${installToken}`,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch protected Studio manifest: HTTP ${response.status}`);
+    }
+    return validateStudioManifest(await response.json());
+}
 async function fetchStudioManifest(manifestUrl, fetchImpl = fetch) {
     const response = await fetchImpl(manifestUrl, {
         headers: {
@@ -257,6 +571,37 @@ async function fetchStudioManifest(manifestUrl, fetchImpl = fetch) {
     }
     return validateStudioManifest(await response.json());
 }
+async function requestStudioInstallToken(apiBaseUrl, channel, firebaseIdToken, fetchImpl = fetch) {
+    const response = await fetchImpl(`${apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/studio/install-token`, {
+        method: "POST",
+        headers: {
+            Accept: "application/json",
+            Authorization: `Bearer ${firebaseIdToken}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ channel }),
+    });
+    const responseBody = await readJsonBody(response);
+    if (!response.ok) {
+        const detail = typeof responseBody?.detail === "string" ? responseBody.detail : "";
+        if (detail === "pending_approval" || detail === "access_pending") {
+            throw new StudioInstallApprovalError("Access request submitted. Check your email for approval, then rerun `npx tapi studio install`.", detail, response.status);
+        }
+        if (detail === "access_rejected") {
+            throw new StudioInstallApprovalError("Studio install access was rejected. Contact the Tapi admin if this is unexpected.", detail, response.status);
+        }
+        throw new StudioInstallApprovalError(detail || `Failed to request Studio install token: HTTP ${response.status}`, detail || "install_token_request_failed", response.status);
+    }
+    const payload = responseBody;
+    const installToken = typeof payload?.installToken === "string" ? payload.installToken.trim() : "";
+    if (!installToken) {
+        throw new Error("Studio install token response did not include installToken.");
+    }
+    return {
+        installToken,
+        expiresAt: typeof payload?.expiresAt === "string" ? payload.expiresAt : undefined,
+    };
+}
 async function downloadAndVerify(url, destination, expectedSha256) {
     const partialPath = `${destination}.partial`;
     await downloadFile(url, partialPath);
@@ -278,6 +623,198 @@ async function downloadFile(url, destination) {
     }
     await pipeline(Readable.fromWeb(response.body), createWriteStream(destination));
 }
+async function browserGoogleSignIn(timeoutMs = DEFAULT_INSTALL_AUTH_TIMEOUT_MS) {
+    ensureWindowsHost();
+    return new Promise((resolvePromise, rejectPromise) => {
+        let timeoutHandle;
+        const cleanup = () => {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+                timeoutHandle = undefined;
+            }
+            try {
+                server.close();
+            }
+            catch {
+                // ignore close races
+            }
+        };
+        const server = createServer((req, res) => {
+            const requestUrl = new URL(req.url || "/", "http://127.0.0.1");
+            const idToken = requestUrl.searchParams.get("idToken") || "";
+            const accessToken = requestUrl.searchParams.get("accessToken") || "";
+            const error = requestUrl.searchParams.get("error") || "";
+            const detail = requestUrl.searchParams.get("detail") || "";
+            const ok = Boolean(idToken);
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "text/html; charset=utf-8");
+            res.end(renderBrowserSignInResponseHtml(ok));
+            cleanup();
+            if (!ok) {
+                rejectPromise(new Error(error || detail || "Browser sign-in did not return Google credentials."));
+                return;
+            }
+            resolvePromise({
+                accessToken: accessToken || undefined,
+                detail: detail || undefined,
+                idToken,
+            });
+        });
+        timeoutHandle = setTimeout(() => {
+            cleanup();
+            rejectPromise(new Error("Browser sign-in timed out or was cancelled."));
+        }, timeoutMs);
+        server.once("error", (error) => {
+            cleanup();
+            rejectPromise(error);
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address ? address.port : 0;
+            if (!port) {
+                cleanup();
+                rejectPromise(new Error("Could not start local callback server for Studio sign-in."));
+                return;
+            }
+            try {
+                openBrowser(`${getStudioAuthHtmlUrl()}?port=${port}`);
+            }
+            catch (error) {
+                cleanup();
+                rejectPromise(error);
+            }
+        });
+    });
+}
+async function exchangeGoogleToFirebase(googleIdToken, googleAccessToken, fetchImpl = fetch) {
+    const postBody = [
+        `id_token=${encodeURIComponent(googleIdToken)}`,
+        "providerId=google.com",
+        googleAccessToken ? `access_token=${encodeURIComponent(googleAccessToken)}` : "",
+    ].filter(Boolean).join("&");
+    const response = await fetchImpl(`https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=${getFirebaseApiKey()}`, {
+        method: "POST",
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            postBody,
+            requestUri: "http://127.0.0.1",
+            returnSecureToken: true,
+            returnIdpCredential: true,
+        }),
+    });
+    const responseBody = await readJsonBody(response);
+    if (!response.ok) {
+        throw new Error(`Firebase exchange failed: HTTP ${response.status}`);
+    }
+    const uid = typeof responseBody?.localId === "string" ? responseBody.localId.trim() : "";
+    const idToken = typeof responseBody?.idToken === "string" ? responseBody.idToken.trim() : "";
+    const refreshToken = typeof responseBody?.refreshToken === "string" ? responseBody.refreshToken.trim() : "";
+    if (!uid || !idToken || !refreshToken) {
+        throw new Error("Firebase exchange response is missing uid, idToken, or refreshToken.");
+    }
+    return { uid, idToken, refreshToken };
+}
+async function refreshCachedFirebaseCredentials(fetchImpl = fetch) {
+    const cache = readStudioAuthCache();
+    if (!cache?.refreshToken) {
+        return null;
+    }
+    const response = await fetchImpl(`https://securetoken.googleapis.com/v1/token?key=${getFirebaseApiKey()}`, {
+        method: "POST",
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: `grant_type=refresh_token&refresh_token=${encodeURIComponent(cache.refreshToken)}`,
+    });
+    const responseBody = await readJsonBody(response);
+    if (!response.ok) {
+        return null;
+    }
+    const uid = typeof responseBody?.user_id === "string" ? responseBody.user_id.trim() : "";
+    const idToken = typeof responseBody?.id_token === "string" ? responseBody.id_token.trim() : "";
+    const refreshToken = typeof responseBody?.refresh_token === "string" ? responseBody.refresh_token.trim() : "";
+    if (!uid || !idToken || !refreshToken) {
+        return null;
+    }
+    return { uid, idToken, refreshToken };
+}
+function readStudioAuthCache() {
+    const cachePath = getStudioAuthCachePath();
+    if (!existsSync(cachePath)) {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(readFileSync(cachePath, "utf8"));
+        const uid = typeof payload.uid === "string" ? payload.uid.trim() : "";
+        const idToken = typeof payload.id_token === "string" ? payload.id_token.trim() : "";
+        const refreshToken = typeof payload.refresh_token === "string" ? payload.refresh_token.trim() : "";
+        if (!uid || !refreshToken) {
+            return null;
+        }
+        return { uid, idToken, refreshToken };
+    }
+    catch {
+        return null;
+    }
+}
+async function writeStudioAuthCache(credentials) {
+    await mkdir(getDefaultTapiDataDir(), { recursive: true });
+    await writeFile(getStudioAuthCachePath(), `${JSON.stringify({
+        uid: credentials.uid,
+        refresh_token: credentials.refreshToken,
+        id_token: credentials.idToken,
+    }, null, 2)}\n`, "utf8");
+}
+function getStudioAuthCachePath() {
+    return join(getDefaultTapiDataDir(), "auth.json");
+}
+function getDefaultTapiDataDir() {
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA
+            ?? (process.env.USERPROFILE ? join(process.env.USERPROFILE, "AppData", "Local") : join(homedir(), "AppData", "Local"));
+        return join(localAppData, "Tapi");
+    }
+    return join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "tapi");
+}
+function getStudioAuthHtmlUrl() {
+    return normalizeHttpUrl(envString("TAPI_STUDIO_AUTH_HTML_URL") ?? DEFAULT_STUDIO_AUTH_HTML_URL, "TAPI_STUDIO_AUTH_HTML_URL");
+}
+function getFirebaseApiKey() {
+    return (envString("TAPI_FIREBASE_API_KEY") ?? DEFAULT_FIREBASE_API_KEY).trim();
+}
+function openBrowser(url) {
+    const child = spawn("cmd", ["/c", "start", "", url], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    child.unref();
+}
+async function readJsonBody(response) {
+    const text = await response.text();
+    if (!text.trim()) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function isApprovalTerminalError(error) {
+    return error instanceof StudioInstallApprovalError
+        && (error.code === "pending_approval" || error.code === "access_pending" || error.code === "access_rejected");
+}
+function renderBrowserSignInResponseHtml(success) {
+    return success
+        ? "<!DOCTYPE html><html><body style='font-family:system-ui;text-align:center;padding:80px'><h2 style='color:#22c55e'>&#10003; Signed in!</h2><p>Return to your terminal.</p><script>setTimeout(()=>window.close(),1600)</script></body></html>"
+        : "<!DOCTYPE html><html><body style='font-family:system-ui;text-align:center;padding:80px'><h2 style='color:#ef4444'>&#9888; Sign-in failed</h2><p>Return to your terminal for details.</p></body></html>";
+}
 async function hasVerifiedCachedInstaller(path, expectedSha256) {
     if (!existsSync(path)) {
         return false;
@@ -323,6 +860,34 @@ function cachedInstallerName(manifest) {
     const rawName = manifest.artifactName || basename(new URL(manifest.url).pathname) || `TapiStudioSetup-${manifest.version}.exe`;
     return rawName.replace(/[^A-Za-z0-9._-]/g, "_");
 }
+function installEventOptions(options) {
+    return {
+        channel: options.channel,
+        apiBaseUrl: options.apiBaseUrl,
+        manifestUrl: options.manifestUrl,
+        manifestUrlOverride: options.manifestUrlOverride,
+        cacheDir: options.cacheDir,
+        downloadOnly: options.downloadOnly,
+        silent: options.silent,
+        exePath: options.exePath,
+        installTokenProvided: Boolean(options.installToken),
+    };
+}
+function manifestEventSummary(manifest) {
+    return {
+        product: manifest.product,
+        version: manifest.version,
+        channel: manifest.channel,
+        platform: manifest.platform,
+        artifactName: manifest.artifactName,
+        url: manifest.url,
+        sha256: manifest.sha256,
+        sizeBytes: manifest.sizeBytes,
+        minSdkVersion: manifest.minSdkVersion,
+        commitShort: manifest.commitShort,
+        bundledService: manifest.bundledService,
+    };
+}
 function parseChannel(value) {
     if (value === "pilot" || value === "stable" || value === "nightly") {
         return value;
@@ -409,7 +974,7 @@ function printHelp() {
     console.log(`Tapi CLI
 
 Usage:
-  tapi studio install [--channel pilot] [--manifest URL]
+  tapi studio install [--channel pilot] [--api-base-url URL]
   tapi studio open
   tapi studio doctor
   tapi doctor
@@ -430,17 +995,63 @@ Usage:
   tapi studio doctor [options]
 
 Options:
-  --channel <name>      Release channel: pilot, stable, or nightly
-  --manifest <url>      Exact release manifest URL
-  --cache-dir <path>    Installer download cache directory
-  --download-only       Download and verify without running the installer
-  --silent              Run the NSIS installer with /S
-  --exe <path>          Tapi Studio executable path for open/doctor
+  --channel <name>       Release channel: pilot, stable, or nightly
+  --api-base-url <url>   Tapi API base URL for approval and protected downloads
+  --server <url>         Alias for --api-base-url
+  --install-token <tok>  Preissued Studio install token (skips browser sign-in)
+  --manifest <url>       Exact release manifest URL for doctor only
+  --cache-dir <path>     Installer download cache directory
+  --download-only        Download and verify without running the installer
+  --silent               Run the NSIS installer with /S
+  --exe <path>           Tapi Studio executable path for open/doctor
 `);
 }
 function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function errorDetails(error) {
+    if (error instanceof Error) {
+        const details = {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+        };
+        const cause = error.cause;
+        if (cause) {
+            details.cause = serializeError(cause);
+        }
+        return details;
+    }
+    return {
+        message: String(error),
+    };
+}
+function serializeError(error) {
+    if (error instanceof Error) {
+        const record = error;
+        const details = {
+            name: error.name,
+            message: error.message,
+        };
+        for (const key of ["code", "errno", "syscall", "address", "port"]) {
+            const value = record[key];
+            if (value !== undefined) {
+                details[key] = value;
+            }
+        }
+        const cause = error.cause;
+        if (cause) {
+            details.cause = serializeError(cause);
+        }
+        return details;
+    }
+    if (error && typeof error === "object") {
+        return Object.fromEntries(Object.entries(error).filter(([, value]) => value !== undefined));
+    }
+    return {
+        message: String(error),
+    };
+}
 function isCliEntrypoint() {
     const invokedPath = process.argv[1];
     return Boolean(invokedPath && resolve(invokedPath) === fileURLToPath(import.meta.url));

package/dist/types.d.ts

@@ -31,7 +31,10 @@ export interface TapiRunner {
 }
 export interface RuntimeRequirements {
     daemonRequired: boolean;
+    serviceRequired?: boolean;
     localControlUrl?: string;
+    serviceName?: string;
+    serviceVersion?: string;
     windowsServiceName?: string;
     [key: string]: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapi-dev/sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",