@2kw/ai 5.2.0-dev.6 → 5.2.0

package/dist/lib/config.d.ts

@@ -2,16 +2,41 @@ import Conf from "conf";
 import type { Command } from "commander";
 export interface ContextEntry {
     baseUrl: string;
-    apiKey: string;
+    /** Present on API-key contexts (CI/scripts and manual logins). */
+    apiKey?: string;
+    /** Present on session contexts created by the browser device-flow login. */
+    sessionToken?: string;
+    /** Auth service base URL for this context (e.g. https://auth.2kw.ai). */
+    authUrl?: string;
+    /** Active organization chosen at login / via set-org. */
+    organizationId?: string;
+    /** Short-lived org JWT cache — avoids one auth round-trip between rapid commands. */
+    cachedJwt?: string;
+    /** Epoch millis when cachedJwt expires. */
+    cachedJwtExp?: number;
 }
 export interface BackboneConfigStore {
     activeContext: string;
     contexts: Record<string, ContextEntry>;
 }
-export interface BackboneConfig {
+/**
+ * What a command actually authenticates with. Either a raw API key, or a
+ * browser session that a later step exchanges for a short-lived org JWT.
+ */
+export type ResolvedConfig = {
+    kind: "apiKey";
     apiKey: string;
     baseUrl: string;
-}
+} | {
+    kind: "session";
+    contextName: string;
+    sessionToken: string;
+    authUrl: string;
+    baseUrl: string;
+    organizationId?: string;
+    cachedJwt?: string;
+    cachedJwtExp?: number;
+};
 /**
  * Fallback base URL when the user has no context, env var, or local config.
  * Override at runtime by setting AI_2KW_DEFAULT_BASE_URL (or the legacy
@@ -19,6 +44,12 @@ export interface BackboneConfig {
  * deployment.
  */
 export declare const DEFAULT_BASE_URL: string;
+/**
+ * Fallback auth-service URL used when the API host is not one we recognise.
+ * Override at runtime with AI_2KW_DEFAULT_AUTH_URL.
+ */
+export declare const DEFAULT_AUTH_URL: string;
+export declare function defaultAuthUrlFor(baseUrl: string): string;
 declare const store: Conf<BackboneConfigStore>;
 export { store };
 export declare function validateContextName(name: string): void;
@@ -27,18 +58,46 @@ export declare function getActiveContext(): ContextEntry | undefined;
 export declare function getAllContexts(): Record<string, ContextEntry>;
 export declare function getContextCount(): number;
 export declare function setContext(name: string, entry: ContextEntry): void;
+/**
+ * Merge a partial update into an existing context, leaving unmentioned fields
+ * intact.
+ *
+ * Note the spread semantics: a key present in `patch` with the value
+ * `undefined` CLEARS that field rather than being ignored. That is deliberate
+ * and relied upon — e.g. `updateContext(name, { cachedJwt: undefined,
+ * cachedJwtExp: undefined })` drops a stale cached JWT.
+ */
+export declare function updateContext(name: string, patch: Partial<ContextEntry>): void;
 export declare function deleteContext(name: string): void;
 export declare function renameContext(oldName: string, newName: string): void;
 export declare function setActiveContext(name: string): void;
+/**
+ * Every input resolution considers, made explicit so the precedence rules can
+ * be exercised without touching the store, the environment, or the cwd.
+ *
+ * Flags, env vars, and the local file are API-key-only by design: session
+ * credentials are issued by the browser login and only ever live in the store.
+ */
+export interface ConfigSources {
+    flagApiKey?: string;
+    flagBaseUrl?: string;
+    envApiKey?: string;
+    envBaseUrl?: string;
+    localApiKey?: string;
+    localBaseUrl?: string;
+    activeContextName: string;
+    activeContext?: ContextEntry;
+}
+export declare function resolveConfigFromSources(s: ConfigSources): ResolvedConfig;
 /**
  * Resolve configuration with priority:
  *   1. CLI flags (--api-key, --base-url)
  *   2. Environment variables (AI_2KW_API_KEY then legacy BACKBONE_API_KEY,
  *      same for AI_2KW_BASE_URL / BACKBONE_BASE_URL)
  *   3. Local .2kw file (or legacy .backbone)
- *   4. Active context from config store
+ *   4. Active context from config store (API key or browser session)
  */
-export declare function resolveConfig(command: Command): BackboneConfig;
+export declare function resolveConfig(command: Command): ResolvedConfig;
 /** Check if --json flag is set on root command */
 export declare function isJsonOutput(command: Command): boolean;
 //# sourceMappingURL=config.d.ts.map

package/dist/lib/config.js

@@ -10,6 +10,32 @@ import { resolve } from "node:path";
 export const DEFAULT_BASE_URL = process.env.AI_2KW_DEFAULT_BASE_URL ??
     process.env.BACKBONE_DEFAULT_BASE_URL ??
     "https://backbone.manfred-kunze.dev/api";
+/**
+ * Fallback auth-service URL used when the API host is not one we recognise.
+ * Override at runtime with AI_2KW_DEFAULT_AUTH_URL.
+ */
+export const DEFAULT_AUTH_URL = process.env.AI_2KW_DEFAULT_AUTH_URL ?? "https://auth.2kw.ai";
+/** Known API-host → auth-service mappings for interactive login defaults. */
+const AUTH_URL_BY_API_HOST = {
+    "api.2kw.ai": "https://auth.2kw.ai",
+    "api-dev.2kw.ai": "https://auth-dev.2kw.ai",
+    "backbone.manfred-kunze.dev": "https://auth.2kw.ai",
+    "localhost:8080": "http://localhost:3001",
+    "127.0.0.1:8080": "http://localhost:3001",
+};
+export function defaultAuthUrlFor(baseUrl) {
+    try {
+        const host = new URL(baseUrl).host;
+        // hasOwn, not a bare index: a host like "constructor" or "toString" would
+        // otherwise resolve through Object.prototype and yield a bogus auth URL.
+        return Object.hasOwn(AUTH_URL_BY_API_HOST, host)
+            ? AUTH_URL_BY_API_HOST[host]
+            : DEFAULT_AUTH_URL;
+    }
+    catch {
+        return DEFAULT_AUTH_URL;
+    }
+}
 // One-shot flag so we only print the deprecation warning once per process,
 // even if resolveConfig is called multiple times across commands.
 let legacyEnvWarned = false;
@@ -30,9 +56,17 @@ function warnLegacyEnv(legacyName, canonicalName) {
  * fully self-contained.
  */
 const CONFIG_DIR_OVERRIDE = process.env.AI_2KW_CONFIG_DIR;
+/**
+ * Owner-only, like an ssh private key: this file holds live credentials — an
+ * API key, or a session token and the org JWT minted from it. conf defaults to
+ * 0o666, which on any shared POSIX box makes every account on it a reader.
+ * Windows largely ignores mode bits, where this is simply inert.
+ */
+const CONFIG_FILE_MODE = 0o600;
 const store = new Conf({
     projectName: "2kw",
     projectSuffix: "",
+    configFileMode: CONFIG_FILE_MODE,
     defaults: {
         activeContext: "default",
         contexts: {},
@@ -56,6 +90,9 @@ const store = new Conf({
     const legacy = new Conf({
         projectName: "backbone",
         projectSuffix: "",
+        // Same credentials, same restriction — this instance only computes a path
+        // today, but it must not be the one that widens a file if it ever writes.
+        configFileMode: CONFIG_FILE_MODE,
         defaults: { activeContext: "default", contexts: {} },
         ...(CONFIG_DIR_OVERRIDE ? { cwd: CONFIG_DIR_OVERRIDE } : {}),
     });
@@ -117,6 +154,24 @@ export function setContext(name, entry) {
     contexts[name] = entry;
     store.set("contexts", contexts);
 }
+/**
+ * Merge a partial update into an existing context, leaving unmentioned fields
+ * intact.
+ *
+ * Note the spread semantics: a key present in `patch` with the value
+ * `undefined` CLEARS that field rather than being ignored. That is deliberate
+ * and relied upon — e.g. `updateContext(name, { cachedJwt: undefined,
+ * cachedJwtExp: undefined })` drops a stale cached JWT.
+ */
+export function updateContext(name, patch) {
+    const contexts = getAllContexts();
+    const existing = contexts[name];
+    if (!existing) {
+        throw new Error(`Context "${name}" does not exist.`);
+    }
+    contexts[name] = { ...existing, ...patch };
+    store.set("contexts", contexts);
+}
 export function deleteContext(name) {
     const contexts = getAllContexts();
     if (!contexts[name]) {
@@ -186,32 +241,67 @@ function readEnv(canonical, legacy) {
     }
     return undefined;
 }
+const NO_AUTH_ERROR = 'No credentials configured. Run "2kw auth login" (browser sign-in), ' +
+    '"2kw auth login --api-key <key>", or set AI_2KW_API_KEY.';
+export function resolveConfigFromSources(s) {
+    const baseUrl = s.flagBaseUrl ??
+        s.envBaseUrl ??
+        s.localBaseUrl ??
+        s.activeContext?.baseUrl ??
+        DEFAULT_BASE_URL;
+    // Explicit API keys (flag > env > local file) always win — they are the
+    // CI/script escape hatch and must never be shadowed by a stored session.
+    const explicitApiKey = s.flagApiKey ?? s.envApiKey ?? s.localApiKey;
+    if (explicitApiKey) {
+        return { kind: "apiKey", apiKey: explicitApiKey, baseUrl };
+    }
+    const ctx = s.activeContext;
+    if (ctx?.sessionToken) {
+        // A session without an auth URL cannot be exchanged for a JWT — treat it
+        // as unusable rather than failing later with an opaque request error.
+        if (!ctx.authUrl)
+            throw new Error(NO_AUTH_ERROR);
+        return {
+            kind: "session",
+            contextName: s.activeContextName,
+            sessionToken: ctx.sessionToken,
+            authUrl: ctx.authUrl,
+            baseUrl,
+            organizationId: ctx.organizationId,
+            cachedJwt: ctx.cachedJwt,
+            cachedJwtExp: ctx.cachedJwtExp,
+        };
+    }
+    if (ctx?.apiKey) {
+        return { kind: "apiKey", apiKey: ctx.apiKey, baseUrl };
+    }
+    throw new Error(NO_AUTH_ERROR);
+}
 /**
  * Resolve configuration with priority:
  *   1. CLI flags (--api-key, --base-url)
  *   2. Environment variables (AI_2KW_API_KEY then legacy BACKBONE_API_KEY,
  *      same for AI_2KW_BASE_URL / BACKBONE_BASE_URL)
  *   3. Local .2kw file (or legacy .backbone)
- *   4. Active context from config store
+ *   4. Active context from config store (API key or browser session)
  */
 export function resolveConfig(command) {
     const root = getRootCommand(command);
     const opts = root.opts();
     const local = readLocalFile();
-    const activeCtx = getActiveContext();
-    const apiKey = opts.apiKey ??
-        readEnv("AI_2KW_API_KEY", "BACKBONE_API_KEY") ??
-        local.apiKey ??
-        activeCtx?.apiKey;
-    const baseUrl = opts.baseUrl ??
-        readEnv("AI_2KW_BASE_URL", "BACKBONE_BASE_URL") ??
-        local.baseUrl ??
-        activeCtx?.baseUrl ??
-        DEFAULT_BASE_URL;
-    if (!apiKey) {
-        throw new Error('No API key configured. Run "2kw auth login" (or "backbone auth login") or set AI_2KW_API_KEY.');
-    }
-    return { apiKey, baseUrl };
+    // readEnv now runs even when a flag overrides it, so the BACKBONE_* legacy
+    // deprecation warning can fire in cases the old short-circuit chain silenced.
+    // Accepted: the variable IS set and IS deprecated, flag or no flag.
+    return resolveConfigFromSources({
+        flagApiKey: opts.apiKey,
+        flagBaseUrl: opts.baseUrl,
+        envApiKey: readEnv("AI_2KW_API_KEY", "BACKBONE_API_KEY"),
+        envBaseUrl: readEnv("AI_2KW_BASE_URL", "BACKBONE_BASE_URL"),
+        localApiKey: local.apiKey,
+        localBaseUrl: local.baseUrl,
+        activeContextName: getActiveContextName(),
+        activeContext: getActiveContext(),
+    });
 }
 /** Walk up Commander's parent chain to find root program */
 function getRootCommand(cmd) {

package/dist/lib/errors.d.ts

@@ -10,5 +10,23 @@ export declare class BackboneApiError extends Error {
     readonly timestamp: string;
     constructor(body: ApiErrorBody);
 }
+/**
+ * Discriminated cause of a failed credential check. Lets callers give a
+ * precise message instead of guessing, because `2kw auth status` otherwise
+ * collapses every failure into one string.
+ */
+export type AuthFailureKind = "UNAUTHORIZED" | "FORBIDDEN" | "UNREACHABLE" | "UNKNOWN";
+/**
+ * Classify why a credential check failed, from the thrown error alone.
+ *
+ * - An HTTP rejection arrives as {@link BackboneApiError} (the API) or
+ *   {@link AuthServiceError} (the auth service): 401 → UNAUTHORIZED,
+ *   403 → FORBIDDEN, anything else → UNKNOWN.
+ * - A network fault (fetch throws before any response) → UNREACHABLE, detected
+ *   by undici's `fetch failed` TypeError or a known network error code on the
+ *   error or its `cause`.
+ * - Everything else → UNKNOWN.
+ */
+export declare function classifyAuthFailure(err: unknown): AuthFailureKind;
 export declare function handleError(err: unknown, json: boolean): void;
 //# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.js

@@ -1,4 +1,7 @@
 import chalk from "chalk";
+import { AuthServiceError } from "./auth-service.js";
+import { SessionExpiredError } from "./auth-session.js";
+import { getActiveContext, getActiveContextName, updateContext } from "./config.js";
 export class BackboneApiError extends Error {
     status;
     errorType;
@@ -11,8 +14,62 @@ export class BackboneApiError extends Error {
         this.timestamp = body.timestamp;
     }
 }
+// Node/undici surface network faults through the error's `code`. A DNS or
+// connection failure means the host was never reached — distinct from the
+// API rejecting the key.
+const NETWORK_ERROR_CODES = new Set([
+    "ENOTFOUND",
+    "ECONNREFUSED",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "ECONNRESET",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+]);
+/** Shared status → kind mapping: the two rejection types agree on what a 401
+ *  and a 403 mean, and differ only in who sent them. */
+function classifyStatus(status) {
+    if (status === 401)
+        return "UNAUTHORIZED";
+    if (status === 403)
+        return "FORBIDDEN";
+    return "UNKNOWN";
+}
+/**
+ * Classify why a credential check failed, from the thrown error alone.
+ *
+ * - An HTTP rejection arrives as {@link BackboneApiError} (the API) or
+ *   {@link AuthServiceError} (the auth service): 401 → UNAUTHORIZED,
+ *   403 → FORBIDDEN, anything else → UNKNOWN.
+ * - A network fault (fetch throws before any response) → UNREACHABLE, detected
+ *   by undici's `fetch failed` TypeError or a known network error code on the
+ *   error or its `cause`.
+ * - Everything else → UNKNOWN.
+ */
+export function classifyAuthFailure(err) {
+    if (err instanceof BackboneApiError)
+        return classifyStatus(err.status);
+    if (err instanceof AuthServiceError)
+        return classifyStatus(err.status);
+    if (isNetworkError(err))
+        return "UNREACHABLE";
+    return "UNKNOWN";
+}
+function isNetworkError(err) {
+    if (!(err instanceof Error))
+        return false;
+    // undici throws `TypeError: fetch failed` when the request never completes.
+    if (err instanceof TypeError && /fetch failed/i.test(err.message))
+        return true;
+    const code = err.code;
+    if (typeof code === "string" && NETWORK_ERROR_CODES.has(code))
+        return true;
+    const cause = err.cause;
+    const causeCode = cause?.code;
+    return typeof causeCode === "string" && NETWORK_ERROR_CODES.has(causeCode);
+}
 const HINTS = {
-    401: 'Invalid or missing API key. Run "backbone auth login" to configure credentials.',
+    401: 'Invalid or missing API key. Run "2kw auth login" to configure credentials.',
     402: "Billing limit reached. Check your plan limits or upgrade at the dashboard.",
     403: "You don't have permission for this action. Check your organization role.",
     404: "Resource not found. Verify the ID is correct.",
@@ -20,8 +77,39 @@ const HINTS = {
     422: "Validation error. Check the input values.",
     429: "Rate limit exceeded. Wait a moment and try again.",
 };
+/**
+ * Drop the cached org JWT of the active session context.
+ *
+ * Called when the session behind that JWT turns out to be dead: keeping the
+ * token would only make the next command spend a request discovering the same
+ * 401. Best-effort by design — a read-only store is not worth a second error on
+ * top of the one being reported.
+ */
+function clearCachedJwt() {
+    try {
+        const ctx = getActiveContext();
+        // API-key contexts have no session and no cache to clear.
+        if (!ctx?.sessionToken)
+            return;
+        updateContext(getActiveContextName(), { cachedJwt: undefined, cachedJwtExp: undefined });
+    }
+    catch {
+        // Nothing actionable: the message below is still the one the user needs.
+    }
+}
 export function handleError(err, json) {
-    if (err instanceof BackboneApiError) {
+    if (err instanceof SessionExpiredError) {
+        clearCachedJwt();
+        // Reached by every command once the stored session dies, so it gets the
+        // one line that names the fix — never a stack trace.
+        if (json) {
+            console.error(JSON.stringify({ error: "session_expired", message: err.message }));
+        }
+        else {
+            console.error(chalk.yellow(err.message));
+        }
+    }
+    else if (err instanceof BackboneApiError) {
         if (json) {
             console.error(JSON.stringify({
                 error: err.errorType,
@@ -40,7 +128,21 @@ export function handleError(err, json) {
     }
     else if (err instanceof Error) {
         if (json) {
-            console.error(JSON.stringify({ error: err.name, message: err.message }));
+            // Errors from outside the typed client (AuthServiceError, undici network
+            // faults) carry their own status/code. Passing them through is what lets
+            // a scripted caller tell an "invalid_client" apart from a dead DNS name
+            // instead of string-matching the message.
+            const status = err.status;
+            // undici hangs the real code off `cause`, so read both — same pair
+            // isNetworkError checks above.
+            const code = err.code ??
+                err.cause?.code;
+            console.error(JSON.stringify({
+                error: err.name,
+                message: err.message,
+                ...(typeof status === "number" ? { status } : {}),
+                ...(typeof code === "string" ? { code } : {}),
+            }));
         }
         else {
             console.error(chalk.red(`Error: ${err.message}`));

package/dist/lib/redact.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The one place that decides how a stored credential is allowed to appear —
+ * on screen, and in `--json` output.
+ *
+ * Every surface that prints a {@link ContextEntry} goes through here (`context
+ * list`, `context current`, `config list`), because a secret that reaches a
+ * terminal also reaches scrollback, CI logs, and pasted bug reports. Keeping
+ * the rules next to the shape they redact is what stops the next surface from
+ * re-deriving them and forgetting a field.
+ */
+import type { ContextEntry } from "./config.js";
+/**
+ * Enough of an API key to recognise which one it is, never enough to use it.
+ * A key too short to keep both ends of is blanked outright rather than
+ * printed with its middle "hidden".
+ */
+export declare function maskApiKey(key: string | undefined): string;
+/**
+ * Session tokens are opaque and long; the leading characters are enough to
+ * tell two apart in a bug report, and are useless on their own.
+ */
+export declare function maskSessionToken(token: string): string;
+/** The credential column of `context list` / `context current`, either kind. */
+export declare function credentialSummary(ctx: ContextEntry): string;
+/**
+ * A {@link ContextEntry} safe to serialize.
+ *
+ * The shape is otherwise the stored one so scripts reading `context list
+ * --json` keep working: `apiKey` and `sessionToken` are masked in place,
+ * `cachedJwt` is dropped entirely (it is a bearer token for the API and has no
+ * identifying value at all), and `cachedJwtExp` stays — knowing when the cache
+ * turns over is useful and expiries are not secret.
+ */
+export declare function redactContext(ctx: ContextEntry): Record<string, unknown>;
+//# sourceMappingURL=redact.d.ts.map

package/dist/lib/redact.js

@@ -0,0 +1,54 @@
+/**
+ * The one place that decides how a stored credential is allowed to appear —
+ * on screen, and in `--json` output.
+ *
+ * Every surface that prints a {@link ContextEntry} goes through here (`context
+ * list`, `context current`, `config list`), because a secret that reaches a
+ * terminal also reaches scrollback, CI logs, and pasted bug reports. Keeping
+ * the rules next to the shape they redact is what stops the next surface from
+ * re-deriving them and forgetting a field.
+ */
+/**
+ * Enough of an API key to recognise which one it is, never enough to use it.
+ * A key too short to keep both ends of is blanked outright rather than
+ * printed with its middle "hidden".
+ */
+export function maskApiKey(key) {
+    if (!key)
+        return "-";
+    if (key.length <= 11)
+        return "****";
+    return key.slice(0, 7) + "..." + key.slice(-4);
+}
+/**
+ * Session tokens are opaque and long; the leading characters are enough to
+ * tell two apart in a bug report, and are useless on their own.
+ */
+export function maskSessionToken(token) {
+    return token.length <= 8 ? "****" : token.slice(0, 8) + "...";
+}
+/** The credential column of `context list` / `context current`, either kind. */
+export function credentialSummary(ctx) {
+    if (ctx.sessionToken)
+        return `session ${maskSessionToken(ctx.sessionToken)}`;
+    return maskApiKey(ctx.apiKey);
+}
+/**
+ * A {@link ContextEntry} safe to serialize.
+ *
+ * The shape is otherwise the stored one so scripts reading `context list
+ * --json` keep working: `apiKey` and `sessionToken` are masked in place,
+ * `cachedJwt` is dropped entirely (it is a bearer token for the API and has no
+ * identifying value at all), and `cachedJwtExp` stays — knowing when the cache
+ * turns over is useful and expiries are not secret.
+ */
+export function redactContext(ctx) {
+    const { apiKey, sessionToken, cachedJwt, ...rest } = ctx;
+    void cachedJwt; // destructured only to keep it out of `rest`.
+    return {
+        ...rest,
+        ...(apiKey !== undefined ? { apiKey: maskApiKey(apiKey) } : {}),
+        ...(sessionToken !== undefined ? { sessionToken: maskSessionToken(sessionToken) } : {}),
+    };
+}
+//# sourceMappingURL=redact.js.map

package/dist/lib/update-notifier.js

@@ -2,7 +2,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import chalk from "chalk";
-const PKG_NAME = "@manfred-kunze-dev/backbone-cli";
+const PKG_NAME = "@2kw/ai";
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 1 day
 const CACHE_DIR = join(homedir(), ".config", "backbone");
 const CACHE_FILE = join(CACHE_DIR, "update-check.json");

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@2kw/ai",
-  "version": "5.2.0-dev.6",
-  "description": "CLI for the 2kw.ai platform (engineering name: Backbone)",
+  "version": "5.2.0",
+  "description": "CLI for 2kw.ai — schema-driven document extraction, an OpenAI-compatible EU LLM gateway, transcription, prompts, datasets, and experiments from your terminal or agentic workflows. Ships as 2kw, backbone, and bb.",
+  "keywords": [
+    "cli",
+    "llm-gateway",
+    "ai-gateway",
+    "document-extraction",
+    "structured-data-extraction",
+    "pdf-extraction",
+    "openai-compatible",
+    "transcription",
+    "prompt-management",
+    "llm-evaluation",
+    "llm-observability",
+    "agentic-workflows",
+    "gdpr",
+    "eu-data-residency",
+    "2kw",
+    "backbone"
+  ],
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -28,6 +46,7 @@
     "cli-table3": "^0.6.5",
     "commander": "^13.1.0",
     "conf": "^13.1.0",
+    "open": "^10.2.0",
     "openapi-fetch": "^0.13.5",
     "ora": "^8.2.0"
   },