dazzer-connect 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dazzer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# dazzer-cli
+
+Sign in to Dazzer from your terminal and get a copy-paste MCP client configuration.
+
+Requires Node.js 20 or later.
+
+## Install
+
+```bash
+# One-off sign-in (downloads and runs the CLI)
+npx dazzer-cli auth login
+
+# Or install globally — the command is `dazzer`
+npm i -g dazzer-cli
+dazzer auth login
+```
+
+The CLI opens your browser to sign in (or falls back to a device code when headless). On success it prints MCP client configuration to your terminal.
+
+## Configure Claude Desktop
+
+After `dazzer auth login`, copy the JSON block from your terminal into your Claude Desktop MCP settings file:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+The block looks like this (your access token is filled in automatically):
+
+```json
+{
+  "mcpServers": {
+    "dazzer": {
+      "url": "https://graph.dazzer.io/mcp",
+      "headers": {
+        "Authorization": "Bearer <your-access-token>"
+      }
+    }
+  }
+}
+```
+
+Merge it with any existing `mcpServers` entries, save the file, then restart Claude Desktop.
+
+If keychain storage failed during login, the printed config is your fallback — paste it before closing the terminal.
+
+## Other commands
+
+```bash
+dazzer auth status    # show sign-in status
+dazzer auth logout    # sign out and remove stored tokens
+dazzer --help
+```
+
+## Configuration
+
+Production defaults apply when you omit flags and env vars:
+
+| Source | Variable | Default |
+|--------|----------|---------|
+| Flag | `--issuer` | — |
+| Env | `DAZZER_AUTH_ISSUER` | `https://auth.dazzer.io` |
+| Env | `DAZZER_AUTH_CLIENT_ID` | `dazzer-cli-local` |
+| Env | `DAZZER_AUTH_RESOURCE` | `https://graph.dazzer.io/mcp` |
+
+For local development against a running authorization server:
+
+```bash
+dazzer auth login --issuer http://localhost:3003
+```
+
+## Token storage
+
+- **Secrets** (access + refresh tokens): OS keychain via `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, Linux Secret Service). Prebuilt binaries install with the package — no compiler required.
+- **Metadata** (issuer, client id, expiry): config directory from `env-paths("dazzer")` — typically `~/Library/Application Support/dazzer/` on macOS.
+
+If keychain storage fails, login still completes and prints copy-paste-ready MCP client config to stdout.
+
+## Develop from source
+
+```bash
+pnpm --filter dazzer-cli build
+node packages/oauth-cli/dist/index.js auth login --issuer http://localhost:3003
+```

package/dist/commands/login.js

@@ -0,0 +1,72 @@
+/**
+ * @purpose Runs the browser loopback sign-in flow (gcloud-style) by default and
+ * falls back to the device-code flow for headless environments, then stores
+ * tokens and prints copy-paste-ready MCP client config for the user.
+ */
+import { saveAuthMetadata } from "../lib/config-store.js";
+import { pollForTokens, requestDeviceCode } from "../lib/device-flow.js";
+import { discoverEndpoints } from "../lib/discovery.js";
+import { browserLikelyAvailable, runLoopbackFlow } from "../lib/loopback-flow.js";
+import { fail, printBrowserOpening, printDeviceInstructions, printLoginSuccess, printMcpClientConfig, } from "../lib/output.js";
+import { persistLoginTokens } from "../lib/refresh.js";
+import { createTokenStore } from "../lib/token-store.js";
+/** Executes auth login: browser loopback (or device fallback), keychain storage, config output. */
+export async function runLogin(options) {
+    const tokenStore = createTokenStore();
+    let keychainOk = true;
+    let discovery;
+    try {
+        discovery = await discoverEndpoints(options.issuer);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : "Could not reach the authorization server.");
+    }
+    // Loopback (gcloud-style) is the default; device-code is the headless fallback.
+    const useLoopback = !options.noBrowser && Boolean(discovery.authorizationEndpoint) && browserLikelyAvailable();
+    let tokens;
+    try {
+        if (useLoopback) {
+            tokens = await runLoopbackFlow({
+                discovery,
+                clientId: options.clientId,
+                resource: options.resource,
+                onPrompt: printBrowserOpening,
+            });
+        }
+        else {
+            const deviceAuth = await requestDeviceCode({
+                discovery,
+                clientId: options.clientId,
+            });
+            printDeviceInstructions(deviceAuth);
+            tokens = await pollForTokens({
+                discovery,
+                clientId: options.clientId,
+                deviceCode: deviceAuth.device_code,
+                deviceAuth,
+                resource: options.resource,
+            });
+        }
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : "Sign-in failed.");
+    }
+    if (!tokens.refresh_token) {
+        fail("The authorization server did not return a refresh token.");
+    }
+    try {
+        await persistLoginTokens(tokenStore, tokens);
+    }
+    catch {
+        keychainOk = false;
+    }
+    const expiresAt = typeof tokens.expires_in === "number" ? Date.now() + tokens.expires_in * 1000 : null;
+    await saveAuthMetadata({
+        issuer: discovery.issuer,
+        clientId: options.clientId,
+        expiresAt,
+    });
+    printLoginSuccess(keychainOk);
+    // The MCP client connects to the resource server (the Brain), not the issuer.
+    printMcpClientConfig(tokens.access_token, options.resource ?? discovery.issuer);
+}

package/dist/commands/logout.js

@@ -0,0 +1,21 @@
+/**
+ * @purpose Clears stored tokens and auth metadata so the user is fully signed out.
+ */
+import { clearAuthMetadata, loadAuthMetadata } from "../lib/config-store.js";
+import { printLogoutSuccess } from "../lib/output.js";
+import { createTokenStore } from "../lib/token-store.js";
+/** Executes auth logout: keychain clear + config file removal. */
+export async function runLogout() {
+    const tokenStore = createTokenStore();
+    await tokenStore.clear();
+    await clearAuthMetadata();
+    printLogoutSuccess();
+}
+/** Returns whether the user appears signed in (metadata + tokens present). */
+export async function isSignedIn() {
+    const meta = await loadAuthMetadata();
+    if (!meta)
+        return false;
+    const tokens = await createTokenStore().load();
+    return tokens !== null;
+}

package/dist/commands/status.js

@@ -0,0 +1,38 @@
+/**
+ * @purpose Shows whether the user is signed in and attempts a transparent refresh
+ * so status reflects a currently valid access token when possible.
+ */
+import { loadAuthMetadata } from "../lib/config-store.js";
+import { discoverEndpoints } from "../lib/discovery.js";
+import { printAuthStatus } from "../lib/output.js";
+import { getValidAccessToken } from "../lib/refresh.js";
+import { createTokenStore } from "../lib/token-store.js";
+/** Executes auth status: load metadata, refresh if possible, print result. */
+export async function runStatus(options) {
+    const tokenStore = createTokenStore();
+    const meta = await loadAuthMetadata();
+    const tokens = await tokenStore.load();
+    if (!meta || !tokens) {
+        printAuthStatus({ signedIn: false });
+        return;
+    }
+    const issuer = options.issuer ?? meta.issuer;
+    const clientId = options.clientId ?? meta.clientId;
+    let expiresAt = meta.expiresAt;
+    try {
+        const discovery = await discoverEndpoints(issuer);
+        const refreshed = await getValidAccessToken({
+            discovery,
+            clientId,
+            tokenStore,
+            resource: options.resource,
+        });
+        if (refreshed?.expiresIn) {
+            expiresAt = Date.now() + refreshed.expiresIn * 1000;
+        }
+    }
+    catch {
+        // show last known status
+    }
+    printAuthStatus({ signedIn: true, issuer: meta.issuer, expiresAt });
+}

package/dist/env.js

@@ -0,0 +1,25 @@
+/**
+ * @purpose Validates CLI environment variables once at startup so every command
+ * receives a typed, fail-fast config snapshot instead of ad-hoc parsing.
+ */
+import { z } from "zod/v4";
+const cliEnvSchema = z.object({
+    /** Authorization server issuer URL. Defaults to production; override for local dev. */
+    DAZZER_AUTH_ISSUER: z.url().default("https://auth.dazzer.io"),
+    /** OAuth public client id. */
+    DAZZER_AUTH_CLIENT_ID: z.string().min(1).default("dazzer-cli-local"),
+    /** Resource indicator for JWT access tokens. Defaults to the production MCP server. */
+    DAZZER_AUTH_RESOURCE: z.url().default("https://graph.dazzer.io/mcp"),
+});
+let cachedEnv = null;
+/** Validates process.env once and returns the typed CLI env snapshot. */
+export function validateEnv() {
+    if (!cachedEnv) {
+        cachedEnv = cliEnvSchema.parse(process.env);
+    }
+    return cachedEnv;
+}
+/** Test helper: clears lazy env cache between cases. */
+export function resetEnvCacheForTests() {
+    cachedEnv = null;
+}

package/dist/index.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * @purpose Entry point for the dazzer CLI — wires Commander subcommands for
+ * auth login, logout, and status against a configurable authorization server.
+ */
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import { runLogin } from "./commands/login.js";
+import { runLogout } from "./commands/logout.js";
+import { runStatus } from "./commands/status.js";
+import { validateEnv } from "./env.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+const program = new Command();
+program.name("dazzer").description("Sign in to Dazzer from your terminal").version(version);
+const auth = program.command("auth").description("Manage sign-in");
+auth
+    .command("login")
+    .description("Sign in through your browser; falls back to a device code when headless")
+    .option("--issuer <url>", "Authorization server URL")
+    .option("--client-id <id>", "OAuth client id")
+    .option("--resource <url>", "Resource indicator for access tokens")
+    .option("--no-browser", "Use the device-code flow instead of opening a browser")
+    .action(async (opts) => {
+    const env = validateEnv();
+    await runLogin({
+        issuer: opts.issuer ?? env.DAZZER_AUTH_ISSUER,
+        clientId: opts.clientId ?? env.DAZZER_AUTH_CLIENT_ID,
+        resource: opts.resource ?? env.DAZZER_AUTH_RESOURCE,
+        noBrowser: opts.browser === false,
+    });
+});
+auth
+    .command("logout")
+    .description("Sign out and remove stored tokens")
+    .action(async () => {
+    await runLogout();
+});
+auth
+    .command("status")
+    .description("Show sign-in status")
+    .option("--issuer <url>", "Authorization server URL")
+    .option("--client-id <id>", "OAuth client id")
+    .option("--resource <url>", "Resource indicator for access tokens")
+    .action(async (opts) => {
+    await runStatus({
+        issuer: opts.issuer,
+        clientId: opts.clientId,
+        resource: opts.resource,
+    });
+});
+program.parseAsync(process.argv).catch((err) => {
+    process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/lib/config-store.js

@@ -0,0 +1,44 @@
+/**
+ * @purpose Persists non-secret auth metadata on disk so status and refresh know
+ * which issuer and client issued the current tokens without storing secrets.
+ */
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import envPaths from "env-paths";
+const paths = envPaths("dazzer", { suffix: "" });
+const CONFIG_FILE = join(paths.config, "auth.json");
+async function ensureConfigDir() {
+    await mkdir(paths.config, { recursive: true });
+}
+/** Saves non-secret auth metadata to the CLI config directory. */
+export async function saveAuthMetadata(meta) {
+    await ensureConfigDir();
+    await writeFile(CONFIG_FILE, `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+}
+/** Loads auth metadata, or null if the user has never signed in. */
+export async function loadAuthMetadata() {
+    try {
+        const raw = await readFile(CONFIG_FILE, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.issuer !== "string" || typeof parsed.clientId !== "string") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Removes auth metadata from disk. */
+export async function clearAuthMetadata() {
+    try {
+        await unlink(CONFIG_FILE);
+    }
+    catch {
+        // ignore missing file
+    }
+}
+/** Returns the CLI config directory path (for documentation / diagnostics). */
+export function getConfigDir() {
+    return paths.config;
+}

package/dist/lib/device-flow.js

@@ -0,0 +1,110 @@
+const DEFAULT_SCOPE = "openid offline_access";
+function parseDeviceResponse(body) {
+    const deviceCode = body.device_code;
+    const userCode = body.user_code;
+    const verificationUri = body.verification_uri;
+    const expiresIn = body.expires_in;
+    if (typeof deviceCode !== "string" ||
+        typeof userCode !== "string" ||
+        typeof verificationUri !== "string" ||
+        typeof expiresIn !== "number") {
+        throw new Error("The authorization server returned an unexpected device response.");
+    }
+    return {
+        device_code: deviceCode,
+        user_code: userCode,
+        verification_uri: verificationUri,
+        verification_uri_complete: typeof body.verification_uri_complete === "string"
+            ? body.verification_uri_complete
+            : undefined,
+        expires_in: expiresIn,
+        interval: typeof body.interval === "number" ? body.interval : undefined,
+    };
+}
+/** Requests a device code from the authorization server. */
+export async function requestDeviceCode(options) {
+    const fetchFn = options.fetchFn ?? fetch;
+    const endpoint = options.discovery.deviceAuthorizationEndpoint;
+    if (!endpoint) {
+        throw new Error("This authorization server does not support device sign-in.");
+    }
+    const params = new URLSearchParams({
+        client_id: options.clientId,
+        scope: options.scope ?? DEFAULT_SCOPE,
+    });
+    if (options.resource) {
+        params.set("resource", options.resource);
+    }
+    const res = await fetchFn(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: params.toString(),
+    });
+    if (!res.ok) {
+        throw new Error(`Device sign-in request failed (${res.status}).`);
+    }
+    return parseDeviceResponse((await res.json()));
+}
+/** Polls the token endpoint until the user completes authorization or time runs out. */
+export async function pollForTokens(options) {
+    const fetchFn = options.fetchFn ?? fetch;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const baseIntervalMs = (options.deviceAuth.interval ?? 5) * 1000;
+    let intervalMs = options.pollIntervalMs ?? baseIntervalMs;
+    const deadline = Date.now() + (options.maxWaitMs ?? options.deviceAuth.expires_in * 1000);
+    while (Date.now() < deadline) {
+        await sleep(intervalMs);
+        const params = new URLSearchParams({
+            grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+            device_code: options.deviceCode,
+            client_id: options.clientId,
+        });
+        if (options.resource) {
+            params.set("resource", options.resource);
+        }
+        const res = await fetchFn(options.discovery.tokenEndpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: params.toString(),
+        });
+        const body = (await res.json());
+        if (res.ok) {
+            const accessToken = body.access_token;
+            if (typeof accessToken !== "string") {
+                throw new Error("The authorization server returned an unexpected token response.");
+            }
+            return {
+                access_token: accessToken,
+                refresh_token: typeof body.refresh_token === "string" ? body.refresh_token : undefined,
+                expires_in: typeof body.expires_in === "number" ? body.expires_in : undefined,
+                token_type: typeof body.token_type === "string" ? body.token_type : undefined,
+            };
+        }
+        const error = typeof body.error === "string" ? body.error : "unknown_error";
+        if (error === "authorization_pending") {
+            continue;
+        }
+        if (error === "slow_down") {
+            intervalMs += 5000;
+            continue;
+        }
+        if (error === "access_denied") {
+            throw new Error("Sign-in was denied.");
+        }
+        if (error === "expired_token") {
+            throw new Error("The device code expired. Run auth login again.");
+        }
+        throw new Error(`Token request failed: ${error}`);
+    }
+    throw new Error("Timed out waiting for sign-in. Run auth login again.");
+}
+/** Runs the full device-code flow: request code then poll for tokens. */
+export async function runDeviceFlow(options) {
+    const deviceAuth = await requestDeviceCode(options);
+    const tokens = await pollForTokens({
+        ...options,
+        deviceCode: deviceAuth.device_code,
+        deviceAuth,
+    });
+    return { deviceAuth, tokens };
+}

package/dist/lib/discovery.js

@@ -0,0 +1,27 @@
+/** Fetches and validates the authorization server metadata document. */
+export async function discoverEndpoints(issuer) {
+    const normalized = issuer.replace(/\/$/, "");
+    const url = `${normalized}/.well-known/oauth-authorization-server`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Could not reach the authorization server (${res.status}). Check --issuer.`);
+    }
+    const body = (await res.json());
+    const authorizationEndpoint = body.authorization_endpoint;
+    const deviceAuthorizationEndpoint = body.device_authorization_endpoint;
+    const tokenEndpoint = body.token_endpoint;
+    if (typeof tokenEndpoint !== "string" || tokenEndpoint === "") {
+        throw new Error("This authorization server is missing a token endpoint.");
+    }
+    const hasAuthorization = typeof authorizationEndpoint === "string" && authorizationEndpoint !== "";
+    const hasDevice = typeof deviceAuthorizationEndpoint === "string" && deviceAuthorizationEndpoint !== "";
+    if (!hasAuthorization && !hasDevice) {
+        throw new Error("This authorization server does not support browser or device sign-in.");
+    }
+    return {
+        issuer: typeof body.issuer === "string" ? body.issuer : normalized,
+        authorizationEndpoint: hasAuthorization ? authorizationEndpoint : undefined,
+        deviceAuthorizationEndpoint: hasDevice ? deviceAuthorizationEndpoint : undefined,
+        tokenEndpoint,
+    };
+}

package/dist/lib/loopback-flow.js

@@ -0,0 +1,212 @@
+/**
+ * @purpose Runs the RFC 8252 loopback authorization-code + PKCE flow so a real
+ * user signs in through their browser with one click and the CLI captures the
+ * resulting tokens — no device code, no manual code entry, no polling.
+ */
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+const DEFAULT_SCOPE = "openid offline_access brain";
+const CALLBACK_PATH = "/callback";
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+function base64url(buf) {
+    return buf.toString("base64").replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+function createPkce() {
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+/** Opens the default browser cross-platform; best-effort and never throws. */
+function launchBrowser(url) {
+    const platform = process.platform;
+    const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(command, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // best-effort; the caller surfaces the URL via onPrompt
+    }
+}
+function buildAuthorizeUrl(endpoint, params) {
+    const url = new URL(endpoint);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", params.clientId);
+    url.searchParams.set("redirect_uri", params.redirectUri);
+    url.searchParams.set("scope", params.scope);
+    url.searchParams.set("state", params.state);
+    url.searchParams.set("code_challenge", params.challenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    if (params.resource) {
+        url.searchParams.set("resource", params.resource);
+    }
+    return url.toString();
+}
+const BRAND_STYLE = `
+:root{--teal:#0FB6AE;--teal-deep:#0B8C86;--ink:#15211F;--muted:#5B6B68;--line:#E4ECEA;--bg:#F5F8F7;}
+*{box-sizing:border-box;margin:0;padding:0;}html,body{height:100%;}
+body{font-family:'Inter',-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;color:var(--ink);background:var(--bg);
+-webkit-font-smoothing:antialiased;display:flex;align-items:center;justify-content:center;min-height:100vh;padding:32px 20px;text-align:center;}
+.card{max-width:392px;background:#fff;border:1px solid var(--line);border-radius:14px;padding:40px 36px;
+box-shadow:0 1px 2px rgba(16,40,38,.04),0 12px 32px rgba(16,40,38,.07);}
+.icon{width:46px;height:46px;margin:0 auto 18px;display:block;}
+h1{font-family:'Space Grotesk',sans-serif;font-weight:600;font-size:20px;letter-spacing:-.015em;margin-bottom:8px;color:var(--ink);}
+p{font-size:14px;line-height:1.55;color:var(--muted);}
+.foot{margin-top:22px;padding-top:16px;border-top:1px solid var(--line);font-size:12px;color:#7C8B88;}
+`;
+const SUCCESS_MARK = `<svg class="icon" viewBox="0 0 46 46" aria-hidden="true"><circle cx="23" cy="23" r="23" fill="#E3F5F2"/><path d="M14 23.5l6 6 12-13" fill="none" stroke="#0B8C86" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
+const ERROR_MARK = `<svg class="icon" viewBox="0 0 46 46" aria-hidden="true"><circle cx="23" cy="23" r="23" fill="#FBEAEA"/><path d="M23 13v13M23 31.5v.5" fill="none" stroke="#B23B3B" stroke-width="2.6" stroke-linecap="round"/></svg>`;
+function brandPage(title, heading, body, mark) {
+    return `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>
+<link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500&family=Space+Grotesk:wght@600&display=swap" rel="stylesheet">
+<style>${BRAND_STYLE}</style></head>
+<body><main class="card">${mark}<h1>${heading}</h1><p>${body}</p>
+<div class="foot">Dazzer secure sign-in</div></main></body></html>`;
+}
+function successPage() {
+    return brandPage("Signed in to Dazzer", "You're signed in", "You can close this tab and return to your terminal.", SUCCESS_MARK);
+}
+/** The branded success page served on the loopback callback — exported for tests/preview. */
+export function renderLoopbackSuccessPage() {
+    return successPage();
+}
+/** Escapes a user-provided value before it is embedded in server-rendered HTML. */
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function errorPage(reason) {
+    // `reason` can originate from the OAuth `error` query param (user-controlled),
+    // so escape it before it reaches the HTML sink (reflected-XSS guard).
+    return brandPage("Sign-in failed", "Something went wrong", `We couldn't complete sign-in (${escapeHtml(reason)}). Close this tab and run the command again.`, ERROR_MARK);
+}
+function sendHtml(res, html) {
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.end(html);
+}
+/**
+ * Runs the full loopback flow: bind an ephemeral 127.0.0.1 port, open the
+ * browser to the authorization endpoint, capture the redirect, and exchange the
+ * code (with the PKCE verifier) for tokens.
+ */
+export async function runLoopbackFlow(options) {
+    const fetchFn = options.fetchFn ?? fetch;
+    const { authorizationEndpoint } = options.discovery;
+    if (!authorizationEndpoint) {
+        throw new Error("This authorization server does not support browser sign-in.");
+    }
+    const { verifier, challenge } = createPkce();
+    const state = base64url(randomBytes(16));
+    const scope = options.scope ?? DEFAULT_SCOPE;
+    const { code, redirectUri } = await new Promise((resolve, reject) => {
+        let timer;
+        const server = createServer((req, res) => {
+            const requestUrl = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (requestUrl.pathname !== CALLBACK_PATH) {
+                res.statusCode = 404;
+                res.end("Not found");
+                return;
+            }
+            const addr = server.address();
+            const redirect = `http://127.0.0.1:${addr.port}${CALLBACK_PATH}`;
+            const returnedState = requestUrl.searchParams.get("state");
+            const errorParam = requestUrl.searchParams.get("error");
+            const returnedCode = requestUrl.searchParams.get("code");
+            const finish = (err) => {
+                if (timer)
+                    clearTimeout(timer);
+                server.close();
+                if (err)
+                    reject(err);
+            };
+            if (errorParam) {
+                sendHtml(res, errorPage(errorParam));
+                finish(new Error(`Sign-in failed: ${errorParam}.`));
+                return;
+            }
+            if (returnedState !== state) {
+                sendHtml(res, errorPage("state_mismatch"));
+                finish(new Error("Sign-in failed: state mismatch."));
+                return;
+            }
+            if (!returnedCode) {
+                sendHtml(res, errorPage("missing_code"));
+                finish(new Error("Sign-in failed: no authorization code returned."));
+                return;
+            }
+            sendHtml(res, successPage());
+            finish();
+            resolve({ code: returnedCode, redirectUri: redirect });
+        });
+        server.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(err);
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            const redirect = `http://127.0.0.1:${addr.port}${CALLBACK_PATH}`;
+            const authorizeUrl = buildAuthorizeUrl(authorizationEndpoint, {
+                clientId: options.clientId,
+                redirectUri: redirect,
+                scope,
+                state,
+                challenge,
+                resource: options.resource,
+            });
+            timer = setTimeout(() => {
+                server.close();
+                reject(new Error("Timed out waiting for sign-in. Run the command again."));
+            }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            (options.openBrowser ?? launchBrowser)(authorizeUrl);
+            options.onPrompt?.(authorizeUrl);
+        });
+    });
+    const params = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri,
+        client_id: options.clientId,
+        code_verifier: verifier,
+    });
+    if (options.resource) {
+        params.set("resource", options.resource);
+    }
+    const res = await fetchFn(options.discovery.tokenEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: params.toString(),
+    });
+    const body = (await res.json());
+    if (!res.ok) {
+        const error = typeof body.error === "string" ? body.error : "token_exchange_failed";
+        throw new Error(`Token request failed: ${error}`);
+    }
+    const accessToken = body.access_token;
+    if (typeof accessToken !== "string") {
+        throw new Error("The authorization server returned an unexpected token response.");
+    }
+    return {
+        access_token: accessToken,
+        refresh_token: typeof body.refresh_token === "string" ? body.refresh_token : undefined,
+        expires_in: typeof body.expires_in === "number" ? body.expires_in : undefined,
+        token_type: typeof body.token_type === "string" ? body.token_type : undefined,
+    };
+}
+/** True when the environment can plausibly open a browser (loopback viable). */
+export function browserLikelyAvailable() {
+    if (process.platform === "darwin" || process.platform === "win32") {
+        return true;
+    }
+    // Linux/other: a display server is needed to open a browser.
+    return Boolean(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+}

package/dist/lib/output.js

@@ -0,0 +1,79 @@
+function writeOut(message) {
+    process.stdout.write(`${message}\n`);
+}
+function writeErr(message) {
+    process.stderr.write(`${message}\n`);
+}
+/** Prints device-flow instructions for the user to complete in a browser. */
+export function printDeviceInstructions(deviceAuth) {
+    writeOut("");
+    if (deviceAuth.verification_uri_complete) {
+        writeOut("To finish signing in, open this link in your browser:");
+        writeOut(`  ${deviceAuth.verification_uri_complete}`);
+    }
+    else {
+        writeOut("To finish signing in, open this page in your browser:");
+        writeOut(`  ${deviceAuth.verification_uri}`);
+        writeOut("");
+        writeOut("Then enter this code:");
+        writeOut(`  ${deviceAuth.user_code}`);
+    }
+    writeOut("");
+    writeOut("Waiting for you to approve in the browser...");
+}
+/** Tells the user their browser is opening for the loopback sign-in, with a manual fallback. */
+export function printBrowserOpening(url) {
+    writeOut("");
+    writeOut("Opening your browser to sign in…");
+    writeOut("If it doesn't open automatically, paste this into your browser:");
+    writeOut(`  ${url}`);
+    writeOut("");
+}
+/** Prints success message after login completes. */
+export function printLoginSuccess(keychainOk) {
+    writeOut("");
+    writeOut("Signed in successfully.");
+    if (!keychainOk) {
+        writeErr("Warning: could not save tokens to the OS keychain. Use the config below.");
+    }
+}
+/** Prints copy-paste-ready MCP client config with Bearer authorization. */
+export function printMcpClientConfig(accessToken, mcpServerUrl) {
+    writeOut("");
+    writeOut("Copy this into your MCP client configuration:");
+    writeOut("");
+    writeOut("{");
+    writeOut('  "mcpServers": {');
+    writeOut('    "dazzer": {');
+    writeOut(`      "url": "${mcpServerUrl.replace(/\/$/, "")}",`);
+    writeOut('      "headers": {');
+    writeOut(`        "Authorization": "Bearer ${accessToken}"`);
+    writeOut("      }");
+    writeOut("    }");
+    writeOut("  }");
+    writeOut("}");
+    writeOut("");
+}
+/** Prints auth status for the status command. */
+export function printAuthStatus(params) {
+    if (!params.signedIn) {
+        writeOut("Not signed in. Run: dazzer auth login");
+        return;
+    }
+    writeOut("Signed in.");
+    if (params.issuer) {
+        writeOut(`  Issuer: ${params.issuer}`);
+    }
+    if (params.expiresAt) {
+        writeOut(`  Token expires: ${new Date(params.expiresAt).toISOString()}`);
+    }
+}
+/** Prints logout confirmation. */
+export function printLogoutSuccess() {
+    writeOut("Signed out.");
+}
+/** Prints a user-facing error and exits. */
+export function fail(message) {
+    writeErr(`Error: ${message}`);
+    process.exit(1);
+}

package/dist/lib/refresh.js

@@ -0,0 +1,60 @@
+/** Exchanges a refresh token for a new access token (and rotated refresh token). */
+export async function refreshAccessToken(options) {
+    const fetchFn = options.fetchFn ?? fetch;
+    const params = new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: options.clientId,
+        refresh_token: options.refreshToken,
+    });
+    if (options.resource) {
+        params.set("resource", options.resource);
+    }
+    const res = await fetchFn(options.discovery.tokenEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: params.toString(),
+    });
+    const body = (await res.json());
+    if (!res.ok) {
+        const error = typeof body.error === "string" ? body.error : "refresh_failed";
+        throw new Error(`Could not refresh token: ${error}`);
+    }
+    const accessToken = body.access_token;
+    const refreshToken = body.refresh_token;
+    if (typeof accessToken !== "string") {
+        throw new Error("The authorization server returned an unexpected refresh response.");
+    }
+    const newRefresh = typeof refreshToken === "string" ? refreshToken : options.refreshToken;
+    const expiresIn = typeof body.expires_in === "number" ? body.expires_in : null;
+    await options.tokenStore.save({ accessToken, refreshToken: newRefresh });
+    return { accessToken, refreshToken: newRefresh, expiresIn };
+}
+/** Returns a valid access token, refreshing when possible. */
+export async function getValidAccessToken(options) {
+    const stored = await options.tokenStore.load();
+    if (!stored) {
+        return null;
+    }
+    try {
+        return await refreshAccessToken({ ...options, refreshToken: stored.refreshToken });
+    }
+    catch {
+        return {
+            accessToken: stored.accessToken,
+            refreshToken: stored.refreshToken,
+            expiresIn: null,
+        };
+    }
+}
+/** Saves freshly issued tokens after login. */
+export async function persistLoginTokens(tokenStore, tokens) {
+    if (!tokens.refresh_token) {
+        throw new Error("The authorization server did not return a refresh token.");
+    }
+    const stored = {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+    };
+    await tokenStore.save(stored);
+    return stored;
+}

package/dist/lib/token-store.js

@@ -0,0 +1,60 @@
+/**
+ * @purpose Defines the token storage contract and provides keychain-backed and
+ * in-memory implementations so secrets stay out of disk while tests stay hermetic.
+ */
+import { Entry } from "@napi-rs/keyring";
+const SERVICE = "dazzer-oauth-cli";
+const ACCESS_ACCOUNT = "access-token";
+const REFRESH_ACCOUNT = "refresh-token";
+function accessEntry() {
+    return new Entry(SERVICE, ACCESS_ACCOUNT);
+}
+function refreshEntry() {
+    return new Entry(SERVICE, REFRESH_ACCOUNT);
+}
+/** Persists tokens in the OS keychain via @napi-rs/keyring. */
+export class KeychainTokenStore {
+    async save(tokens) {
+        accessEntry().setPassword(tokens.accessToken);
+        refreshEntry().setPassword(tokens.refreshToken);
+    }
+    async load() {
+        const accessToken = accessEntry().getPassword();
+        const refreshToken = refreshEntry().getPassword();
+        if (!accessToken || !refreshToken) {
+            return null;
+        }
+        return { accessToken, refreshToken };
+    }
+    async clear() {
+        try {
+            accessEntry().deletePassword();
+        }
+        catch {
+            // ignore missing entry
+        }
+        try {
+            refreshEntry().deletePassword();
+        }
+        catch {
+            // ignore missing entry
+        }
+    }
+}
+/** In-memory store for unit tests. */
+export class MemoryTokenStore {
+    tokens = null;
+    async save(tokens) {
+        this.tokens = { ...tokens };
+    }
+    async load() {
+        return this.tokens ? { ...this.tokens } : null;
+    }
+    async clear() {
+        this.tokens = null;
+    }
+}
+/** Default production token store. */
+export function createTokenStore() {
+    return new KeychainTokenStore();
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "dazzer-connect",
+  "private": false,
+  "version": "0.1.0",
+  "description": "Sign in to Dazzer from your terminal and configure MCP clients",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "dazzer": "dist/index.js"
+  },
+  "files": ["dist/**/*.js", "LICENSE"],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dazzer-io/dazzer.git",
+    "directory": "packages/oauth-cli"
+  },
+  "homepage": "https://github.com/dazzer-io/dazzer/tree/main/packages/oauth-cli",
+  "bugs": {
+    "url": "https://github.com/dazzer-io/dazzer/issues"
+  },
+  "keywords": ["dazzer", "oauth", "cli", "mcp", "auth"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@napi-rs/keyring": "^1.2.0",
+    "commander": "^14.0.0",
+    "env-paths": "^3.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.5"
+  }
+}