@aixle/insights 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dualboot Partners
+
+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,137 @@
+# @aixle/insights
+
+stdio **MCP server** for AI coding-assistant telemetry. Ingests Claude Code JSONL transcripts and Cursor IDE SQLite telemetry into your organization's ingest API, exposes operator tools on the MCP bridge, and pairs with `aixle-insights init` so teammates can onboard without juggling cron jobs or brittle shell hooks.
+
+## Install
+
+```bash
+# One-shot via npx (recommended — always pulls the latest):
+npx -y @aixle/insights init \
+  --host https://YOUR-API-HOST \
+  --keycloak-url https://YOUR-KEYCLOAK/realms/YOUR_REALM
+
+# Or global install:
+npm i -g @aixle/insights
+aixle-insights init --host https://YOUR-API-HOST --keycloak-url https://YOUR-KEYCLOAK/realms/YOUR_REALM
+```
+
+`init` performs a Keycloak device login, stores credentials locally (OS keychain via `keytar` when available, otherwise `~/.aixle-insights/credentials.json` mode 0600), and merges the MCP server entry into `~/.claude.json` under `mcpServers.aixle-insights`.
+
+After `init` succeeds:
+
+1. **Restart Claude Code** — it discovers the new MCP server on the next launch.
+2. Open Claude Code; confirm `/mcp` lists **aixle-insights**.
+3. During a Claude session invoke the **`db90_status`** MCP tool (or `aixle-insights health` from the shell) to see connectivity + last sync metadata.
+
+## Multi-org
+
+If your account has several organization memberships, `init` mints ingest tokens for the **oldest** membership unless you scope to a different org:
+
+```bash
+npx -y @aixle/insights init \
+  --host https://YOUR-API-HOST \
+  --keycloak-url https://YOUR-KEYCLOAK/realms/YOUR_REALM \
+  --organization-id <uuid>
+```
+
+You can also set `DB90_ORGANIZATION_ID=<uuid>` in your shell environment, or pin it via `mcpServers.aixle-insights.env` in `~/.claude.json`. The CLI flag overrides the env var when both are set.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `aixle-insights run` | Start the MCP stdio server (the default; spawned by Claude Code on demand). |
+| `aixle-insights run --once` | Perform one multi-tool sync, exit. Useful for cron / manual flushes. |
+| `aixle-insights run --once --full` | Backfill: ignore Cursor watermarks and commit-hash dedupe. |
+| `aixle-insights init` | Keycloak device login + persist credentials + merge `~/.claude.json` entry. |
+| `aixle-insights init --hooks --tool-name cursor` | Also install the Cursor-side hook forwarder (opt-in; requires Cursor restart). |
+| `aixle-insights uninstall-hooks` | Remove the hook forwarder + restore `~/.cursor/hooks.json` backup. |
+| `aixle-insights verify-hooks` | Print hooks install status + queue depth as JSON. |
+| `aixle-insights health` | Multi-line diagnostic (credentials, sync, log path, state files). |
+
+## Environment
+
+| Variable | Purpose |
+|---|---|
+| `DB90_API_URL` | API origin for ingestion + MCP exchange (defaults to `http://localhost:3000`; `init --host` overrides). |
+| `KEYCLOAK_ISSUER` / `DB90_KEYCLOAK_ISSUER` | Realm issuer URLs (preferred on servers + CI). |
+| `DB90_KEYCLOAK_CLIENT_ID` | Defaults to `db90-web`; must allow device authorization in Keycloak. |
+| `DB90_ORGANIZATION_ID` | Optional UUID scoping `init` to that org membership (header `X-Organization-ID`). |
+| `AIXLE_INSIGHTS_HOME` | Override the local state directory (defaults to `~/.aixle-insights/`). |
+
+Note: the `DB90_*` variables above are retained as compatibility names for the deployment-side Keycloak realm/client identifiers. Future versions may rename them with a deprecation window.
+
+Optional `~/.aixle-insights/config.json` accepts Cursor line-cost overrides (per-model rates):
+
+```json
+{
+  "cursor": {
+    "line_costs": {
+      "claude-sonnet-4-5": { "input_per_line": 0.0002, "output_per_line": 0.0008 }
+    }
+  }
+}
+```
+
+## Cursor hook forwarder (opt-in)
+
+`aixle-insights init --hooks --tool-name cursor` installs a Node script as a Cursor hook (`~/.cursor/hooks.json`). The script appends redacted hook payloads to `~/.aixle-insights/hooks-queue.ndjson`; the background sync drains the queue on its next cycle and POSTs the events with accurate per-turn model attribution. Requires a Cursor restart after install. To remove, run `aixle-insights uninstall-hooks` and restart Cursor again.
+
+## State + credentials
+
+- **App home directory**: `~/.aixle-insights/` (override with `AIXLE_INSIGHTS_HOME`).
+- **Credentials**: OS keychain via `keytar` when available (service: `aixle-insights`); fallback file `~/.aixle-insights/credentials.json` with mode 0600 on POSIX.
+- **State files**: `state-<hostname>-<token-hash>.json` per credential, plus `state.lock` advisory lock, `mcp.log` rotating diagnostic log, optional `hooks-queue.ndjson`.
+
+The internal state-file shape is implementation-detail; don't depend on it from outside this package.
+
+## Diagnostics
+
+```bash
+aixle-insights health        # connectivity + last sync metadata
+aixle-insights verify-hooks  # JSON: hooks installed + queue depth
+```
+
+`mcp.log` (rotates at 5 MiB to `mcp.log.1`) under the app home directory captures operational events. Inside Claude Code, the **`db90_status`** MCP tool returns the same diagnostic structure as `aixle-insights health`.
+
+## Local development — `/aixle-reset` skill
+
+> Audience: contributors editing this package. If you installed `@aixle/insights` from npm and aren't modifying the source, you can skip this section.
+
+When you iterate on `src/` against a real Claude Code or Cursor session, the running MCP routinely drifts out of sync with the code you just wrote. Common causes:
+
+- Rebuilt `dist/` but never restarted the long-lived MCP process — your changes aren't in memory.
+- `~/.claude.json` accumulated both `mcpServers.insights` and `mcpServers.aixle-insights` (or a legacy `mcpServers.db90`), and Claude Code spawned the wrong one.
+- The MCP launched from a non-git-rooted `cwd` (e.g. `~/`), so pre-resolution returned `project_id: null` and every turn in that session inherited it.
+
+The repo ships a Claude Code skill, **`/aixle-reset`** (lives at `.claude/skills/aixle-reset/SKILL.md`), that restores known-good local state in one shot.
+
+It runs `scripts/reset-local-env.mjs`, which:
+
+1. Stops any running `aixle-insights/dist/cli.js run` process.
+2. Rebuilds `dist/` if anything in `src/` is newer.
+3. Repairs `~/.claude.json` and `~/.cursor/mcp.json` so the entries point at `node <abs path>/dist/cli.js run`, stripping duplicate `insights` and legacy `db90` keys. Backs up each file it modifies.
+4. Warns non-blockingly about leftover direct-curl ingest hooks in `~/.claude/settings.json` and stale `@db90/*` npm globals.
+5. Restarts the MCP from the repo root so pre-resolution finds the project from `git remote`.
+6. Waits up to 30 s for the first `project_attribution_resolved` log line and asserts `project_id` is non-null.
+
+Invoke manually:
+
+```bash
+node packages/tools/aixle-insights/scripts/reset-local-env.mjs
+```
+
+Or, inside Claude Code, run the **`/aixle-reset`** skill.
+
+A `PostToolUse` hook (`.claude/hooks/on-aixle-insights-edit.ts`) **suggests** running the skill whenever you edit a file under `packages/tools/aixle-insights/**` (excluding `dist/`, `*.md`, and any test path). The hook is advisory only — it never auto-executes, so you can iterate freely and reset when you're ready to test end-to-end.
+
+After the script reports success: **quit and reopen Claude Code / Cursor** so each IDE re-spawns its own MCP from the now-canonical config. The MCP the script started manually keeps running standalone and will still sweep transcripts correctly until you replace it.
+
+## Requirements
+
+- Node.js ≥ 20.
+- macOS / Linux / Windows. On Windows, the package writes a `cmd /c npx …` wrapper in `~/.claude.json` so Claude Code can spawn the MCP server reliably.
+
+## License
+
+MIT.

package/dist/auth/credentials.d.ts

@@ -0,0 +1,23 @@
+/** Ingest tool IDs that MCP can provision tokens for via `/integrations/mcp/exchange`. */
+export type TelemetryToolId = "claude_code" | "cursor";
+/** Normalized persisted credentials (v2); all accounts share one ingest host namespace. */
+export interface StoredCredentials {
+    host: string;
+    organizationId?: string;
+    accounts: Partial<Record<TelemetryToolId, string>>;
+}
+export declare const KEYTAR_SERVICE = "aixle-insights";
+/** Returns true when at least one tool has a non-empty token. */
+export declare function credentialsHaveAnyToken(creds: StoredCredentials): boolean;
+export declare function pickProjectLookupToken(creds: StoredCredentials): string | null;
+/** Read credentials from disk only (tests / fallback). */
+export declare function loadCredentialsFromFileOnly(appDir?: string): StoredCredentials | null;
+/** Prefer OS keychain when keytar works; otherwise read `credentials.json`. */
+export declare function loadCredentials(appDir?: string): Promise<StoredCredentials | null>;
+/**
+ * Persist multi-tool ingest tokens for one host namespace.
+ */
+export declare function saveStoredCredentials(creds: StoredCredentials, appDir?: string): Promise<void>;
+/** Back-compat: persists a Claude-only ingest token bundle. */
+export declare function saveCredentials(token: string, host: string, appDir?: string): Promise<void>;
+export declare function clearCredentials(appDir?: string): Promise<void>;

package/dist/auth/credentials.js

@@ -0,0 +1,174 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAppDir } from "../state.js";
+export const KEYTAR_SERVICE = "aixle-insights";
+const KEYTAR_ACCOUNT = "aixle-insights-ingest-credential";
+function credentialsPath(appDir) {
+    return join(appDir, "credentials.json");
+}
+function keytarDisabled() {
+    return ["1", "true", "yes"].includes(process.env["DB90_MCP_DISABLE_KEYTAR"]?.toLowerCase() ?? "");
+}
+/** Returns true when at least one tool has a non-empty token. */
+export function credentialsHaveAnyToken(creds) {
+    const acc = creds.accounts;
+    if (acc === null || acc === undefined || typeof acc !== "object")
+        return false;
+    return Object.values(acc).some((t) => typeof t === "string" && t.length > 0);
+}
+export function pickProjectLookupToken(creds) {
+    return creds.accounts.claude_code ?? creds.accounts.cursor ?? null;
+}
+function normalizeLoadedCredentials(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const o = raw;
+    const host = o.host;
+    const v = o.version;
+    if (v === 2) {
+        const acc = o.accounts;
+        if (typeof host !== "string" || host.length === 0)
+            return null;
+        if (typeof acc !== "object" || acc === null)
+            return null;
+        const accounts = acc;
+        const out = {};
+        for (const tid of ["claude_code", "cursor"]) {
+            const tok = accounts[tid];
+            if (typeof tok === "string" && tok.length > 0)
+                out[tid] = tok;
+        }
+        if (!credentialsHaveAnyToken({ host, accounts: out }))
+            return null;
+        const org = o.organizationId;
+        return {
+            host,
+            accounts: out,
+            organizationId: typeof org === "string" ? org : undefined,
+        };
+    }
+    const token = o.token;
+    if (typeof token === "string" && token.length > 0 && typeof host === "string" && host.length > 0) {
+        return { host, accounts: { claude_code: token } };
+    }
+    return null;
+}
+/** Read credentials from disk only (tests / fallback). */
+export function loadCredentialsFromFileOnly(appDir = getAppDir()) {
+    const filePath = credentialsPath(appDir);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+        return normalizeLoadedCredentials(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function tryKeytarGet() {
+    if (keytarDisabled())
+        return null;
+    try {
+        const keytar = await import("keytar");
+        const raw = await keytar.default.getPassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT);
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        return normalizeLoadedCredentials(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+async function tryKeytarSet(payload) {
+    if (keytarDisabled())
+        return false;
+    try {
+        const keytar = await import("keytar");
+        await keytar.default.setPassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT, payload);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function tryKeytarDelete() {
+    if (keytarDisabled())
+        return;
+    try {
+        const keytar = await import("keytar");
+        await keytar.default.deletePassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT);
+    }
+    catch {
+        // ignore
+    }
+}
+function writeFileCredential(appDir, creds) {
+    mkdirSync(appDir, { recursive: true });
+    const filePath = credentialsPath(appDir);
+    const body = {
+        version: 2,
+        host: creds.host,
+        organizationId: creds.organizationId,
+        accounts: { ...creds.accounts },
+    };
+    writeFileSync(filePath, `${JSON.stringify(body, null, 2)}\n`, {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
+    if (process.platform !== "win32") {
+        try {
+            chmodSync(filePath, 0o600);
+        }
+        catch {
+            // ignore chmod failures on exotic FS
+        }
+    }
+}
+function removeFileCredential(appDir) {
+    const filePath = credentialsPath(appDir);
+    if (existsSync(filePath)) {
+        try {
+            unlinkSync(filePath);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+/** Prefer OS keychain when keytar works; otherwise read `credentials.json`. */
+export async function loadCredentials(appDir = getAppDir()) {
+    const fromFile = loadCredentialsFromFileOnly(appDir);
+    if (fromFile)
+        return fromFile;
+    const fromKeytar = await tryKeytarGet();
+    if (fromKeytar)
+        return fromKeytar;
+    return null;
+}
+/**
+ * Persist multi-tool ingest tokens for one host namespace.
+ */
+export async function saveStoredCredentials(creds, appDir = getAppDir()) {
+    if (!credentialsHaveAnyToken(creds)) {
+        throw new Error("saveStoredCredentials requires at least one account token");
+    }
+    const payload = JSON.stringify({ version: 2, ...creds, accounts: { ...creds.accounts } });
+    const keytarOk = await tryKeytarSet(payload);
+    if (keytarOk) {
+        removeFileCredential(appDir);
+    }
+    else {
+        await tryKeytarDelete();
+        writeFileCredential(appDir, creds);
+    }
+}
+/** Back-compat: persists a Claude-only ingest token bundle. */
+export async function saveCredentials(token, host, appDir = getAppDir()) {
+    await saveStoredCredentials({ host, accounts: { claude_code: token } }, appDir);
+}
+export async function clearCredentials(appDir = getAppDir()) {
+    await tryKeytarDelete();
+    removeFileCredential(appDir);
+}

package/dist/auth/exchange.d.ts

@@ -0,0 +1,25 @@
+export interface ExchangeAccount {
+    ingestToken: string;
+}
+export interface ExchangeResult {
+    ingestHost: string;
+    organizationId: string;
+    /** Present when exchanging a single tool (legacy shape). */
+    ingestToken?: string;
+    /** Per-tool ingest tokens (`claude_code`, `cursor`). */
+    accounts: Partial<Record<"claude_code" | "cursor", ExchangeAccount>>;
+}
+type ExchangeToolId = "claude_code" | "cursor";
+export declare function exchangeIngestToken(params: {
+    db90Host: string;
+    keycloakAccessToken: string;
+    /** Legacy single-tool mint. Omit when tools is provided. */
+    toolName?: ExchangeToolId;
+    /** Mint / rotate ingest tokens for all listed tools under one OAuth session. */
+    tools?: readonly ExchangeToolId[];
+    deviceLabel?: string;
+    /** When set, sent as `X-Organization-ID` so the API scopes exchange to that membership. */
+    exchangeOrganizationId?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<ExchangeResult>;
+export {};

package/dist/auth/exchange.js

@@ -0,0 +1,87 @@
+export async function exchangeIngestToken(params) {
+    const fetchFn = params.fetchImpl ?? fetch;
+    const requestedTools = params.tools?.length ? [...params.tools] : params.toolName ? [params.toolName] : [];
+    const base = params.db90Host.replace(/\/$/, "");
+    const url = `${base}/api/v1/integrations/mcp/exchange`;
+    const body = {};
+    if (params.tools?.length) {
+        body.tools = [...params.tools];
+    }
+    else if (params.toolName) {
+        body.tool_name = params.toolName;
+    }
+    else {
+        throw new Error("exchangeIngestToken: provide toolName or tools[]");
+    }
+    if (params.deviceLabel) {
+        body.device_label = params.deviceLabel;
+    }
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${params.keycloakAccessToken}`,
+    };
+    const orgHeader = params.exchangeOrganizationId?.trim();
+    if (orgHeader) {
+        headers["X-Organization-ID"] = orgHeader;
+    }
+    const res = await fetchFn(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`DB90 exchange: invalid JSON (HTTP ${res.status}): ${text.slice(0, 200)}`);
+    }
+    if (!res.ok) {
+        throw new Error(`DB90 exchange failed (HTTP ${res.status}): ${text.slice(0, 500)}`);
+    }
+    const root = json;
+    const data = root["data"];
+    if (typeof data !== "object" || data === null) {
+        throw new Error("DB90 exchange: missing data object");
+    }
+    const d = data;
+    const ingestHost = d["ingestHost"];
+    const organizationId = d["organizationId"];
+    if (typeof ingestHost !== "string" || typeof organizationId !== "string") {
+        throw new Error("DB90 exchange: missing ingestHost or organizationId in data");
+    }
+    const ingestTokenRaw = d["ingestToken"];
+    const accountsRaw = d["accounts"];
+    const accounts = {};
+    if (typeof accountsRaw === "object" && accountsRaw !== null && !Array.isArray(accountsRaw)) {
+        for (const key of ["claude_code", "cursor"]) {
+            const entry = accountsRaw[key];
+            if (typeof entry === "object" && entry !== null) {
+                const tok = entry["ingestToken"];
+                if (typeof tok === "string" && tok.length > 0) {
+                    accounts[key] = { ingestToken: tok };
+                }
+            }
+        }
+    }
+    let ingestToken = typeof ingestTokenRaw === "string" && ingestTokenRaw.length > 0 ? ingestTokenRaw : undefined;
+    if (!ingestToken && Object.keys(accounts).length === 1) {
+        const only = Object.values(accounts)[0];
+        if (only?.ingestToken)
+            ingestToken = only.ingestToken;
+    }
+    if (Object.keys(accounts).length === 0) {
+        if (!ingestToken) {
+            throw new Error("DB90 exchange: no ingestToken / accounts returned in data");
+        }
+        const fallbackTool = requestedTools.length === 1 ? requestedTools[0] : d["toolName"];
+        const tid = fallbackTool === "cursor" ? "cursor" : "claude_code";
+        accounts[tid] = { ingestToken };
+    }
+    const missingTools = requestedTools.filter((tool) => !accounts[tool]?.ingestToken);
+    if (missingTools.length > 0) {
+        throw new Error(`DB90 exchange: missing requested account(s): ${missingTools.join(", ")}`);
+    }
+    return { ingestHost, organizationId, ingestToken, accounts };
+}

package/dist/auth/flow.d.ts

@@ -0,0 +1,24 @@
+import { defaultKeycloakClientId, defaultKeycloakIssuer } from "./keycloak.js";
+import type { TelemetryToolId } from "./credentials.js";
+export interface LoginAndPersistOptions {
+    db90Host: string;
+    keycloakIssuer: string;
+    /** @deprecated Prefer `tools`; kept for callers that mint a single ingest account. */
+    toolName?: string;
+    tools?: TelemetryToolId[];
+    deviceLabel?: string;
+    /** Optional org UUID for `X-Organization-ID` on MCP exchange (multi-org users). */
+    exchangeOrganizationId?: string;
+    clientId?: string;
+    appDir?: string;
+    onVisitInstructions?: (verification_uri: string, user_code: string) => void;
+    fetchImpl?: typeof fetch;
+}
+export declare function loginAndPersistCredentials(opts: LoginAndPersistOptions): Promise<{
+    ok: true;
+    organizationId: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+export { defaultKeycloakIssuer, defaultKeycloakClientId };

package/dist/auth/flow.js

@@ -0,0 +1,66 @@
+import { exchangeIngestToken } from "./exchange.js";
+import { defaultKeycloakClientId, defaultKeycloakIssuer, obtainKeycloakAccessTokenViaDeviceFlow } from "./keycloak.js";
+import { loadCredentials, saveStoredCredentials } from "./credentials.js";
+import { getAppDir } from "../state.js";
+export async function loginAndPersistCredentials(opts) {
+    const issuer = opts.keycloakIssuer.trim();
+    if (!issuer) {
+        return { ok: false, error: "Keycloak issuer is empty; set KEYCLOAK_ISSUER or pass --keycloak-url." };
+    }
+    const clientId = opts.clientId?.trim() || defaultKeycloakClientId();
+    const appDir = opts.appDir ?? getAppDir();
+    const requestedTools = opts.tools ??
+        ((opts.toolName ?? "claude_code") === "cursor" ? ["cursor"] : ["claude_code"]);
+    let accessToken;
+    try {
+        accessToken = await obtainKeycloakAccessTokenViaDeviceFlow({
+            issuer,
+            clientId,
+            onInstructions: opts.onVisitInstructions,
+            fetchImpl: opts.fetchImpl,
+        });
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+    let exchanged;
+    try {
+        if (requestedTools.length > 1) {
+            exchanged = await exchangeIngestToken({
+                db90Host: opts.db90Host,
+                keycloakAccessToken: accessToken,
+                tools: requestedTools,
+                deviceLabel: opts.deviceLabel,
+                exchangeOrganizationId: opts.exchangeOrganizationId,
+                fetchImpl: opts.fetchImpl,
+            });
+        }
+        else {
+            exchanged = await exchangeIngestToken({
+                db90Host: opts.db90Host,
+                keycloakAccessToken: accessToken,
+                toolName: requestedTools[0],
+                deviceLabel: opts.deviceLabel,
+                exchangeOrganizationId: opts.exchangeOrganizationId,
+                fetchImpl: opts.fetchImpl,
+            });
+        }
+        const existing = await loadCredentials(appDir);
+        const stored = {
+            host: exchanged.ingestHost,
+            organizationId: exchanged.organizationId,
+            accounts: existing?.host === exchanged.ingestHost ? { ...existing.accounts } : {},
+        };
+        for (const tid of ["claude_code", "cursor"]) {
+            const acc = exchanged.accounts[tid];
+            if (acc?.ingestToken)
+                stored.accounts[tid] = acc.ingestToken;
+        }
+        await saveStoredCredentials(stored, appDir);
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+    return { ok: true, organizationId: exchanged.organizationId };
+}
+export { defaultKeycloakIssuer, defaultKeycloakClientId };

package/dist/auth/keycloak.d.ts

@@ -0,0 +1,35 @@
+/**
+ * RFC 8628 OAuth 2.0 Device Authorization Grant against Keycloak OIDC endpoints.
+ */
+export interface DeviceAuthorizationStart {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval?: number;
+    code_verifier?: string;
+}
+export declare function startDeviceAuthorization(params: {
+    issuer: string;
+    clientId: string;
+    scope?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<DeviceAuthorizationStart>;
+export declare function pollDeviceAccessToken(params: {
+    issuer: string;
+    clientId: string;
+    deviceAuthorization: DeviceAuthorizationStart;
+    /** Called once before polling so UIs can show the visit URL and user code. */
+    onInstructions?: (verification_uri: string, user_code: string) => void;
+    fetchImpl?: typeof fetch;
+}): Promise<string>;
+export declare function obtainKeycloakAccessTokenViaDeviceFlow(params: {
+    issuer: string;
+    clientId: string;
+    scope?: string;
+    onInstructions?: (verification_uri: string, user_code: string) => void;
+    fetchImpl?: typeof fetch;
+}): Promise<string>;
+export declare function defaultKeycloakIssuer(): string;
+export declare function defaultKeycloakClientId(): string;